Run your own indexer
Every number in this system is derivable from the blockchain. Running your own indexer is how you stop taking anyone's word for it.
- What an indexer needs from a Bitcoin node, and why it must keep a block hash per height rather than heights alone.
- Why indexing starts at the deployment height and not at block zero.
- Why no software may build a mainnet transaction without the authorisation flag and a record naming at least two approvers.
- The order that finds bugs earliest: regtest, then signet, then the golden vectors, then serving.
- What has to match between two indexers before a difference in their answers counts as a disagreement.
Why
- You stop trusting a server. Your own index answers from your own node.
- You can check us. Two indexers on the same chain must agree. If they do not, one has a bug worth finding.
- You are not affected by our outages. The protocol keeps working whether or not any particular indexer does.
- Your queries stay private. Nobody learns which artifacts you look at.
The public site makes the same case for a reader who has not opened an editor yet, on Verify it yourself, where running your own index is the step it calls the strongest position.
What it needs
Five requirements, and one of them catches almost everybody. An indexer that stores heights without the block hash at each height cannot tell a reorganised chain from the one it already read, so it carries wrong state forward and never notices.
| Requirement | Detail |
|---|---|
| A Bitcoin node | Fully validating, on the network you are indexing. Transaction index enabled if your indexer reads transactions by id. |
| Block access | The indexer reads blocks in order and needs input values, which means either a node RPC that supplies them or its own UTXO tracking. |
| Reorg detection | Block hashes stored per height, not just heights. See Reorg behavior. |
| Durable storage | Sized for artifacts, rings, carriers, and invalid events. It is small next to the chain itself. |
| A deployment record | The network and window heights it is indexing, including spec_sha256. |
The indexer does not need a wallet, does not need keys, and should never be given any.
The path from nothing to a served API
-
Get a node synced
Start on regtest, which takes minutes, then signet. Do not start on mainnet while you are still learning the moving parts.
-
Load the deployment record
Regtest and signet deployments ship in the protocol repo. Mainnet values stay unset until activation is authorised, and software must refuse to construct mainnet transactions without both the authorisation flag and a record naming at least two approvers.
-
Index from the deployment start height
There is nothing to find before the window opens, so the start height is the deployment's, not block zero. Walk blocks in order and apply the rules.
-
Prove it against the golden vectors
Before serving anything, run the vectors and compare state roots. An indexer that has not passed them is an indexer with unknown behaviour. See Golden vectors and state roots.
-
Serve the endpoints
Implement the contract in the endpoint reference. Keep
/readyhonest: it must fail during initial sync and during reorg replay. -
Point something at it
The prober on the endpoint reference page will read
/statusand/windowfrom your instance and print the raw responses.
Cross checking against another indexer
curl -s https://a.example.org/patina/status | grep -o '"indexed_height":[0-9]*'
curl -s https://b.example.org/patina/status | grep -o '"indexed_height":[0-9]*'Compare like for like. Two indexers at different heights are expected to differ. Two indexers at the same
height, on the same network, running the same spec_sha256, must produce the same state root.
If they do not, follow Report a disagreement.
Sizing and cost
PATINA state is small: a record per artifact, a row per ring, and an entry per invalid event. The expensive part is the Bitcoin node, not the index on top of it. Plan the node first and the indexer will fit alongside it.
Actual figures depend on how many artifacts exist, which is chain data and cannot be quoted here. Measure your own instance rather than trusting a number in a document.
Operating it
Everything about running one in production is in the operator guide: deploy and configure, sync and reindex, verify and monitor, back up and restore, and incident actions.