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.

Edit this page on GitHub