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:

Blocks consist of the following fields:

FieldDescriptionType
gasLimitthe system-wide maximum amount of gas permitted in this blockgas
hashthe hash of the current blockhash
blockNumberthe number of the blockblknum
parentHashhash of previous blockhash
mineraddress of block’s winning mineraddress
difficultythe computational difficulty at this blockvalue
timestampthe Unix timestamp of the objecttimestamp
datethe timestamp as a date (calculated)datetime
transactionsa possibly empty array of transactionsTransaction[]
baseFeePerGasthe base fee for this blockgas
unclesa possibly empty array of uncle hasheshash[]
withdrawalsa possibly empty array of withdrawals (post Shanghai)Withdrawal[]

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:

Transactions consist of the following fields:

FieldDescriptionType
hashthe hash of the transactionhash
blockHashthe hash of the block containing this transactionhash
blockNumberthe number of the blockblknum
transactionIndexthe zero-indexed position of the transaction in the blocktxnum
noncesequence number of the transactions sent by the sendervalue
timestampthe Unix timestamp of the objecttimestamp
datethe timestamp as a date (calculated)datetime
fromaddress from which the transaction was sentaddress
toaddress to which the transaction was sentaddress
valuethe amount of wei sent with this transactionswei
etherif –ether is specified, the value in ether (calculated)ether
gasthe maximum number of gas allowed for this transactiongas
gasPricethe number of wei per unit of gas the sender is willing to spendgas
inputbyte data either containing a message or funcational data for a smart contracts. See the –articulatebytes
receiptReceipt
statementsarray of reconciliations (calculated)Statement[]
articulatedTxFunction
hasTokentrue if the transaction is token related, false otherwisebool
isErrortrue if the transaction ended in error, false otherwisebool
compressedTxtruncated, more readable version of the articulation (calculated)string

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:

Withdrawals consist of the following fields:

FieldDescriptionType
addressthe recipient for the withdrawn etheraddress
amounta nonzero amount of ether given in gwei (1e9 wei)wei
etherif –ether is specified, the amount in ether (calculated)ether
blockNumberthe number of this blockblknum
indexa monotonically increasing zero-based index that increments by 1 per withdrawal to uniquely identify each withdrawalvalue
timestampthe timestamp for this blocktimestamp
datethe timestamp as a date (calculated)datetime
validatorIndexthe validator_index of the validator on the consensus layer the withdrawal corresponds tovalue

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:

Receipts consist of the following fields:

FieldDescriptionType
blockHashhash
blockNumberblknum
contractAddressthe address of the newly created contract, if anyaddress
gasUsedthe amount of gas actually used by the transactiongas
isErrorbool
logsa possibly empty array of logsLog[]
status1 on transaction suceess, null if tx preceeds Byzantium, 0 otherwisevalue
transactionHashhash
transactionIndextxnum

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:

Logs consist of the following fields:

FieldDescriptionType
blockNumberthe number of the blockblknum
transactionIndexthe zero-indexed position of the transaction in the blocktxnum
logIndexthe zero-indexed position of this log relative to the blocklognum
timestampthe timestamp of the block this log appears intimestamp
datethe timestamp as a date (calculated)datetime
addressthe smart contract that emitted this logaddress
topicsthe first topic hashes event signature of the log, up to 3 additional index parameters may appeartopic[]
dataany remaining un-indexed parameters to the eventbytes
transactionHashthe hash of the transctionhash
blockHashthe hash of the blockhash
articulatedLoga human-readable version of the topic and data fieldsFunction
compressedLoga truncated, more readable version of the articulation (calculated)string

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:

Traces consist of the following fields:

FieldDescriptionType
blockHashthe hash of the block containing this tracehash
blockNumberthe number of the blockblknum
timestampthe timestamp of the blocktimestamp
datethe timestamp as a date (calculated)datetime
transactionHashthe transaction’s hash containing this tracehash
transactionIndexthe zero-indexed position of the transaction in the blocktxnum
traceAddressa particular trace’s address in the trace treeuint64[]
subtracesthe number of children traces that the trace hashuint64
typethe type of the tracestring
actionthe trace action for this traceTraceAction
resultthe trace result of this traceTraceResult
articulatedTracehuman readable version of the trace action input dataFunction
compressedTracea compressed string version of the articulated trace (calculated)string

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:

FieldWhen rendered in JSONWhen rendered in csv/txt
Action.FromAction.Address
Action::ToAction.RefundAddress
Action::ValueAction.Balance
Action.RefundAddress
Action.Balance

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:

