• Stars
    star
    179
  • Rank 213,983 (Top 5 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created over 4 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Build indexers, standards and protocols on top of Ordinals and Inscriptions (BRC20, etc).
   /     /   â–¶ Ordhook
  / --- /      Ordinal indexing engine based on Chainhook.
 /     /       Build indexes, standards and protocols on top of Ordinals and Inscriptions (BRC20, etc).

                                   Introduction     Features     Getting started     Documentation     Contribute


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

Installing ordhook from source

$ git clone https://github.com/hirosystems/ordhook.git
$ cd ordhook
$ cargo ordhook-install

Getting started with ordhook

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.


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.

$ 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.

More Repositories

1

stacks.js

JavaScript libraries for identity, auth, storage and transactions on the Stacks blockchain.
TypeScript
950
star
2

clarinet

Write, test and deploy high-quality smart contracts to the Stacks blockchain and Bitcoin.
Rust
301
star
3

wallet

The most popular and trusted wallet for apps built on Bitcoin
TypeScript
248
star
4

ordinals-api

Bitcoin Ordinals API
TypeScript
199
star
5

desktop-wallet

Stacks Wallet—Send and receive STX tokens on the Stacks Blockchain.
TypeScript
174
star
6

stacks-blockchain-api

API for the Stacks blockchain
TypeScript
174
star
7

chainhook

Extract transactions from Stacks and Bitcoin and build event driven re-org resistant indexers and databases.
Rust
143
star
8

explorer

Explore transactions and accounts on the Stacks blockchain. Clone any contract and experiment in your browser with the Explorer sandbox.
TypeScript
136
star
9

connect

A library for building excellent user experiences with Stacks.
SCSS
76
star
10

todos

A simple todos app built with Stacks
JavaScript
70
star
11

stacks-subnets

Stacks Subnets: a layer-2 scaling solution for Stacks, intended for high-throughput, low-latency workloads
Rust
51
star
12

btc-us-website

Svelte
50
star
13

ui

The Blockstack design system implemented with react, styled-components, and styled-system.
TypeScript
34
star
14

docs

Hiro developer documentation website
MDX
34
star
15

ordinals-explorer

Explore Ordinals inscriptions, using the Hiro Ordinals API powered by Chainhooks.
TypeScript
32
star
16

heystack

TypeScript
17
star
17

stacks.js-starters

Quick-start frontend projects using Stacks.js
JavaScript
15
star
18

lockstacks

TypeScript
13
star
19

clarity-notebook

A set of Jupyter notebooks for getting started with Clarity.
Jupyter Notebook
12
star
20

stacks-pyth-bridge

Retrieve trading pairs (BTC-USD, STX-USD, etc) from Clarity smart contracts.
Clarity
12
star
21

clarity-examples

Shell
9
star
22

rx

Reactive Extensions client for the Stacks Blockchain
TypeScript
8
star
23

token-metadata-api

Stacks Token Metadata API
TypeScript
8
star
24

runehook

Bitcoin Runes indexer and Runes API
Rust
8
star
25

stacks-e2e-testing

TypeScript
7
star
26

stacks-encoding-native-js

Encoding & decoding functions for the Stacks blockchain exposed as a fast native Node.js addon
Rust
6
star
27

MIT-Bitcoin-Expo-2022-Hiro-Hackathon-Resources

Some resources and educational materials to get hackers started at the MIT Bitcoin Expo 2022
5
star
28

stacks-scout

TypeScript
5
star
29

orchestra-archive

Development Studio designed for the Stacks blockchain. Bleeding edge prototype.
Rust
5
star
30

clarity-lsp

Rust
5
star
31

nft-nyc-exclusive-app

Exclusive Bitcoin NFT minting app for NFT.NYC
TypeScript
5
star
32

community-meeting

Monthly developer calls between the Hiro product teams and the developers building on Stacks
4
star
33

clarity-starter

Clarity
4
star
34

bitcoin-docker

Dockerize bitcoind
Shell
4
star
35

stacks-regtest-env

Easily run a Stacks node in Kypton mode with a Bitcoind regtest instance
Shell
4
star
36

multisig-stx-btc

A webscript for generating, signing, decoding multisig STX operations in the STX-over-BTC wire format
JavaScript
4
star
37

gaia-docker

Shell
3
star
38

charts

Hiro Systems Helm Charts
Smarty
3
star
39

clarity-factory

TypeScript
3
star
40

debug_types

Rust
3
star
41

api-toolkit

API toolkit
TypeScript
3
star
42

stacks-devnet-api

The Stacks Devnet API runs a server that can be used to deploy, delete, manage, and make requests to Stacks Devnets run on Kubernetes.
Rust
3
star
43

lunar-hirover

Rust
3
star
44

clarity-playground

Run Clarity code in the browser Clarinet
JavaScript
3
star
45

rfc-clarity-lang-converter

2
star
46

stacks-repl

JavaScript
2
star
47

clarity.tmbundle

A repository with Clarity syntax-highlighting grammar files
2
star
48

eslint-config

A set of re-usable ESLint configuration for Blockstack PBC projects
JavaScript
2
star
49

stacks-event-replay

Python
2
star
50

stacks-adoption-report

This project is used to generate a list of Stacks-related projects
JavaScript
2
star
51

stacks-billboard

TypeScript
2
star
52

vitest-environment-clarinet

JavaScript
2
star
53

gh-actions-example

Dockerfile
1
star
54

prettier-config

@stacks Prettier config
JavaScript
1
star
55

hiro-kit.clar

Hiro Kit: collection of utility functions for Clarity contracts
Clarity
1
star
56

clear-waters

A Clarity Learning Game
Clarity
1
star
57

clar2wasm

Compile Clarity to WebAssembly
1
star
58

rfc-web3-oauth

1
star
59

examples

A collection of example apps showcasing /-/iro products
TypeScript
1
star
60

hiro-hacks-template

Starter template for Hiro Hacks
TypeScript
1
star
61

stacks-rpc-proxy

TypeScript
1
star
62

app.co-api

API Server for app.co
JavaScript
1
star
63

subnet-demo-app

The project demonstrates some of the capabilities of subnets through a simple NFT marketplace where minting, listing and offers happen on L2.
TypeScript
1
star