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:

Appearances consist of the following fields:

FieldDescriptionType
addressthe address of the appearanceaddress
blockNumberthe number of the blockuint32
transactionIndexthe index of the transaction in the blockuint32
traceIndexthe zero-based index of the trace in the transactionuint32
reasonthe location in the data where the appearance was foundstring
timestampthe timestamp for this appearancetimestamp
datethe timestamp as a date (calculated)datetime

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:

Monitors consist of the following fields:

FieldDescriptionType
addressthe address of this monitoraddress
nRecordsthe number of appearances for this monitorint64
fileSizethe size of this monitor on discint64
lastScannedthe last scanned block numberuint32
deletedtrue if this monitor has been deletedbool

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 address 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:

Names consist of the following fields:

FieldDescriptionType
tagscolon separated list of tagsstring
addressthe address associated with this nameaddress
namethe name associated with this address (retrieved from on-chain data if available)string
symbolthe symbol for this address (retrieved from on-chain data if available)string
sourceuser supplied source of where this name was found (or on-chain if name is on-chain)string
decimalsnumber of decimals retrieved from an ERC20 smart contract, defaults to 18uint64
petnamethe petname such as described here http://www.erights.org/elib/capability/pnml.htmlstring
deletedtrue if deleted, false otherwisebool
isCustomtrue if the address is a custom address, false otherwisebool
isPrefundtrue if the address was one of the prefund addresses, false otherwisebool
isContracttrue if the address is a smart contract, false otherwisebool
isErc20true if the address is an ERC20, false otherwisebool
isErc721true if the address is an ERC720, false otherwisebool

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:

Bounds consist of the following fields:

FieldDescriptionType
countthe number of appearances for this addressuint64
firstAppthe block number and transaction id of the first appearance of this addressAppearance
firstTsthe timestamp of the first appearance of this addresstimestamp
firstDatethe first appearance timestamp as a date (calculated)datetime
latestAppthe block number and transaction id of the latest appearance of this addressAppearance
latestTsthe timestamp of the latest appearance of this addresstimestamp
latestDatethe latest appearance timestamp as a date (calculated)datetime

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:

Statements 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 the log in the block, if applicablelognum
transactionHashthe hash of the transaction that triggered this reconciliationhash
timestampthe Unix timestamp of the objecttimestamp
datethe timestamp as a date (calculated)datetime
assetAddr0xeeee…eeee for ETH reconciliations, the token address otherwiseaddress
assetSymboleither ETH, WEI, or the symbol of the asset being reconciled as extracted from the chainstring
decimalsthe value of decimals from an ERC20 contract or, if ETH or WEI, then 18value
spotPricethe on-chain price in USD (or if a token in ETH, or zero) at the time of the transactionfloat
priceSourcethe on-chain source from which the spot price was takenstring
accountedForthe address being accounted for in this reconciliationaddress
senderthe initiator of the transfer (the sender)address
recipientthe receiver of the transfer (the recipient)address
begBalthe beginning balance of the asset prior to the transactionint256
amountNettotalIn - totalOut (calculated)int256
endBalthe on-chain balance of the asset (see notes about intra-block reconciliations)int256
reconciliationTypeone of regular, prevDiff-same, same-nextDiff, or same-same. Appended with eth or token (calculated)string
reconciledtrue if endBal === endBalCalc and begBal === prevBal. false otherwise. (calculated)bool
totalInthe sum of the following In fields (calculated)int256
amountInthe top-level value of the incoming transfer for the accountedFor addressint256
internalInthe internal value of the incoming transfer for the accountedFor addressint256
selfDestructInthe incoming value of a self-destruct if recipient is the accountedFor addressint256
minerBaseRewardInthe base fee reward if the miner is the accountedFor addressint256
minerNephewRewardInthe nephew reward if the miner is the accountedFor addressint256
minerTxFeeInthe transaction fee reward if the miner is the accountedFor addressint256
minerUncleRewardInthe uncle reward if the miner who won the uncle block is the accountedFor addressint256
correctingInfor unreconciled token transfers only, the incoming amount needed to correct the transfer so it balancesint256
prefundInat block zero (0) only, the amount of genesis income for the accountedFor addressint256
totalOutthe sum of the following Out fields (calculated)int256
amountOutthe amount (in units of the asset) of regular outflow during this transactionint256
internalOutthe value of any internal value transfers out of the accountedFor accountint256
correctingOutfor unreconciled token transfers only, the outgoing amount needed to correct the transfer so it balancesint256
selfDestructOutthe value of the self-destructed value out if the accountedFor address was self-destructedint256
gasOutif the transaction’s original sender is the accountedFor address, the amount of gas expendedint256
totalOutLessGastotalOut - gasOut (calculated)int256
prevBalthe account balance for the given asset for the previous reconciliationint256
begBalDiffdifference between expected beginning balance and balance at last reconciliation, if non-zero, the reconciliation failed (calculated)int256
endBalDiffendBal - endBalCalc, if non-zero, the reconciliation failed (calculated)int256
endBalCalcbegBal + amountNet (calculated)int256
correctingReasonthe reason for the correcting entries, if anystring

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:

AppearanceTables consist of the following fields:

FieldDescriptionType
AddressRecordthe address record for these appearancesAddrRecord
Appearancesall the appearances for this addressAppRecord[]

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
datetimea JSON formatted dateas a string
hashan ‘0x’-prefixed 32-byte hex stringlowercase
int256a signed big numberas a string
int64a 64-bit signed integer
lognuman alias for a uint64
stringa normal character string
timestampa 64-bit unsigned integerUnix timestamp
txnuman alias for a uint64
uint32a 32-bit unsigned integer
uint64a 64-bit unsigned integer
valuean alias for a 64-bit unsigned integer

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

Edit this page on GitHub