trueblocks-core: a local Unchained Index over EVM address histories, driven by the chifra CLI

What the Unchained Index actually stores

The Unchained Index is described as an index of address appearances, and it is the primary data structure TrueBlocks produces. The README's point about it is speed: it provides very quick access to transaction histories for any address, without the round trip to a node for every lookup.

That framing explains the surrounding tooling. The project describes itself as improving access to blockchain data for EVM-compatible chains, particularly Ethereum mainnet, while remaining entirely local. Nothing here requires a hosted provider, and the licence is GPL-3.0 with the documentation hosted at trueblocks.io.

The index is built by chifra init and chifra scrape, and the README gives two ways to get one. You can build the entire index from scratch, which the README says requires an EVM-compatible tracing or archive node, or you can download a snapshot of the index built from one. The second path is the practical one for evaluation, since a from-scratch build against a mainnet archive node is a serious undertaking. Both routes are described in the Indexing Addresses article linked from the README.

One design decision is worth naming because it affects cost. A binary cache is optional, and the README says it speeds up queries to the RPC by orders of magnitude. So the speedup that makes the Unchained Index attractive is partly a caching layer over a node you already run, not a substitute for one.

The chifra command surface and its sub-commands

Every tool in the system hangs off one binary, chifra. The README is explicit that chifra gives you access to all the other tools, and that help is available per sub-command through chifra <cmd> --help, with the full reference on the website.

The first check after installation is status.

chifra status

If that returns a bunch of data, the README says, the installation is working. The next step shows every tenth block between the first and the 100,000th, and the expected result is a long stream of data that you stop with Control+C.

chifra blocks 0-100000:10

The colon notation is a compact range and step selector, and it is the kind of thing that makes the tool pleasant for analysts who want to slice blocks without writing a script. The README highlights two categories of use for data scientists and analysts: extracting all logs produced by a smart contract, and viewing all ERC-20 holdings for an account.

There is also a group of tools for producing reconciled bank statements and an accounting export for any token including ETH. The word reconciled is doing real work in that sentence. It implies that the tool cross-checks what a token contract reports against what actually moved, which is the sort of thing that matters when the contract itself lies.

chifra server and chifra daemon, and the single user limit

Two HTTP surfaces exist, and the README draws a clear line between them.

serve is a simple API that mimics the command line, and the README says it is intended to be used only for single user environments.

chifra server

daemon runs the account explorer, which the README describes as a pre-beta Account Explorer that you can drive with curl, and the API is documented as providing identical tools and options as the command line.

chifra daemon

The warning about serve deserves quoting rather than paraphrasing, because it explains a design choice. The README says Chifra was built for the command line, a fact purposefully taken advantage of to ensure continued operation on small machines, and that the tool is not intended to serve multiple end users in a cloud-based server environment, followed by the sentence that this is by design and to be forewarned.

So the constraint is not a missing feature that a later release might add. A local-first tool that runs on small machines and avoids the cost of a hosted backend cannot also be a shared production API. If your requirement is a public endpoint with many concurrent users, this is the wrong project, and the README says so before you install it.

For deployment, the official Docker image lives in a separate repository, trueblocks-docker, rather than in this one.

Node configuration and the trueblocks.toml failure everyone hits

The troubleshooting section names a specific error that the README says you may get depending on your setup, when running some chifra commands.

  Warning: A request to your Ethereum node (http://localhost:8545)
  resulted in the following error [Could not connect to server].
  Specify a valid rpcProvider by editing $rootPath/trueblocks.toml.

The fix is in the message itself: edit trueblocks.toml and set a valid rpcProvider. The default assumes a node on localhost:8545, which is the standard JSON-RPC port for a local Ethereum node, and the README also points to a FAQ page and a Discord discussion for harder cases.

This is a good illustration of the project's dependency posture. TrueBlocks is entirely local, but it is not standalone. Even a reader who downloaded an index snapshot rather than building one still needs a reachable RPC endpoint for the commands that touch live chain state, and for the initial setup that the status command exercises.

The repository also carries a MIGRATIONS.md at the top level, and the README opens with a warning that anyone with an installation earlier than v6.0.0 must complete the applicable migrations before proceeding. That sits at the very top of the document for a reason: an outdated install that is not migrated will produce confusing failures rather than a clear error.

Repository shape, release cadence and the migration burden

Although the primary language is listed as Shell, the tree is a mixed Go and shell project. The top level includes src, scripts, tests, dev-tools, examples, sdk, a chifra directory, a khedra directory, and a bin directory. There is a .golangci.yml, which is the configuration for the Go linter used in the build, a .goreleaser.yml, a .clang-format, a .prettierrc and a .markdownlint.yaml, and a shell.nix for reproducible environments.

The build requires your contribution to be linted, and the README gives an explicit install command for the primary linter, golangci-lint, pinned to a version.

curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.53.3

You then verify with golangci-lint --version and run golangci-lint linters to confirm the default linter list is present. A small inconsistency is visible in the README itself, since the verification output shown says version 1.50.1 while the install command pins v1.53.3.

The recent releases are v5.9.3, v5.9.2 and v5.9.1, published in September 2025, with v5.9.1 named Lancaster - Many Cleanings. There is a VERSION file, a VERSION_BUMP.md and a release-name.txt, which is a release process that is documented inside the repository rather than only on a hosting site. The last push was on 2026-10-13, and the repository is not archived.

The upgrade cost is therefore not small, but it is bounded and signposted. Migrations are a named artefact you can read before upgrading, and the version history is visible in CHANGES.md. For a GPL-3.0 project, note that the licence obligates you to convey derivative versions under the same terms, which matters if you plan to embed the tools in a proprietary product. That is a note about the licence text, not legal advice.

Editorial conclusion

Adopt trueblocks-core if you need repeatable, local access to EVM address histories and reconciled token statements, and you can run or reach a tracing or archive node and tolerate the storage a full index needs. Do not adopt it for a multi-user cloud API, because the README states that chifra server and chifra daemon are for single user environments by design. Verify first whether your chain is covered by the index build you obtain, and if you installed before v6.0.0, work through MIGRATIONS.md before running any command.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. TrueBlocks/trueblocks-core on GitHub