TrueBlocks / Docker Version
Table of Contents
Introduction
TrueBlocks is a local-first indexing / data access solution that you may use for data science or as a locally-running backend for your Web 3.0 projects.
This docker repo is intentionally minimal. See the core repo for more information about the Unchained Index, chifra (our command-line tool), and the TrueBlocks data API.
This repo is pre-alpha and comes with no warrenty implied or otherwise. Use at your own discretion.
Configuration
To get started, create a file called .env in this folder. An env.example file explaining each setting is provided to help you. Adjust the RPC provider to point to a (preferably local) RPC endpoint.
TB_SETTINGS_DEFAULTCHAIN=mainnet
TB_CHAINS_MAINNET_RPCPROVIDER=http://host.docker.internal:8545
TB_KEYS_ETHERSCAN_APIKEY=<your-key>
TB_SETTINGS_CACHEPATH=/cache
TB_SETTINGS_INDEXPATH=/unchained
The ETHERSCAN_APIKEY key is optional, but useful to enable the articulation feature.
By default, the system stores the Unchained Index and binary caches internally to docker. If you wish to to access this data from your host machine (you do, because you want faster access), complete these steps. (Otherwise skip to Running the tool)
Create two folders on your host machine:
mkdir -p /Users/user/Data/cache
mkdir -p /Users/user/Data/unchained
Note: Adjust these paths appropriately for your machine.
Next, create a file called docker-compose.local.yml in the current folder. See the docker-compose.local.example for more information.
services:
core:
volumes:
- type: bind
source: /Users/user/Data/docker/cache
target: /cache
- type: bind
source: /Users/user/Data/docker/unchained
target: /unchained
Note: Adjust the source paths appropriately for your machine.
The above process attaches (binds) the internal-to-docker target folders to the external-on-the-host source folders. This allows the files created internally by the docker to be visible on your host machine.
Running the tool
Assuming you've completed the above instructions, start the container by running this command:
docker compose -f docker.compose.yml -f docker.compose.local.yml up
This will start the TrueBlocks API server. Leave this process running and open a new terminal window.
Use curl to access the API through http://localhost:8080. For example, the command
curl "http://localhost:8080/blocks?blocks=1-1000:10"
will extract every 10th block between blocks 1 and 1,000.
You may also use the chifra command line tool directly. From the current folder, type:
./scripts/chifra.sh blocks 1-1000:10
This will produce the same results as the curl command.
./scripts/chifra.sh --help
will show all available chifra tools. See the full documentation for detailed information.
The unchained index
In the future, this docker will initialize and maintain the Unchained Index. Until then, you must initialize it and maintain it yourself.
Before doing that, please read and understand this discussion. It will have an important impact on how chifra works for you.
Once you've read the above, run one of the following two commands:
# If you want to initialize the full index (recommended if you have space), or
./scripts/chifra.sh init --all
# If you want a minimal index and don't mind slower initial queries
./scripts/chifra.sh init
# Do not run both commands, chose one or the other
Depending on your connection, the above will take several minutes or as much as several hours.
When the initialization finishes, decide if you want to run the scraper. The scrape maintains the index to the front of the chain. (Note: if you're exploring older data, this step may be optional.)
To start the scraper, do this only after the chifra init command finishes:
./scripts/chifra.sh scrape
Allow this process to continue running in its own terminal window or tmux session. If you stop it, the next time you run chifra, you will have to re-run the scraper to catch up to the chain.
Data science
chifra is an excellent data science tool. See a few of our articles (here, here, and here) for ideas on how to take advantage of this very useful tool.
TODO: Add tutorials.
Other
Documentation
See the TrueBlocks website for the most recent documentation.
License
This software is licensed under GNU Version 3.
Contributing
We love contributors. Please see information about our work flow before proceeding.
- Fork this repository into your own repo.
- Create a branch:
git checkout -b <branch_name>. - Make changes to your local branch and commit them to your forked repo:
git commit -m '<commit_message>' - Push back to the original branch:
git push origin TrueBlocks/trueblocks-core - Create the pull request.
Contact
If you have questions, comments, or complaints, please join the discussion on our discord server which is linked from our website.
List of Contributors
Thanks to the following people who have contributed to this project: