Many of the chifra commands allow you to customize their behaviour through configuration files and/or environment variables. These options are documented here.

Environment variables

Each command-line option may be overridden by exporting an environment variable in your shell prior to running a chifra command.

The name of those environment variables is as follows:

  1. The environment variable beings with TB_
  2. The environment variable is ALL_UPPER_CASE
  3. The environment variable name removes underbars from the item_name (item_name becomes ITEMNAME)
  4. The environment variable name starts with the group the item belongs to


A more concrete example might be:

export TB_SETTINGS_RPCPROVIDER=http://localhost:9876
chifra blocks 100

which would cause chifra to use an alternate rpcProvider without having to edit the configuration file.

This feature comes in handy when build shell scripts to automate various tasks with chifra.

Where are configs stored?

The configuration files for chifra are stored in the operating system specific locations in the TrueBlocks folder.

Separate files

A single global configuration, called trueBlocks.toml, which stores all the configuration items, is located at the root of the configuration folder.

The remained of this documentation is incorrect. See the configuration file itself or the source code for more information.

Note: As of version 2.5.2, this is no longer true.

In addition, each individual tool may have its own configuration file with items peculuar to that tool. If a configuration item is found in a particular file, it applies only to that tool.

If, however, one of the items documented below under trueBlocks.toml is found in a tool’s individual config, it will override that value for that tool only.

For historical reasons, the configuration files are names based on old tool names. Please see the table below for the name of each tool’s config file.


If you’re running against mutliple chains, you may place any of these files in the root of the chain’s configuration folder, and the values found there will replace any values found at the top level. In this way, you may configure all chains for certain values, but customize your configuration per chain.

Configuration files

trueBlocks.toml (all tools)
ItemDescription / Default
rpcProviderThe RPC endpoint (required)
cachePathLocation of binary cache
indexPathLocation of unchained index
etherscan_keyAPI key for Etherscan (optional)
debug_curlIncreases log level for curl commands
All tools (in each file)
ItemDescription / Default
formatCustomizes default output of tool
acctExport.toml for chifra export
ItemDescription / Default
cacheIf true, queried transactions are cached
cache_tracesIf true, queried traces are cached
ether_roundingWhen doing reconciliations, round to this number of decimals places
start_when_deployedFor smart contracts only, if true, start scan when contract is first deployed. If false, scan entire history (slower)
max_tracesFor any given transaction, limit number of traces to this number
skip_ddosSkip over 2016 dDos attacks
formatDisplay format when exporting transactions (search source code)
receiptDisplay format when exporting receipts
logDisplay format when exporting logs
traceDisplay format when exporting traces
appearancesDisplay format when exporting appearances
neighborDisplay format when exporting neighbors
statementDisplay format when exporting statements
enabledIf true, exclude addresses in list from extractions
listIf [exclusions]enabled is true, exclude this list of addresses from extractions
blockScrape.toml for chifra scrape

Configuration group: [settings]

ItemTypeDefaultDescription / Default
apps_per_chunkuint64200000the number of appearances to build into a chunk before consolidating it
snap_to_griduint64100000an override to apps_per_chunk to snap-to-grid at every modulo of this value, this allows easier corrections to the index
first_snapuint640the first block at which snap_to_grid is enabled
unripe_distuint6428the distance (in blocks) from the front of the chain under which (inclusive) a block is considered unripe
channel_countuint6420number of concurrent processing channels
allow_missingboolfalsedo not report errors for blockchains that contain blocks with zero addresses
chunkMan.toml for chifra chunks
ItemDescription / Default
download_manifestIf true, download the index manifest prior to processing
getTraces.toml for chifra traces
ItemDescription / Default
skip_ddosIf true, skip over September 2016 dDos transactions
maxIf skip_ddos is true, this number of traces defines a ‘dDos’ transaction
ethslurp.toml for chifra slurp

See the source code for information on customizing this tool – this legacy code does not comply with other tools.

Other tools

The following tools are documented, but customizing them is not supported. If you change something here, and you break your installation, please don’t tell us we didn’t warn you.

testRunner.toml for testRunner
ItemDescription / Default
api_providerThe location of the API endpoint gotten from chifra daemon
run_localIf true, run tests labeled as local (most will fail)
json_pretty_printPost processor for API test cases (formats output to verify valid JSON production)
jq .
test_epochThe epoch to report in the performance testing tool - usually tracks current version
copy_pathAn alternate path to which to copy performance results
makeClass.toml for makeClass
ItemDescription / Default
disabledIf true, makeClass is enabled. Be warned – this will overwrite source code file if improperly configured
last_formatThe timestamp at date the makeClass formatter was run
auto_formatIf true, run the auto-formatter
generateIf true, run the auto-code generator
readmesIf true, generate README files with make generate

The follow values are defined for each classDefinition file

ItemDescription / Default
classThe name of the C++ class
fieldsThe name of the file holding the field definitions for the class
includesThe include files for the class’s header file
cpp_includesThe include files for the class’s c++ file
sortIf true, add sorting function to the class
equalsIf true, add equality function to the class
contained_byIf present, the name of the class that contains items of this type
doc_producerThe name of the chifra tool that produces this type of data
doc_groupThe documentation group this class belongs to
doc_descrThe description of the class for the documentation
doc_routeThe command line tool and/or the API route
force_objgetSome flag for some reason

Edit this page on GitHub