/ / â–¶ Ordhook
/ --- / Ordinal indexing engine based on Chainhook.
/ / Build indexes, standards and protocols on top of Ordinals and Inscriptions (BRC20, etc).
                                                  Â
Introduction
The Ordinal Theory is a protocol aiming at attributing unique identifiers to minted satoshis (sats). With its numbering scheme, satoshis can be inscribed with arbitrary content (aka inscriptions), creating bitcoin-native digital artifacts more commonly known as NFTs. Inscriptions do not require a sidechain or separate token, which makes it attractive for new entrants to adopt, extend, and use. These inscribed sats can be transferred using Bitcoin transactions, sent to Bitcoin addresses, and held in Bitcoin UTXOs. In all respects, these transactions, addresses, and UTXOs are normal Bitcoin transactions, addresses, and UTXOs, except that to send individual sats, transactions must control the order and value of inputs and outputs per Ordinal Theory.
Now that we discussed Ordinal Theory, let's dive into what ordhook attempts to solve for developers.
The ordhook is an indexer designed to help developers build new re-org-resistant applications on top of the Ordinal Theory. This indexer will make it easy for protocol developers and users of those protocols to trace and discover the ownership of Ordinal's inscriptions, along with a wealth of information about each inscription.
The ordhook uses Chainhook SDK from the Chainhook project, which is a re-org-aware transaction indexing engine for Stacks and Bitcoin. The SDK is designed with first-class event-driven principles, so it helps developers extract transactions from blocks efficiently and keeps a consistent view of the chain state.
With ordhook, Bitcoin developers can reliably implement feature-rich protocols and business models utilizing near-real-time Ordinals inscriptions and transfers events.
Quick Start
ordhook
from source
Installing $ git clone https://github.com/hirosystems/ordhook.git
$ cd ordhook
$ cargo ordhook-install
ordhook
Getting started with Explore Ordinal activities in your terminal
Once ordhook
is installed, Ordinals activities scanning can simply be performed using the following command:
$ ordhook scan blocks --interval 767430:767753 --mainnet
Inscription 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0 revealed at block #767430 (ordinal_number 1252201400444387, inscription_number 0)
Inscription 26482871f33f1051f450f2da9af275794c0b5f1c61ebf35e4467fb42c2813403i0 revealed at block #767753 (ordinal_number 727624168684699, inscription_number 1)
In this command, an interval of blocks to scan (starting at block 767430
, ending at block 767753
) is being provided. ordhook
will display inscriptions and transfers activities occurring in the range of the specified blocks.
The activity for a given inscription can be retrieved using the following command:
$ ordhook scan inscription 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0 --mainnet
Inscription 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0 revealed at block #767430 (ordinal_number 1252201400444387, inscription_number 0)
Transferred in transaction bc4c30829a9564c0d58e6287195622b53ced54a25711d1b86be7cd3a70ef61ed at block 785396
Stream Ordinal activities to an indexer
ordhook
is designed to help developers extract ordinals activities (inscriptions and transfers) from the Bitcoin chain and streaming these activities to their indexer / web application.
In order to get started, a bitcoind
instance with access to the RPC methods getblockhash
and getblock
must be running. The RPC calls latency will directly impact the speed of the scans.
Note: the configuration of a bitcoind
instance is out of scope for this guide.
Assuming:
1)
a bitcoind
node correctly configured and
2)
a local HTTP server running on port 3000
exposing a POST /api/events
endpoint,
A configuration file Ordhook.toml
can be generated using the command:
$ ordhook config new --mainnet
✔ Generated config file Ordhook.toml
After adjusting the Ordhook.toml
settings to make them match the bitcoind
configuration, the following command can be ran:
$ ordhook scan blocks --interval 767430:767753 --post-to=http://localhost:3000/api/events --config-path=./Ordhook.toml
ordhook
will retrieve the full Ordinals activities (including the inscriptions content) and send all these informations to the http://localhost:3000/api/events
HTTP POST endpoint.
ordhook
as a service for streaming blocks
Run ordhook
can be ran as a 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
New http-post
endpoints can also be added dynamically by adding the following section in the Ordhook.toml
configuration file:
[http_api]
http_port = 20456
Running ordhook
with the command
$ ordhook service start --config-path=./Ordhook.toml
will spin up a HTTP API for managing events destinations.
A comprehensive OpenAPI specification explaining how to interact with this HTTP REST API can be found here.
Troubleshooting: Performance and System Requirements
The Ordinals Theory protocol is resource-intensive, demanding significant CPU, memory, and disk capabilities. As we continue to refine and optimize, keep in mind the following system requirements and recommendations to ensure optimal performance:
CPU: The ordhook tool efficiently utilizes multiple cores when detected at runtime, parallelizing tasks to boost performance.
Memory: A minimum of 16GB RAM is recommended.
Disk: To enhance I/O performance, SSD or NVMe storage is suggested.
OS Requirements: Ensure your system allows for a minimum of 4096 open file descriptors. Configuration may vary based on your operating system. On certain systems, this can be adjusted using the ulimit
command or the launchctl limit
command.