Chain Models

Lily relational data format is defined according to the following models, each corresponding to a table. These tables contain chain state and derived chain state.


Blocks

block_headers

Blocks included in tipsets at an epoch.

  • Task: block_header
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
cidtextNOCID of the block.
parent_weighttextNOAggregate chain weight of the block’s parent set.
parent_state_roottextNOCID of the block’s parent state root.
heightbigintNOEpoch when this block was mined.
minertextNOAddress of the miner who mined this block.
timestampbigintNOTime the block was mined in Unix time, the number of seconds elapsed since January 1, 1970 UTC.
win_countbigintYESNumber of reward units won in this block.
parent_base_feetextNOThe base fee after executing the parent tipset.
fork_signalingbigintNOFlag used as part of signaling forks.

block_messages

Message CIDs and the Blocks CID which contain them.

  • Task: block_message
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
blocktextNOCID of the block that contains the message.
messagetextNOCID of a message in the block.
heightbigintNOEpoch when the block was mined.

block_parents

Block CIDs to many parent Block CIDs.

  • Task: block_parent
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
blocktextNOCID of the block.
parenttextNOCID of the parent block.
heightbigintNOEpoch when the block was mined.

drand_block_entries

Drand randomness round numbers used in each block.

  • Task: drand_block_entrie
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
roundbigintNOThe round number of the randomness used.
blocktextNOCID of the block.

Messages

messages

Validated on-chain messages by their CID and their metadata.

  • Task: message
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
cidtextNOCID of the message.
fromtextNOAddress of the actor that sent the message.
totextNOAddress of the actor that received the message.
size_bytesbigintNOSize of the serialized message in bytes.
noncebigintNOThe message nonce, which protects against duplicate messages and multiple messages with the same values.
valuenumericNOAmount of FIL (in attoFIL) transferred by this message.
gas_fee_capnumericNOThe maximum price that the message sender is willing to pay per unit of gas.
gas_premiumnumericNOThe price per unit of gas (measured in attoFIL/gas) that the message sender is willing to pay (on top of the BaseFee) to “tip” the miner that will include this message in a block.
methodbigintYESThe method number invoked on the recipient actor. Only unique to the actor the method is being invoked on. A method number of 0 is a plain token transfer - no method exectution.
heightbigintNOEpoch this message was executed at.

receipts

Message receipts after being applied to chain state by message CID and parent state root CID of tipset when message was executed.

  • Task: receipt
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
messagetextNOCID of the message this receipt belongs to.
state_roottextNOCID of the parent state root that this epoch.
idxbigintNOIndex of message indicating execution order.
exit_codebigintNOThe exit code that was returned as a result of executing the message. Exit code 0 indicates success. Codes 0-15 are reserved for use by the runtime. Codes 16-31 are common codes shared by different actors. Codes 32+ are actor specific.
gas_usedbigintNOA measure of the amount of resources (or units of gas) consumed, in order to execute a message.
heightbigintNOEpoch the message was executed and receipt generated.
returnbyteaYESReturns value of message receipt.
parsed_returnjsonbYESResult returned from executing a message parsed and serialized as a JSON object.

parsed_messages

Messages parsed to extract useful information.

  • Task: parsed_message
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
cidtextNOCID of the message.
heightbigintNOEpoch this message was executed at.
fromtextNOAddress of the actor that sent the message.
totextNOAddress of the actor that received the message.
valuenumericNOAmount of FIL (in attoFIL) transferred by this message.
methodtextNOThe name of the method that was invoked on the recipient actor.
paramsjsonbYESMethod parameters parsed and serialized as a JSON object.

internal_messages

Messages generated implicitly by system actors and by using the runtime send method.

  • Task: internal_messages
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
heightbigintNOEpoch this message was executed at.
cidtextNOCID of the message.
state_roottextNOCID of the parent state root at which this message was executed.
source_messagetextYESCID of the message that caused this message to be sent.
fromtextNOAddress of the actor that sent the message.
totextNOAddress of the actor that received the message.
valuenumericNOAmount of FIL (in attoFIL) transferred by this message.
methodbigintNOThe method number invoked on the recipient actor. Only unique to the actor the method is being invoked on. A method number of 0 is a plain token transfer - no method exectution.
actor_nametextNOThe full versioned name of the actor that received the message (for example fil/3/storagepower).
actor_familytextNOThe short unversioned name of the actor that received the message (for example storagepower).
exit_codebigintNOThe exit code that was returned as a result of executing the message. Exit code 0 indicates success. Codes 0-15 are reserved for use by the runtime. Codes 16-31 are common codes shared by different actors. Codes 32+ are actor specific.
gas_usedbigintNOA measure of the amount of resources (or units of gas) consumed, in order to execute a message.

internal_parsed_messages

Internal messages parsed to extract useful information.

  • Task: internal_parsed_messages
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
heightbigintNOEpoch this message was executed at.
cidtextNOCID of the message.
fromtextNOAddress of the actor that sent the message.
totextNOAddress of the actor that received the message.
valuenumericNOAmount of FIL (in attoFIL) transferred by this message.
methodtextNOThe method number invoked on the recipient actor. Only unique to the actor the method is being invoked on. A method number of 0 is a plain token transfer - no method exectution.
paramsjsonbYESMethod parameters parsed and serialized as a JSON object.

vm_messages

Messages sent internally through the VM not appearing on chain. Requires the environment variable LOTUS_VM_ENABLE_TRACING=1 to be set before running the lily daemon command.

  • Task: vm_messages
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
heightbigintNOHeight message was executed at.
state_roottextNOCID of the parent state root at which this message was executed.
cidtextNOCID of the message (note this CID does not appear on chain).
sourcetextNOCID of the on-chain message or implicit (internal) message that caused this message to be sent.
fromtextNOAddress of the actor that sent the message.
totextNOAddress of the actor that received the message.
valuenumericNOAmount of FIL (in attoFIL) transferred by this message.
methodbigintNOThe method number invoked on the recipient actor. Only unique to the actor the method is being invoked on. A method number of 0 is a plain token transfer - no method execution
actor_codetextNOThe CID of the actor that received the message.
exit_codebigintNOThe exit code that was returned as a result of executing the message.
gas_usedbigintNOA measure of the amount of resources (or units of gas) consumed, in order to execute a message.
paramsjsonbYESMessage parameters parsed and serialized as a JSON object.
returnsjsonbYESResult returned from executing a message parsed and serialized as a JSON object.

Derived

chain_consensus

Height and TipSet to Parent TipSet or Null Round.

  • Task: chain_consensus
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnDescription
heightEpoch when the blocks were mined in this tipset.
tip_setCID of the tipset or NULL_ROUND
parent_tip_setCID of the parent tipset
parent_state_rootCID of the parent tipset state root

chain_economics

Economic summaries per state root CID.

  • Task: chain_economics
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
heightbigintNOEpoch of the economic summary.
parent_state_roottextNOCID of the parent state root.
circulating_filnumericNOThe amount of FIL (attoFIL) circulating and tradeable in the economy. The basis for Market Cap calculations.
vested_filnumericNOTotal amount of FIL (attoFIL) that is vested from genesis allocation.
mined_filnumericNOThe amount of FIL (attoFIL) that has been mined by storage miners.
burnt_filnumericNOTotal FIL (attoFIL) burned as part of penalties and on-chain computations.
locked_filnumericNOThe amount of FIL (attoFIL) locked as part of mining, deals, and other mechanisms.
fil_reserve_disbursednumericNOThe amount of FIL (attoFIL) that has been disbursed from the mining reserve.

derived_gas_outputs

