Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add inscription guide #912

Merged
merged 33 commits into from
Dec 8, 2022
Merged
Show file tree
Hide file tree
Changes from 14 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/book.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[book]
title = "Ordinal Hunter's Manual"
title = "Ordinal Theory Handbook"
language = "en"
src = "src"

Expand Down
11 changes: 7 additions & 4 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@

[Introduction](introduction.md)

- [Theory](theory.md)
- [Block Explorer](block-explorer.md)
- [Hunting](hunting.md)
- [Overview](overview.md)
- [FAQ](faq.md)

- [Bounties](bounty.md)
- [Guides](guides.md)
- [Explorer](guides/explorer.md)
- [Inscriptions](guides/inscriptions.md)
- [Ordinal Hunting](guides/ordinal-hunting.md)

- [Bounties](bounties.md)
- [Bounty 0: 100,000 sats Claimed!](bounty/0.md)
- [Bounty 1: 200,000 sats Claimed!](bounty/1.md)
- [Bounty 2: 300,000 sats Claimed!](bounty/2.md)
Expand Down
4 changes: 2 additions & 2 deletions docs/src/bounty.md → docs/src/bounties.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
Ordinal Bounty Hunting Hints
============================

- There are no ordinal wallets or transaction construction libraries. However,
- The `ord` wallet can send and receive specific satoshis. Additionally,
ordinal theory is extremely simple. A clever hacker should be able to write
code to manipulate ordinals in no time.
code from scratch to manipulate satoshis using ordinal theory in no time.

