Run Ordhook as a service

In order to build out a more robust and secure web app, you can run Chainhook as a service to stream your events continously to a server you designate.

In this guide, you will learn how to:

1. Configure an existing Bitcoin node to work with Ordhook.
2. Generate a Ordhook predicate to target specific transactions.
3. Scan the Bitcoin blockchain for transactions that match your predicate.
4. Initiate a Ordhook service to watch for matching transactions.
5. Dynamically register your predicate with Ordhook.

Prerequisites

A fully synced Bitcoin node is required to run Ordhook as a service. Check out our guide on How to sync a Bitcoin node before proceeding.

Configure Ordhook

In this section, you will configure Ordhook to match the network configurations with the bitcoin config file. First, install the latest version of Ordhook.

Next, you will generate a Ordhook.toml file to connect Ordhook with your bitcoind node. Navigate to the directory where you want to generate the Ordhook.toml file and use the following command in your terminal:

ordhook config generate --mainnet

Several network parameters in the generated Ordhook.toml configuration file need to match those in the bitcoin.conf file created earlier in the setting up a Bitcoin node section. Please update the following parameters accordingly:

1. Update bitcoind_rpc_username with the username set for rpcuser in bitcoin.conf.
2. Update bitcoind_rpc_password with the password set for rpcpassword in bitcoin.conf.
3. Update bitcoind_rpc_url with the same host and port used for rpcport in bitcoin.conf.

Additionally, if you want to receive events from the configured Bitcoin node, substitute stacks_node_rpc_url with bitcoind_zmq_url, as follows:

[storage]
working_dir = "ordhook"

# The http API allows you to register / deregister predicates dynamically.
# This is disabled by default.
#
# [http_api]
# http_port = 20456
# database_uri = "redis://localhost:6379/"

[network]
mode = "mainnet"
bitcoind_rpc_url = "http://0.0.0.0:8332"
bitcoind_rpc_username = "devnet"
bitcoind_rpc_password = "devnet"
# Bitcoin block events can be received by Chainhook
# either through a Bitcoin node's ZeroMQ interface,
# or through the Stacks node. Zmq is being
# used by default:
bitcoind_zmq_url = "tcp://0.0.0.0:18543"
# but stacks can also be used:
# stacks_node_rpc_url = "http://0.0.0.0:20443"

[limits]
max_number_of_bitcoin_predicates = 100
max_number_of_concurrent_bitcoin_scans = 100
max_number_of_processing_threads = 16
bitcoin_concurrent_http_requests_max = 16
max_caching_memory_size_mb = 32000

# Disable the following section if the state
# must be built locally
[bootstrap]
download_url = "https://archive.hiro.so/mainnet/ordhook/mainnet-ordhook-sqlite-latest"

[logs]
ordinals_internals = true
chainhook_internals = true

Here is a table of the relevant parameters this guide changes in our configuration files.

Initiate Ordhook service

In this section, you'll learn how to run Ordhook as a service using the Ordhook SDK to post events to a server.

Use the following command to start the Ordhook service for streaming and processing new blocks appended to the Bitcoin blockchain:

ordhook service start --post-to=http://localhost:3000/api/events --config-path=./Ordhook.toml

When the Ordhook service starts, it is initiated in the background to augment the blocks from Bitcoin. Bitcoind sends ZeroMQ notifications to Ordhook to retrieve the inscriptions.

Add http-post endpoints dynamically

To enable dynamically posting endpoints to the server, you can spin up the Redis server by enabling the following lines of code in the Ordhook.toml file:

[http_api]
http_port = 20456
database_uri = "redis://localhost:6379/"

Run ordhook service

Based on the Ordhook.toml file configuration, the Ordhook service spins up an HTTP API to manage event destinations. Use the following command to start the Ordhook service:

ordhook service start --config-path=./Ordhook.toml

A comprehensive OpenAPI specification explaining how to interact with this HTTP REST API can be found here.