Mac beginner's guide for ORD development (updated as of Bitcoin Core v26.1 and ord v0.18.3)

README_bitcoin.md

Ord Guide for Mac

Main source for this: https://discord.com/channels/987504378242007100/1078719003624747108 🙏🙏 by ETS (so7ow on Discord)

This guide mostly assumes a primary SSD and an external SSD, formatted as APFS. If you want to follow the commands verbatim, name your external SSD volume as ord-dev. You'll still need ~100 GB free on your internal disk, as only the bitcoin blocks are moved to the external SSD. This configuration allows for moving the bulk of the storage needs to the external but leaving enough in the default locations to make commands easier.

⚠️ This guide won't work well if your primary or external storage are on a spinning disk. SSD only! Like really, you will regret your wasted time otherwise!

1️⃣ INSTALL HOMEBREW

Install Homebrew from http://brew.sh/ During installation you may be prompted for a password. This is your main Mac password and you won't see any letters as you type it. After typing it, press enter to continue.

⚠️ When installation completes, follow the steps listed in "Next steps" to add Homebrew to your path.

2️⃣ INSTALL BITCOIN

After Homebrew installation and "Next steps", run this from terminal:

brew install bitcoin

3️⃣ CREATE BLOCKS DIR

⚠️Skip this step if no external SSD.