TraceActions consist of the following fields:

FieldDescriptionType
fromaddress from which the trace was sentaddress
toaddress to which the trace was sentaddress
gasthe maximum number of gas allowed for this tracegas
inputan encoded version of the function callbytes
callTypethe type of callstring
refundAddressif the call type is self-destruct, the address to which the refund is sentaddress
rewardTypethe type of rewardstring
valuethe value (in wei) of this trace actionwei
etherif –ether is specified, the value in ether (calculated)ether
selfDestructedtrue if the contract self-destructed, false otherwiseaddress
balanceif self-destructed, the balance of the contract at that timewei
balanceEthif –ether is specified, the balance in ether (calculated)ether

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:

TraceResults consist of the following fields:

FieldDescriptionType
addressaddress of new contract, if anyaddress
codeif this trace is creating a new smart contract, the byte code of that contractbytes
gasUsedthe amount of gas used by this tracegas
outputthe result of the call of this tracebytes

TraceCount

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

The following commands produce and manage TraceCounts:

TraceCounts consist of the following fields:

FieldDescriptionType
blockNumberthe block numberblknum
transactionIndexthe transaction indextxnum
transactionHashthe transaction’s hashhash
timestampthe timestamp of the blocktimestamp
datethe timestamp as a date (calculated)datetime
tracesCntthe number of traces in the transactionuint64

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:

TraceFilters consist of the following fields:

FieldDescriptionType
fromBlockthe first block to include in the queried list of traces.blknum
toBlockthe last block to include in the queried list of traces.blknum
fromAddressif included, only traces from this address will be included.address
toAddressif included, only traces to this address will be included.address
afteronly traces after this many traces are included.uint64
countonly this many traces are included.uint64

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:

BlockCounts consist of the following fields:

FieldDescriptionType
blockNumberthe block’s block numberblknum
timestampthe timestamp of the blocktimestamp
datethe timestamp as a date (calculated)datetime
transactionsCntthe number transactions in the blockuint64
unclesCntthe number of uncles in the blockuint64
logsCntthe number of logs in the blockuint64
tracesCntthe number of traces in the blockuint64
withdrawalsCntthe number of withdrawals in the blockuint64
addressCntthe number of address appearances in the blockuint64

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:

NamedBlocks consist of the following fields:

FieldDescriptionType
blockNumberthe number of the blockblknum
timestampthe Unix timestamp of the blocktimestamp
datethe timestamp as a date (calculated)datetime
namean optional name for the blockstring
descriptionan optional description of the blockstring

Timestamp

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

The following commands produce and manage Timestamps:

Timestamps consist of the following fields:

FieldDescriptionType
blockNumberthe number of the blockblknum
timestampthe Unix timestamp of the blocktimestamp
datethe timestamp as a date (calculated)datetime
diffthe number of seconds since the last blockint64

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:

LightBlocks consist of the following fields:

FieldDescriptionType
gasLimitthe system-wide maximum amount of gas permitted in this blockgas
hashthe hash of the current blockhash
blockNumberthe number of the blockblknum
parentHashhash of previous blockhash
mineraddress of block’s winning mineraddress
difficultythe computational difficulty at this blockvalue
timestampthe Unix timestamp of the objecttimestamp
datethe timestamp as a date (calculated)datetime
transactionsa possibly empty array of transaction hashesstring[]
baseFeePerGasthe base fee for this blockgas
unclesa possibly empty array of uncle hasheshash[]
withdrawalsa possibly empty array of withdrawals (post Shanghai)Withdrawal[]

Base types

This documentation mentions the following basic data types.

TypeDescriptionNotes
addressan ‘0x’-prefixed 20-byte hex stringlowercase
blknuman alias for a uint64
booleither true, false, 1, or 0
bytesan arbitrarily long string of bytes
datetimea JSON formatted dateas a string
ethera big number floatas a string
gasa 64-bit unsigned integer
hashan ‘0x’-prefixed 32-byte hex stringlowercase
int64a 64-bit signed integer
lognuman alias for a uint64
stringa normal character string
timestampa 64-bit unsigned integerUnix timestamp
topican ‘0x’-prefixed 32-byte hex stringlowercase
txnuman alias for a uint64
uint256a 256-bit unsigned integer
uint64a 64-bit unsigned integer
valuean alias for a 64-bit unsigned integer
weian unsigned big numberas a string

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

Edit this page on GitHub