-- What's the long term vision for TrueBlocks?

Answer:

• 30-year vision: you can't buy a computer of any type without a blockchain node inside and that blockchain node is so well indexed, anyone can get any portion of the entire history of the world without asking permission.
• 15-year vision: a special type of node software called an indexing node that does not carry the actual details of the chain, but can build the index and share it for free.
• 5-year vision: a large number of end-user (probably desktop) application built upon an excellent, complete, automatically-shared, super-fast index.
• 1-year vision: complete the work we promised to the Ethereum Foundation as described here: Ethereum Foundation Grant - TrueBlocks
• 1-month vision: get a speaking gig at EthDenver.
• 1-day vision: finish porting chifra traces to GoLang.

-- What is your policy on new features?

Answer:

• New features are "sort of" on hold for now as we port the entire C++ code base to GoLang. Once that's completed, we will focus on improving speed by taking advantage of GoLang's natural concurrency. Throughout our development, as new features are requested/suggested, if the feature can be added relatively easily to the GoLang code, we may add them. If the suggested feature needs to be added to the C++ code, it probably won't be added.

System Architecture

High-Level Architecture Diagram

Chifra Command Line"

The chifra command provides access to all the applications and tools available:

Purpose:
  Access to all TrueBlocks tools (chifra <cmd> --help for more).

  Accounts:
    list          list every appearance of an address anywhere on the chain
    export        export full detail of transactions for one or more addresses
    monitors      add, remove, clean, and list address monitors
    names         query addresses or names of well known accounts
    abis          fetches the ABI for a smart contract
  Chain Data:
    blocks        retrieve one or more blocks from the chain or local cache
    transactions  retrieve one or more transactions from the chain or local cache
    receipts      retrieve receipts for the given transaction(s)
    logs          retrieve logs for the given transaction(s)
    traces        retrieve traces for the given transaction(s)
    when          find block(s) based on date, blockNum, timestamp, or 'special'
  Chain State:
    state         retrieve account balance(s) for one or more addresses at given block(s)
    tokens        retrieve token balance(s) for one or more addresses at given block(s)
  Admin:
    status        report on the status of the TrueBlocks system
    serve         serve the TrueBlocks API using the flame server
    scrape        scan the chain and update (and optionally pin) the TrueBlocks index of appearances
    chunks        manage and investigate chunks and bloom filters
    init          initialize the TrueBlocks system by downloading from IPFS
  Other:
    quotes        update or display Ethereum price data, this tool has been deprecated
    explore       open a local or remote explorer for one or more addresses, blocks, or transactions
    slurp         fetch data from EtherScan for any address
  Flags:
    -h, --help    display this help screen

  Use "chifra [command] --help" for more information about a command.

Click on the links to the left for more information on each command

Using chifra

Like git, TrueBlocks has a command called chifra that gives you access to all of the other subcommands.

Type:

chifra

You will see a long list of commands similar to this

  Usage:    chifra command
  Purpose:  Access to all TrueBlocks tools (chifra <cmd> --help for more).

  Where:
  Accounts:
    list          list every appearance of an address anywhere on the chain
    export        export full details of transactions for one or more addresses
    monitors      add, remove, clean, and list address monitors
    names         query addresses or names of well-known accounts
    abis          fetches the ABI for a smart contract
  Chain Data:
    blocks        retrieve one or more blocks from the chain or local cache
    transactions  retrieve one or more transactions from the chain or local cache
    receipts      retrieve receipts for the given transaction(s)
    logs          retrieve logs for the given transaction(s)
    traces        retrieve traces for the given transaction(s)
    when          find block(s) based on date, blockNum, timestamp, or 'special'
  Chain State:
    state         retrieve account balance(s) for one or more addresses at given block(s)
    tokens        retrieve token balance(s) for one or more addresses at given block(s)
  Admin:
    config        report on and edit the configuration of the TrueBlocks system
    daemon        initialize and control long-running processes such as the API and the scrapers
    scrape        scan the chain and update the TrueBlocks index of appearances
    chunks        manage, investigate, and display the Unchained Index
    init          initialize the TrueBlocks system by downloading from IPFS
  Other:
    explore       open a local or remote explorer for one or more addresses, blocks, or transactions
    slurp         fetch data from Etherscan for any address

You may get more help on any command by typing chifra <cmd> --help.

Getting status

Let's look at an easy command to get started called config.

chifra config

If you get a valid response, 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 config command returns a valid response, you may move to the next section. If you continue to have trouble, join our discord disscussion.

Using chifra

If you've gotten this far, you're ready to use TrueBlocks.

Let's try another simple command to show Ethereum block data. This command shows every 10th block between the first and the 100,000th.

chifra blocks 0-100000:10

Hit Control+C to stop the processing.

This shows one of the basic ideas behind TrueBlocks: make the Ethereum data easier to use.

Play around with other options. See what you can do.

Conclusion

By this point, you should have TrueBlocks properly installed and be able to get simple blockchain data from your node. All of the chifra commands should now work. The next section further introduces you to chifra.

Please see the Using Chifra page to proceed.

Tutorials

A few more examples in more detail.

Getting help

Every chifra sub-command comes with an associated help page. To get help for chifra itself, simply type

chifra

A long list of commands should show. (If you have trouble, see the Installation page.)

To get help for a specific command, type

chifra <cmd> --help

To get more detailed help, type

chifra <cmd> --help --verbose 2

Getting system status

The chifra command gives you access to all of TrueBlocks' functionality. Get system status by typing

chifra config

Getting blockchain data

Let's see if we can get some actual blockchain data.

Getting Blocks

The following command returns block data from block 2,001,002. The data is returned as JSON.

chifra blocks 2001002

Notice the full transactional details are included for each of the seven transactions in the block. You can show just the transaction hashes with

chifra blocks 2001002 --hashes

Copy one of those transaction hashes and paste it into the next command

chifra transactions 0x5f965c...9f26e12  # use the full hash

This command shows a single transaction's data. But, you may have noticed that the data is shown as tab separated rows. In general, block data (which is structured) is presented as JSON while primarily non-structured data is presented as TXT.

Formatting Output

Every chifra command accepts a few optional parameters including --verbose and --fmt. --verbose is useful when debugging. The --fmt option allows you to specify the format of the output. It accepts three values:

chifra blocks 2002 --fmt json   # the default for blocks
chifra blocks 2002 --fmt txt    # tab delimited text
chifra blocks 2002 --fmt csv    # comma separated values

These options are available for all chifra commands. (Although in some cases, they are ignored.) One might wish to use the csv and txt options if one is engaged in data science for example.

More data commands

Below, we present a few of the other chifra commands without a lot of description.

Transactions and Logs and Traces, Oh My!

# The first transaction in block 2,002,002
chifra transactions 2001002.0

# All transactions in block 2,002,002 as comma separated values
chifra transactions --fmt csv 2001002.\*

# Every event in block 4,503,002
chifra logs --fmt json 4503002.\*

# Every event in block 4,503,002 -- articulated (see below)
chifra logs --fmt json --articulate 4503002.\*

# Every trace in the second transaction of block 4,503,002
chifra traces --fmt json --articulate 4503002.1

Please see the help files for chifra blocks --help and chifra transactions --help for more information, including all the options for specifying blocks and transactions (which are many and varied).

Articulated Data

Most TrueBlocks' commands accept an option called --articulate. The easiest way to explain articulated data is to say it is "ugly blockchain data turned into human readable text".

For example, the following command shows logs from the third transaction in block 4,503,002

chifra logs --fmt json 4503002.2

Pretty ugly. Compare that to this command

chifra logs --fmt json --articulate 4503002.2

You'll see additional (and much more easy to understand) data. In particular, you'll see an articulatedLog. That is "ugly log data presented in human-readable form."

See Getting ERC20 Transfer Events for an example of using articulation.

Links to more detail

There are many other chifra commands including list and export that we still study next. Other commands allow you to serve a JSON API presenting each command as an API route, init which pulls parts of the index data from IPFS, and scrape which builds the index.

In the following sections, each command is presented with its options and in more detail. In addition,

• Our blog has a few longer "tutorials"for accomplishing various tasks.
• Our data model reference describes the fields that are returned with each command

Accounts

The Accounts group of commands is at the heart of TrueBlocks. They allow you to produce and analyze transactional histories for one or more Ethereum addresses.

You may also name addresses; grab the ABI file for a given address; add, delete, and remove monitors, and, most importantly, export transactional histories in various formats, This includes re-directing output to remote or local databases.

To the right is a list of commands in this group. Click on a command to see its full documentation.

chifra list

chifra list takes one or more addresses, queries the index of appearances, and builds TrueBlocks monitors. A TrueBlocks monitor is a file that contains blockNumber.transactionIndex pairs (transaction identifiers) representing the history of the address.

Because TrueBlocks only extracts data from the Ethereum node when it's requested, the first time you list an address it takes about a minute. Subsequent queries are much faster because TrueBlocks caches the results.

Note that chifra list only queries the index, it does not extract the full transactional details. You may use chifra export for that.

Purpose:
  List every appearance of an address anywhere on the chain.

Usage:
  chifra list [flags] <address> [address...]

Arguments:
  addrs - one or more addresses (0x...) to list (required)

Flags:
  -U, --count               display only the count of records for each monitor
  -z, --no_zero             for the --count option only, suppress the display of zero appearance accounts
  -b, --bounds              report first and last block this address appears
  -u, --unripe              list transactions labeled unripe (i.e. less than 28 blocks old)
  -s, --silent              freshen the monitor only (no reporting)
  -c, --first_record uint   the first record to process
  -e, --max_records uint    the maximum number of records to process (default 250)
  -E, --reversed            produce results in reverse chronological order
  -F, --first_block uint    first block to export (inclusive, ignored when freshening)
  -L, --last_block uint     last block to export (inclusive, ignored when freshening)
  -x, --fmt string          export format, one of [none|json*|txt|csv]
  -v, --verbose             enable verbose output
  -h, --help                display this help screen

