Ethereum Chain Data Structures

This section contains the IPLD schemas for the blockchain data structures of Ethereum. This includes: headers, uncle sets, transactions, and receipts. The state trie, storage trie, receipt trie, and transaction trie IPLDs are described in the state section. It is important to note that traversal from header to a specific transaction or receipt requires traversal across their respective tries beginning at the root referenced in the header. Alternatively, uncles are referenced directly from the header by the hash of the RLP encoded list of uncles.

Header IPLD

This is the IPLD schema for a canonical Ethereum block header.

# Header contains the consensus fields of an Ethereum block header
type Header struct {
    # CID link to the parent header
    # This CID is composed of the KECCAK_256 multihash of the linked RLP encoded header and the EthHeader codec (0x90)
    ParentCID &Header
    
    # CID link to the list of uncles at this block
    # This CID is composed of the KECCAK_256 multihash of the RLP encoded list of Uncles and the EthHeaderList codec (0x91)
    # Note that an uncle is simply a header that does not have an associated body
    UnclesCID &Uncles
    Coinbase Address
    
    # CID link to the root node of the state trie
    # This CID is composed of the KECCAK_256 multhash of the RLP encoded state trie root node and the EthStateTrie codec (0x96)
    # This steps us down into the state trie, from which we can link to the rest of the state trie nodes and all the linked storage tries
    StateRootCID &StateTrieNode
    
    # CID link to the root node of the transaction trie
    # This CID is composed of the KECCAK_256 multihash of the RLP encoded tx trie root node and the EthTxReceiptTrie codec (0x92)
    # This steps us down into the transaction trie, from which we can link to the rest of the tx trie nodes and all of the linked transactions
    TxRootCID &TxTrieNode
    
    # CID link to the root of the receipt trie
    # This CID is composed of the KECCAK_256 multihash of the RLP encoded rct trie root node and the EthTxReceiptTrie codec (0x94)
    # This steps us down into the receipt trie, from which we can link to the rest of the rct trie nodes and all of the linked receipts
    RctRootCID &RctTrieNode
    
    Bloom Bloom
    Difficulty BigInt
    Number BigInt
    GasLimit Uint
    GasUser Uint
    Time Uint
    Extra Bytes
    MixDigest Hash
    Nonce BlockNonce
}

Uncles IPLD

This is the IPLD schema for a list of uncles ordered in ascending order by their block number.

# Uncles contains an ordered list of Ethereum uncles (headers that have no associated body)
# This IPLD object is referenced by a CID composed of the KECCAK_256 multihash of the RLP encoded list and the EthHeaderList codec (0x91)
type Uncles [Header]

Transaction IPLD

This is the IPLD schema for a canonical Ethereum transaction. It contains only the fields required for consensus. Note that this will need to be updated once EIP-1559 and EIP-2718 are approved.

# Transaction contains the consensus fields of an Ethereum transaction
type Transaction struct {
    AccountNonce Uint
    Price        BigInt
    GasLimit     Uint
    Recipient    nullable Address # null recipient means the tx is a contract creation
    Amount       BigInt
    Payload      Bytes
    
    # Signature values
    V            BigInt
    R            BigInt
    S            BigInt
}

Receipt IPLD

This is the IPLD schema for a canonical Ethereum receipt. It contains only the fields required for consensus.

# Receipt contains the consensus fields of an Ethereum receipt
type Receipt struct {
    PostStateOrStatus Bytes
    CumulativeGasUsed Uint
    Bloom             Bloom
    Logs              [Log]
}

# Log contains the consensus fields of an Etherem receipt log
type Log struct {
    Address Address
    Topics  [Hash]
    Data    Bytes
}