trueblocks-core

README

Recent Migrations

Complete any applicable Migrations which contains important information.

TrueBlocks Core

Table of Contents

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

Introduction

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 order of magnitude 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 to extract (export) and list (list) historical transactions per address.

Quick Install

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.

1. 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>"

1. Test a command!

chifra blocks 12345

Optional steps

1. To make deep data queries, get the index
2. To explore the data visually, install the explorer application.

Introducing chifra

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.

Getting status

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.

-- Troubleshooting

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.

Using chifra

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.

Building the Index

---

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 download part of the index and build it from there.

This process is described in this article Indexing Addresses.

Docker

Our official docker version is in a separate repo. Please see that repo for more information.

Below is the old docker instructions. This section will be moved shortly.

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

1. 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

Contributing to TrueBlocks

---

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.

Contributors

---

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

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

Contact

---

If you have specific requests, contact us here info@quickblocks.io.