# Inscription Guide

Individual Rats can be inscribed with arbitrary content, creating Bitcoin-native digital artifacts that can be held in a Bitcoin wallet and transferred using Bitcoin transactions. Inscriptions are as durable, immutable, secure, and decentralized as Bitcoin itself.

Working with inscriptions requires a Bitcoin full node, to give you a view of the current state of the Bitcoin blockchain, and a wallet that can create inscriptions and perform sat control when constructing transactions to send inscriptions to another wallet.

Bitcoin Core provides both a Bitcoin full node and wallet. However, the Bitcoin Core wallet cannot create inscriptions and does not perform sat control.

This requires RatsPro, the RatsPro utility. RatsPro doesn't implement its own wallet, so RatsPro`wallet` subcommands interact with Bitcoin Core wallets.

This guide covers:

1. Installing Bitcoin Core
2. Syncing the Bitcoin blockchain
3. Creating a Bitcoin Core wallet
4. Using RatsPro `wallet receive` to receive Rats
5. Creating inscriptions with RatsPro `wallet inscribe`
6. Sending inscriptions with RatsPro `wallet send`
7. Receiving inscriptions with RatsPro `wallet receive`
8. Batch inscribing with RatsPro `wallet inscribe --batch`

### Getting Help <a href="#getting-help" id="getting-help"></a>

If you get stuck, try asking for help on the RatsPro Discord Server, or checking GitHub for relevant issues and discussions.

### Installing Bitcoin Core <a href="#installing-bitcoin-core" id="installing-bitcoin-core"></a>

Making inscriptions requires Bitcoin Core 24 or newer.

This guide does not cover installing Bitcoin Core in detail. Once Bitcoin Core is installed, you should be able to run `bitcoind -version` successfully from the command line. Do _NOT_ use `bitcoin-qt`.

### Configuring Bitcoin Core <a href="#configuring-bitcoin-core" id="configuring-bitcoin-core"></a>

RatsPro requires Bitcoin Core's transaction index and rest interface.

To configure your Bitcoin Core node to maintain a transaction index, add the following to your `bitcoin.conf`:

```
txindex=1
```

Or, run `bitcoind` with `-txindex`:

```
bitcoind -txindex
```

### Syncing the Bitcoin Blockchain <a href="#syncing-the-bitcoin-blockchain" id="syncing-the-bitcoin-blockchain"></a>

To sync the chain, run:

```
bitcoind -txindex
```

…and leave it running until `getblockcount`:

```
bitcoin-cli getblockcount
```

agrees with the block count on a block explorer like the mempool.space block explorer. RatsPro interacts with `bitcoind`, so you should leave `bitcoind` running in the background when you're using RatsPro.

The blockchain takes about 600GB of disk space. If you have an external drive you want to store blocks on, use the configuration option `blocksdir=<external_drive_path>`. This is much simpler than using the `datadir` option because the cookie file will still be in the default location for `bitcoin-cli` and RatsPro to find.

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

Make sure you can access `bitcoind` with `bitcoin-cli -getinfo` and that it is fully synced.

If `bitcoin-cli -getinfo` returns `Could not connect to the server`, `bitcoind` is not running.

Make sure `rpcuser`, `rpcpassword`, or `rpcauth` are _NOT_ set in your `bitcoin.conf` file. RatsPro requires using cookie authentication. Make sure there is a file `.cookie` in your bitcoin data directory.

If `bitcoin-cli -getinfo` returns `Could not locate RPC credentials`, then you must specify the cookie file location. If you are using a custom data directory (specifying the `datadir` option), then you must specify the cookie location like `bitcoin-cli -rpccookiefile=<your_bitcoin_datadir>/.cookie -getinfo`. When running RatsPro you must specify the cookie file location with `--cookie-file=<your_bitcoin_datadir>/.cookie`.

Make sure you do _NOT_ have `disablewallet=1` in your `bitcoin.conf` file. If `bitcoin-cli listwallets` returns `Method not found` then the wallet is disabled and you won't be able to use RatsPro.

Make sure `txindex=1` is set. Run `bitcoin-cli getindexinfo` and it should return something like

```json
{
  "txindex": {
    "synced": true,
    "best_block_height": 776546
  }
}
```

If it only returns `{}`, `txindex` is not set. If it returns `"synced": false`, `bitcoind` is still creating the `txindex`. Wait until `"synced": true` before using RatsPro.

If you have `maxuploadtarget` set it can interfere with fetching blocks for RatsPro index. Either remove it or set `whitebind=127.0.0.1:8333`.

