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.

Recursive length prefix (RLP) encoding is used extensively as the binary encoded format for Ethereum IPLD blocks, more info on RLP encoding can be found here.

The list of CID multicodec types, including the multicodec types used for Ethereum objects, can be found here.

The KECCAK_256 multihash is used for all Ethereum CIDs, more info on multihashes can be found here and more info on the KECCAK_256 hash function can be found here. Note that KECCAK_256 used by Ethereum is distinguished from SHA_3 (FIPS 202), KECCAK_256 refers to the original algorithm that won the 2012 NIST competition. Both KECCAK_256 and SHA_3 use the same underlying Keccak hashing algorithm but use different padding, and so their output do not match.

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
    GasUsed Uint
    Time Time
    Extra Bytes
    MixDigest Hash
    Nonce BlockNonce
    BaseFee nullable BigInt  # BaseFee is null unless the header is post-EIP-1559
}

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.

# Transaction contains the consensus fields of an Ethereum transaction
type Transaction struct {
    Type         TxType
    ChainID      nullable BigInt # null unless the transaction is an EIP-2930 or EIP-1559 transaction
    AccountNonce Uint
    GasPrice     nullable BigInt # null if the transaction is an EIP-1559 transaction
    GasTipCap    nullable BigInt # null unless the transaciton is an EIP-1559 transaction
    GasFeeCap    nullable BigInt # null unless the transaction is an EIP-1559 transaction
    GasLimit     Uint
    Recipient    nullable Address # null recipient means the tx is a contract creation tx
    Amount       BigInt
    Data         Bytes
    AccessList   nullable AccessList # null unless the transaction is an EIP-2930 or EIP-1559 transaction
    
    # Signature values
    V            BigInt
    R            BigInt
    S            BigInt
}

// AccessList is an EIP-2930 access list.
type AccessList [AccessElement]

// AccessElement are the element type of an access list.
type AccessElement struct {
    Address     Address
    StorageKeys StorageKeys
}

// StorageKeys are the keys contained in an AccessElement
type StorageKeys [Hash]

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 {
    Type              TxType
    PostState         nullable Hash
    PostStatus        nullable Status
    CumulativeGasUsed Uint
    Bloom             Bloom
    Logs              [Log]
}

# Status is an enum indicating whether or not the application of a tx was succesful
type Status enum {
    | Failed  ("0")
    | Successful   ("1")
} representation int

# Logs is a list of logs
type Logs [Log]

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

# Topics is a list of log topics
type Topics [Hash]