Notes:
  - An address must be either an ENS name or start with '0x' and be forty-two characters long.
  - No other options are permitted when --silent is selected.

Data models produced by this tool:

• appearance
• bounds
• monitor

Links:

• api docs
• source code

chifra export

The chifra export tools provides a major part of the functionality of the TrueBlocks system. Using the index of appearances created with chifra scrape and the list of transaction identifiers created with chifra list, chifra export completes the actual extraction of an address's transactional history from the node.

You may use topics, fourbyte values at the start of a transaction's input data, and/or a log's source address or emitter to filter the results.

You may also choose which portions of the Ethereum data structures (--transactions, --logs, --traces, etc.) as you wish.

By default, the results of the extraction are delivered to your console, however, you may export the results to any database (with a little bit of work). The format of the data, its content and its destination are up to you.

Purpose:
  Export full details of transactions for one or more addresses.

Usage:
  chifra export [flags] <address> [address...] [topics...] [fourbytes...]

Arguments:
  addrs - one or more addresses (0x...) to export (required)
  topics - filter by one or more log topics (only for --logs option)
  fourbytes - filter by one or more fourbytes (only for transactions and trace options)

Flags:
  -p, --appearances         export a list of appearances
  -r, --receipts            export receipts instead of transactional data
  -l, --logs                export logs instead of transactional data
  -t, --traces              export traces instead of transactional data
  -n, --neighbors           export the neighbors of the given address
  -C, --accounting          attach accounting records to the exported data (applies to transactions export only)
  -A, --statements          for the accounting options only, export only statements
  -b, --balances            traverse the transaction history and show each change in ETH balances
  -i, --withdrawals         export withdrawals for the given address
  -a, --articulate          articulate transactions, traces, logs, and outputs
  -R, --cache_traces        force the transaction's traces into the cache
  -U, --count               for --appearances mode only, display only the count of records
  -c, --first_record uint   the first record to process
  -e, --max_records uint    the maximum number of records to process (default 250)
  -N, --relevant            for log and accounting export only, export only logs relevant to one of the given export addresses
  -m, --emitter strings     for the --logs option only, filter logs to show only those logs emitted by the given address(es)
  -B, --topic strings       for the --logs option only, filter logs to show only those with this topic(s)
  -V, --reverted            export only transactions that were reverted
  -P, --asset strings       for the accounting options only, export statements only for this asset
  -f, --flow string         for the accounting options only, export statements with incoming, outgoing, or zero value
                            One of [ in | out | zero ]
  -y, --factory             for --traces only, report addresses created by (or self-destructed by) the given address(es)
  -u, --unripe              export transactions labeled unripe (i.e. less than 28 blocks old)
  -E, --reversed            produce results in reverse chronological order
  -z, --no_zero             for the --count option only, suppress the display of zero appearance accounts
  -F, --first_block uint    first block to process (inclusive)
  -L, --last_block uint     last block to process (inclusive)
  -H, --ether               specify value in ether
  -o, --cache               force the results of the query into the cache
  -D, --decache             removes related items from the cache
  -x, --fmt string          export format, one of [none|json*|txt|csv]
  -v, --verbose             enable verbose output
  -h, --help                display this help screen

Notes:
  - An address must be either an ENS name or start with '0x' and be forty-two characters long.
  - Articulating the export means turn the EVM's byte data into human-readable text (if possible).
  - For the --logs option, you may optionally specify one or more --emitter, one or more --topics, or both.
  - The --logs option is significantly faster if you provide an --emitter or a --topic.
  - Neighbors include every address that appears in any transaction in which the export address also appears.
  - If present, --first_/--last_block are applied, followed by user-supplied filters such as asset or topic, followed by --first_/--max_record if present.
  - The --first_record and --max_record options are zero-based (as are the block options).
  - The _block and _record filters are ignored when used with the --count option.
  - If the --reversed option is present, the appearance list is reversed prior to all processing (including filtering).
  - The --decache option will remove all cache items (blocks, transactions, traces, etc.) for the given address(es).
  - The --withdrawals option is only available on certain chains. It is ignored otherwise.
  - The --traces option requires your RPC to provide trace data. See the README for more information.

Data models produced by this tool:

• appearance
• function
• log
• message
• monitor
• parameter
• receipt
• statement
• token
• trace
• traceaction
• traceresult
• transaction
• withdrawal

Links:

• api docs
• source code

further info

The --traces option requires your node to enable the trace_block (and related) RPC endpoints. Please see the README file for the chifra traces command for more information.

chifra monitors

chifra monitors has two purposes: (1) to display information about the current set of monitors, and (2) to --watch a set of addresses. The --watch function allows one to "follow" an address (or set of addresses) and keep an off-chain database fresh.

Crud commands

chifra list creates a new monitor. See that tool's help file for more information.

The chifra monitors --delete command deletes (or --undelete if already deleted) an address but does not remove it from your hard drive. The monitor is marked as being deleted, making it invisible to other tools.

Use the --remove command to permanently remove a monitor from your computer. This is an irreversible operation and requires the monitor to have been previously deleted.

The --decache option will remove not only the monitor but all of the cached data associated with the monitor (for example, transactions or traces). This is an irreversible operation (except for the fact that the cache can be easily re-created with chifra list <address>). The monitor need not have been previously deleted.

Watching addresses

The --watch command is special. It starts a long-running process that continually reads the blockchain looking for appearances of the addresses it is instructed to watch. It command requires two additional parameters: --watchlist <filename> and --commands <filename>. The --watchlist file is simply a list of addresses or ENS names, one per line:

0x5e349eca2dc61abcd9dd99ce94d04136151a09ee
trueblocks.eth
0x855b26bc8ebabcdbefe82ee5e9d40d20a1a4c11f
etc.

You may monitor as many addresses as you wish, however, if the commands you specify take longer than the --sleep amount you specify (14 seconds by default), the results are undefined. (Adjust --sleep if necessary.)

The --commands file may contain a list of any valid chifra command that operates on addresses. (Currently export, list, state, tokens.) Each command in the --commands file is executed once for each address in the --watchlist file. The --commands file may contain any number of commands, one per line with the above proviso. For example:

chifra list [{ADDRESS}]
chifra export --logs [{ADDRESS}]
etc.

The [{ADDRESS}] token is a stand-in for all addresses in the --watchlist. Addresses are processed in groups of batch_size (default 8).

Invalid commands or invalid addresses are ignored. If a command fails, the process continues with the next command. If a command fails for a particular address, the process continues with the next address. A warning is generated.

Purpose:
  Add, remove, clean, and list address monitors.

Usage:
  chifra monitors [flags] <address> [address...]

Arguments:
  addrs - one or more addresses (0x...) to process

Flags:
      --delete             delete a monitor, but do not remove it
      --undelete           undelete a previously deleted monitor
      --remove             remove a previously deleted monitor
  -C, --clean              clean (i.e. remove duplicate appearances) from monitors, optionally clear stage
  -l, --list               list monitors in the cache (--verbose for more detail)
  -c, --count              show the number of active monitors (included deleted but not removed monitors)
  -S, --staged             for --clean, --list, and --count options only, include staged monitors
  -w, --watch              continually scan for new blocks and extract data as per the command file
  -a, --watchlist string   available with --watch option only, a file containing the addresses to watch
  -d, --commands string    available with --watch option only, the file containing the list of commands to apply to each watched address
  -b, --batch_size uint    available with --watch option only, the number of monitors to process in each batch (default 8)
  -u, --run_count uint     available with --watch option only, run the monitor this many times, then quit
  -s, --sleep float        available with --watch option only, the number of seconds to sleep between runs (default 14)
  -D, --decache            removes related items from the cache
  -x, --fmt string         export format, one of [none|json*|txt|csv]
  -v, --verbose            enable verbose output
  -h, --help               display this help screen

Notes:
  - An address must be either an ENS name or start with '0x' and be forty-two characters long.
  - If no address is presented to the --clean command, all existing monitors will be cleaned.
  - The --watch option requires two additional parameters to be specified: --watchlist and --commands.
  - Addresses provided on the command line are ignored in --watch mode.
  - Providing the value existing to the --watchlist monitors all existing monitor files (see --list).

Data models produced by this tool:

• message
• monitor
• monitorclean

Links:

• api docs
• source code

chifra names

chifra names is a surprisingly useful tool. It allows one to associate textual names with Ethereum addresses. One may ask why this is necessary given that ENS exists. The answer is a single word: "privacy". ENS names are public. In many cases, users desire to keep personal addresses private. Try to do this on a website.

Like chifra abis, this tool is useful from the command line but is primarily used in support of other tools, especially chifra export where naming addresses becomes the single best way to turn unintelligible blockchain data into understandable information.

The various options allow you to search and filter the results. The tags option is used primarily by the TrueBlocks explorer.

You may use the TrueBlocks explorer to manage (add, edit, delete) address-name associations.

Purpose:
  Query addresses or names of well-known accounts.

Usage:
  chifra names [flags] <term> [term...]

Arguments:
  terms - a space separated list of one or more search terms (required)

Flags:
  -e, --expand            expand search to include all fields (search name, address, and symbol otherwise)
  -m, --match_case        do case-sensitive search
  -a, --all               include all (including custom) names in the search
  -c, --custom            include only custom named accounts in the search
  -p, --prefund           include prefund accounts in the search
  -s, --addr              display only addresses in the results (useful for scripting, assumes --no_header)
  -g, --tags              export the list of tags and subtags only
  -C, --clean             clean the data (addrs to lower case, sort by addr)
  -r, --regular           only available with --clean, cleans regular names database
  -d, --dry_run           only available with --clean or --autoname, outputs changes to stdout instead of updating databases
  -A, --autoname string   an address assumed to be a token, added automatically to names database if true
  -x, --fmt string        export format, one of [none|json*|txt|csv]
  -v, --verbose           enable verbose output
  -h, --help              display this help screen

Notes:
  - The tool will accept up to three terms, each of which must match against any field in the database.
  - The --match_case option enables case sensitive matching.

Data models produced by this tool:

• message
• name

Links:

• api docs
• source code

chifra abis

