Blockbook: the index behind Trezor Suite

An index, not a node

Blockbook is a back-end service for Trezor Suite, and the feature list describes exactly what it is for. It maintains an index of addresses and address balances of the connected block chain. It provides fast index search. It acts as a simple blockchain explorer. It exposes websocket, API and legacy Bitcore Insight compatible REST interfaces. It supports multiple coins of the Bitcoin and Ethereum type with easy extensibility to other coins. And it ships scripts for easy creation of debian packages for the backend and for blockbook itself.

The distinction that matters is between a node and an index. A Bitcoin node validates the chain and holds the full transaction history. Blockbook does not replace it. Blockbook connects to a node, follows the chain, and builds its own structures so that a question like what is the balance of this address can be answered from a local index rather than by scanning the chain. That is the whole reason the hardware wallet does not have to run a node itself, and the reason a wallet UI can show a balance instantly.

The interface story is deliberate. The websocket interface is for a live connection, the API is the modern REST surface, and the Bitcore Insight compatible REST interface is there for existing tooling that already speaks that older dialect. Serving all three is the kind of pragmatism you only see in a service that has to keep old clients working.

The coin support is the other thing the feature list is selling. Blockbook currently supports over 30 coins, with the Trezor team having implemented Bitcoin, Bitcoin Cash, Zcash, Dash, Litecoin, Bitcoin Gold, Ethereum, Ethereum Classic, Dogecoin, Namecoin, Vertcoin, DigiByte and Liquid, and the rest implemented by the community. Testnets are supported for some coins, for example Bitcoin Testnet, Bitcoin Cash Testnet, ZCash Testnet and the Ethereum testnets Sepolia and Hoodi.

The primary language is Go, and the repository is a substantial one: bchain for the coin implementations, db for storage, server for the HTTP and websocket layer, api, common, configs, contrib for the packaging scripts, fiat for exchange rate data, fourbyte for function signature lookup, and a static directory for the web front end.

The cost of an initial Bitcoin mainnet sync

The README is specific about resources, and this is the number that decides whether the project fits your machine.

Memory and disk requirements for initial synchronization of Bitcoin mainnet are around 32 GB RAM and over 180 GB of disk space. After initial synchronization, a fully synchronized instance uses about 10 GB RAM. Other coins should have lower requirements depending on the size of their block chain, and fast SSD disks are highly recommended.

So the pattern is a spike at sync time and a much smaller steady state afterwards. That is a reasonable shape for a server, and it is also the shape that trips people up on a laptop or a small VPS, where 32 GB of RAM during the sync is a real constraint and 180 GB of disk is a real commitment.

The officially supported platform is Debian Linux on AMD64 architecture. The README does not present that as a preference, and the Ubuntu section later in the document is framed as an issue where people add their experience, which tells you how firm the boundary is in practice.

Three documents carry the rest of the operational detail, and they are all in the repository. The user installation guide is a wiki page on running a local instance of the Trezor Wallet backend, the developer build guide is in docs/build.md, and the contribution guide is CONTRIBUTING.md.

The build itself is containerised, which is worth knowing if you plan to modify it. The Makefile drives a Docker build with a pinned Docker version, 29.4.3, and a recorded SHA256 for it, and a base image derived from the host distribution and version. The build target runs a container that mounts the current directory at /src and the build directory at /out, and passes through the packaging identity and a set of BB_ prefixed environment variables, with the prefix list itself held in a file under build/ that is shared with the CI action and the build templates.

That last detail is a sign of how the project is organised. A single source of truth for which build variables are forwarded, used by the local Makefile, the GitHub action and the code generator, is the kind of care that shows up when the same build runs in three places.

RocksDB storage and the two failure modes to expect

Blockbook stores its data in the key-value store RocksDB, and the database format is described in docs/rocksdb.md. The Go module shows how that binding is done, through linxGnu/grocksdb, and the Makefile offers a JEMALLOC variable alongside a TCMALLOC one and a PORTABLE flag, so the allocator and portability are build-time choices rather than fixed.

Two failure modes are documented in enough detail to be useful, and both come from the same place.

The first is running out of memory during the initial synchronization. The README gives two ways to reduce the footprint. Disable the RocksDB cache with the parameter `-dbcache=0`, since the default cache size is 500MB. And run blockbook with `-workers=1`, which disables bulk import mode, the mode that caches a lot of data in memory rather than in the RocksDB cache. The trade is stated directly: it will run about twice as slowly, but especially for smaller blockchains it is no problem at all. The README asks people to add their experience to issue 43.