- For more information about ordinals, check out the [FAQ](./faq.md) for an
overview, the [BIP](https://github.com/casey/ord/blob/master/bip.mediawiki)
Expand Down
Empty file added docs/src/guides.md
Empty file.
4 changes: 2 additions & 2 deletions docs/src/block-explorer.md → docs/src/guides/explorer.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Ordinal Block Explorer
======================
Ordinal Explorer
================

The `ord` binary includes a block explorer. We host a instance of the block
explorer on mainnet at [ordinals.com](https://ordinals.com), and on signet at
Expand Down
208 changes: 208 additions & 0 deletions docs/src/guides/inscriptions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,208 @@
Ordinal Inscription Guide
=========================

Individual satoshis 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 the Bitcoin blockchain 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 make
ordinal-aware transactions that inscribe satoshis with content and transfer
individual satoshis using ordinal theory.

Bitcoin Core provides both a Bitcoin full node and wallet. However, the Bitcoin
Core wallet cannot make ordinal-aware transactions. Making ordinal-aware
transactions requires [`ord`](https://github.com/casey/ord), the ordinal theory
utility. `ord wallet` subcommands interact with an existing Bitcoin Core
wallet.

This guide covers:

1. Installing Bitcoin Core
2. Syncing the Bitcoin blockchain
3. Creating a Bitcoin Core wallet
4. Using `ord wallet receive` to receive satoshis
5. Creating inscriptions with `ord wallet inscribe`
6. Sending inscriptions with `ord wallet send`
7. Receiving inscriptions with `ord wallet receive`

Getting Help
------------

If you get stuck, try asking for help on the [Ordinal Theory Discord
Server](https://discord.com/invite/87cjuz4FYg), or checking GitHub for relevant
[issues](https://github.com/casey/ord/issues) and
[discussions](https://github.com/casey/ord/discussions).

Installing Bitcoin Core
-----------------------

Bitcoin Core is available from [bitcoincore.org](https://bitcoincore.org/) on
the [download page](https://bitcoincore.org/en/download/).

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.

Configuring Bitcoin Core to use Signet
--------------------------------------

`ord wallet` subcommands cannot yet be used on mainnet, so your Bitcoin Core
node must be configured to use another chain. This guide uses signet, but
testnet or regtest mode may also be used.

To configure your Bitcoin Core node to use signet, add `signet=1` to your
`bitcoin.conf` configuration file, or pass `-signet` to `bitcoind` and
`bitcoin-cli`, e.g. `bitcoind -signet` and `bitcoin-cli -signet`.

casey marked this conversation as resolved.
Show resolved Hide resolved
Syncing the Bitcoin Blockchain
------------------------------

Once Bitcoin Core has been configured to use signet, you'll need to sync the
blockchain. Signet is a low-volume test network, so this shoudln't take long.

To sync the chain, run `bitcoind -signet` and leave it running until
`bitcoin-cli -signet getblockcount` agrees with the block count on a block
explorer like [the mempool.space signet block
explorer](https://mempool.space/signet).

Creating a Bitcoin Core Wallet
------------------------------

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

`ord` wallets must be named `ord`, or start with `ord-`, to avoid
unintentionally using the `ord` utility with non-ordinal Bitcoin wallets.

To create a wallet for use with `ord`, run:

```
bitcoin-cli -signet createwallet ord
```

Loading the Bitcoin Core Wallet
-------------------------------

Bitcoin Core wallets must be loaded before the can be used with `ord`. To load
your wallet, run:

```
bitcoin-cli -signet loadwallet ord
```

Installing `ord`
----------------

The `ord` utility is written in Rust and can be built from
[source](https://github.com/casey/ord). Pre-built binaries are available on the
[releases page](https://github.com/casey/ord/releases).

Once `ord` is installed, you shoud be able to run `ord --version` on the
command line.

Receiving Satoshis
------------------

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


Get a new address from your `ord` wallet by running `ord --chain signet wallet
receive`

Use a signet faucet to send satoshis to the address you generated. Two faucets
you might try are [signet.bc-2.jp](https://signet.bc-2.jp/) and
[alt.signetfaucet.com](https://alt.signetfaucet.com/).

Once the faucet transaction confirms, you should be able to see the
transactions outputs with `ord --chain signet wallet utxos`.

Creating Inscription Content
----------------------------

Create a `.png` or `.txt` file smaller than 1024 bytes to inscribe.

Satoshis can be inscribed with any kind of content, but the `ord` wallet and
explorer are currently limited to `.png` and `.txt` files.

Additionally, inscriptions made on signet must be 1024 bytes or less, to avoid
congesting signet for other users. Inscriptions are stored in Taproot input
witnesses, so mainnet inscriptions will only be limited by the 4,000,000 byte
witness size limit.

Creating Inscriptions
---------------------

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

```
ord --chain signet wallet inscribe --file CONTENTS
```

Ord will output two transactions IDs, one for the commit transaction, and one
for the reveal transaction.

The commit transaction commits to a tapscript containing the contents of the
inscription, and the reveal transaction spends from that tapscript, reaveling
casey marked this conversation as resolved.
Show resolved Hide resolved
the contents on chain and inscribing them on the first satoshi of the first
output of the reveal transaction.

Wait for the reveal transaction to be mined. You can check the status of the
commit and reveal transactions using [the mempool.space signet block
explorer](https://mempool.space/signet).

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

```
ord --chain signet wallet inscriptions
```

And when you visit [the signet ordinals explorer](https://signet.ordinals.com/)
at `signet.ordinals.com/inscription/INSCRIPTION_ID`.


Sending Inscriptions
--------------------

Ask the recipient to generate a new address by running:

```
ord --chain signet wallet receive
```

Send the inscription by running:

```
ord --chain signet wallet send INSCRIPTION_ID ADDRESS
```

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

```
ord --chain signet wallet inscriptions
```

Receiving Inscriptions
----------------------

Generate a new receive address using:

```
ord --chain signet wallet receive
```

The sender can transfer the inscription to your address using:

```
ord --chain signet wallet send INSCRIPTION_ID ADDRESS
```

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

```
ord --chain signet wallet inscriptions
```
19 changes: 12 additions & 7 deletions docs/src/hunting.md → docs/src/guides/ordinal-hunting.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
Ordinal Hunting
===============

*This guide is out of date. Since it was written, the `ord` binary was changed
to only build the full ordinal index when the `--ordinal-index` flag is
supplied. Additionally, `ord` now has a built-in wallet that wraps a Bitcoin
Core wallet. See `ord wallet --help`.*

Ordinal hunting is difficult but rewarding. The feeling of owning a wallet full
of UTXOs, redolent with the scent of rare and exotic ordinals, is beyond
compare.
of UTXOs, redolent with the scent of rare and exotic sats, is beyond compare.

Ordinals are numbers for satoshis. Every satoshi has an ordinal number and
every ordinal number has a satoshi.
Expand Down Expand Up @@ -234,11 +238,12 @@ those multiple descriptors into Bitcoin Core.

#### Sparrow Wallet

Navigate to the `Settings` tab, then to `Script Policy`, and press the edit button to display the descriptor.
Navigate to the `Settings` tab, then to `Script Policy`, and press the edit
button to display the descriptor.

### Transferring Ordinals

`ord` does not yet support transferring specific ordinals. Currently, your best
bet is to use the `bitcoin-cli` commands `createrawtransaction`,
`signrawtransactionwithwallet`, and `sendrawtransaction`, however, how to do so
is complex and outside the scope of this guide.
The `ord` wallet supports transferring specific satoshis. You can also use
`bitcoin-cli` commands `createrawtransaction`, `signrawtransactionwithwallet`,
and `sendrawtransaction`, how to do so is complex and outside the scope of this
guide.
35 changes: 33 additions & 2 deletions docs/src/introduction.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,35 @@
Ordinals are a namespace for Bitcoin. For an overview, check out the [theory](theory.md) page.
Introduction
============

This handbook is a guide to ordinal theory. Ordinal theory concerns itself with
distinguishing satoshis, giving them an identity and allowing them to be
tracked and transferred individually.

Satoshis, not bitcoin, are the atomic, native currency of the Bitcoin network.
One bitcoin can be sub-divided into 100,000,000 satoshis, but no further.

Ordinal theory is not a side chain, does not require any token aside from
Bitcoin, and can be used without any changes to the Bitcoin network. It works
right now.

Ordinal theory imbues satoshis with numismatic value, allowing them to
collected and traded as curios.

Individual satoshis 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 the Bitcoin blockchain itself.

Other, more unusual use-cases are possible: off-chain colored-coins, public key
infrastructure with key rotation, a decentralized replacement for the DNS. For
now though, such use cases are theoretical, and exist only in the minds of
fringe ordinal theorists.

For more details on ordinal theory, see the [overview](overview.md).

When you're ready to get your hands dirty, a good place to start is with
[inscriptions](guides/inscriptions.md), a curious species of digital artifact
enabled by ordinal theory.

Links
-----
Expand All @@ -7,7 +38,7 @@ Links
- [BIP](https://github.com/casey/ord/blob/master/bip.mediawiki)
- [Discord](https://discord.gg/87cjuz4FYg)
- [Mainnet Block Explorer](https://ordinals.com)
- [Signet Block Explorer](https://ordinals.com)
- [Signet Block Explorer](https://signet.ordinals.com)

Videos
------
Expand Down
Loading