Derived gas costs resulting from execution of a message in the VM.

  • Task: derived_gas_outputs
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
cidtextNOCID of the message.
fromtextNOAddress of actor that sent the message.
totextNOAddress of actor that received the message.
valuenumericNOThe FIL value transferred (attoFIL) to the message receiver.
gas_fee_capnumericNOThe maximum price that the message sender is willing to pay per unit of gas.
gas_premiumnumericNOThe price per unit of gas (measured in attoFIL/gas) that the message sender is willing to pay (on top of the BaseFee) to “tip” the miner that will include this message in a block.
gas_limitbigintYESA hard limit on the amount of gas (i.e., number of units of gas) that a message’s execution should be allowed to consume on chain. It is measured in units of gas.
size_bytesbigintYESSize in bytes of the serialized message.
noncebigintYESThe message nonce, which protects against duplicate messages and multiple messages with the same values.
methodbigintYESThe method number to invoke. Only unique to the actor the method is being invoked on. A method number of 0 is a plain token transfer - no method exectution.
state_roottextNOCID of the parent state root.
exit_codebigintNOThe exit code that was returned as a result of executing the message. Exit code 0 indicates success. Codes 0-15 are reserved for use by the runtime. Codes 16-31 are common codes shared by different actors. Codes 32+ are actor specific.
gas_usedbigintNOA measure of the amount of resources (or units of gas) consumed, in order to execute a message.
parent_base_feenumericNOThe set price per unit of gas (measured in attoFIL/gas unit) to be burned (sent to an unrecoverable address) for every message execution.
base_fee_burnnumericNOThe amount of FIL (in attoFIL) to burn as a result of the base fee. It is parent_base_fee (or gas_fee_cap if smaller) multiplied by gas_used. Note: successful window PoSt messages are not charged this burn.
over_estimation_burnnumericNOThe fee to pay (in attoFIL) for overestimating the gas used to execute a message. The overestimated gas to burn (gas_burned) is a portion of the difference between gas_limit and gas_used. The over_estimation_burn value is gas_burned * parent_base_fee.
miner_penaltynumericNOAny penalty fees (in attoFIL) the miner incured while executing the message.
miner_tipnumericNOThe amount of FIL (in attoFIL) the miner receives for executing the message. Typically it is gas_premium * gas_limit but may be lower if the total fees exceed the gas_fee_cap.
refundnumericNOThe amount of FIL (in attoFIL) to refund to the message sender after base fee, miner tip and overestimation amounts have been deducted.
gas_refundbigintNOThe overestimated units of gas to refund. It is a portion of the difference between gas_limit and gas_used.
gas_burnedbigintNOThe overestimated units of gas to burn. It is a portion of the difference between gas_limit and gas_used.
heightbigintNOEpoch this message was executed at.
actor_nametextNOHuman readable identifier for the type of the actor.

message_gas_economy

Gas economics for all messages in all blocks at each epoch.

  • Task: message_gas_economy
  • Network Range: [v0 - v∞)
  • Epoch Range: [0 - )
ColumnTypeNullableDescription
state_roottextNOCID of the parent state root at this epoch.
gas_limit_totalnumericNOThe sum of all the gas limits.
gas_limit_unique_totalnumericYESThe sum of all the gas limits of unique messages.
base_feenumericNOThe set price per unit of gas (measured in attoFIL/gas unit) to be burned (sent to an unrecoverable address) for every message execution.
base_fee_change_logdouble precisionNOThe logarithm of the change between new and old base fee.
gas_fill_ratiodouble precisionYESThe gas_limit_total / target gas limit total for all blocks.
gas_capacity_ratiodouble precisionYESThe gas_limit_unique_total / target gas limit total for all blocks.
gas_waste_ratiodouble precisionYES(gas_limit_total - gas_limit_unique_total) / target gas limit total for all blocks.
heightbigintNOEpoch these economics apply to.

FEVM

fevm_block_headers

Blocks included in tipsets at an epoch.

  • Task: fevm_block_header
  • Network Range: [v18 - v∞)
  • Epoch Range: [2683348 - )
ColumnTypeNullableDescription
heightbigintNOEpoch when this block was mined.
hashtextNOBlock hash.
parent_hashtextNOThe hash of the preceding block.
minertextNOETH Address of the miner who mined this block.
state_roottextNOBlock state root ETH hash.
transactions_roottextNOSet to a hardcoded value which is used by some clients to determine if has no transactions.
receipts_roottextNOHash of the transaction receipts trie.
difficultybigintNOETH mining difficulty.
numberbigintNOThe number of the current block.
gas_limitbigintNOMaximum gas allowed in this block.
gas_usedbigintNOThe actual amount of gas used in this block.
timestampbigintNOThe block time.
extra_datatextYESArbitrary additional data as raw bytes.
base_fee_per_gastextNOThe base fee value.
sizebigintNOBlock size.

fevm_transactions