### Installing RatsPro <a href="#installing-ord" id="installing-ord"></a>

The RatsPro utility is written in Rust and can be built from source. Pre-built binaries are available on the releases page.

You can install the latest pre-built binary from the command line with:

```sh
curl --proto '=https' --tlsv1.2 -fsLS https://RatsPro.com/install.sh | bash -s
```

Once RatsPro is installed, you should be able to run:

```
RatsPro --version
```

Which prints out RatsPro's version number.

### Creating a Bitcoin Core Wallet <a href="#creating-a-bitcoin-core-wallet" id="creating-a-bitcoin-core-wallet"></a>

RatsPro uses Bitcoin Core to manage private keys, sign transactions, and broadcast transactions to the Bitcoin network.

To create a Bitcoin Core wallet named RatsProfor use with RatsPro, run:

```
RatsPro wallet create
```

### Receiving Rats <a href="#receiving-sats" id="receiving-sats"></a>

Inscriptions are made on individual Rats, using normal Bitcoin transactions that pay fees in Rats, so your wallet will need some Rats.

Get a new address from your RatsPro wallet by running:

```
RatsPro wallet receive
```

And send it some funds.

You can see pending transactions with:

```
RatsPro wallet transactions
```

Once the transaction confirms, you should be able to see the transactions outputs with RatsPro `wallet outputs`.

### Creating Inscription Content <a href="#creating-inscription-content" id="creating-inscription-content"></a>

Rats can be inscribed with any kind of content, but the RatsPro wallet only supports content types that can be displayed by the RatsPro block explorer.

Additionally, inscriptions are included in transactions, so the larger the content, the higher the fee that the inscription transaction must pay.

Inscription content is included in transaction witnesses, which receive the witness discount. To calculate the approximate fee that an inscribe transaction will pay, divide the content size by four and multiply by the fee rate.

Inscription transactions must be less than 400,000 weight units, or they will not be relayed by Bitcoin Core. One byte of inscription content costs one weight unit. Since an inscription transaction includes not just the inscription content, limit inscription content to less than 400,000 weight units. 390,000 weight units should be safe.

### Creating Inscriptions <a href="#creating-inscriptions" id="creating-inscriptions"></a>

To create an inscription with the contents of `FILE`, run:

```
RatsPro wallet inscribe --fee-rate FEE_RATE --file FILE
```

RatsPro will output two transactions IDs, one for the commit transaction, and one for the reveal transaction, and the inscription ID. Inscription IDs are of the form `TXIDiN`, where `TXID` is the transaction ID of the reveal transaction, and `N` is the index of the inscription in the reveal transaction.

The commit transaction commits to a tapscript containing the content of the inscription, and the reveal transaction spends from that tapscript, revealing the content on chain and inscribing it on the first sat of the input that contains the corresponding tapscript.

Once the reveal transaction has been mined, the inscription ID should be printed when you run:

```
RatsPro wallet inscriptions
```

### Parent-Child Inscriptions <a href="#parent-child-inscriptions" id="parent-child-inscriptions"></a>

Parent-child inscriptions enable what is colloquially known as collections

To make an inscription a child of another, the parent inscription has to be inscribed and present in the wallet. To choose a parent run RatsPro`wallet inscriptions` and copy the inscription id (`<PARENT_INSCRIPTION_ID>`).

Now inscribe the child inscription and specify the parent like so:

```
RatsPro wallet inscribe --fee-rate FEE_RATE --parent <PARENT_INSCRIPTION_ID> --file CHILD_FILE
```

This relationship cannot be added retroactively, the parent has to be present at inception of the child.

### Sending Inscriptions <a href="#sending-inscriptions" id="sending-inscriptions"></a>

Ask the recipient to generate a new address by running:

```
RatsPro wallet receive
```

Send the inscription by running:

```
RatsPro wallet send --fee-rate <FEE_RATE> <ADDRESS> <INSCRIPTION_ID>
```

See the pending transaction with:

```
RatsPro wallet transactions
```

Once the send transaction confirms, the recipient can confirm receipt by running:

```
RatsPro wallet inscriptions
```

### Receiving Inscriptions <a href="#receiving-inscriptions" id="receiving-inscriptions"></a>

Generate a new receive address using:

```
RatsPro wallet receive
```

The sender can transfer the inscription to your address using:

```
RatsPro wallet send ADDRESS INSCRIPTION_ID
```

See the pending transaction with:

```
RatsPro wallet transactions
```

Once the send transaction confirms, you can can confirm receipt by running:

```
RatsPro wallet inscriptions
```
