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.

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.