After the bitcoin installation, create your bitcoin blocks directory on your external SSD (most Macs don't have enough storage on their internal SSDs. 1 TB free for comfort.) Name the folder bitcoin. If your external SSD volume name has a space, rename that, too. No spaces! In this guide, the external SSD has the name ord-dev!

4️⃣ CONFIGURE BITCOIN.CONF

Run these commands in Terminal:

mkdir ~/Library/Application\ support/Bitcoin

echo blocksdir=/Volumes/ord-dev/Bitcoin > ~/Library/Application\ Support/Bitcoin/bitcoin.conf
echo txindex=1 >> ~/Library/Application\ Support/Bitcoin/bitcoin.conf
echo server=1 >> ~/Library/Application\ Support/Bitcoin/bitcoin.conf

echo blocksdir=/Volumes/ord-dev/Bitcoin\\ntxindex=1\\nserver=1\\n > ~/Library/Application\ support/Bitcoin/bitcoin.conf

(where the /ord-dev/Bitcoin part is the actual path to the SSD and folder you created above.-- ⚠️ CAREFUL MODIFYING THIS COMMAND, EVERY SPACE AND SLASH AND ~ IS NEEDED! ⚠️)

⚠️ If you don't have an external drive, then skip the blocksdir line!

• txindex=1 If you want to be able to access any transaction with commands like gettransaction , you need to configure Bitcoin Core to build a complete transaction index, which can be achieved with the txindex option.
• server=1 tells Bitcoin-Qt and bitcoind to accept JSON-RPC commands, so you can query it

Confirm all settings with:

cat ~/Library/Application\ Support/Bitcoin/bitcoin.conf

5️⃣ START/STOP BITCOIN SERVICE

In terminal:

brew services start bitcoin

and this if you want to stop it again (not yet)

brew services stop bitcoin

6️⃣ CONFIRM SETTINGS

In the debug.log file located in ~/Library/Application\ Support/Bitcoin/, look for lines similar to these:

2023-11-15T13:16:47Z Default data directory /Users/username/Library/Application Support/Bitcoin
2023-11-15T13:16:47Z Using data directory /Users/username/Library/Application Support/Bitcoin
2023-11-15T13:16:47Z Config file: /Users/username/Library/Application Support/Bitcoin/bitcoin.conf
2023-11-15T13:16:47Z Config file arg: blocksdir="/Volumes/ord-dev/Bitcoin"
2023-11-15T13:16:47Z Config file arg: server="1"
2023-11-15T13:16:47Z Config file arg: txindex="1"
2023-11-15T13:16:47Z Generated RPC authentication cookie /Users/username/Library/Application Support/Bitcoin/.cookie

⚠️ An easy way to monitor the file in Terminal is to use this command:

tail -F -n 10000 ~/Library/Application\ Support/Bitcoin/debug.log

These entries in the output confirm that the blocks dir and the configuration entries have been recognized and have taken effect. Pay attention to the cookie line. You'll need that later, so make sure you have it!

7️⃣ INITIAL BLOCK DOWNLOAD (aka BLOCKCHAIN SYNC)

The initial block download will generally take 1+ days, depending on factors like CPU/disk/network speed. As it progresses, you'll see lines like this in the debug.log file:

 2023-02-22T15:18:23Z UpdateTip: new best=00000000000000000000e2319131e7e41d3b93e8b9086fc427f2ee9383aa2686 height=777656 version=0x20004000 log2_work=94.017345 tx=807469638 date='2023-02-21T14:40:00Z' progress=0.999679 cache=2.5MiB(18835txo)

The progress= entry tells you how far you are along. It will reach 1.000000 at completion of the initial block download and then you can leave bitcoin running as a service and proceed to the ord installation and configuration.

7️⃣ EXTRA: FINAL CONFIRMATION OF READINESS

Run this in terminal:

bitcoin-cli getindexinfo

You should see a response like this:

{
  "txindex": {
    "synced": true,
    "best_block_height": 839505
}

If it shows synced:false or the block height is not current, wait longer and run the command again. If it shows synced:true and current block height, proceed to ord installation!

README_ord.md

1️⃣ INSTALL ORD

Run this command in terminal:

brew install ord

Confirm success by typing this in terminal:

ord --version

You should get a response like this:

ord 0.18.3

2️⃣ CREATE ORD INDEX

⚠️ If you don't have an internal SSD (you have an internal spinning disk) this may not work well. Seek assistance to relocate your index file with the --index switch. Doing so will change all following ord commands in this guide, as well.

We will create a full-blown ord index with sats and runes on your internal SSD. Run this command:

ord --index-runes --index-sats --index ~/ordindex.redb  server

If all's well you'll see an indexing progress bar. It will start fast and slow down considerably. If it completes, great -- often it doesn't if your computer's resources are constrained. If it slows or appears to stop--WAIT LONGER. A trick that seems to work if it completely bombs out at the end or stops for many hours, is to press ctrl-c (only once!) when it's a few blocks from completing, then give it time to exit gracefully, reboot and run it again. Repeat until successful.

JUST DOWNLOAD AN ORD INDEX

Tired of waiting? Ok, there are Ordinals Index files pre-built by Greg. These are the pre-built index.redb files, ready for download:

https://ordstuff.info/

Thanks Greg! 🙏

Yeah, that's just the .torrent file. You need to plug that into a torrent app to download the multi-gigabyte .redb.gz file.

Two possible clients for Mac:

• Transmission
• qbittorrent

README_z_esplora.md

How to run the explorer for Bitcoin mainnet (unfinished)

esplora is just the web ui frontend, you also need to setup the (forked) electrs backend for indexing and for providing the HTTP API that esplora queries.

electrs can index the bitcoin block chain using two methods: by reading the blk files directly out of disk, or by querying for blocks using the bitcoind rpc. The first method is significantly faster, but requires electrs to have filesystem access to the bitcoin datadir, which would typically mean running them on the same server (you could technically do this remotely but you'll lose most of the performance gain, so not much point in doing that). The second method can work if you have two separate servers, but I wouldn't recommend it (would be painfully slow).

https://bitcoin.stackexchange.com/a/91859

Without Docker

brew install rust

To setup electrs, install Rust and:

$ sudo apt install clang cmake # required for building rust-rocksdb $ git clone https://github.com/blockstream/electrs && cd electrs $ git checkout new-index $ cargo run --release --bin electrs -- -vvv --daemon-dir ~/.bitcoin

With Docker (runs own bitcoin node, will index again!!!)

docker run -p 50001:50001 -p 8080:80 \
           --volume $PWD/data_bitcoin_mainnet:/data \
           --rm -i -t esplora \
           bash -c "/srv/explorer/run.sh bitcoin-mainnet explorer"

For my drive and for the pre-build imgage:

mkdir ~/Library/Application\ Support/Bitcoin/esplora-mainnet

docker run -p 50001:50001 -p 8080:80 \
           --volume ~/Library/Application\ Support/Bitcoin/esplora-mainnet:/data \
           --rm -i -t blockstream/esplora \
           bash -c "/srv/explorer/run.sh bitcoin-mainnet explorer"

README_z_extra.md

disablesleep 1

You don’t want your MacBook to sleep when you close the lid?

sudo pmset -a disablesleep 1

That should stop your Mac sleeping.