Transactions, which change the state of the EVM, need to be broadcast to the whole network.

  • Task: fevm_transaction
  • Network Range: [v18 - v∞)
  • Epoch Range: [2683348 - )
ColumnTypeNullableDescription
heightbigintNOEpoch when this transaction been created.
hashtextNOHash of transaction.
transaction_indexbigintNOInteger of the transactions index position in the block.
block_hashtextNOHash of the block where this transaction was in.
block_numberbigintNOBlock number where this transaction was in.
noncebigintNOA sequentially incrementing counter which indicates the transaction number from the account.
fromtextNOAddress of the sender.
totextYESAddress of the receiver. null when its a contract creation transaction.
chain_idbigintNOEVM network id.
valuetextNOAmount of attoFIL to transfer from sender to recipient.
inputtextNOThe data sent along with the transaction.
typetextNOType of transactions.
gasbigintNOGas provided by the sender.
max_fee_per_gasnumericNOThe maximum fee per unit of gas willing to be paid for the transaction.
max_priority_fee_per_gasnumericNOThe maximum price of the consumed gas to be included as a tip to the validator.
vbigintNOTransaction’s signature. Recovery Identifier.
rbigintNOTransaction’s signature. Outputs of an ECDSA signature.
sbigintNOTransaction’s signature. Putputs of an ECDSA signature.
from_filecoin_addresstextNOFilecoin Address of the sender.
to_filecoin_addresstextYESFilecoin Address of the receiver.
from_actor_nametextNOHuman-readable identifier of sender (From).
to_actor_nametextYESHuman-readable identifier of receiver (To).
message_cidtextNOOn-chain message cid.

fevm_receipts

Data returned by an Ethereum client to represent the result of a particular transaction

  • Task: fevm_receipt
  • Network Range: [v18 - v∞)
  • Epoch Range: [2683348 - )
ColumnTypeNullableDescription
heightbigintNOEpoch when this receipt been created.
transaction_hashtextNOHash of transaction.
transaction_indexbigintNOInteger of the transactions index position in the block.
block_hashtextNOHash of the block where this transaction was in.
block_numberbigintNOBlock number where this transaction was in.
fromtextNOAddress of the sender.
totextNOAddress of the receiver. null when its a contract creation transaction.
contract_addresstextYESThe contract address created, if the transaction was a contract creation, otherwise null.
statusbigintNO0 indicates transaction failure , 1 indicates transaction succeeded.
cumulative_gas_usedbigintNOThe total amount of gas used when this transaction was executed in the block.
gas_usedbigintNOThe actual amount of gas used in this block.
effective_gas_pricebigintNOThe actual value per gas deducted from the senders account.
logs_bloomtextYESIncludes the bloom filter representation of the logs.
logsjsonbNOArray of log objects, which this transaction generated.
messagetextNOThe cid in filecoin

fevm_trace

Messages sent internally through the VM not appearing on chain.

  • Task: fevm_traces
  • Network Range: [v18 - v∞)
  • Epoch Range: [2683348 - )
ColumnTypeNullableDescription
heightbigintNOEpoch when this trace been created.
message_state_toottextNOStateRoot message was applied to.
message_cidtextNOOn-chain message triggering the message.
transaction_hashtextNOOn-chain message ETH transaction hash.
trace_cidtextNOCid of the trace.
fromtextNOAddress of the sender.
totextYESAddress of the receiver. null when its a contract creation transaction.
from_filecoin_addresstextNOFilecoin Address of the sender.
to_filecoin_addresstextYESFilecoin Address of the receive.
valuenumericNOValue attoFIL contained in message.
methodbigintNOMethod called on To (receiver).
parsed_methodtextNOMethod in readable name.
actor_codetextNOActorCode of To (receiver).
exit_codebigintNOExitCode of message execution.
paramstextNOParams contained in message encode in eth bytes.
returnstextNOReturns value of message receipt encode in eth bytes.
indexbigintNOIndex indicating the order of the messages execution.
parsed_paramsjsonbNOParsed Params contained in message.
parsed_returnsjsonbNOParsed Returns value of message receipt.
params_codecbigintNOParams codec.
returns_codecbigintNOReturns codec.
from_actor_nametextNOHuman-readable identifier of sender (From).
to_actor_nametextYESHuman-readable identifier of receiver (To).