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 chifra config 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, txs. 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 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 Statuses:

Statuses consist of the following fields:

FieldDescriptionType
clientVersionthe version string as reported by the rpcProviderstring
clientIdsnetword_id and chain_id from the rpcProviderstring
trueblocksVersionthe TrueBlocks version stringstring
rpcProviderthe current rpcProviderstring
configPaththe path to config filesstring
cachePaththe path to the local binary cachesstring
indexPaththe path to the local binary indexesstring
hostthe host portion of the local API serverstring
isTestingtrue if the server is running in test modebool
isApitrue if the server is running in API modebool
isScrapingtrue if the index scraper is runningbool
isArchivetrue if the rpcProvider is an archive nodebool
isTracingtrue if the rpcProvider provides Parity tracesbool
hasEskeytrue if an EtherScan key is presentbool
hasPinkeytrue if a Pinata API key is presentbool
tsthe timestamp when this status data was producedtimestamp
chainsthe list of configured chainsChain[]
cachesa collection of information concerning the binary cachesCache[]

Manifest

The Manifest details the index of appearance’s PinnedChunks. 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:

Manifests consist of the following fields:

FieldDescriptionType
versionthe version string hashed into the chunk datastring
chainthe chain to which this manifest belongsstring
schemasIPFS cid of file describing the schemas for the various databasesipfshash
databasesIPFS cid of file containing CIDs for the various databasesipfshash
chunksa list of the IPFS hashes of all of the chunks in the unchained indexPinnedChunk[]

PinnedChunk

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, PinnedChunks. 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 PinnedChunks:

PinnedChunks consist of the following fields:

FieldDescriptionType
rangefor each chunk, the range of blocks contained in that chunkstring
bloomHashthe IPFS hash of the bloom filter at that rangeipfshash
indexHashthe IPFS hash of the index chunk at that rangeipfshash
firstAppthe first appearance in the chunkblknum
latestAppthe latest appearance in the chunkblknum

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:

ChunkIndexes consist of the following fields:

FieldDescriptionType
rangeThe block range (inclusive) covered by this chunkblockRange
magicAn internal use only magic number to indicate file formatstring
hashThe hash of the specification under which this chunk was generatedhash
addressCountThe number of addresses in this chunkuint64
appearanceCountThe number of appearances in this chunkuint64
sizeThe size of the chunk in bytesuint64

ChunkBlooms

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:

ChunkBlooms consist of the following fields:

FieldDescriptionType
rangeThe block range (inclusive) covered by this chunkblockRange
magicAn internal use only magic number to indicate file formatstring
hashThe hash of the specification under which this chunk was generatedhash
countThe number of individual bloom filters in this bloom fileuint64
nInsertedThe number of addresses inserted into the bloom fileuint64
sizeThe size on disc in bytes of this bloom fileuint64
widthThe width of the bloom filteruint64

ChunkAddresses

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

ChunkAddresses consist of the following fields:

FieldDescriptionType
addressThe address in this recordaddress
rangeThe block range of the chunk from which this address record was takenblockRange
offsetThe offset into the appearance table of the first record for this addressuint64
countThe number of records in teh appearance table for this addressuint64

ChunkAppearances

The appearances data model is the second of two tables inside of the Unchained Index chunks. The other is the addresses table which relates the addresses in that table to this table via the offset and count fields.

The following commands produce and manage ChunkAppearances:

ChunkAppearances consist of the following fields:

FieldDescriptionType
blockNumberThe block number of this appearanceuint64
transactionIndexThe transaction index of this appearanceuint64

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:

ChunkStats consist of the following fields:

FieldDescriptionType
startthe first block in the chunk’s rangeuint64
endthe last block in the chunk’s rangeuint64
nAddrsthe number of addresses in the chunkuint64
nAppsthe number of appearances in the chunkuint64
nBlocksthe number of blocks in the chunkuint64
nBloomsthe number of bloom filters in the chunk’s bloomuint64
recWidthe record width of a single bloom filteruint64
bloomSzthe size of the bloom filters on disc in bytesuint64
chunkSzthe size of the chunks on disc in bytesuint64
addrsPerBlockthe average number of addresses per blockdouble
appsPerBlockthe average number of appearances per blockdouble
appsPerAddrthe average number of appearances per addressdouble
ratiothe ratio of appearances to addressesdouble

Cache

The chifra config reports on the binary caches. Those reports come in the form of the Cache data type. Each cache data object may carry unique information for the given cache. See the source code for more information.

The following commands produce and manage Caches:

Caches consist of the following fields:

FieldDescriptionType
typethe type of the cache (one of the nine different types)string
paththe physical path to the cache on the hard drivestring
nFilesthe number of files in the cacheuint64
nFoldersthe number of subfolders in the cacheuint64
sizeInBytesthe size of the cache in bytesuint64
itemsan array of cache itemsCacheEntry[]

CacheEntry

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

The following commands produce and manage CacheEntries:

CacheEntries consist of the following fields:

FieldDescriptionType
addressaddress
namestring

IndexCacheItem

The indexCacheItem is used to present a single Unchained Index chunk in the Explorer app.

The following commands produce and manage IndexCacheItems:

IndexCacheItems consist of the following fields:

FieldDescriptionType
nAddrsthe number of addresses in this chunkuint32
nAppsthe number of appearances in this chunkuint32
firstAppthe first appearance in this chunkblknum
latestAppthe last appeaerance in this chunkblknum
firstTsthe first timestamp in this chunktimestamp
latestTsthe last timestamp in this chunktimestamp
filenamethe filename of this chunkstring
fileDatethe file date of this chunkdatetime
indexSizeBytesthe size in bytes of the index portion of this chunkuint32
indexHashthe IPFS hash of the index portion of this chunkipfshash
bloomSizeBytesthe size in bytes of the bloom filter for this chunkuint32
bloomHashthe IPFS has of the bloom filter for this chunkipfshash

Chain

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

The following commands produce and manage Chains:

Chains consist of the following fields:

FieldDescriptionType
chainThe common name of the chainstring
chainIdThe chain id as reported by the RPCuint64
symbolThe symbol of the base currency on the chainstring
rpcProviderA valid RPC provider for the chainstring
apiProviderA valid API provider for the explorerstring
remoteExplorerA remote explorer for the chain such as EtherScanstring
localExplorerThe local explorer for the chain (typically TrueBlocks Explorer)string
ipfsGatewayAn IPFS gateway for pinning the index if enabledstring

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
doublea double precision float64 bits
hashan ‘0x’-prefixed 32-byte hex stringlowercase
ipfshasha multi-hash produced by IPFSmixed-case
stringa normal character string
timestampa 64-bit unsigned integerUnix timestamp
uint32a 32-bit unsigned integer
uint64a 64-bit unsigned integer

Edit this page on GitHub