The chifra abis tool retrieves one or more ABI files for the given address(es). It searches for ABIs, sequentially, in the following locations:

• the current working folder,
• the TrueBlocks local cache,
• Etherscan,
• (in the future) ENS and Sourcify.

While this tool may be used from the command line, its primary purpose is in support of the --articulate option for tools such as chifra export and chifra logs.

If possible, the tool will follow proxied addresses searching for the ABI, but that does not always work. In that case, you may use the --proxy_for option.

The --known option prints a list of semi-standard function signatures such as the ERC20 standard, ERC 721 standard, various functions from OpenZeppelin, various Uniswap functions, etc. As an optimization, the known signatures are searched first during articulation.

The --encode option generates a 32-byte encoding for a given cannonical function or event signature. For functions, you may manually extract the first four bytes of the hash.

The --find option is experimental. Please see the notes below for more information.

Purpose:
  Fetches the ABI for a smart contract.

Usage:
  chifra abis [flags] <address> [address...]

Arguments:
  addrs - a list of one or more smart contracts whose ABIs to display (required)

Flags:
  -k, --known              load common 'known' ABIs from cache
  -r, --proxy_for string   redirects the query to this implementation
  -l, --list               a list of downloaded abi files
  -c, --count              show the number of abis downloaded
  -f, --find strings       search for function or event declarations given a four- or 32-byte code(s)
  -n, --hint strings       for the --find option only, provide hints to speed up the search
  -e, --encode string      generate the 32-byte encoding for a given cannonical function or event signature
  -o, --cache              force the results of the query into the cache
  -D, --decache            removes related items from the cache
  -x, --fmt string         export format, one of [none|json*|txt|csv]
  -v, --verbose            enable verbose output
  -h, --help               display this help screen

Notes:
  - Search for either four byte signatures or event signatures with the --find option.

Data models produced by this tool:

• abi
• function
• parameter

Links:

• api docs
• source code

further information

Without the --verbose option, the result is a compacted form of the ABI. Add --verbose for full details.

The chifra abis --find option scans the cross product of two sets. The first set contains more than 100,000 function and event names. The second set contains approximately 700 function signatures. The cross product of these two sets creates 70,000,000 combinations of name(signature) each of which is hashed to create either a four-byte or a 32-byte hash. Very infrequently, the tool will find matches for an otherwise unknown signatures.

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Chain data

The Chain Data group of tools extract blockchain data directly from the node. You may extract block data, transactional data, receipts, logs, traces, and other information. Each tool has it own set of options, allowing you to get exactly the data you need.

To the right is a list of commands in this group. Click on a command to see its full documentation.

chifra blocks

The chifra blocks tool retrieves block data from your Ethereum node or, if previously cached, from the TrueBlocks cache. You may specify multiple blocks per invocation.

By default, chifra blocks queries the full transactional details of the block (including receipts). You may optionally retrieve only the transaction hashes in the block (which is significantly faster). Additionally, you may also use this tool to retrieve uncle blocks at a give height.

Another useful feature of chifra blocks is the ability to extract address appearances from a block. TrueBlocks uses a similar feature internally to build its index of appearances. This type of data is very insightful when studying end user behavior and chain-wide adoption analysis.

Purpose:
  Retrieve one or more blocks from the chain or local cache.

Usage:
  chifra blocks [flags] <block> [block...]

Arguments:
  blocks - a space-separated list of one or more block identifiers (required)

Flags:
  -e, --hashes            display only transaction hashes, default is to display full transaction detail
  -c, --uncles            display uncle blocks (if any) instead of the requested block
  -t, --traces            export the traces from the block as opposed to the block data
  -u, --uniq              display a list of uniq address appearances per transaction
  -f, --flow string       for the --uniq option only, export only from or to (including trace from or to)
                          One of [ from | to | reward ]
  -l, --logs              display only the logs found in the block(s)
  -m, --emitter strings   for the --logs option only, filter logs to show only those logs emitted by the given address(es)
  -B, --topic strings     for the --logs option only, filter logs to show only those with this topic(s)
  -i, --withdrawals       export the withdrawals from the block as opposed to the block data
  -a, --articulate        for the --logs option only, articulate the retrieved data if ABIs can be found
  -U, --count             display only the count of appearances for --addrs or --uniq
  -X, --cache_txs         force a write of the block's transactions to the cache (slow)
  -R, --cache_traces      force a write of the block's traces to the cache (slower)
  -H, --ether             specify value in ether
  -o, --cache             force the results of the query into the cache
  -D, --decache           removes related items from the cache
  -x, --fmt string        export format, one of [none|json*|txt|csv]
  -v, --verbose           enable verbose output
  -h, --help              display this help screen

Notes:
  - Blocks is a space-separated list of values, a start-end range, a special, or any combination.
  - Blocks may be specified as either numbers or hashes.
  - Special blocks are detailed under chifra when --list.
  - With the --logs option, optionally specify one or more --emitter, one or more --topics, either or both.
  - The --logs option is significantly faster if you provide an --emitter and/or a --topic.
  - Multiple topics match on topic0, topic1, and so on, not on different topic0's.
  - The --decache option removes the block(s), all transactions in those block(s), and all traces in those transactions from the cache.
  - The --withdrawals option is only available on certain chains. It is ignored otherwise.
  - The --traces option requires your RPC to provide trace data. See the README for more information.

Data models produced by this tool:

• appearance
• block
• blockcount
• lightblock
• log
• message
• trace
• traceaction
• traceresult
• withdrawal

Links:

• api docs
• source code

further information

The --traces option requires your node to enable the trace_block (and related) RPC endpoints. Please see the README file for the chifra traces command for more information.

chifra transactions

The chifra transactions tool retrieves transactions directly from the Ethereum node or from the TrueBlocks cache (if present). You may specify multiple transaction identifiers per invocation. Unlike the Ethereum RPC, the reported transactions include the transaction's receipt and generated logs.

The --articulate option fetches the ABI from each encountered smart contract (including those encountered in a trace--if the --trace option is enabled) to better describe the reported data.

