If you have ever tried to answer a simple question like "what is the transaction history of this address?" by talking directly to a blockchain node, you already know the problem. Nodes are excellent at validating and storing blocks. They are not built to answer questions about addresses.
This article explains why blockchain indexers exist, what Blockbook is and which networks it supports, and then walks through building a working indexer, including the problems you are likely to hit on a real mainnet sync.
1. Why You Need a Blockchain Indexer
What a node gives you
A full node such as Bitcoin Core or Dogecoin Core downloads every block, validates it, and keeps the chain on disk. Through its RPC interface you can ask things like:
- Give me the block at height 100,000.
- Give me transaction
abc...(if the transaction index is enabled). - What is the current chain tip?
- Broadcast this raw transaction.
Every one of those questions starts from a block hash, a height, or a transaction ID.
What applications actually ask
Wallets, explorers, exchanges, custody platforms and analytics tools ask questions that start from an address:
- What is this address's balance?
- Show every transaction this address has ever been part of.
- Which outputs does this address still have unspent?
- What does the history of this extended public key (xpub) look like?
- Notify me when this address receives funds.
A node cannot answer these efficiently. Bitcoin-style chains store data by transaction and block, not by address. To find an address's history, a node would have to scan the entire chain, which can mean hundreds of gigabytes of data for a single query. Address-level lookups are simply not part of the node's design.
The indexer's job
A blockchain indexer sits beside the node and does the expensive work once:
┌────────────┐ blocks via RPC ┌──────────────┐ │ Full node │ ───────────────────► │ Indexer │ │ (the │ new-block events │ (address- │ ──► fast API │ ledger) │ ───────────────────► │ indexed DB)│ └────────────┘ └──────────────┘ - It reads every block from the node.
- It builds its own database, keyed by address, transaction and block.
- It keeps that database current as new blocks arrive.
- It serves the results through a fast API.
The result is that a query that would take a node minutes or hours returns in milliseconds. The cost is extra disk, extra memory during the initial sync, and one more service to operate.
Why not build your own?
You can, and many teams start there. But a correct indexer has to handle:
- Reorganizations, where the chain tip is replaced by a different branch and your index must roll back cleanly.
- The mempool, so unconfirmed transactions show up and disappear correctly.
- UTXO tracking and spent/unspent state.
- Extended public keys for wallet-style lookups.
- Crash safety, so a restart does not corrupt the index.
Using a mature open-source indexer saves months of work, and Blockbook is one of the best-known options.
2. What Is Blockbook?
Blockbook is an open-source blockchain indexer and explorer backend written in Go, created by SatoshiLabs, the company behind the Trezor hardware wallet. It powers the backend of Trezor Suite, so it is built for wallet-grade lookups, not just casual browsing.
Blockbook:
- Connects to a full node you run (or have access to) over RPC.
- Optionally subscribes to the node's ZMQ message queue for instant new-block and new-transaction notifications.
- Stores its index in RocksDB, an embedded key-value database designed for heavy write workloads.
- Exposes a REST API, a WebSocket API and, optionally, a simple built-in block explorer web interface.
- Supports address lookups, transactions, blocks, UTXOs, xpub/descriptor queries, balance history and fiat rates.
Important: Blockbook does not replace the node. It needs one. The node is the source of truth, and Blockbook is the searchable index built on top of it.
Check the license
Review the license in the repository before using it in a product. As far as I know it is a copyleft license, which matters if you plan to modify and distribute it. Confirm the current terms on the project page rather than relying on this article.
3. Networks Blockbook Supports
Blockbook supports a long list of networks, and each one is described by a JSON file in the repository's configs/coins/ directory. The most reliable way to see what your version supports is to look at that directory:
git clone https://github.com/trezor/blockbook.git ls blockbook/configs/coins/ The supported networks fall into two families. The exact list changes between releases, so always check the directory for your checkout.
Bitcoin-type chains
These use a UTXO model and a Bitcoin-like node API. Blockbook works with them through the node's RPC interface:
| Examples | Notes |
|---|---|
| Bitcoin | The primary use case, with testnet/regtest variants |
| Litecoin | |
| Dogecoin | Used in the walkthrough below |
| Bitcoin Cash | |
| Dash, Zcash, Vertcoin, Namecoin and similar forks | Many Bitcoin-derived coins have a config file |
Ethereum-type chains
For account-based chains, Blockbook connects to an Ethereum-compatible node and indexes accounts, transactions, token transfers and internal transactions. Supported networks have included Ethereum and several EVM-compatible chains, each using their own backend node (such as Geth or an equivalent). Whether a particular EVM chain is supported depends on the release, so verify against configs/coins/.
Things to check for any network
Before committing to a network:
- Is there a config file for it in
configs/coins/? - Which node software and version does the config expect? Blockbook needs a compatible node, not just any implementation.
- Does the node need special settings? For Bitcoin-type chains, the node must have its full transaction index on (
txindex=1) and must not be pruned. - How large are the chain and the index? This decides your disk and RAM budget.
4. Building an Indexer With Blockbook
This walkthrough indexes Dogecoin mainnet against an existing, fully synced Dogecoin node. The same pattern applies to other Bitcoin-type chains: change the coin name, the ports and the credentials.
Setting up the node itself is outside the scope of this article. You need a node that is reachable from your Blockbook server and already synced.
Architecture
┌──────────────────┐ RPC (TCP 22555) ┌────────────────────────┐ │ Dogecoin node │ ◄──────────────────── │ Blockbook server │ │ (existing) │ ZMQ (TCP 28333) │ RocksDB index │ │ │ ──────────────────► │ HTTP API on :9130 │ └──────────────────┘ └────────────────────────┘ Throughout this guide, NODE_IP, RPC_USER and RPC_PASS are placeholders for your node's address and credentials. Never paste real credentials into chats, tickets or version control.
Step 1: Check the node is ready
Blockbook has hard requirements on the node. Verify them before you install anything, because it is much cheaper to find a problem now than after a 20-hour sync.
Reachability:
nc -zv NODE_IP 22555 # RPC nc -zv NODE_IP 28333 # ZMQ (your node's port may differ) Health and settings:
curl -s --user RPC_USER:RPC_PASS \ --data-binary '{"jsonrpc":"1.0","id":"t","method":"getblockchaininfo","params":[]}' \ -H 'content-type: text/plain;' http://NODE_IP:22555/ Look for:
| Field | Required |
|---|---|
"chain" | "main" for mainnet |
"initialblockdownload" | false (fully synced) |
"pruned" | false |
blocks vs headers | equal, or almost |
Transaction index: fetch any old transaction with getrawtransaction. If you get an error mentioning -txindex, the node's owner has to enable it.
Common failures: Connection refused or a timeout means a wrong address or a firewall; 403 Forbidden means your server's IP is not in the node's rpcallowip; 401 Unauthorized means wrong credentials.
Step 2: Size the server
These figures come from a real Dogecoin mainnet run and should be treated as a starting point. Chain sizes change over time, so check current numbers before provisioning.
| Resource | Recommendation |
|---|---|
| CPU | 4 cores minimum, 8 comfortable |
| RAM | 32 GB for the initial sync (see the memory section below) |
| Disk | 500 GB or more of fast storage, plus room to grow |
| Network | Low-latency link to the node, ideally the same LAN |
Fast disks matter: the initial sync is write-heavy.
Step 3: Prepare the machine
On Ubuntu 24.04:
sudo apt update sudo apt install -y build-essential git curl wget pkg-config libssl-dev \ libsnappy-dev zlib1g-dev libbz2-dev liblz4-dev libzstd-dev tmux # Runtime libraries the compiled binary needs on the host sudo apt install -y libzmq5 libsnappy1v5 libgflags2.2 zlib1g libbz2-1.0 liblz4-1 libzstd1 The second line matters. Blockbook is compiled inside a Docker container, so the finished binary links against libraries your host may not have. Without libzmq5, it fails with error while loading shared libraries: libzmq.so.5.
Install Go (check go.dev/dl for the current version, and use sudo for the extraction because /usr/local is root-owned):
cd ~ wget https://go.dev/dl/go1.27.3.linux-amd64.tar.gz sudo rm -rf /usr/local/go sudo tar -C /usr/local -xzf go1.27.3.linux-amd64.tar.gz echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc source ~/.bashrc go version Install Docker, which the build uses, and let your user run it:
curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker docker version Step 4: Get Blockbook and generate the configuration
cd ~ git clone https://github.com/trezor/blockbook.git cd blockbook ls configs/coins/dogecoin.json go run build/templates/generate.go dogecoin Note the coin file is named after the full coin name (dogecoin.json), not an abbreviation. The generate step writes build/pkg-defs/blockbook/blockchaincfg.json.
Open it and point it at your node. The generated file defaults to 127.0.0.1, which is only correct when the node runs on the same machine:
{ "coin_name": "Dogecoin", "coin_shortcut": "DOGE", "rpc_url": "http://NODE_IP:22555", "rpc_user": "RPC_USER", "rpc_pass": "RPC_PASS", "message_queue_binding": "tcp://NODE_IP:28333" } (The real file contains more keys. Only change the ones above.) Validate it and lock it down, since it holds the RPC password:
python3 -m json.tool build/pkg-defs/blockbook/blockchaincfg.json > /dev/null && echo OK chmod 600 build/pkg-defs/blockbook/blockchaincfg.json Step 5: Build
The build runs in Docker and compiles RocksDB from source. Expect 10 to 25 minutes the first time.
ldd ./build/blockbook | grep "not found" No output means all libraries are present.
Step 6: Run it in the foreground first
A short foreground run lets you see problems directly:
./build/blockbook -blockchaincfg=build/pkg-defs/blockbook/blockchaincfg.json \ -datadir=./data-dogecoin-mainnet -sync -public=0.0.0.0:9130 -certfile= -explorer= In another terminal:
curl -s http://localhost:9130/api/ | python3 -m json.tool You should see "coin": "Dogecoin", a backend chain of main, and a bestHeight that rises. Stop it with Ctrl+C and confirm nothing is left running (pgrep -a blockbook). Two copies on the same data directory will conflict.
Step 7: Run it as a service, with memory limits
On a real mainnet sync, memory is the part that bites. In one run on a 16 GB machine, Blockbook grew to about 15 GB while processing the busier part of the chain, and the Linux out-of-memory killer terminated it. That left the database marked as inconsistent, and Blockbook refused to open it afterwards. The only recovery was to wipe the index and start again from block 0, after roughly 18 hours of work.
So the unit file below does three things: it limits memory in a way that slows the process instead of killing it, it reduces parallelism, and it stops the service from restart-looping on a fatal error.
sudo tee /etc/systemd/system/blockbook.service > /dev/null << EOF [Unit] Description=Blockbook Dogecoin Indexer (mainnet) After=network-online.target Wants=network-online.target StartLimitIntervalSec=600 StartLimitBurst=5 [Service] Type=simple User=$USER WorkingDirectory=$HOME/blockbook ExecStart=$HOME/blockbook/build/blockbook -blockchaincfg=$HOME/blockbook/build/pkg-defs/blockbook/blockchaincfg.json -datadir=$HOME/blockbook/data-dogecoin-mainnet -sync -public=0.0.0.0:9130 -certfile= -explorer= -workers=4 -chunk=50 Restart=on-failure RestartSec=10 RestartPreventExitStatus=255 TimeoutStopSec=120 [Install] WantedBy=multi-user.target EOF sudo mkdir -p /etc/systemd/system/blockbook.service.d sudo tee /etc/systemd/system/blockbook.service.d/memory.conf > /dev/null << 'EOF' [Service] Environment=GOMEMLIMIT=12GiB Environment=MALLOC_ARENA_MAX=2 MemoryHigh=18G MemoryMax=26G MemorySwapMax=16G EOF sudo systemctl daemon-reload sudo systemctl enable --now blockbook What each setting does:
| Setting | Purpose |
|---|---|
-workers=4 | Halves the default of 8 parallel block-processing workers, reducing memory at some cost in speed |
-chunk=50 | Halves the default bulk chunk size of 100 blocks, so less is held in memory at once |
GOMEMLIMIT | A soft target for the Go heap. It makes the garbage collector work harder near the limit |
MALLOC_ARENA_MAX=2 | Limits glibc malloc arenas, which can reduce fragmentation from the C libraries RocksDB uses |
MemoryHigh | A cgroup soft limit. Above it, the kernel throttles the process and reclaims memory instead of killing it |
MemoryMax | A hard limit that kills the process. Keep it well above MemoryHigh as a last-resort backstop |
RestartPreventExitStatus=255 | A fatal exit (such as an inconsistent database) is not retried forever |
I cannot promise these exact numbers keep your sync under any specific memory figure, because the cause of the growth depends on the chain and the version. They are reasonable settings, and the memory log below shows whether they work for you. If the sync runs too slowly, raise -chunk back toward 100 first. If memory still climbs, add -notxcache and lower -workers further, accepting a slower sync.
A cautionary rule: a hard memory kill during the bulk sync can corrupt the index, so avoid anything that kills the process. That includes the OOM killer, kill -9, and a VM reboot or backup that stops the machine. Always stop it with sudo systemctl stop blockbook.
Step 8: Monitor the initial sync
The initial sync processes the entire chain, so expect many hours to several days. It starts fast, because early blocks are nearly empty, and slows as blocks fill with more transactions.
Progress:
curl -s http://localhost:9130/api/ | python3 -m json.tool | Field | Meaning |
|---|---|
blockbook.bestHeight | Blocks indexed so far |
backend.blocks | The node's height (the target) |
blockbook.initialSync | true during the bulk phase |
blockbook.inSync | true when fully caught up |
blockbook.dbSize | Index size in bytes |
A small script gives a rate and an ETA, and handles the API being briefly down:
cat > ~/bbprog.sh << 'EOF' #!/bin/bash get() { curl -s --max-time 5 localhost:9130/api/ | python3 -c 'import sys,json;d=json.load(sys.stdin);print(d["blockbook"]["bestHeight"],d["backend"]["blocks"])' 2>/dev/null; } read h1 n < <(get); [ -z "$n" ] && { echo "Blockbook API not responding. Check: systemctl status blockbook"; exit 1; } sleep 60 read h2 n < <(get); [ -z "$n" ] && { echo "API stopped responding"; exit 1; } rate=$(( (h2-h1)/60 )) echo "height $h2 / $n ($(( h2*100/n ))%) rate ${rate} blk/s" [ $rate -gt 0 ] && echo "ETA ~ $(( (n-h2)/rate/3600 )) h at current rate" EOF chmod +x ~/bbprog.sh Treat the ETA as optimistic. Percent-by-height is misleading, because the later blocks hold far more work than the early ones.
Logs. Blockbook uses glog, which writes log files to /tmp rather than the systemd journal, so journalctl -u blockbook looks nearly empty. Read the files instead:
ls -lt /tmp/blockbook.*INFO* | head -3 tail -f /tmp/blockbook.INFO ls /tmp | grep -i blockbook # an ERROR file means errors were logged For journal output, add -logtostderr to the ExecStart line; for persistent files, add -log_dir= pointing at a directory you own.
Disk:
df -h / du -sh ~/blockbook/data-dogecoin-mainnet Grow the disk before it passes about 80% full. A disk that fills mid-sync can corrupt the index.
When it is finished: inSync becomes true and bestHeight matches backend.blocks. Only now does the ZMQ subscription start doing real work, so check the log for message-queue warnings. If the node's ZMQ port does not publish the topics Blockbook expects, it still works through RPC polling, but new blocks appear with a short delay. Ask whoever runs the node which ports publish the block and transaction topics.
Step 9: Query the index
# Status (keep the trailing slash, or add -L to follow the redirect) curl http://localhost:9130/api/ # A block by height or hash curl "http://localhost:9130/api/v2/block/100000" # An address and its transactions curl "http://localhost:9130/api/v2/address/ADDRESS?details=txs" # A transaction curl "http://localhost:9130/api/v2/tx/TXID" # Unspent outputs for an address curl "http://localhost:9130/api/v2/utxo/ADDRESS" This is the payoff. An address history lookup that a bare node could not answer returns immediately, as JSON, ready for an application.
Step 10: Secure and maintain it
Restrict access. -public=0.0.0.0:9130 listens on every interface. Limit who can reach it:
sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow from YOUR_ADMIN_SUBNET to any port 22 proto tcp sudo ufw allow from CLIENT_SUBNET to any port 9130 proto tcp sudo ufw enable Allow SSH before enabling the firewall, or you can lock yourself out. Also remember that RPC credentials and ZMQ traffic between your server and the node travel unencrypted. Keep both on a trusted network, or tunnel the link.
Routine care:
| Task | How |
|---|---|
| Health | Confirm inSync is true and the height keeps rising |
| Disk | Watch df -h / weekly, since the index grows |
| Updates | Check the Blockbook and node release pages, then git pull, make build and restart |
| Backups | Keep blockchaincfg.json and the unit files. The index can be rebuilt from the node, at the cost of the full sync time |
| Node changes | If the node's address, ports or credentials change, update blockchaincfg.json and restart |
| Load | If the node is shared, tell its owner the initial sync makes heavy RPC requests for hours or days |
5. Lessons From a Real Mainnet Sync
A few things that are easy to miss until they cost you a day:
- Verify the node first. Pruned nodes and nodes without
txindexcannot work with Blockbook, and you only discover it after a long wait if you skip the checks. - Install the runtime libraries. A binary built in Docker still needs
libzmq5and friends on the host. - Plan memory for the heavy part of the chain. Early progress looks cheap, and the later blocks cost far more in both time and RAM.
- A killed bulk sync is not resumable. An interrupted initial import leaves the database flagged inconsistent, and the supported recovery is a full resync. The
-repairoption fixes physical RocksDB corruption, not an interrupted bulk import. - Do not let a service restart-loop on a fatal error. Use
Restart=on-failurewithRestartPreventExitStatusand a start limit, or you can end up with hundreds of pointless restarts. - The logs are in
/tmp. An empty journal does not mean nothing is happening. - Disk can be smaller than you think. Check the actual filesystem size, not the size of the virtual disk.
6. When Blockbook Is (and Isn't) the Right Choice
A good fit when:
- You need wallet-grade address, UTXO and xpub lookups on a supported chain.
- You want to self-host rather than depend on a third-party API.
- You are comfortable operating a node and a database service.
Consider alternatives when:
- Your chain or network is not in
configs/coins/. - You need custom, contract-level event indexing with your own schema, which general-purpose indexing frameworks handle better.
- You cannot dedicate the disk, memory and operational effort a full mainnet index needs.
Conclusion
Nodes store blockchains, and indexers make them usable. Blockbook gives you a proven, wallet-grade indexer for a wide range of networks, with a clean API on top of a fast RocksDB store.
The setup itself is straightforward: verify the node, build the binary, point the configuration at the node, and run it as a service. The real work is operational. Budget enough memory for the heavy blocks, avoid anything that kills the process during the bulk sync, watch your disk, and keep the node's owner informed. Do those things and you end up with a self-hosted address index that answers in milliseconds the questions a bare node cannot answer at all.
