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 is ALL_UPPER_CASE
  2. The environment variable name preserves underbars in the item_name
  3. The name of the variable starts with the group the item belongs to

For example: GROUP_ITEM_NAME.

A more concrete example might be:

export 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 Configuration Files Stored?

Please see TODO: PLACE_HODLER for more information.

Separate Files

A single global configuration, called trueBlocks.toml, is stored at the root of the configuration folder.

In addition, each individual tool has 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)
Item Description / Default
rpcProvider The RPC endpoint (required)
cachePath Location of binary cache
indexPath Location of unchained index
etherscan_key API key for EtherScan (optional)
debug_curl Increases log level for curl commands
All tools (in each file)
Item/Default Description
format Customizes default output of tool
acctExport.toml for chifra export
Item/Default Description
cache If true, queried transactions are cached
cache_traces If true, queried traces are cached
max_slow_queries In API mode only, if transactions do not reconcile, only produce this many results per page
ether_rounding When doing reconciliations, round to this number of decimals places
start_when_deployed For smart contracts only, if true, start scan when contract is first deployed. If false, scan entire history (slower)
max_traces For any given transaction, limit number of traces to this number
skip_ddos Skip over 2016 dDos attacks
format Display format when exporting transactions (search source code)
receipt Display format when exporting receipts
log Display format when exporting logs
trace Display format when exporting traces
appearances Display format when exporting appearances
neighbor Display format when exporting neighbors
statement Display format when exporting statements
enabled If true, exclude addresses in list from extractions
list If [exclusions]enabled is true, exclude this list of addresses from extractions

blockScrape.toml for chifra scrape
Item/Default Description
block_cnt The number of blocks to process with each round of the scraper
block_chan_cnt The number of go routines to devote to block processors
addr_chan_cnt The number of go routines to devote to address processors
n_blocks_fallback The number of blocks to process during dDos or other busy block ranges
apps_per_chunk the number of appearances to build into a chunk before consolidating it
unripe_dist The distance (in blocks) from the front of the chain under which (inclusive) a block is considered unripe
snap_to_grid An override to apps_per_chunk to snap-to-grid at every modulo of this value, this allows easier corrections to the index
first_snap The first block at which snap_to_grid is enabled
allow_missing Do not report errors for blockchain that contain blocks with zero addresses
n_test_runs In live testing mode, the number of test runs to process before quitting
pinata_api_key If –pin is on, the key to Pinata at which to pin
pinata_secret_api_key If –pin is on, the secret key to Pinata at which to pin
[requires] (this section will be removed when full multi-chain support is finished)
tracing If true, require the node to be able to produce traces
archive If true, require the node to be an archive node
parity If true, require the node to be parity (deprecated)
[dev] (this section will be removed when full multi-chain support is finished)
ipfs_gateway The default IPFS gateway endpoint for chifra init
chunkMan.toml for chifra chunks
Item/Default Description
download_manifest If true, download the index manifest prior to processing
getTraces.toml for chifra traces
Item/Default Description
skip_ddos If true, skip over September 2016 dDos transactions
max If 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
Item/Default Description
api_provider The location of the API endpoint gotten from chifra serve
run_local If true, run tests labeled as local (most will fail)
json_pretty_print Post processor for API test cases (formats output to verify valid JSON production)
jq .
test_epoch The epoch to report in the performance testing tool - usually tracks current version
copy_path An alternate path to which to copy performance results
makeClass.toml for makeClass
Item/Default Description
disabled If true, makeClass is enabled. Be warned – this will overwrite source code file if improperly configured
last_format The timestamp at date the makeClass formatter was run
last_lint The timestamp at the date the makeClass linter was run
auto_format If true, run the auto-formatter
generate If true, run the auto-code generator
readmes If true, generate README files with make generate
lint_all If true, run the linter when doing make finish
tsx (deprecated)

The follow values are defined for each classDefinition file

Item/Default Description
class The name of the C++ class
base_class The baseclass for class
fields The name of the file holding the field definitions for the class
includes The include files for the class’s header file
cpp_includes The include files for the class’s c++ file
sort If true, add sorting function to the class
equals If true, add equality function to the class
contained_by If present, the name of the class that contains items of this type
doc_producer The name of the chifra tool that produces this type of data
tsx (deprecated)
doc_group The documentation group this class belongs to
doc_descr The description of the class for the documentation
doc_api The API something or other for something or other
force_objget Some flag for some reason

Edit this page on GitHub