The second failure is the one that will cost you the most time if you hit it unprepared, because the error message does not explain itself. The error `internalState: database is in inconsistent state and cannot be used` appears when Blockbook was killed during the initial import, most commonly by the OOM killer. By default Blockbook performs the initial import in bulk import mode, which for performance reasons does not store all data immediately to the database, and if the process is killed during that phase the database is left in an inconsistent state.

The recovery is to reduce the memory footprint as described above, delete the database files and run the import again. The README points at issue 89 and issue 147 for more detail.

The reason this happens at all is a design decision, not a bug. Bulk import mode trades durability for speed during the initial sync, which is the right call when you have a fast machine and 32 GB of RAM, and the wrong call when you do not. The `-workers=1` flag is the escape hatch.

Adding a coin, and the parser contract

The most interesting section in the README for anyone extending the project is about parse errors, because it reveals the architecture.

If a coin implementation reports parse errors when importing a blockchain, the cause is usually that the coin's block and transaction data is not compatible with the default parser, BitcoinParser, and specifically its ParseBlock and ParseTx methods. The fix is to implement the coin in a similar way to how the Zcash implementation does it, and the principle is stated plainly: do not parse the block and transaction data in Blockbook, but instead get parsed transactions as json from the backend.

That is a clean separation. Blockbook does the indexing and the serving; the coin-specific parsing lives in the coin's own backend, which returns already parsed JSON, and Blockbook's generic machinery takes it from there.

The list of all implemented coins is in the registry of ports, docs/ports.md, and the coin configuration files live in the configs directory, one JSON per coin, since the Makefile derives its target list from the file names in configs/coins. The build tooling is aware of this structure too, with a helper that maps build variables to a coin-specific alias and a config-absent coin exemption, and a standalone BB_STAGING control variable for staging builds.

The API itself is described in docs/api.md, and there is an openapi.yaml at the repository root, so the REST surface is documented in machine-readable form as well as in prose. The environment variables that affect behaviour are listed in docs/env.md, and a TypeScript type definition file, blockbook-api.ts, sits alongside the Go code, with the typescriptify-golang-structs dependency in the module list to generate it.

The Prometheus client and the OpenMetrics style model packages are in the dependency list, so metrics are a first-class output rather than an afterthought, and the WebSocket library is gorilla/websocket, the same one used by the Bitcore Insight ecosystem it is compatible with.

The primary language is Go with a module path of github.com/trezor/blockbook and a Go version of 1.25.0 required, and the module also pulls in go-ethereum and a set of decred packages, which shows that the Ethereum type support and the altcoin bases are real code paths rather than aspirations.

The WebSocket origin check you have to turn on yourself

The security note at the end of the README is short and it matters more than a paragraph usually would.

WebSocket origin checks are not enforced by default. If you expose Blockbook without a proxy that restricts origins, it is your responsibility to configure the origin allowlist, or equivalent controls. The details are in docs/env.md.

The reasoning is easy to reconstruct. Blockbook is designed to be a local service, typically on the same machine or behind a reverse proxy, and the upstream project assumes that deployment. The websocket interface is a live push channel, and a browser page on any origin can open a websocket to a local service if the service accepts the connection. On a developer laptop that is a minor exposure. On a server with a public address, it is a real one, because the address and balance index is a map of who holds what, and a browser on a page an attacker controls can read it.

The practical guidance that follows from this is short. If you run Blockbook on a machine that is reachable from anywhere, put a proxy in front of it that restricts origins, and configure the allowlist in the environment configuration. The README treats the proxy as the normal arrangement and the allowlist as the belt to that pair.

It is also a reminder about the class of tool this is. Blockbook holds a complete index of addresses and balances for a chain. That is exactly the data an exchange would want, and exactly the data that should not be casually exposed. The licence reinforces the point from a different angle. The project is AGPL-3.0, with a COPYING file at the repository root, which for a service that talks to your node and holds chain data is a deliberate choice about what happens if you modify it and run it as a service for others.

Editorial conclusion

Adopt Blockbook if you are running Trezor Suite against your own node, or building a wallet or explorer that needs a fast address and balance index without a full node. Do not adopt it as a general blockchain node, since it is an index derived from a node you already run, and skip it if you cannot give it the disk and memory a Bitcoin mainnet index needs. Verify first that your platform matches the officially supported Debian on AMD64, that your machine has the disk for the chain you intend to index, and that the WebSocket origin allowlist is configured before you expose it.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. trezor/blockbook on GitHub