The --trace option attaches an array transaction traces to the output (if the node you're querying has --tracing enabled), while the --uniq option displays a list of uniq address appearances instead of the underlying data (including uniq addresses in traces if enabled).

Purpose:
  Retrieve one or more transactions from the chain or local cache.

Usage:
  chifra transactions [flags] <tx_id> [tx_id...]

Arguments:
  transactions - a space-separated list of one or more transaction identifiers (required)

Flags:
  -a, --articulate        articulate the retrieved data if ABIs can be found
  -t, --traces            include the transaction's traces in the results
  -u, --uniq              display a list of uniq addresses found in the transaction
  -f, --flow string       for the uniq option only, export only from or to (including trace from or to)
                          One of [ from | to ]
  -l, --logs              display only the logs found in the transaction(s)
  -m, --emitter strings   for the --logs option only, filter logs to show only those logs emitted by the given address(es)
  -B, --topic strings     for the --logs option only, filter logs to show only those with this topic(s)
  -R, --cache_traces      force the transaction's traces into the cache
  -H, --ether             specify value in ether
  -o, --cache             force the results of the query into the cache
  -D, --decache           removes related items from the cache
  -x, --fmt string        export format, one of [none|json*|txt|csv]
  -v, --verbose           enable verbose output
  -h, --help              display this help screen

Notes:
  - The transactions list may be one or more transaction hashes, blockNumber.transactionID pairs, or a blockHash.transactionID pairs.
  - This tool checks for valid input syntax, but does not check that the transaction requested actually exists.
  - If the queried node does not store historical state, the results for most older transactions are undefined.
  - The --decache option removes the all transaction(s) and all traces in those transactions from the cache.
  - The --traces option requires your RPC to provide trace data. See the README for more information.

Data models produced by this tool:

• appearance
• function
• log
• message
• parameter
• transaction

Links:

• api docs
• source code

further information

The --traces option requires your node to enable the trace_block (and related) RPC endpoints. Please see the README file for the chifra traces command for more information.

chifra receipts

chifra receipts returns the given transaction's receipt. You may specify multiple transaction identifiers per invocation.

The --articulate option fetches the ABI from each encountered smart contract (including those encountered in a trace--if the --trace option is enabled) to better describe the reported data.

Generally speaking, this tool is less useful than others as you may report the same data using chifra transactions and more focused data using chifra logs. It is included here for completeness, as the receipt is a fundamental data structure in Ethereum.

Purpose:
  Retrieve receipts for the given transaction(s).

Usage:
  chifra receipts [flags] <tx_id> [tx_id...]

Arguments:
  transactions - a space-separated list of one or more transaction identifiers (required)

Flags:
  -a, --articulate   articulate the retrieved data if ABIs can be found
  -o, --cache        force the results of the query into the cache
  -D, --decache      removes related items from the cache
  -x, --fmt string   export format, one of [none|json*|txt|csv]
  -v, --verbose      enable verbose output
  -h, --help         display this help screen

Notes:
  - The transactions list may be one or more transaction hashes, blockNumber.transactionID pairs, or a blockHash.transactionID pairs.
  - This tool checks for valid input syntax, but does not check that the transaction requested actually exists.
  - If the queried node does not store historical state, the results for most older transactions are undefined.

Data models produced by this tool:

• function
• parameter
• receipt

Links:

• api docs
• source code

chifra logs

chifra logs returns the given transaction's logs. You may specify multiple transaction identifiers per invocation.

The --articulate option fetches the ABI from each encountered smart contract to better describe the reported data. The --topic and --source options allow you to filter your results.

Purpose:
  Retrieve logs for the given transaction(s).

Usage:
  chifra logs [flags] <tx_id> [tx_id...]

Arguments:
  transactions - a space-separated list of one or more transaction identifiers (required)

Flags:
  -m, --emitter strings   filter logs to show only those logs emitted by the given address(es)
  -B, --topic strings     filter logs to show only those with this topic(s)
  -a, --articulate        articulate the retrieved data if ABIs can be found
  -o, --cache             force the results of the query into the cache
  -D, --decache           removes related items from the cache
  -x, --fmt string        export format, one of [none|json*|txt|csv]
  -v, --verbose           enable verbose output
  -h, --help              display this help screen

Notes:
  - The transactions list may be one or more transaction hashes, blockNumber.transactionID pairs, or a blockHash.transactionID pairs.
  - This tool checks for valid input syntax, but does not check that the transaction requested actually exists.
  - If the queried node does not store historical state, the results for most older transactions are undefined.
  - If you specify a 32-byte hash, it will be assumed to be a transaction hash, if it is not, the hash will be used as a topic.

Data models produced by this tool:

• function
• log
• message
• parameter

Links:

• api docs
• source code

chifra traces

The chifra traces tool retrieves a transaction's traces. You may specify multiple transaction identifiers per invocation.

The --articulate option fetches the ABI from each encountered smart contract to better describe the reported data.

The --filter option calls your node's trace_filter routine (if available) using a bang-separated string of the same values used by trace_fitler.

Purpose:
  Retrieve traces for the given transaction(s).

Usage:
  chifra traces [flags] <tx_id> [tx_id...]

Arguments:
  transactions - a space-separated list of one or more transaction identifiers (required)

Flags:
  -a, --articulate      articulate the retrieved data if ABIs can be found
  -f, --filter string   call the node's trace_filter routine with bang-separated filter
  -U, --count           display only the number of traces for the transaction (fast)
  -H, --ether           specify value in ether
  -o, --cache           force the results of the query into the cache
  -D, --decache         removes related items from the cache
  -x, --fmt string      export format, one of [none|json*|txt|csv]
  -v, --verbose         enable verbose output
  -h, --help            display this help screen

Notes:
  - The transactions list may be one or more transaction hashes, blockNumber.transactionID pairs, or a blockHash.transactionID pairs.
  - This tool checks for valid input syntax, but does not check that the transaction requested actually exists.
  - If the queried node does not store historical state, the results for most older transactions are undefined.
  - A bang separated filter has the following fields (at least one of which is required) and is separated with a bang (!): fromBlk, toBlk, fromAddr, toAddr, after, count.
  - This command requires your RPC to provide trace data. See the README for more information.

Data models produced by this tool:

• function
• message
• parameter
• trace
• traceaction
• tracecount
• tracefilter
• traceresult

Links:

• api docs
• source code

further information

The --traces option requires your node to enable the trace_block (and related) RPC endpoints. Many remote RPC providers do not enable these endpoints due to the additional load they can place on the node. If you are running your own node, you can enable these endpoints by adding trace to your node's startup.

The test for tracing assumes your node provides tracing starting at block 1. If your is partially synced, you may export the following enviroment variable before running the command to instruct chifra where to test.

export TB_<chain>_FIRSTTRACE=<bn>

where <chain> is the chain you are running and <bn> is the block number at which tracing starts. For example, to start tracing at block 1000 on the mainnet, you would export TB_MAINNET_FIRSTTRACE=1000.

chifra when

The chifra when tool answers one of two questions: (1) "At what date and time did a given block occur?" or (2) "What block occurred at or before a given date and time?"

In the first case, supply a block number or hash and the date and time of that block are displayed. In the later case, supply a date (and optionally a time) and the block number that occurred at or just prior to that date is displayed.

The values for date and time are specified in JSON format. hour/minute/second are optional, and if omitted, default to zero in each case. Block numbers may be specified as either integers or hexadecimal number or block hashes. You may specify any number of dates and/or blocks per invocation.

Purpose:
  Find block(s) based on date, blockNum, timestamp, or 'special'.

Usage:
  chifra when [flags] < block | date > [ block... | date... ]

Arguments:
  blocks - one or more dates, block numbers, hashes, or special named blocks (see notes)

Flags:
  -l, --list         export a list of the 'special' blocks
  -t, --timestamps   display or process timestamps
  -U, --count        with --timestamps only, returns the number of timestamps in the cache
  -r, --repair       with --timestamps only, repairs block(s) in the block range by re-querying from the chain
  -c, --check        with --timestamps only, checks the validity of the timestamp data
  -u, --update       with --timestamps only, bring the timestamp database forward to the latest block
  -d, --deep         with --timestamps --check only, verifies timestamps from on chain (slow)
  -o, --cache        force the results of the query into the cache
  -D, --decache      removes related items from the cache
  -x, --fmt string   export format, one of [none|json*|txt|csv]
  -v, --verbose      enable verbose output
  -h, --help         display this help screen

Notes:
  - The block list may contain any combination of number, hash, date, special named blocks.
  - Block numbers, timestamps, or dates in the future are estimated with 13 second blocks.
  - Dates must be formatted in JSON format: YYYY-MM-DD[THH[:MM[:SS]]].

Data models produced by this tool:

• count
• message
• namedblock
• timestamp

Links:

• api docs
• source code

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Chain state

The two tools in this group deal with the Chain State. As chain state data concerns balances and byte code. it is distinct from Chain Data, which concerns things like blocks, transactions, or traces.

chifra state allows you to query the ETH account balance for an address, the byte code of a smart contract (if available), the nonce, and other information about an address. The second tool, chifra tokens, deals with ERC20 and ERC721 token balances and related data.

To the right is a list of commands in this group. Click on a command to see its full documentation.

Note: The amount of information you can retrieve depends on the type of node you run. Archive nodes and tracing allow you to query historical state (that is, all the way back to the genesis block). TrueBlocks works with non-archive nodes, but they are much less informative.

chifra state

The chifra state tool retrieves the balance of an address (or list of addresses) at the given block (or blocks). Specify multiple addresses and/or multiple blocks if you wish, but you must specify at least one address. If no block is specified, the latest block is reported.

You may also query to see if an address is a smart contract as well as retrieve a contract's byte code.

Purpose:
  Retrieve account balance(s) for one or more addresses at given block(s).

Usage:
  chifra state [flags] <address> [address...] [block...]

Arguments:
  addrs - one or more addresses (0x...) from which to retrieve balances (required)
  blocks - an optional list of one or more blocks at which to report balances, defaults to 'latest'

Flags:
  -p, --parts strings      control which state to export
                           One or more of [ balance | nonce | code | proxy | deployed | accttype | some | all ]
  -c, --changes            only report a balance when it changes from one block to the next
  -z, --no_zero            suppress the display of zero balance accounts
  -l, --call               write-only call (a query) to a smart contract
  -d, --calldata string    for commands (--call or --send), provides the call data (in various forms) for the command (may be empty for --send)
  -a, --articulate         for commands only, articulate the retrieved data if ABIs can be found
  -r, --proxy_for string   for commands only, redirects calls to this implementation
  -H, --ether              specify value in ether
  -o, --cache              force the results of the query into the cache
  -D, --decache            removes related items from the cache
  -x, --fmt string         export format, one of [none|json*|txt|csv]
  -v, --verbose            enable verbose output
  -h, --help               display this help screen

Notes:
  - An address must be either an ENS name or start with '0x' and be forty-two characters long.
  - Blocks is a space-separated list of values, a start-end range, a special, or any combination.
  - If the queried node does not store historical state, the results are undefined.
  - Special blocks are detailed under chifra when --list.
  - Balance is the default mode. To select a single mode use none first, followed by that mode.
  - Valid parameters for --calldata include Solidity-like syntax: balanceOf(0x316b...), a four-byte followed by parameters: 0x70a08231(0x316b...), or encoded input data.
  - You may specify multiple parts on a single line.
  - In the --call string, you may separate multiple calls with a colon.
  - Your use of the unaudited --send option legally absolves TrueBlocks, LLC or any associated parties from liability or loss related to such use.
  - The --send option does not validate its input before sending your transaction to the network. If you provide invalid data, you may lose your funds. Be warned.
  - As of version 4.0.0, use --call --calldata <cmd> to provide your command.
  - --calldata may be one or more colon-seperated solidity calls, four-byte plus parameters, or encoded call data strings.

Data models produced by this tool:

• function
• message
• parameter
• result
• state

Links:

• api docs
• source code

chifra tokens

Given the address of an ERC20 token contract, the chifra tokens tool reports token balances for one or more additional addresses. Alternatively, the tool can report the token balances for multiple ERC20 tokens for a single addresses.

In normal operation the first item in the address_list is assumed to be an ERC20 token contract whose balances are being queried, whereas the remainder of the list is assumed to be addresses on which to report.

In --byAcct mode, all addresses in the address_list are assumed to be ERC20 token contracts, except the final one which is the account whose token balances are reported.

You may optionally specify one or more blocks at which to report. If no block is specified, the latest block is assumed. You may also optionally specify which parts of the token data to extract.

Purpose:
  Retrieve token balance(s) for one or more addresses at given block(s).

Usage:
  chifra tokens [flags] <address> <address> [address...] [block...]

Arguments:
  addrs - two or more addresses (0x...), the first is an ERC20 token, balances for the rest are reported (required)
  blocks - an optional list of one or more blocks at which to report balances, defaults to 'latest'

Flags:
  -p, --parts strings   which parts of the token information to retrieve
                        One or more of [ name | symbol | decimals | totalSupply | version | some | all ]
  -b, --by_acct         consider each address an ERC20 token except the last, whose balance is reported for each token
  -c, --changes         only report a balance when it changes from one block to the next
  -z, --no_zero         suppress the display of zero balance accounts
  -o, --cache           force the results of the query into the cache
  -D, --decache         removes related items from the cache
  -x, --fmt string      export format, one of [none|json*|txt|csv]
  -v, --verbose         enable verbose output
  -h, --help            display this help screen

Notes:
  - An address must be either an ENS name or start with '0x' and be forty-two characters long.
  - Blocks is a space-separated list of values, a start-end range, a special, or any combination.
  - If the token contract(s) from which you request balances are not ERC20 compliant, the results are undefined.
  - If the queried node does not store historical state, the results are undefined.
  - Special blocks are detailed under chifra when --list.
  - If the --parts option is not empty, all addresses are considered tokens and each token's attributes are presented.

Data models produced by this tool:

• token

Links:

• api docs
• source code

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Admin

The Admin group of commands allows you to query the status of the TrueBlocks system and manage various aspects including the Unchained Index. You may query the status; query for information about TrueBlocks caches; control the creation, sharing, and pinning of the Unchained Index; and even serve the data through an API.

See the API documentation for all information about using the API.

To the right is a list of commands in this group. Click on a command to see its full documentation.

chifra config

The chifra config program allows you to manage the various TrueBlocks caches. You may list all of the caches, some of the cache, or even individual caches either in terse or full detail. The cache of interest is specified with the modes option.

TrueBlocks maintains caches for the index of address appearances, named addresses, abi files, as well as other data including blockchain data, and address monitors.

Purpose:
  Report on and edit the configuration of the TrueBlocks system.

Usage:
  chifra config <mode> [flags]

Arguments:
  mode - either show or edit the configuration
    One of [ show | edit ]

Flags:
  -a, --paths        show the configuration paths for the system
  -d, --dump         dump the configuration to stdout
  -x, --fmt string   export format, one of [none|json*|txt|csv]
  -v, --verbose      enable verbose output
  -h, --help         display this help screen

Data models produced by this tool:

• chain

Links:

• api docs
• source code

chifra status

The chifra status tool reports on the state (and size) of the various TrueBlocks local binary caches. TrueBlocks produces nine difference caches: abis, blocks, monitors, names, objs, recons, slurps, traces, transactions. In general practice, these caches may take up a few GB of hard drive space, however, for very popular smart contract the size of the caches may grow rather large. Keep an eye on it.

The chifra status program allows you to manage the various TrueBlocks caches. You may list all of the caches, some of the cache, or even individual caches either in terse or full detail. The cache of interest is specified with the modes option.

TrueBlocks maintains caches for the index of address appearances, named addresses, abi files, as well as other data including blockchain data, and address monitors.

Purpose:
  Report on the state of the internal binary caches.

Usage:
  chifra status <mode> [mode...] [flags]

Arguments:
  modes - the (optional) name of the binary cache to report on, terse otherwise
    One or more of [ index | blooms | blocks | transactions | traces | logs | statements | results | state | tokens | monitors | names | abis | slurps | staging | unripe | maps | some | all ]

Flags:
  -d, --diagnose            same as the default but with additional diagnostics
  -c, --first_record uint   the first record to process
  -e, --max_records uint    the maximum number of records to process (default 10000)
  -a, --chains              include a list of chain configurations in the output
  -k, --healthcheck         an alias for the diagnose endpoint
  -x, --fmt string          export format, one of [none|json*|txt|csv]
  -v, --verbose             enable verbose output
  -h, --help                display this help screen

Notes:
  - The some mode includes index, monitors, names, slurps, and abis.
  - If no mode is supplied, a terse report is generated.

Data models produced by this tool:

• cacheitem
• chain
• status

Links:

• api docs
• source code

chifra daemon

chifra daemon manages chifra's API server. Each of the chifra commands along with all of its options, are provided not only by the command line, but also the API server. We call this process the flame server, which is written in Go. chifra serve is an alias for the chifra daemon command.

In the future, this daemon may also manage other long-running processes such as chifra scrape and chifra monitors, but for now, it's only managing the API server.

If the default port for the API server is in use, you may change it with the --url option.

To get help for any command, please see the API documentation on our website. But, you may also run chifra --help or chifra <cmd> --help on your command line to get help.

See below for an example of converting command line options to a call to the API. There's a one-to-one correspondence between the command line tools and options and the API routes and their options.

Purpose:
  Initialize and control long-running processes such as the API and the scrapers.

Usage:
  chifra daemon [flags]

Aliases:
  daemon, serve

Flags:
  -u, --url string   specify the API server's url and optionally its port (default "localhost:8080")
      --silent       disable logging (for use in SDK for example)
  -v, --verbose      enable verbose output
  -h, --help         display this help screen

Notes:
  - To start API open terminal window and run chifra daemon.
  - See the API documentation (https://trueblocks.io/api) for more information.
  - The --port option is deprecated, use --url instead.
  - The --grpc option is deprecated, there is no replacement.
  - The --api option is deprecated, there is no replacement.
  - The --scrape option is deprecated, use chifra scrape instead.
  - The --monitor option is deprecated, use chifra monitors --watch instead.

Data models produced by this tool:

• none

Links:

• no api for this command
• source code

further information

To convert the options for a command line tool to an API call, do the following:

1. Any --snake_case argument to the command line should be converted to camelCase. For example, --no_header on the command line should be sent as &noHeader to the API server.
2. Any switch on the command line, (i.e., options whose presence indicates true and whose absence indicates false) should be sent as a boolean to the API server. For example, --no_header on the command line should be sent as &noHeader=true to the API server. If the option is fales, you do not need to send it to the API server.
3. Positionals such as the addresses, topics, and four-bytes for chifra export, must be prepended with their positional name. For example, chifra export <address> <topic> should be sent as &addrs=<address>&topics=<topic> to the API server. For some commands (experiment) you may send more than one value for a positional with %20 separating the entries or by sending multiple positionals (i.e., &addrs=<address1>&addrs=<address2>).

chifra scrape

The chifra scrape application creates TrueBlocks' chunked index of address appearances -- the fundamental data structure of the entire system. It also, optionally, pins each chunk of the index to IPFS.

chifra scrape is a long running process, therefore we advise you run it as a service or in terminal multiplexer such as tmux. You may start and stop chifra scrape as needed, but doing so means the scraper will not be keeping up with the front of the blockchain. The next time it starts, it will have to catch up to the chain, a process that may take several hours depending on how long ago it was last run. See the section below and the "Papers" section of our website for more information on how the scraping process works and prerequisites for its proper operation.

You may adjust the speed of the index creation with the --sleep and --block_cnt options. On some machines, or when running against some EVM node software, the scraper may overburden the hardware. Slowing things down will ensure proper operation. Finally, you may optionally --pin each new chunk to IPFS which naturally shards the database among all users. By default, pinning is against a locally running IPFS node, but the --remote option allows pinning to an IPFS pinning service such as Pinata.

Purpose:
  Scan the chain and update the TrueBlocks index of appearances.

Usage:
  chifra scrape [flags]

Flags:
  -n, --block_cnt uint   maximum number of blocks to process per pass (default 2000)
  -s, --sleep float      seconds to sleep between scraper passes (default 14)
  -l, --touch uint       first block to visit when scraping (snapped back to most recent snap_to_grid mark)
  -u, --run_count uint   run the scraper this many times, then quit
  -d, --dry_run          show the configuration that would be applied if run,no changes are made
  -o, --notify           enable the notify feature
  -v, --verbose          enable verbose output
  -h, --help             display this help screen

Notes:
  - The --touch option may only be used for blocks after the latest scraped block (if any). It will be snapped back to the latest snap_to block.
  - This command requires your RPC to provide trace data. See the README for more information.
  - The --notify option requires proper configuration. Additionally, IPFS must be running locally. See the README.md file.

Data models produced by this tool:

• chunkrecord
• manifest
• message

Links:

• no api for this command
• source code

configuration

Each of the following additional configurable command line options are available.

Configuration file: trueBlocks.toml
Configuration group: [scrape.<chain>]

Note that for Ethereum mainnet, the default values for appsPerChunk and firstSnap are 2,000,000 and 2,300,000 respectively. See the specification for a justification of these values.

These items may be set in three ways, each overriding the preceding method:

-- in the above configuration file under the [scrape.<chain>] group,
-- in the environment by exporting the configuration item as upper case (with underbars removed) and prepended with (TB underbar SCRAPE underbar CHAIN) with the underbars included, or
-- on the command line using the configuration item with leading dashes and in snake case (i.e., --snake_case).

further information

Each time chifra scrape runs, it begins at the last block it completed processing (plus one). With each pass, the scraper descends into each block's complete data. (This is why TrueBlocks requires a --tracing node.) As the scraper encounters appearances of address in the block's data, it adds those appearances to a growing index. Periodically (after processing the block that contains the 2,000,000th appearance), the system consolidates an index chunk.

An index chunk is a portion of the index containing approximately 2,000,000 records (although, this number is adjustable for different chains). As part of the consolidation, the scraper creates a Bloom filter representing the set membership in the associated index portion. The Bloom filters are an order of magnitude smaller than the index chunks. The system then pushes both the index chunk and the Bloom filter to IPFS. In this way, TrueBlocks creates an immutable, uncapturable index of appearances that can be used not only by TrueBlocks, but any member of the community who needs it. (Hint: We all need it.)

Users of of any of the TrueBlocks applications (or anyone else's applications) may subsequently download the Bloom filters, query them to determine which index chunks need to be downloaded, and thereby build a historical list of transactions for a given address. This is accomplished while imposing a minimum amount of resource requirement on the end user's machine.

Recently, we enabled the ability for the end user to pin these downloaded index chunks and blooms on their own machines. The user needs the data for the software to operate--sharing requires minimal effort and makes the data available to other people. Everyone is better off. A naturally-occuring network effect.

tracing

The chifra scrape command requires your node to provide the trace_block (and related) RPC endpoints. Please see the README file for the chifra traces command for more information.

prerequisites

chifra scrape works with any EVM-based blockchain, but does not currently work without a "tracing, archive" RPC endpoint. The Erigon and Reth blockchain nodes, given their minimal disc footprint for an archive node and their support of the required trace_ endpoint routines, are recommended.

Please see this article for more information about running the scraper and building and sharing the index of appearances.

notifications

The chifra scrape command provides a notification feature which is used primarily for trueblocks-key. To configure it, you must edit the trueBlocks.toml file. You may edit the configuration file with chifra config edit. Add the following configuration items to the [settings] group:

[settings.notify]
    url = "http://localhost:5555" # or other
    author = "TrueBlocks" #optional

In addition, you must enable the feature by adding the --notify option to the command line.

chifra chunks

The chifra chunks routine provides tools for interacting with, checking the validity of, cleaning up, and analyzing the Unchained Index. It provides options to list pins, the Manifest, summary data on the index, Bloom filters, addresses, and appearances. While still in its early stages, this tool will eventually allow users to clean their local index, clean their remote index, study the indexes, etc. Stay tuned.

Purpose:
  Manage, investigate, and display the Unchained Index.

Usage:
  chifra chunks <mode> [flags] [blocks...] [address...]

Arguments:
  mode - the type of data to process (required)
    One of [ manifest | index | blooms | pins | addresses | appearances | stats ]
  blocks - an optional list of blocks to intersect with chunk ranges

Flags:
  -c, --check              check the manifest, index, or blooms for internal consistency
  -i, --pin                pin the manifest or each index chunk and bloom
  -p, --publish            publish the manifest to the Unchained Index smart contract
  -r, --remote             prior to processing, retrieve the manifest from the Unchained Index smart contract
  -b, --belongs strings    in index mode only, checks the address(es) for inclusion in the given index chunk
  -F, --first_block uint   first block to process (inclusive)
  -L, --last_block uint    last block to process (inclusive)
  -m, --max_addrs uint     the max number of addresses to process in a given chunk
  -d, --deep               if true, dig more deeply during checking (manifest only)
  -e, --rewrite            for the --pin --deep mode only, writes the manifest back to the index folder (see notes)
  -U, --count              for certain modes only, display the count of records
  -s, --sleep float        for --remote pinning only, seconds to sleep between API calls
  -x, --fmt string         export format, one of [none|json*|txt|csv]
  -v, --verbose            enable verbose output
  -h, --help               display this help screen

Notes:
  - Mode determines which type of data to display or process.
  - Certain options are only available in certain modes.
  - If blocks are provided, only chunks intersecting with those blocks are displayed.
  - The --truncate option updates the manifest and removes local data, but does not alter remote pins.
  - The --belongs option is only available in the index mode.
  - The --first_block and --last_block options apply only to addresses, appearances, and index --belongs mode.
  - The --pin option requires a locally running IPFS node or a pinning service API key.
  - The --publish option requires a private key.
  - The --publisher option is ignored with the --publish option since the sender of the transaction is recorded as the publisher.
  - Without --rewrite, the manifest is written to the temporary cache. With it, the manifest is rewritten to the index folder.

Data models produced by this tool:

• appearance
• appearancetable
• chunkaddress
• chunkbloom
• chunkindex
• chunkpin
• chunkrecord
• chunkstats
• count
• ipfspin
• manifest
• message
• rangedates
• reportcheck

Links:

• api docs
• source code

chifra init

When invoked, chifra init reads a value from a smart contract called The Unchained Index (0x0c316b7042b419d07d343f2f4f5bd54ff731183d).

This value (manifestHashMap) is an IPFS hash pointing to a pinned file (called the Manifest) that contains a large collection of other IPFS hashes. These other hashes point to each of the Bloom filter and Index Chunk. TrueBlocks periodically publishes the Manifest's hash to the smart contract. This makes the index available for our software to use and impossible for us to withhold. Both of these aspects of the manifest are by design.

If you stop chifra init before it finishes, it will pick up again where it left off the next time you run it.

Certain parts of the system (chifra list and chifra export for example) if you have not previously run chifra init or chifra scrape. You will be warned by the system until it's satisfied.

If you run chifra init and allow it to complete, the next time you run chifra scrape, it will start where init finished. This means that only the blooms will be stored on your hard drive. Subsequent scraping will produce both chunks and blooms, although you can, if you wish delete chunks that are not being used. You may periodically run chifra init if you prefer not to scrape.

Purpose:
  Initialize the TrueBlocks system by downloading the Unchained Index from IPFS.

Usage:
  chifra init [flags]

Flags:
  -a, --all                in addition to Bloom filters, download full index chunks (recommended)
  -e, --example string     create an example for the SDK with the given name
  -d, --dry_run            display the results of the download without actually downloading
  -F, --first_block uint   do not download any chunks earlier than this block
  -s, --sleep float        seconds to sleep between downloads
  -v, --verbose            enable verbose output
  -h, --help               display this help screen

Notes:
  - If run with no options, this tool will download or freshen only the Bloom filters.
  - The --first_block option will fall back to the start of the containing chunk.
  - You may re-run the tool as often as you wish. It will repair or freshen the index.

Data models produced by this tool:

• chunkrecord
• manifest

Links:

• api docs
• source code

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Other

The commands in the Other group provide useful miscellaneous features.

• chifra explore provides a quick way to open the configured blockchain explorer,
• ethslurp (an older tool) allows you call extract data from Etherscan.

To the right is a list of commands in this group. Click on a command to see its full documentation.

Note: Some of these tools, such as ethslurp, require an API key. Follow these instructions to add a key to your config.

chifra explore

chifra explore opens Etherscan (and other explorers -- including our own) to the block identifier, transaction identifier, or address you specify. It's a handy (configurable) way to open an explorer from the command line, nothing more.

Purpose:
  Open a local or remote explorer for one or more addresses, blocks, or transactions.

Usage:
  chifra explore [flags] [terms...]

Arguments:
  terms - one or more address, name, block, or transaction identifier

Flags:
  -n, --no_open   return the URL without opening it
  -l, --local     open the local TrueBlocks explorer
  -g, --google    search google excluding popular blockchain explorers
  -h, --help      display this help screen

Data models produced by this tool:

• destination

Links:

• no api for this command
• source code

chifra slurp

chifra slurp is the first tool we built in the Ethereum space. It even has its own website.

While it's useful, it has two shortcomings. First, it is fully centralized, pulling its data from http://etherscan.io. Second, is that it does not report every transaction for a given account. This is actually a shortcoming with API providers. It's too complicated to explain here, but see our blog.

While chifra slurp has its shortcomings, it does provides some nice features. You may use it to pull any transaction initiated by an EOA for example or to explore mining rewards. Visit the above referenced website for more information.

Currently supported API providers:

• TrueBlocks Key
• Etherscan
• Covalent
• Alchemy

Purpose:
  Fetch data from Etherscan and other APIs for any address.

Usage:
  chifra slurp [flags] <address> [address...] [block...]

Arguments:
  addrs - one or more addresses to slurp from Etherscan (required)
  blocks - an optional range of blocks to slurp

Flags:
  -r, --parts strings    which types of transactions to request
                         One or more of [ ext | int | token | nfts | 1155 | miner | uncles | withdrawals | some | all ]
  -p, --appearances      show only the blocknumber.tx_id appearances of the exported transactions
  -a, --articulate       articulate the retrieved data if ABIs can be found
  -S, --source string    the source of the slurped data
                         One of [ etherscan | key | covalent | alchemy ] (default "etherscan")
  -U, --count            for --appearances mode only, display only the count of records
  -g, --page uint        the page to retrieve (page number)
      --page_id string   the page to retrieve (page ID)
  -P, --per_page uint    the number of records to request on each page (default 1000)
  -s, --sleep float      seconds to sleep between requests (default 0.25)
  -H, --ether            specify value in ether
  -o, --cache            force the results of the query into the cache
  -D, --decache          removes related items from the cache
  -x, --fmt string       export format, one of [none|json*|txt|csv]
  -v, --verbose          enable verbose output
  -h, --help             display this help screen

Notes:
  - An address must be either an ENS name or start with '0x' and be forty-two characters long.
  - Portions of this software are Powered by Etherscan.io, Covalent, Alchemy, TrueBlocks Key APIs.
  - See slurp/README on how to configure keys for API providers.
  - The withdrawals option is only available on certain chains. It is ignored otherwise.
  - If the value of --source is key, --parts is ignored.
  - The --types option is deprecated, use --parts instead.

Data models produced by this tool:

• appearance
• function
• monitor
• parameter
• slurp

Links:

• api docs
• source code

Adding provider API key

Call chifra config edit to edit the configuration file.

For TrueBlocks Key, add keyEndpoint = "your-key-endpoint-url" to chains.mainnet section.

For all other providers add an entry to keys section like this:

[keys]
  [keys.etherscan]
    apiKey = "etherscan-apikey"
  [keys.covalent]
    apiKey = "covalent-apikey"
  [keys.alchemy]
    apiKey = "alchemy-apikey"

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Globals

Global Options

Every chifra command has the following globally available options (unless the option is removed as shown in the Disabled column below). Certain commands have additional globally available features as noted in the Enabled column.

Where:

-v, --verbose enable verbose output -x, --fmt string export format, one of [none|json*|txt|csv] --version displays the current version string --chain instructs the tool to operate against the given chain --no_header suppresses the display of the header in txt and csv format --file reads options from the specified file --output redirects output to the given file --append for --output only, appends results to the given file -h, --help displays the help screen

Group 1

The tools in this group of commands produce data but do not need the cache because they do not query the node. They all have the above globally available options.

Group 2

The tools in this group have all of the above options, but they query the node, therefore they need the cache.

Where:

-o, --cache force the results of the query into the cache -D, --decache removes related items from the cache

Group 3

The tools in this group have all of the above options, but because they do query the node, they need the cache. They also produce wei values therefore they have the --ether option as well.

Where:

-H, --ether specify value in ether

Group 4

As of version 2.6.0, the --raw option has been removed in its entirity. Prior to that version, the following tools had this option which would pass the data received directly from the node without modification.

chifra blocks
chifra transactions
chifra receipts
chifra logs
chifra traces
chifra slurp

Group 5

This final group of tools do not produce any real data. They are mostly used for configuration and/or to start and stop long-running processes. They allow no additional options over the default, but disable the following options depending on context. The deamon option, which provides all the tools via a local API, disables --chain because one sends chain with the URL.

Configurations

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

For example: TB_GROUP_ITEMNAME.

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.

Multichain

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

Configuration group: [settings]

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.

The follow values are defined for each classDefinition file

Data model

Reference pages about working with Ethereum and TrueBlocks-collected data. Jump to the data model introduction

Blockchain data

TrueBlocks data

On its own blockchain data is an unintelligable blob of binary bytes. But, we all know there is an amazing collection of deeply interesting information contained therein. Thousands of people are trading, voting, expressing their preferences, making markets for valueless items every minute.

What interests us about this data are answers to questions such as:

• What exactly is going on?
• Where is my money?
• Didn't I have some of those tokens somewhere?
• May I please just get a list of my transactions?

TrueBlocks allows you to query this type of information and more. Using the chifra list option, one may list every detail of any transaction that happened against one's own wallet address (or anyone else's for that matter).

The --articulate option, which is available on many commands, reanimates or articulates the impossible-to-understand input and event data fields. TrueBlocks even articulates trace data which reveals the deep history of any transaction include multi-layer deep smart contract calls.

TrueBlocks works as easily with multiple related addresses at a time as it does with individual addresses. One can view entire asset balance histories, detailed voting histories for a DAO, or the ownership status on one's POAPs and ENS names. We even allow exporting of Open Financial Exchange files which is what your bank uses to export your transactions to accounting software.

Consistent apis / interfaces

Each of the TrueBlocks endpoints and command-line tools are built on the same core libraries (many of which are in Go). Our server (chifra serve) uses the command line tools directly to complete many of its tasks, therefore the interfaces are identical. Applications built on top of TrueBlocks have a consistent, stable data interface.

Open source

Furthermore, TrueBlocks is fully open source. If you don't like something, change it and make a PR (non-commercial use only). If you're a commercial entity, feel free to make changes, but remember, you must either license the code separately or release your modifications under the same open source license. Please contact us about our licensing plans if you have a non-public, commercial use case.

Unchained index

Benefits of unchaining the index

We've written a lot about the Unchained Index elsewhere. We won't belabour the point, however, we want to point out that the Unchained Index:

• Allows blazingly fast access to any account anywhere on the chain
• Allows perfectly-private access to query blockchain data completely locally
• Naturally shards itself and distributes itself using IPFS and user behaviour
• Is published periodically to a smart contract and once published cannot be removed from public use
• Is reproducable directly from immutable data with a well-defined series of operations meaning its as immutable as the original blockchain data
• Compact
• Digs deeper into the blockchain than any other source allowing for instantaneous, 18-decimal-place accurate off-chain reconciliation of any account
• Blazingly fast

Links to articles about TrueBlocks

Here we present a number of articles we've written about TrueBlocks over the years. Read at least a few of these and you will better understand what we're trying to do.

Accounts

The primary tool of TrueBlocks is chifra export. This tool extracts, directly from the chain, entire transactional histories for one or more addresses and presents that information for use outside the blockchain. The results of this extraction is stored in a data structure called a Monitor.

Monitors collect together Appearances (blknum.tx_id pairs) along with additional information such as Reconciliations (18-decimal place accurate accounting for each asset transfer), Names (associations of human-readable names with addresses), and Abis which track the "meaning" of each transaction through its Functions and Parameters.

Each data structure is created by one or more tools which are detailed below.

Appearance

An appearance is a pointer (blknum, tx_id pair) into the blockchain indicating where a particular address appears. This includes obvious locations such as to or from as well as esoteric locations such as deep inside a tenth-level trace or as the miner of an uncle block. The primary goal of TrueBlocks is to identify every appearance for any address on the chain.

The TrueBlocks index of appearances (created by chifra scrape) makes the production of such a list possible. Appearances are stored in Monitors.

The following commands produce and manage Appearances:

• chifra list
• chifra export
• chifra blocks
• chifra chunks
• chifra slurp
• chifra transactions

Appearances consist of the following fields:

Monitor

A Monitor is a list of Appearances associated with a given address along with various details about those appearances. A monitor is created when a user expresses interest in an address by calling either chifra list or chifra export tool (or querying thier associated APIs).

Once created, a monitor may be periodically freshened by calling either chifra list or chifra export, however, it is also possible to freshen a monitor continually with chifra scrape --monitors. This tool watches the front of the chain and repeatedly calls chifra list.

The following commands produce and manage Monitors:

• chifra monitors
• chifra list
• chifra export
• chifra slurp

Monitors consist of the following fields:

Name

TrueBlocks allows you to associate a human-readable name with an address. This feature goes a long way towards making the blockchain data one extracts with a Monitor much more readable.

Unlike the blockchain data itself, which is globally available and impossible to censor, the association of names with addresses is not on chain (excepting ENS, which, while fine, is incomplete). TrueBlocks allows you to name addresses of interest to you and either share those names (through an on-chain mechanism) or keep them private if you so desire.

Over the years, we've paid careful attention to the 'airwaves' and have collected together a 'starter-set' of named addresses which is available through the chifra names command line. For example, every time people say "Show me your address, and we will airdrop some tokens" on Twitter, we copy and paste all those addresses. We figure if you're going to DOX yourselves, we might as well take advantage of it. Sorry...not sorry.

The following commands produce and manage Names:

• chifra names

Names consist of the following fields:

Bounds

The Bounds data model displays information about a given address including how many times it's appeared on the chain and when the first and most recent blocks, timestamps, and dates are.

The following commands produce and manage Bounds:

• chifra list

Bounds consist of the following fields:

Statement

When exported with the --accounting option from chifra export, each transaction will have field called statements. Statements are an array for reconciliations. All such exported transactions will have at least one reconciliation (for ETH), however, many will have additional reconciliations for other assets (such as ERC20 and ERC721 tokens).

Because DeFi is essentially swaps and trades around ERC20s, and because and 'programmable money' allows for unlimited actions to happen under a single transaction, many times a transaction has four or five reconciliations.

Reconciliations are relative to an accountedFor address. For this reason, the same transaction will probably have different reconciliations depending on the accountedFor address. Consider a simple transfer of ETH from one address to another. Obviously, the sender's and the recipient's reconciliations will differ (in opposite proportion to each other). The accountedFor address is always present as the assetAddress in the first reconciliation of the statements array.

The following commands produce and manage Statements:

• chifra export

Statements consist of the following fields:

AppearanceTable

The appearanceTable data model carries an address and all appearances for that address found in any given chunk.

The following commands produce and manage AppearanceTables:

• chifra chunks

AppearanceTables consist of the following fields:

Base types

This documentation mentions the following basic data types.

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Chain data

The following data structures describe the output of various TrueBlocks blockchain queries. These data structures basically mimic the data available directly from the RPC.

Each data structure is created by one or more tools which are detailed below.

Block

chifra blocks returns top level data specified block. You can also include an array for the blocks' transactions.

The following commands produce and manage Blocks:

• chifra blocks

Blocks consist of the following fields:

Transaction

Transactions represent eth transfers to and from other addresses.

Most of the fields that TrueBlocks returns are standard to all eth transaction. However, one field is very interesting: articulatedTx provides a human readable output of the input field.

This is a very powerful way to understand the story behind a smart contract.

The following commands produce and manage Transactions:

• chifra transactions
• chifra export

Transactions consist of the following fields:

Withdrawal

withdrawals is an array present in post-Shanghai blocks representing Consensys layer staking reward withdrawals. Note that the amount present is in Gwei. The withdrawals array is not present in pre-Shanghai blocks.

The following commands produce and manage Withdrawals:

• chifra blocks
• chifra export

Withdrawals consist of the following fields:

Receipt

Receipts record the amount of gas used for a transaction among other things. If the transaction succeeded, a receipt might also have logs.

If the to address of a transaction is 0x0, the input data is considered to be the source code (byte code) of a smart contract. In this case, if the creation of the contract succeeds, the contractAddress field of the receipt carries the address of the newly created contract.

The following commands produce and manage Receipts:

• chifra receipts
• chifra export

Receipts consist of the following fields:

Log

Logs appear in a possibly empty array in the transaction's receipt. They are only created if the underlying transaction suceeded. In the case where the transaction failed, no logs will appear in the receipt. Logs are only ever generated during transactions whose to address is a smart contract.

The following commands produce and manage Logs:

• chifra logs
• chifra export
• chifra blocks
• chifra transactions

Logs consist of the following fields:

Trace

The deepest layer of the Ethereum data is the trace. Every transaction has at least one trace which is itself a record of the transaction. If the to address of the transaction is a smart contract, other traces may appear, if, for example, that smart contract calls other smart contracts.

Traces may be arbitrarily deep (up to the gasLimit) and ultimately represent a tree of function calls. Some transactions have 100s of traces. The format of the trace is similar to the transaction itself have a trace action (which contains from, to, value like the transaction) and the trace result (containing gasUsed like the receipt).

The following commands produce and manage Traces:

• chifra traces
• chifra export
• chifra blocks

Traces consist of the following fields:

Notes

Traces and TraceActions, when produced during a self-destruct, export different fields when rendered in JSON. In CSV and TXT output, these fields change thier meaning while retaining the header of the original fields. The following table describes these differences:

Fields that change during self-destruct transaction:

TraceAction

Other than the first trace which is the trace of the transaction itself, traces represent calls into smart contracts. Because of this, trace actions closely resemble the fields of the transaction.

The following commands produce and manage TraceActions:

• chifra traces
• chifra export
• chifra blocks

TraceActions consist of the following fields:

TraceResult

As mentioned above, other than the first trace, traces represent calls into other smart contracts. Because of this, the trace results closely resembles the fields of the receipt.

The following commands produce and manage TraceResults:

• chifra traces
• chifra export
• chifra blocks

TraceResults consist of the following fields:

TraceCount

chifra trace --count returns the number of traces the given transaction.

The following commands produce and manage TraceCounts:

• chifra traces

TraceCounts consist of the following fields:

TraceFilter

The traceFilter is an internal data structure used to query using the chifra traces --filter command. Its use may, in the future, be expanded for other use cases. Note that all fields are optional, but not all may be empty at the same time.

The following commands produce and manage TraceFilters:

• chifra traces

TraceFilters consist of the following fields:

BlockCount

chifra blocks --count returns the number of various types of data in a block. For example, transactionCnt is the number of transactions in the block, and so on.

The following commands produce and manage BlockCounts:

• chifra blocks

BlockCounts consist of the following fields:

NamedBlock

Left to its own devices, the blockchain would try to convince us that only hashes and bytes are important, but being human beings we know that this is not true. TrueBlocks articulates various types of data with chifra names detailing the names for addresses, -articulate describing the Functions and Events of a transaction, and chifra when describing dated blocks. Dated blocks assign a human-readable date to blocks given block numbers or timestamps and vice versa.

The following commands produce and manage NamedBlocks:

• chifra when

NamedBlocks consist of the following fields:

Timestamp

Shows the blockNumber, timestamp and difference in seconds between blocks found in the timestamp database.

The following commands produce and manage Timestamps:

• chifra when

Timestamps consist of the following fields:

LightBlock

chifra blocks --hashes returns top level data specified block with only the hashes of the block's transactions.

The following commands produce and manage LightBlocks:

• chifra blocks

LightBlocks consist of the following fields:

Base types

This documentation mentions the following basic data types.

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Chain state

The data structures produced by tools in the Chain State category provide details on the balances (ERC20 or ETH) of an address against a particular token or block. Additionally, direct access to a smart contract's state may be queries with the chirfa state tool. Data structures in that case are specific to the particular smart contract.

Each data structure is created by one or more tools which are detailed below.

State

For the chifra state --call tool, the result is the result returned by the call to the smart contract. This is the decoded output value of the smart contract call.

The following commands produce and manage States:

• chifra state

States consist of the following fields:

Token

The token data model represents the name, decmials, token symbol, and optionally the totalSupply of an ERC-20 token.

The following commands produce and manage Tokens:

• chifra tokens
• chifra export

Tokens consist of the following fields:

Result

For the chifra state --call tool, the result is the result returned by the call to the smart contract. This is the decoded output value of the smart contract call.

The following commands produce and manage Results:

• chifra state

Results consist of the following fields:

Base types

This documentation mentions the following basic data types.

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Admin

The data models produced by the tools in the Admin category relate to scraping the chain, producing the Unchained Index, and querying the configuration of the system. Additional data related to sharing the indexes via IPFS and pinning the same are also produced by tools in this category.

Each data structure is created by one or more tools which are detailed below.

Status

The status data model is a complex beast. It contains various information including a list of registered chains, information about many of the internal binary caches maintained by chifra as well as current status information about the system including version information for both chifra and the node it's running against.

The following commands produce and manage Status:

• chifra status

Status consist of the following fields:

Manifest

The Manifest details the portions of the index of appearances which are called ChunkRecords. Each record in the Manifest details the block range represented by the chunk as well as the IPFS hash of the index chunk along with the associated IPFS hash for the Bloom filter of the chunk. The manifest itself is also pushed to IPFS and the IPFS of the hash of the manifest is published periodically to the Unchained Index smart contract.

The following commands produce and manage Manifests:

• chifra chunks
• chifra init
• chifra scrape

Manifests consist of the following fields:

ChunkRecord

The TrueBlocks index scraper periodically creates a chunked portion of the index so that it can be more easily stored in a content-addresable data store such as IPFS. We call these periodically-created chunks ChunkRecords. The format of said item is described here. A pinned chunk is effectively a relational table relating all of the addresses appearing in the chunk with a list of appearances appearing in the chunk.

The following commands produce and manage ChunkRecords:

• chifra chunks
• chifra init
• chifra scrape

ChunkRecords consist of the following fields:

ChunkIndex

The indexchunk data model represents internal information about each Unchained Index index chunk. It is used mostly interenally to study the characteristics of the Unchained Index.

The following commands produce and manage ChunkIndexes:

• chifra chunks

ChunkIndexes consist of the following fields:

ChunkBloom

The blooms data model represents the bloom filter files that front the Unchained Index index portions. The information here is mostly for internal use only as it includes the size and number of the bloom filters present as well as the number of addresses inserted into the bloom. This information is used to study the characteristics of the Unchained Index.

The following commands produce and manage ChunkBlooms:

• chifra chunks

ChunkBlooms consist of the following fields:

ChunkAddress

The addresses data model is produced by chifra chunks and represents the records found in the addresses table of each Unchained Index chunk. The offset and count fields represent the location and number of records in the appearances table to which the address table is related.

The following commands produce and manage ChunkAddress:

• chifra chunks

ChunkAddress consist of the following fields:

IpfsPin

ipfsPin represents the date, CID and metadata filename of a single IPFS pinned file.

The following commands produce and manage IpfsPins:

• chifra chunks

IpfsPins consist of the following fields:

ChunkStats

The stats data model is produced by chifra chunks and brings together various statistical information such as average number of addresses in an Unchained Index chunk among other information.

The following commands produce and manage ChunkStats:

• chifra chunks

ChunkStats consist of the following fields:

MonitorClean

MonitorClean is a report on removing duplicates from monitors.

The following commands produce and manage MonitorCleans:

• chifra monitors

MonitorCleans consist of the following fields:

CacheItem

The cacheItem data model is used to display various caches displayed from the chifra config tool.

The following commands produce and manage CacheItems:

• chifra status

CacheItems consist of the following fields:

ReportCheck

ChunkCheck reports on the results of tests conducted under chifra chunks --check

The following commands produce and manage ReportChecks:

• chifra chunks

ReportChecks consist of the following fields:

ChunkPin

Reports on the result of the command chifra chunks manifest --pin [--deep].

The following commands produce and manage ChunkPins:

• chifra chunks

ChunkPins consist of the following fields:

Chain

The chain data model represents the configured chain data found in the trueBlocks.toml configuration file.

The following commands produce and manage Chains:

• chifra status
• chifra config

Chains consist of the following fields:

RangeDates

The following commands produce and manage RangeDates:

• chifra chunks

RangeDates consist of the following fields:

Base types

This documentation mentions the following basic data types.

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Other

The following commands provide useful miscellaneous tools:

• chifra explore a quick way to open a blockchain explorer,
• ethslurp an older tool that lets you call data from Etherscan. (This has issues of centralization and data quality, see explanation in its section).

Note: some of these tools, such as ethslurp, require an Etherscan key. Follow these instructions to add a key to your config.

Each data structure is created by one or more tools which are detailed below.

Abi

An ABI describes an Application Binary Interface -- in other words, the Function and Event signatures for a given smart contract. Along with Names the use of ABIs goes a very long way towards making your Ethereum data much more understandable.

Similar to names of addresses, ABI files are not available on-chain which means they must be acquired somewhere. Unfortunately, the Ethereum community has not yet understood that Etherscan is not a good place to store this very important information. For this reason, TrueBlocks uses Etherscan to acquire ABI files and therefore one needs to get an Etherscan API key to use this function.

The following commands produce and manage Abis:

• chifra abis

Abis consist of the following fields:

Notes

See the chifra abis command line for information about getting an Etherscan key.

Function

ABI files are derived from the Solidity source code of a smart contract by extracting the canonical function and event signatures in a JSON structure. The function signatures are hashed (using keccak) into four-byte encodings for functions and 32-byte encodings for events. Because the blockchain only deals with byte data, TrueBlocks needs a way to decode the bytes back into the human-readable function and event signatures. We call this process --articulate. Most TrueBlocks commands provide an --articulate option. See the commands themselves for more information.

The following commands produce and manage Functions:

• chifra abis
• chifra export
• chifra transactions
• chifra receipts
• chifra logs
• chifra traces
• chifra state
• chifra slurp

Functions consist of the following fields:

Parameter

Parameters are a constituent part of a Function or Event. The parameters of a function are each individual value passed into the function. Along with the function's name, the parameter types (once canonicalized) are used to create a function's four byte signature (or an event's 32-byte signature). Parameters are important to TrueBlocks because we use them as part of the ABI decoding and the --articulate process to convert the blockchain's bytes into human-readable text.

The following commands produce and manage Parameters:

• chifra abis
• chifra export
• chifra transactions
• chifra receipts
• chifra logs
• chifra traces
• chifra state
• chifra slurp

Parameters consist of the following fields:

Slurp

THIS SHOULD BE ETHERSCAN DATA RELATED, BUT IT'S NOT TIED IN, SO IT DOESN'T DO ANYTHING The traceFilter is an internal data structure used to query using the chifra traces --filter command. Its use may, in the future, be expanded for other use cases. Note that all fields are optional, but not all may be empty at the same time.

The following commands produce and manage Slurps:

• chifra slurp

Slurps consist of the following fields:

Message

The Message type is used in various places to return information about a command. For example, when using the chifra names --autoname feature in the SDK, a Message type is returned.

The following commands produce and manage Messages:

• chifra blocks
• chifra chunks
• chifra export
• chifra logs
• chifra monitors
• chifra names
• chifra scrape
• chifra state
• chifra traces
• chifra transactions
• chifra when

Messages consist of the following fields:

Count

Shows the number of timestamps in the timestamps database.

The following commands produce and manage Counts:

• chifra when
• chifra chunks

Counts consist of the following fields:

Destination

The following commands produce and manage Destinations:

• chifra explore

Destinations consist of the following fields:

Base types

This documentation mentions the following basic data types.

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

SDKs

SDKs

Chifra serve provides an API interface to the chifra command line. As part of this functionality, we've written two SDKs for Python and TypeScript to make using the API easier. We welcome contributions for other SDKs.

The GoLang SDK is different. Unlike the other SDKs, the GoLang SDK does not require you to run the API server. This has very significant performance implications because there is no serialization of the data. In the server case, the code must read the data from the RPC (or the local binary cache), turn it into a JSON string, and send it to the TypeScript or Python SDK.

In the GoLang SDK, the data is in memory ready for use directly from disc. No strinification. This makes the GoLang SDK as fast as it can possbily be.

The two API-releated SDKs are the TypeScript SDK and the Python SDK.

The GoLang SDKs is here GoLang SDK.

Here's the SDKs repo.

GoLang SDK

The GoLang SDK is in alpha.

The best documentation is available here.

Typescript SDK

The TypeScript SDK is pre-alpha. There is no documentation other than the code.

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.

Python SDK

Here's a link to the Python SDK.

Warning: It's in its very early stage.

Copyright (c) 2024, TrueBlocks, LLC. All rights reserved. Generated with goMaker.