mirror of
https://github.com/alexgo-io/bitcoin-indexer.git
synced 2026-01-12 08:34:17 +08:00
docs: update readme (#455)
This commit is contained in:
Rafael Cárdenas
@@ -1,5 +1,5 @@
|
||||
[alias]
|
||||
ordhook-install = "install --path components/cli --locked --force"
|
||||
bitcoin-indexer-install = "install --path components/cli --locked --force"
|
||||
|
||||
[env]
|
||||
RUST_TEST_THREADS = "1"
|
||||
|
||||
48
.vscode/launch.json
vendored
48
.vscode/launch.json
vendored
@@ -4,29 +4,16 @@
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug unit tests in library 'chainhook-postgres'",
|
||||
"name": "run: ordinals service",
|
||||
"cargo": {
|
||||
"args": ["test", "--no-run", "--lib", "--package=chainhook-postgres"],
|
||||
"args": ["build", "--bin=bitcoin-indexer", "--package=cli"],
|
||||
"filter": {
|
||||
"name": "chainhook-postgres",
|
||||
"kind": "lib"
|
||||
}
|
||||
},
|
||||
"args": [],
|
||||
"cwd": "${workspaceFolder}"
|
||||
},
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "run: ordhook service",
|
||||
"cargo": {
|
||||
"args": ["build", "--bin=ordhook", "--package=cli"],
|
||||
"filter": {
|
||||
"name": "ordhook",
|
||||
"name": "bitcoin-indexer",
|
||||
"kind": "bin"
|
||||
}
|
||||
},
|
||||
"args": [
|
||||
"ordinals",
|
||||
"service",
|
||||
"start",
|
||||
"--config-path=${workspaceFolder}/.vscode/Indexer.toml",
|
||||
@@ -36,29 +23,20 @@
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug unit tests in executable 'ordhook'",
|
||||
"name": "run: runes service",
|
||||
"cargo": {
|
||||
"args": ["test", "--no-run", "--bin=ordhook", "--package=cli"],
|
||||
"args": ["build", "--bin=bitcoin-indexer", "--package=cli"],
|
||||
"filter": {
|
||||
"name": "ordhook",
|
||||
"name": "bitcoin-indexer",
|
||||
"kind": "bin"
|
||||
}
|
||||
},
|
||||
"args": [],
|
||||
"cwd": "${workspaceFolder}"
|
||||
},
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug unit tests in library 'ordhook'",
|
||||
"cargo": {
|
||||
"args": ["test", "--no-run", "--lib", "--package=ordhook"],
|
||||
"filter": {
|
||||
"name": "ordhook",
|
||||
"kind": "lib"
|
||||
}
|
||||
},
|
||||
"args": [],
|
||||
"args": [
|
||||
"runes",
|
||||
"service",
|
||||
"start",
|
||||
"--config-path=${workspaceFolder}/.vscode/Indexer.toml",
|
||||
],
|
||||
"cwd": "${workspaceFolder}"
|
||||
},
|
||||
{
|
||||
|
||||
181
README.md
181
README.md
@@ -1,128 +1,133 @@
|
||||
/ / ▶ Ordhook
|
||||
/ --- / Ordinal indexing engine based on Chainhook.
|
||||
/ / Build indexes, standards and protocols on top of Ordinals and Inscriptions (BRC20, etc).
|
||||
/ / ▶ Bitcoin Indexer
|
||||
/ --- / Index Bitcoin meta-protocols like Ordinals, BRC-20, and Runes.
|
||||
/ /
|
||||
|
||||
* [Features](#features)
|
||||
* [Quick Start](#quick-start)
|
||||
* [Installing](#installing)
|
||||
* [Running the Indexer](#running-the-indexer)
|
||||
* [Configuration](#configuration)
|
||||
* [System Requirements](#system-requirements)
|
||||
* [Postgres](#postgres)
|
||||
* [Contribute](#contribute)
|
||||
* [Community](#community)
|
||||
|
||||
[](#Introduction)
|
||||
[](#Features)
|
||||
[](#Quick-start)
|
||||
[](#Documentation)
|
||||
[](#Contribute)
|
||||
***
|
||||
|
||||
---
|
||||
# Features
|
||||
|
||||
# Introduction
|
||||
|
||||
The [Ordinal Theory](https://trustmachines.co/glossary/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](https://github.com/hirosystems/chainhook/tree/develop/components/chainhook-sdk) from the [Chainhook](https://github.com/hirosystems/chainhook/tree/develop) 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.
|
||||
**Bitcoin Indexer** is a tool that continuously reads Bitcoin blocks from a connected Bitcoin
|
||||
node in order to extract and index meta-protocol data contained within it. Once indexed, data is
|
||||
stored in a Postgres DB and can be made available to clients or users via REST APIs.
|
||||
|
||||
# Quick Start
|
||||
|
||||
## Installing `ordhook` from source
|
||||
## Installing
|
||||
|
||||
```console
|
||||
$ git clone https://github.com/hirosystems/ordhook.git
|
||||
$ cd ordhook
|
||||
$ cargo ordhook-install
|
||||
$ git clone https://github.com/hirosystems/bitcoin-indexer.git
|
||||
$ cd bitcoin-indexer
|
||||
$ cargo bitcoin-indexer-install
|
||||
```
|
||||
|
||||
## Getting started with `ordhook`
|
||||
Docker images are also available at https://hub.docker.com/r/hirosystems/bitcoin-indexer
|
||||
|
||||
### Explore Ordinal activities in your terminal
|
||||
|
||||
Once `ordhook` is installed, Ordinals activities scanning can simply be performed using the following command:
|
||||
## Running the Indexer
|
||||
|
||||
The following command will start indexing Ordinals activity and will continue to stream new blocks
|
||||
once it reaches the Bitcoin chain tip.
|
||||
```console
|
||||
$ 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)
|
||||
$ bitcoin-indexer ordinals service start --config-path <path>
|
||||
```
|
||||
|
||||
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. Add the option `--meta-protocols=brc20` if you wish to explore BRC-20 activity as well.
|
||||
|
||||
The activity for a given inscription can be retrieved using the following command:
|
||||
|
||||
A similar command exists for indexing Runes
|
||||
```console
|
||||
$ ordhook scan inscription 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0 --mainnet
|
||||
Inscription 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0 revealed at block #767430 (ordinal_number 1252201400444387, inscription_number 0)
|
||||
Transferred in transaction bc4c30829a9564c0d58e6287195622b53ced54a25711d1b86be7cd3a70ef61ed at block 785396
|
||||
$ bitcoin-indexer runes service start --config-path <path>
|
||||
```
|
||||
|
||||
---
|
||||
A fully synced Bitcoin node is required for indexing to start.
|
||||
|
||||
### Stream Ordinal activities to an indexer
|
||||
## Running an API
|
||||
|
||||
`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.
|
||||
Once the index starts advancing, you can deploy the Ordinals API or Runes API to read the same data
|
||||
via REST endpoints.
|
||||
|
||||
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:
|
||||
# Configuration
|
||||
|
||||
Indexer configurations are set via a TOML file. To generate a new config file, run this command:
|
||||
```console
|
||||
$ ordhook config new --mainnet
|
||||
✔ Generated config file Ordhook.toml
|
||||
$ bitcoin-indexer config new
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### Run `ordhook` as a service for streaming blocks
|
||||
|
||||
`ordhook` can be ran as a service for streaming and processing new blocks appended to the Bitcoin blockchain.
|
||||
|
||||
```console
|
||||
$ 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:
|
||||
|
||||
Postgres database configurations are set like this. Each index will have its own database.
|
||||
```toml
|
||||
[http_api]
|
||||
http_port = 20456
|
||||
[ordinals.db]
|
||||
database = "ordinals"
|
||||
host = "localhost"
|
||||
port = 5432
|
||||
username = "postgres"
|
||||
password = "postgres"
|
||||
```
|
||||
|
||||
Running `ordhook` with the command
|
||||
Ordinals meta-protocols like BRC-20 are also configured in this file
|
||||
```toml
|
||||
[ordinals.meta_protocols.brc20]
|
||||
enabled = true
|
||||
lru_cache_size = 10000
|
||||
|
||||
```console
|
||||
$ ordhook service start --config-path=./Ordhook.toml
|
||||
[ordinals.meta_protocols.brc20.db]
|
||||
database = "brc20"
|
||||
host = "localhost"
|
||||
port = 5432
|
||||
username = "postgres"
|
||||
password = "postgres"
|
||||
```
|
||||
|
||||
will spin up a HTTP API for managing events destinations.
|
||||
# System Requirements
|
||||
|
||||
A comprehensive OpenAPI specification explaining how to interact with this HTTP REST API can be found [here](https://github.com/hirosystems/chainhook/blob/develop/docs/chainhook-openapi.json).
|
||||
The Bitcoin Indexer 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.
|
||||
|
||||
### Troubleshooting: Performance and System Requirements
|
||||
* Memory: A minimum of 16GB RAM is recommended.
|
||||
|
||||
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:
|
||||
* Disk: To enhance I/O performance, SSD or NVMe storage is suggested.
|
||||
|
||||
CPU: The ordhook tool efficiently utilizes multiple cores when detected at runtime, parallelizing tasks to boost performance.
|
||||
* 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.
|
||||
|
||||
Memory: A minimum of 16GB RAM is recommended.
|
||||
## Postgres
|
||||
|
||||
Disk: To enhance I/O performance, SSD or NVMe storage is suggested.
|
||||
To store indexed data, a Postgres database is required per index (ordinals, runes, etc.). It is
|
||||
recommended to use Postgres 17+ for optimal performance.
|
||||
|
||||
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.
|
||||
# Contribute
|
||||
|
||||
Development of this product happens in the open on GitHub, and we are grateful
|
||||
to the community for contributing bugfixes and improvements. Read below to learn
|
||||
how you can take part in improving the product.
|
||||
|
||||
## Code of Conduct
|
||||
Please read our [Code of conduct](../../../.github/blob/main/CODE_OF_CONDUCT.md)
|
||||
since we expect project participants to adhere to it.
|
||||
|
||||
## Contributing Guide
|
||||
Read our [contributing guide](.github/CONTRIBUTING.md) to learn about our
|
||||
development process, how to propose bugfixes and improvements, and how to build
|
||||
and test your changes.
|
||||
|
||||
# Community
|
||||
|
||||
Join our community and stay connected with the latest updates and discussions:
|
||||
|
||||
- [Join our Discord community chat](https://discord.gg/ZQR6cyZC) to engage with
|
||||
other users, ask questions, and participate in discussions.
|
||||
|
||||
- [Visit hiro.so](https://www.hiro.so/) for updates and subcribing to the
|
||||
mailing list.
|
||||
|
||||
- Follow [Hiro on Twitter.](https://twitter.com/hirosystems)
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: Getting Started
|
||||
---
|
||||
|
||||
Ordhook is a developer tool designed for interacting with [Bitcoin ordinals](https://www.hiro.so/blog/what-are-bitcoin-ordinals), enabling you to retrieve ordinal activity from the Bitcoin chain. Follow the steps below to install Ordhook.
|
||||
|
||||
## Installing Ordhook
|
||||
|
||||
> **_NOTE_**
|
||||
> Before proceeding, make sure you have the Rust and Cargo (Rust's package manager) installed on your computer.
|
||||
|
||||
### Clone the Repository
|
||||
|
||||
Open your terminal and navigate to the directory where you want to clone the Ordhook repository. Then run the following command to clone the repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/hirosystems/ordhook.git
|
||||
```
|
||||
|
||||
This will download the Ordhook source code to your local machine.
|
||||
|
||||
### Navigate to the Ordhook Directory
|
||||
|
||||
Move into the newly cloned Ordhook directory by running the following command:
|
||||
|
||||
```bash
|
||||
cd ordhook
|
||||
```
|
||||
|
||||
You are now inside the Ordhook directory.
|
||||
|
||||
### Install Ordhook
|
||||
|
||||
> **_NOTE:_**
|
||||
>
|
||||
> Ordhook requires Rust to be installed on your system. If you haven't installed Rust yet, you can do so by following the instructions on the [official Rust website](https://www.rust-lang.org/tools/install).
|
||||
|
||||
Use the Rust package manager, Cargo, to install Ordhook. Run the following command:
|
||||
|
||||
```bash
|
||||
cargo ordhook-install
|
||||
```
|
||||
|
||||
This command compiles the Ordhook code and installs it on your system.
|
||||
|
||||
### Next Steps
|
||||
|
||||
With Ordhook installed, you can:
|
||||
|
||||
- Scan blocks in your terminal. See the [Scanning Ordinal Activities](./how-to-guides/how-to-scan-ordinal-activities.md) guide.
|
||||
- Stream ordinal activity to an external API. Refer to the [Streaming Ordinal Activities](./how-to-guides/how-to-stream-ordinal-activities.md) guide.
|
||||
@@ -1,155 +0,0 @@
|
||||
---
|
||||
title: Run Ordhook as a Service Using Bitcoind
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Setting Up a Bitcoin Node
|
||||
|
||||
The Bitcoin Core daemon (bitcoind) is a program that implements the Bitcoin protocol for remote procedure call (RPC) use. Ordhook 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/).
|
||||
|
||||
> **_NOTE:_**
|
||||
>
|
||||
> While bitcoind can and will start syncing a Bitcoin node, customizing this node to your use cases beyond supporting a Ordhook 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).
|
||||
|
||||
- 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 Ordhook 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 Bitcoin directory
|
||||
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
|
||||
```
|
||||
|
||||
> **_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
|
||||
/Volumes/SSD/bitcoin-25.0/bin/bitcoind -conf=/Volumes/SSD/project/Ordhook/bitcoin.conf
|
||||
```
|
||||
|
||||
Once the above command runs, you will see `zmq_url` entries in the console's stdout, displaying ZeroMQ logs of your bitcoin node.
|
||||
|
||||
### 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](../getting-started.md#installing-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:
|
||||
|
||||
```console
|
||||
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](#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:
|
||||
|
||||
```toml
|
||||
[storage]
|
||||
working_dir = "ordhook"
|
||||
|
||||
# The Http Api allows you to register / deregister
|
||||
# dynamically predicates.
|
||||
# Disable by default.
|
||||
#
|
||||
# [http_api]
|
||||
# http_port = 20456
|
||||
|
||||
[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.
|
||||
|
||||
| bitcoin.conf | Ordhook.toml |
|
||||
| --------------- | --------------------- |
|
||||
| rpcuser | bitcoind_rpc_username |
|
||||
| rpcpassword | bitcoind_rpc_password |
|
||||
| rpcport | bitcoind_rpc_url |
|
||||
| zmqpubhashblock | bitcoind_zmq_url |
|
||||
|
||||
## Initiate Ordhook Service
|
||||
|
||||
In this section, you'll learn how to run Ordhook as a service using [Ordhook SDK](https://github.com/hirosystems/ordhook/tree/develop/components/ordhook-sdk-js) 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
|
||||
|
||||
Dynamic posting endpoints can be enabled by adding the following settings in the `Ordhook.toml` file:
|
||||
|
||||
```toml
|
||||
[http_api]
|
||||
http_port = 20456
|
||||
```
|
||||
|
||||
## 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](https://github.com/hirosystems/ordhook/blob/develop/docs/ordhook-openapi.json).
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
title: Scan Ordinal Activities in Your Terminal
|
||||
---
|
||||
|
||||
Ordhook is a tool that helps you find ordinal activity on the Bitcoin chain. Think of it like a detective that can find and track this activity for you. Once it finds any activity, that data can be used to help build your own database. This guide will show you how to use Ordhook to scan this activity on the Bitcoin chain in your terminal.
|
||||
|
||||
### Explore Ordinal Activity
|
||||
|
||||
You can use the following command to scan a range of blocks on mainnet or testnet:
|
||||
|
||||
`ordhook scan blocks 767430 767753 --mainnet`
|
||||
|
||||
The above command generates a `hord.sqlite.gz` file in your directory and displays inscriptions and transfers activities occurring in the range of the specified blocks.
|
||||
|
||||
> **_NOTE_**
|
||||
> By default, Ordhook creates a folder named `ordhook` in your current directory and stores the `hord.sqlite` file there. This file is used to pull in the latest ordinal data and scan against it based on the block numbers you provide.
|
||||
|
||||
The output of the above command looks like this:
|
||||
|
||||
```
|
||||
Inscription 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0 revealed at block #767430 (inscription_number 0, ordinal_number 1252201400444387)
|
||||
Inscription 26482871f33f1051f450f2da9af275794c0b5f1c61ebf35e4467fb42c2813403i0 revealed at block #767753 (inscription_number 1, ordinal_number 727624168684699)
|
||||
```
|
||||
|
||||
You can also get activity for a given inscription by using the following command:
|
||||
|
||||
`ordhook scan inscription 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0 --mainnet`
|
||||
|
||||
The above command returns ordinal activity for that inscription and also the number of transfers in the transactions.
|
||||
|
||||
```
|
||||
Inscription 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0 revealed at block #767430 (inscription_number 0, ordinal_number 1252201400444387)
|
||||
→ Transferred in transaction 0x2c8a11858825ae2056be90c3e49938d271671ac4245b452cd88b1475cbea8971 (block #785391)
|
||||
→ Transferred in transaction 0xbc4c30829a9564c0d58e6287195622b53ced54a25711d1b86be7cd3a70ef61ed (block #785396)
|
||||
Number of transfers: 2
|
||||
```
|
||||
@@ -1,78 +0,0 @@
|
||||
---
|
||||
title: Stream Ordinal Activities to an API
|
||||
---
|
||||
|
||||
Ordhook is a tool that helps you find ordinal activity from the Bitcoin chain and build your own customized database with that data. This guide will show you how to use Ordhook to stream ordinal activity.
|
||||
|
||||
### Configure Ordhook
|
||||
|
||||
This section walks you through streaming ordinal activities. To post the ordinal activity, you'll need to configure bitcoind. Refer to [Setting up a bitcoin node](./how-to-run-ordhook-as-a-service-using-bitcoind.md#setting-up-a-bitcoin-node) to understand the steps to configure Bitcoind.
|
||||
|
||||
> **_NOTE_**
|
||||
> Ordhook is applicable to the Bitcoin chain only.
|
||||
|
||||
Once the Bitcoin node is configured, you can use the following command in your terminal to create a configuration for Ordhook:
|
||||
|
||||
`ordhook config new --mainnet`
|
||||
|
||||
You will see a success message "Created file Ordhook.toml" in your terminal.
|
||||
|
||||
The generated `Ordhook.toml` file looks like this:
|
||||
|
||||
```toml
|
||||
[storage]
|
||||
working_dir = "ordhook"
|
||||
|
||||
# The Http Api allows you to register / deregister
|
||||
# dynamically predicates.
|
||||
# Disable by default.
|
||||
#
|
||||
# [http_api]
|
||||
# http_port = 20456
|
||||
|
||||
[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
|
||||
```
|
||||
|
||||
Observe that the bitcoind configured fields will appear in the `Ordhook.toml` file. Now, ensure that these fields are configured with the right values and URLs, as shown below:
|
||||
|
||||
```toml
|
||||
bitcoind_rpc_url = "http://0.0.0.0:8332"
|
||||
bitcoind_rpc_username = "devnet"
|
||||
bitcoind_rpc_password = "devnet"
|
||||
bitcoind_zmq_url = "tcp://0.0.0.0:18543"
|
||||
```
|
||||
|
||||
### Post Ordinal Activity to an External Endpoint
|
||||
|
||||
After adjusting the `Ordhook.toml` settings to make them match the bitcoind configuration, the following command can be run to scan blocks and post events to a local server:
|
||||
|
||||
`ordhook scan blocks 767430 767753 --post-to=http://localhost:3000/api/events --config-path=./Ordhook.toml`
|
||||
|
||||
The above command uses Ordhook to stream and then post ordinal activities to `http://localhost:3000/api/events` where you can build out your own database or custom views.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,21 +0,0 @@
|
||||
---
|
||||
title: Overview
|
||||
---
|
||||
|
||||
## Ordinal Theory
|
||||
|
||||
Ordinal Theory is a protocol with a specific goal: assigning unique identifiers to every single satoshi (sat). The protocol achieves this by introducing a numbering scheme. This numbering allows for the inclusion of arbitrary content on these satoshis.
|
||||
|
||||
This content is referred to as _inscriptions_. These inscriptions essentially turn satoshis into Bitcoin-native digital artifacts, often referred to as Non-Fungible Tokens (NFTs). This means that you can associate additional information or data with individual satoshis.
|
||||
|
||||
Ordinal Theory accomplishes this without requiring the use of sidechains or creating separate tokens. This makes it an attractive option for those looking to integrate, expand, or utilize this functionality within the Bitcoin ecosystem.
|
||||
|
||||
Satoshis with inscriptions can be transferred through standard Bitcoin transactions, sent to regular Bitcoin addresses, and held in Bitcoin Unspent Transaction Outputs (UTXOs). The uniqueness of these transactions is identified while sending individual satoshis with inscriptions, and transactions must be crafted to control the order and value of inputs and outputs following the rules defined by Ordinal Theory.
|
||||
|
||||
## Ordhook
|
||||
|
||||
Ordhook is an indexer designed to assist developers in creating new applications that are resistant to blockchain re-organizations (re-orgs) and are built on top of the [Ordinal Theory](https://trustmachines.co/glossary/ordinal-theory) protocol. Its primary purpose is to simplify the process for both protocol developers and users to track and discover the ownership of Ordinal Theory's inscriptions. It also provides a wealth of information about each inscription.
|
||||
|
||||
Ordhook utilizes the Chainhook Software Development Kit (SDK) from the Chainhook project. This SDK is a transaction indexing engine that is aware of re-orgs and is designed for use with both Stacks and Bitcoin. The Chainhook SDK operates on first-class event-driven principles. This means it efficiently extracts transaction data from blocks and maintains a consistent view of the state of the blockchain. This helps ensure that the data retrieved remains accurate and up-to-date.
|
||||
|
||||
Ordhook offers a valuable tool for Bitcoin developers. They can rely on it to implement feature-rich protocols and business models that make use of near-real-time information related to ordinal inscriptions and their transfers.
|
||||
2
package-lock.json
generated
2
package-lock.json
generated
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"name": "ordhook",
|
||||
"name": "bitcoin-indexer",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {}
|
||||
|
||||
Reference in New Issue
Block a user