Skip to content

Commit

Permalink
docs: update chainhook guides (#384)
Browse files Browse the repository at this point in the history
### Description

@mefrem: Fixed a pathname error in docs, fixed a typo, and added some
clarifying language to other sections.

- Fixed `bitcoind` and `bitcoin.conf` pathnames
- Removed double words "predicates" 
- Clarified bitcoind node setup instructions

@ryanwaits to add changes/comments to the "Run Chainhook as a Service
using Stacks" How To guide

---------

Co-authored-by: Ryan Waits <[email protected]>
  • Loading branch information
mefrem and ryanwaits authored Aug 17, 2023
1 parent 131809e commit 2b4b8dc
Show file tree
Hide file tree
Showing 2 changed files with 166 additions and 99 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,24 @@ You can run Chainhook as a service to evaluate your `if_this / then_that` predic

### Setting up a Bitcoin Node

Bitcoind is a program that implements the Bitcoin protocol for remote procedure call (RPC) use. Chainhook can be set up to interact with the Bitcoin chainstate through bitcoind's ZeroMQ interface, its embedded networking library.
The Bitcoin Core daemon (bitcoind) is a program that implements the Bitcoin protocol for remote procedure call (RPC) use. Chainhook can be set up to interact with the Bitcoin chainstate through bitcoind's ZeroMQ interface, its embedded networking library, passing raw blockchain data to be evaluated for relevant events.

This guide is written to work with the latest Bitcoin Core software containing bitcoind, [Bitcoin Core 25.0](https://bitcoincore.org/bin/bitcoin-core-25.0/).
This guide is written to work with the latest Bitcoin Core software containing bitcoind, [Bitcoin Core 25.0](https://bitcoincore.org/bin/bitcoin-core-25.0/).

> **_NOTE:_**
>
> While bitcoind can and will start syncing a Bitcoin node, customizing this node to your use cases beyond supporting a Chainhook is out of scope for this guide. See the Bitcoin wiki for ["Running Bitcoin"](https://en.bitcoin.it/wiki/Running_Bitcoin) or bitcoin.org [Running A Full Node guide](https://bitcoin.org/en/full-node).
- Navigate to your project folder, create a new file, and rename it to `bitcoin.conf` on your local machine. Copy the configuration below to the `bitcoin.conf` file.
- Copy the path of your Bitcoin directory to the `bitcoin.conf`'s `datadir` field. See the Bitcoin wiki for the [list of default directories by operating system](https://en.bitcoin.it/wiki/Data_directory)
- Set a username of your choice for bitcoind and use it in the `rpcuser` configuration below.
- Set a password of your choice for bitcoind and use it in the `rpcpassword` configuration below.

> **_NOTE:_**
>
> Make a note of the `rpcuser`, `rpcpassword` and `rpcport` values to use them later in the chainhook configuration.
- Make note of the path of your `bitcoind` executable (located within the `bin` directory of the `bitcoin-25.0` folder you downloaded above appropriate to your operating system)
- Navigate to your project folder where your Chainhook node will reside, create a new file, and rename it to `bitcoin.conf`. Copy the configuration below to this `bitcoin.conf` file.
- Find and copy your Bitcoin data directory and paste to the `datadir` field in the `bitcoin.conf` file below. Either copy the default path (see [list of default directories by operating system](https://en.bitcoin.it/wiki/Data_directory)) or copy the custom path you set for your Bitcoin data
- Set a username of your choice for bitcoind and use it in the `rpcuser` configuration below (`devnet` is a default).
- Set a password of your choice for bitcoind and use it in the `rpcpassword` configuration below (`devnet` is a default).

```conf
# Bitcoin Core Configuration
datadir=</path/to/bitcoin/directory/> # Path to existing Bitcoin folder. New data directory will be created here otherwise
datadir=/path/to/bitcoin/directory/ # Path to Bitcoin directory
server=1
rpcuser=devnet
rpcpassword=devnet
Expand All @@ -52,18 +49,17 @@ dbcache=4096
zmqpubhashblock=tcp://0.0.0.0:18543
```

Now that you have `bitcoin.conf` file ready with the bitcoind configurations, you can run the bitcoind node.
In the command below, use the path to your `bitcoin.conf` file from your machine and run the command in the terminal.

> **_NOTE:_**
>
> The below command is a startup process that, if this is your first time syncing a node, might take a few hours to a few days to run. Alternatively, if the directory pointed to in the `datadir` field above contains bitcoin blockchain data, syncing will resume.
Now that you have the `bitcoin.conf` file ready with the bitcoind configurations, you can run the bitcoind node. The command takes the form `path/to/bitcoind -conf=path/to/bitcoin.conf`, for example:

```console
./bitcoind -conf=</path/to/bitcoin/directory/>
/Volumes/SSD/bitcoin-25.0/bin/bitcoind -conf=/Volumes/SSD/project/Chainhook/bitcoin.conf
```

Once the above command runs, you will see `zmq_url` entries in the console's stdout, displaying ZeroMQ.
Once the above command runs, you will see `zmq_url` entries in the console's stdout, displaying ZeroMQ logs of your bitcoin node.

### Configure Chainhook

Expand All @@ -88,9 +84,9 @@ Additionally, if you want to receive events from the configured Bitcoin node, su
working_dir = "cache"

# The Http Api allows you to register / deregister
# dynamically predicates.
# Disable by default.
#
# predicates dynamically.
# This is disabled by default.

# [http_api]
# http_port = 20456
# database_uri = "redis://localhost:6379/"
Expand Down Expand Up @@ -132,7 +128,7 @@ Here is a table of the relevant parameters this guide changes in our configurati

## Scan blockchain based on predicates

Now that your bitcoind and Chainhook configurations are complete, you can define the [predicates](../overview.md#if-this-predicate-design) you would like to scan against bitcoin blocks [predicates](../overview.md#if-this-predicate-design). These predicates are where the user specifies the kinds of blockchain events they want their Chainhook to trigger to the deliver a result (either a file appendation or an HTTP POST result). This section helps you with an example JSON file to scan a range of blocks in the blockchain to trigger results. To understand the supported predicates for Bitcoin, refer to [how to use chainhooks with bitcoin](how-to-use-chainhooks-with-bitcoin.md).
Now that your bitcoind and Chainhook configurations are complete, you can define the Chainhook [predicates](../overview.md#if-this-predicate-design) you would like to scan against bitcoin blocks. These predicates are where the user specifies the kinds of blockchain events that trigger Chainhook to deliver a result (either a file appendation or an HTTP POST request). This section helps you with an example JSON file to scan a range of blocks in the blockchain to trigger results. To understand the supported predicates for Bitcoin, refer to [how to use chainhooks with bitcoin](how-to-use-chainhooks-with-bitcoin.md).

The following is an example to walk you through an `if_this / then_that` predicate design that appends event payloads to the configured file destination.

Expand Down
Loading

0 comments on commit 2b4b8dc

Please sign in to comment.