How to Sync a Bitcoin Node

In this guide, we’ll walk through syncing a Bitcoin node, so that you can use Chainhook, which enables you to create real-time event streams for Bitcoin. With Chainhook, you can stream on-chain events (such as tracking deposits to a particular address) to your app.

Download Bitcoin Core daemon

In order for Chainhook to interact with Bitcoin chainstate, we will use Bitcoin Core daemon (bitcoind). This is a program that implements the Bitcoin protocol for remote procedure call (RPC) usage, and Chainhook can be configured to interact with bitcoind’s ZeroMQ interface, an embedded networking library.

To get started, we first need to download version 25.0 of bitcoind. You can select a software version compatible with your device from this list. 

Configure bitcoind

Now that you’ve downloaded the file, we need to configure bitcoind to work with Chainhook before we start syncing the node.

Note Your Executable Path

Open the <code-rich-text>bitcoin-25.0<code-rich-text> folder you downloaded in the previous step. Inside you’ll find a <code-rich-text>bin<code-rich-text> directory. 

When you sync your node, we’ll be running the program at <code-rich-text>/download/location/bitcoin-25.0/bin/bitcoin<code-rich-text>, so make note of this path now for later use.

Select or Create a Directory for Your Bitcoin Data

Now you need to choose where to send Bitcoin data from your node. In our case, we are going to use an external hard drive that we have living at <code-rich-text>/Volumes/SSD/bitcoin-data<code-rich-text>.

Note: This folder, <code-rich-text>bitcoin-data<code-rich-text>, can be named whatever you like, and can live locally or in an external hard drive - the most important part being that it should exist in a place that has enough storage to hold all the Bitcoin data we will be receiving once it starts to sync.

You can either copy the default path (you can find a list of default directories by operating system here) or you can copy a custom path that you’ve set for your Bitcoin data (such as an external SSD).

Update the bitcoin.conf File

Now navigate to the directory of your <code-rich-text>bitcoin-25.0<code-rich-text> and update your <code-rich-text>bitcoin.conf<code-rich-text> file. 

Copy the configuration below into that new file, including the path to where you will be storing all of the Bitcoin data that we will be receiving once it starts syncing:

# Bitcoin Core Configuration

datadir=/path/to/bitcoin-data/ # In our case, /Volumes/SSD/bitcoin-data
server=1
rpcuser=devnet
rpcpassword=devnet
rpcport=8332
rpcallowip=0.0.0.0/0
rpcallowip=::/0
txindex=1
listen=1
discover=0
dns=0
dnsseed=0
listenonion=0
rpcserialversion=1
disablewallet=0
fallbackfee=0.00001
rpcthreads=8
blocksonly=1
dbcache=4096

# Start zeromq
zmqpubhashblock=tcp://0.0.0.0:18543

Set a Username/Password

Now it’s time to set some credentials for bitcoind. Pick a username and password of your choice and add them to the config file above.

Note: in the boilerplate code sample above, <code-rich-text>devnet<code-rich-text> is listed as the default username and password.

Run the bitcoind Node

Now that you’ve finished configuring your <code-rich-text>bitcoin.conf<code-rich-text> file, it’s time to start up your bitcoind node.

The command for this takes the form <code-rich-text>path/to/bitcoind -conf=path/to/bitcoin.conf<code-rich-text>, which in practice looks like:

/Volumes/SSD/bitcoin-25.0/bin/bitcoind -conf=/Volumes/SSD/project/Chainhook/bitcoin.conf

Once that command runs, you will see <code-rich-text>zmq_url<code-rich-text> entries in your console’s stdout, displaying ZeroMQ logs from your Bitcoin node. Congrats! You’re now syncing!‍

Please note: if this is your first time syncing a node, it might take anywhere from a few hours to a few days to run and fully sync. While you’re syncing, check out some videos on our YouTube channel or make some sourdough bread.

Proper Shutdown and Restart Procedure

If you run into any trouble with syncing your node, it’s important to know how to properly shut down your bitcoind node and eject your external hard drive (if applicable), so you can start them up again. Since you will be taking your setup with you to Bitcoin++, shutting down can lead to data corruption and loss. Here’s a few steps to ensure that doesn’t happen.

Shutting Down Your bitcoind Node

To shut down your bitcoind node safely, use the following command from your terminal (open a new tab if your node is already running in your current terminal):

Assuming your <code-rich-text>bitcoind<code-rich-text> path looks like this: <code-rich-text>/Volumes/SSD/bitcoin-25.0/bin/bitcoind<code-rich-text>, you can run the <code-rich-text>bitcoin-cli<code-rich-text> command as follows:

/Volumes/SSD/bitcoin-25.0/bin/bitcoin-cli --conf=path/to/bitcoin.conf --rpcuser={{your-rpc-username}} --rpcpassword={{your-rpc-password}} stop

Ejecting the External Hard Drive

Secondly, to eject your hard drive safely:

1. On Mac, go to the Finder, then the sidebar, and select the disk you want to eject under “Devices”. Click on the eject icon next to the name.
2. On Windows, open File Explorer, select the drive from the list under “This PC” (PC > Devices and Drives), and click the “Eject” button.

Wait for a confirmation message saying it’s safe to eject the device before you unplug the drive.

Starting Your Node Back Up

To start your node back up, all you need to do is refer to the previous steps from above:

Run  <code-rich-text>path/to/bitcoind -conf=path/to/bitcoin.conf<code-rich-text>.

Next Steps

Now that your node is syncing, you’ll soon be ready to build a compact Bitcoin index. You can continue setting up your Chainhook by following our documentation. If you run into any problems, reach out to us on the #chainhook channel on the Stacks discord.