Please complete any applicable Migrations which contains important information.

• Introduction
• Quick Install
• Introducing chifra
• Using chifra
• Building the Index of Appearances
• Contributing
• List of Contributors
• Contact

TrueBlocks is a collection of libraries, tools, and applications that improve access to the Ethereum data while remaining fully local. The interface is similar to the Ethereum RPC, but offers a number of improvements:

1. TrueBlocks allows you to scrape the chain to build an index of address appearances. This index enables lightning-fast access to transactional histories for a given address (something not available from the node itself),

2. TrueBlocks also provides for a local binary cache of data extracted from the node. This speeds up subsequent queries for the same data by an order of magintude or more. This enables a much better user experience for distributed applications written directly against the node such as the TrueBlocks Explorer,

3. TrueBlocks enhances the Ethereum RPC interfaces. For example, you may query blocks and transactions by date, by block range, by hashes or any combination. Furthermore, two additional endpoints are provided for extracting (export) and listing (list) historical transactions per address.

TrueBlocks runs on Linux and Mac. There is no official Windows support. Some users have had success using WSL─you're on your own!

These instructions assume you can navigate directories with the command line and edit configuration files. If you need help with a step, see the installation's troubleshooting section.

0. Install dependencies
   • ☑ Install the latest version of Go.
   • ☑ Install the other dependencies with your command line: build-essential git cmake python python-dev libcurl3-dev clang-format jq.

Alternatively, for nix users, you can drop into an isolated environment with necessary dependencies with nix-shell.

1. Compile from the codebase

   git clone -b develop https://github.com/trueblocks/trueblocks-core
   cd trueblocks-core
   mkdir build && cd build
   cmake ../src
   make

   (You may use make -j <ncores> to parallelize the build. represents the number of cores to devote to the make job)

2. Add trueblocks-core/bin to your shell PATH.

3. Find your TrueBlocks configuration directory. It should be in one of these places:

   • On linux at ~/.local/share/trueblocks
   • On mac at ~/Library/Application Support/TrueBlocks
   • If you've configured it, wherever the location of $XDG_CONFIG_HOME is

4. In the configuration directory, edit trueblocks.toml to add your RPC and API keys. It should look something like this:

[settings]
rpcProvider = "<url-to-rpc-endpoint>"

5. Test a command!

chifra blocks 12345

6. To make deep data queries, get the index
7. To explore the data visually, install the explorer application.

A Dockerfile is included in this repo as an example for creating a Docker image.

1. Build a docker image (example tagged with latest)

docker build . --tag=trueblocks-core:latest

2. Run a docker container (Examples:)

# Running a simple chifra command
docker run trueblocks-core:latest chifra status

# Mounting separate config, cache, and index folders and running chifra init
docker run \
  -v ./trueblocks:/root/.local/share/trueblocks \
  -v ./cache:/root/.local/share/trueblocks/cache \
  -v ./unchained:/root/.local/share/trueblocks/unchained \
  trueblocks-core:latest chifra init

# Mounting those same folders and starting the chifra serve
docker run \
  -v ./trueblocks:/root/.local/share/trueblocks \
  -v ./cache:/root/.local/share/trueblocks/cache \
  -v ./unchained:/root/.local/share/trueblocks/unchained \
  trueblocks-core:latest chifra serve --port 0.0.0.0:8080

Similar to git, TrueBlocks has an overarching command called chifra that gives you access to all of the other subcommands.

Type:

chifra

You will see a long list of commands.

You can get more help on any command with chifra <cmd> --help.

Let's look at the first subcommand, called status.

chifra status --terse

If you get a bunch of JSON data, congratulations, your installation is working. You may skip ahead to the 'Using TrueBlocks' section below.

Depending on your setup, you may get the following error message when you run 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 $CONFIG/trueblocks.toml.

If you get this error, edit the configuration file mentioned. The file is well documented, so refer to that file for further information.

When the chifra status command returns a valid response, you may move to the next section. If you continue to have trouble, join our discord discussion.

If you've gotten this far, you're ready to use TrueBlocks. Run this command which shows every 10th block between the first and the 100,000th.

chifra blocks 0-100000:10

Hit Control+C to stop the processing.

The primary data structure produced by TrueBlocks is an index of address appearances. This index provides very quick access to transaction histories for a given address.

You may either build the entire index from scratch (requires a tracing, archive node), or you may download part of the index and build it from there on.

This process is described in this article Indexing Addresses.

We love contributors. Please see information about our work flow before proceeding.

1. Fork this repository into your own repo.
2. Create a branch: git checkout -b <branch_name>.
3. Make changes to your local branch and commit them to your forked repo: git commit -m '<commit_message>'
4. Push back to the original branch: git push origin TrueBlocks/trueblocks-core
5. Create the pull request.

Thanks to the following people who have contributed to this project:

• @tjayrush
• @dszlachta
• @MattDodsonEnglish
• @wildmolasses
• @crodnun
• @MysticRyuujin

If you have specific requests, contact us here [email protected].