CINXE.COM

<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="/css/layout.css?1732633144785"> <link rel="stylesheet" href="/css/nav.css?1732633144785"> <link rel="stylesheet" href="/css/style.css?1732633144785"> <link rel="stylesheet" href="/css/prismjs@1.24-themes-prism.css"> <title>IPLD ♦ </title> </head> <body> <header> <div class="sidebar-button" onclick="document.getElementById('sidebar').classList.toggle('sidebar-open')"> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"> <path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path> </svg> </div> <a href="/" class="logo">IPLD</a> <aside id=breadcrumbs> <ul> <li><a href="/specs">specs</a></li> <li><a href="/specs/codecs">codecs</a></li> <li><a href="/specs/codecs/dag-eth">dag-eth</a></li> <li><a href="/specs/codecs/dag-eth/chain/">chain</a></li> </ul> </aside> </header> <aside id=sidebar> <nav> <ul> <li> <a href="/docs/">Docs</a><ul> <li> <a href="/docs/intro/">Intro</a><ul> <li> <a href="/docs/intro/hello-world/">Hello, World</a></li> <li> <a href="/docs/intro/primer/">The Brief Primer</a></li> <li> <a href="/docs/intro/ecosystem/">InterPlanetary Ecosystem Overview</a></li> <li> <a href="/docs/intro/community/">Finding Community</a></li></ul></li> <li> <a href="/docs/motivation/">Motivation</a><ul> <li> <a href="/docs/motivation/benefits-of-content-addressing/">Benefits of Content Addressing</a></li> <li> <a href="/docs/motivation/data-to-data-structures/">From Data to Data Structures</a></li></ul></li> <li> <a href="/docs/codecs/">Codecs</a><ul> <li> <a href="/docs/codecs/known/">Known Codecs</a><ul> <li> <a href="/docs/codecs/known/dag-cbor/">DAG-CBOR</a></li> <li> <a href="/docs/codecs/known/dag-json/">DAG-JSON</a></li> <li> <a href="/docs/codecs/known/dag-pb/">DAG-PB</a></li></ul></li></ul></li> <li> <a href="/docs/data-model/">Data Model</a><ul> <li> <a href="/docs/data-model/node/">Nodes</a></li> <li> <a href="/docs/data-model/kinds/">Kinds</a></li> <li> <a href="/docs/data-model/pathing/">Pathing</a></li> <li> <a href="/docs/data-model/traversal/">Traversal</a></li></ul></li> <li> <a href="/docs/advanced-data-layouts/">Advanced Data Layouts</a><ul> <li> <a href="/docs/advanced-data-layouts/intro/">Intro to ADLs</a></li> <li> <a href="/docs/advanced-data-layouts/naming/">ADL Naming</a></li> <li> <a href="/docs/advanced-data-layouts/signalling/">Signalling ADLs</a></li> <li> <a href="/docs/advanced-data-layouts/dynamic-loading/">Dynamic Loading</a></li> <li> <a href="/docs/advanced-data-layouts/known/">Known ADLs</a></li></ul></li> <li> <a href="/docs/schemas/">Schemas</a><ul> <li> <a href="/docs/schemas/intro/">Introduction</a><ul> <li> <a href="/docs/schemas/intro/compare/">compare</a></li> <li> <a href="/docs/schemas/intro/goals/">Goals</a></li> <li> <a href="/docs/schemas/intro/feature-summary/">Feature Summary</a></li></ul></li> <li> <a href="/docs/schemas/features/">Features</a><ul> <li> <a href="/docs/schemas/features/typekinds/">Type Kinds</a></li> <li> <a href="/docs/schemas/features/representation-strategies/">Representation Strategies</a></li> <li> <a href="/docs/schemas/features/links/">Links</a></li> <li> <a href="/docs/schemas/features/indicating-adls/">Using ADLs in Schemas</a></li></ul></li> <li> <a href="/docs/schemas/using/">Using Wisely</a><ul> <li> <a href="/docs/schemas/using/authoring-guide/">Authoring Guide</a></li> <li> <a href="/docs/schemas/using/migrations/">Migrations</a></li></ul></li></ul></li> <li> <a href="/docs/synthesis/">Synthesis</a><ul> <li> <a href="/docs/synthesis/gtd/">Getting Things Done</a></li> <li> <a href="/docs/synthesis/building-in-alignment/">Building in Alignment</a></li> <li> <a href="/docs/synthesis/how-ipfs-web-gateways-work/">How IPFS Web Gateways Work</a></li> <li> <a href="/docs/synthesis/encryption/">Working With Encryption</a></li></ul></li></ul></li> <li> <a href="/specs/">Specs</a><ul> <li> <a href="/specs/about/">About the Specifications</a></li> <li> <a href="/specs/codecs/">Codecs</a><ul> <li> <a href="/specs/codecs/dag-cbor/">DAG-CBOR</a><ul> <li> <a href="/specs/codecs/dag-cbor/spec/">Spec</a></li> <li> <a href="/specs/codecs/dag-cbor/fixtures/">DAG-CBOR Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-cbor/fixtures/cross-codec/">cross-codec</a></li></ul></li></ul></li> <li> <a href="/specs/codecs/dag-cosmos/">DAG-COSMOS</a><ul> <li> <a href="/specs/codecs/dag-cosmos/basic_types/">basic_types</a></li> <li> <a href="/specs/codecs/dag-cosmos/cosmos_state/">cosmos_state</a></li> <li> <a href="/specs/codecs/dag-cosmos/crypto_types/">crypto_types</a></li> <li> <a href="/specs/codecs/dag-cosmos/tendermint_chain/">tendermint_chain</a></li> <li> <a href="/specs/codecs/dag-cosmos/typed_protobuf/">typed_protobuf</a></li></ul></li> <li> <a href="/specs/codecs/dag-eth/">DAG-ETH</a><ul> <li> <a href="/specs/codecs/dag-eth/basic_types/">basic_types</a></li> <li class="active-page"> <a href="/specs/codecs/dag-eth/chain/">chain</a></li> <li> <a href="/specs/codecs/dag-eth/convenience_types/">convenience_types</a></li> <li> <a href="/specs/codecs/dag-eth/state/">state</a></li></ul></li> <li> <a href="/specs/codecs/dag-jose/">DAG-JOSE</a><ul> <li> <a href="/specs/codecs/dag-jose/spec/">Spec</a></li> <li> <a href="/specs/codecs/dag-jose/fixtures/">fixtures</a></li></ul></li> <li> <a href="/specs/codecs/dag-json/">DAG-JSON</a><ul> <li> <a href="/specs/codecs/dag-json/spec/">Spec</a></li> <li> <a href="/specs/codecs/dag-json/fixtures/">DAG-JSON Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-json/fixtures/cross-codec/">cross-codec</a></li></ul></li></ul></li> <li> <a href="/specs/codecs/dag-pb/">DAG-PB</a><ul> <li> <a href="/specs/codecs/dag-pb/spec/">Spec</a></li> <li> <a href="/specs/codecs/dag-pb/fixtures/">DAG-PB Test Fixtures</a><ul> <li> <a href="/specs/codecs/dag-pb/fixtures/cross-codec/">cross-codec</a></li></ul></li></ul></li></ul></li> <li> <a href="/specs/advanced-data-layouts/">Advanced Data Layouts</a><ul> <li> <a href="/specs/advanced-data-layouts/fbl/">FBL ADL</a><ul> <li> <a href="/specs/advanced-data-layouts/fbl/spec/">spec</a></li></ul></li> <li> <a href="/specs/advanced-data-layouts/hamt/">HAMT ADL</a><ul> <li> <a href="/specs/advanced-data-layouts/hamt/spec/">spec</a></li> <li> <a href="/specs/advanced-data-layouts/hamt/fixture/">HashMap (HAMT) Test Fixtures</a><ul> <li> <a href="/specs/advanced-data-layouts/hamt/fixture/alice-words/">alice-words</a></li></ul></li></ul></li></ul></li> <li> <a href="/specs/schemas/">Schemas</a><ul> <li> <a href="/specs/schemas/prelude/">prelude</a></li></ul></li> <li> <a href="/specs/transport/">Transports</a><ul> <li> <a href="/specs/transport/car/">CAR</a><ul> <li> <a href="/specs/transport/car/carv1/">CARv1 Specification</a></li> <li> <a href="/specs/transport/car/carv2/">CARv2 Specification</a></li> <li> <a href="/specs/transport/car/fixture/">CAR Test Fixtures</a><ul> <li> <a href="/specs/transport/car/fixture/carv1-basic/">carv1-basic</a></li> <li> <a href="/specs/transport/car/fixture/carv2-basic/">carv2-basic</a></li></ul></li></ul></li> <li> <a href="/specs/transport/graphsync/">Graphsync</a><ul> <li> <a href="/specs/transport/graphsync/known_extensions/">known_extensions</a></li></ul></li> <li> <a href="/specs/transport/trustless-pathing/">Trustless Pathing</a><ul> <li> <a href="/specs/transport/trustless-pathing/fixtures/">Trustless Pathing Fixtures</a><ul> <li> <a href="/specs/transport/trustless-pathing/fixtures/unixfs_20m_variety/">unixfs_20m_variety</a></li></ul></li></ul></li></ul></li> <li> <a href="/specs/selectors/">Selectors</a><ul> <li> <a href="/specs/selectors/fixtures/">fixtures</a><ul> <li> <a href="/specs/selectors/fixtures/selector-fixtures-1/">selector-fixtures-1</a></li> <li> <a href="/specs/selectors/fixtures/selector-fixtures-adl/">selector-fixtures-adl</a></li> <li> <a href="/specs/selectors/fixtures/selector-fixtures-recursion/">selector-fixtures-recursion</a></li></ul></li></ul></li> <li> <a href="/specs/patch/">Patch</a><ul> <li> <a href="/specs/patch/fixtures/">IPLD Patch Test Fixtures</a><ul> <li> <a href="/specs/patch/fixtures/fixtures-1/">fixtures-1</a></li></ul></li></ul></li></ul></li> <li> <a href="/libraries/">Libraries</a><ul> <li> <a href="/libraries/golang/">Golang</a></li> <li> <a href="/libraries/javascript/">JavaScript</a></li> <li> <a href="/libraries/python/">Python</a></li> <li> <a href="/libraries/rust/">Rust</a></li></ul></li> <li> <a href="/design/">Design</a><ul> <li> <a href="/design/objectives/">Objectives</a></li> <li> <a href="/design/concepts/">Concepts</a><ul> <li> <a href="/design/concepts/type-theory-glossary/">type-theory-glossary</a></li></ul></li> <li> <a href="/design/libraries/">Libraries</a><ul> <li> <a href="/design/libraries/nodes-and-kinds/">nodes-and-kinds</a></li></ul></li> <li> <a href="/design/tricky-choices/">Tricky Choices</a><ul> <li> <a href="/design/tricky-choices/dag-pb-forms-impl-and-use/">dag-pb-forms-impl-and-use</a></li> <li> <a href="/design/tricky-choices/map-key-domain/">map-key-domain</a></li> <li> <a href="/design/tricky-choices/numeric-domain/">numeric-domain</a></li> <li> <a href="/design/tricky-choices/ordering/">ordering</a></li> <li> <a href="/design/tricky-choices/string-domain/">string-domain</a></li></ul></li> <li> <a href="/design/open-research/">Open Research</a><ul> <li> <a href="/design/open-research/ADL-autoexecution/">ADL autoexecution</a></li></ul></li></ul></li> <li> <a href="/tools/">Tools</a></li> <li> <a href="/glossary/">Glossary</a></li> <li> <a href="/media/">Media</a></li> <li> <a href="/FAQ/">FAQ</a></li></ul> </nav> </aside> <main> <div class=content> <h1>Ethereum Chain Data Structures</h1> 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 <a href="../state">state</a> 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 <a href="https://eth.wiki/en/fundamentals/rlp">here</a>. The list of CID multicodec types, including the multicodec types used for Ethereum objects, can be found <a href="https://github.com/multiformats/multicodec/blob/master/table.csv">here</a>. The KECCAK_256 multihash is used for all Ethereum CIDs, more info on multihashes can be found <a href="https://github.com/multiformats/multihash">here</a> and more info on the KECCAK_256 hash function can be found <a href="https://csrc.nist.gov/projects/hash-functions/sha-3-project">here</a>. 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 <a href="https://www.nist.gov/news-events/news/2012/10/nist-selects-winner-secure-hash-algorithm-sha-3-competition">NIST competition</a>. Both KECCAK_256 and SHA_3 use the same underlying Keccak hashing algorithm but use different padding, and so their output do not match. <h2 id="header-ipld" tabindex="-1"><a class="header-anchor" href="#header-ipld">Header IPLD</a></h2> This is the IPLD schema for a canonical Ethereum block header. <ul> <li>The IPLD block is the RLP encoded header <ul> <li>Before EIP-1559 activation: <code>RLP([ParentHash, UnclesHash, Coinbase, StateRoot, TxRoot, RctRoot, Bloom, Difficulty, Number, GasLimit, GasUsed, Time, Extra, MixDigest, Nonce])</code>.</li> <li>After EIP-1559 activation: <code>RLP([ParentHash, UnclesHash, Coinbase, StateRoot, TxRoot, RctRoot, Bloom, Difficulty, Number, GasLimit, GasUsed, Time, Extra, MixDigest, Nonce, BaseFee])</code>.</li> </ul> </li> <li>CID links to a <code>Header</code> use a KECCAK_256 mutlihash of the RLP encoded header and the EthHeader codec (0x90).</li> <li>Parent headers are referenced back to by their child header.</li> <li>The genesis header is unique in that it does not reference a parent header in <code>ParentCID</code>, instead it contains a reference to a <code>GenesisInfo</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># 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 }</code></pre> <h2 id="uncles-ipld" tabindex="-1"><a class="header-anchor" href="#uncles-ipld">Uncles IPLD</a></h2> This is the IPLD schema for a list of uncles ordered in ascending order by their block number. <ul> <li>The IPLD block is the RLP encoded list of uncles: <code>RLP([Header, Header, ...])</code>.</li> <li>CID links to a <code>UncleList</code> use a KECCAK_256 multihash of the RLP encoded list and the EthHeaderList codec (0x91).</li> <li>The <code>Uncles</code> is referenced in an Ethereum <code>Header</code> by the <code>UnclesCID</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># 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]</code></pre> <h2 id="transaction-ipld" tabindex="-1"><a class="header-anchor" href="#transaction-ipld">Transaction IPLD</a></h2> This is the IPLD schema for a canonical Ethereum transaction. It contains only the fields required for consensus. <ul> <li>The IPLD block is the consensus encoding of the transaction: <ul> <li>Legacy transaction encoding: <code>RLP([AccountNonce, GasPrice, GasLimit, Recipient, Amount, Data, V, R, S])</code>. <ul> <li>The V, R, S elements of this transaction either represent a secp256k1 signature over <code>KECCAK_256(RLP([AccountNonce, GasPrice, GasLimit, Recipient, Amount, Data]))</code> OR over <code>KECCAK_256(RLP([AccountNonce, GasPrice, GasLimit, Recipient, Amount, Data, ChainID, 0, 0]))</code> as described by <a href="https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md">EIP-155</a>.</li> </ul> </li> <li>Access list (EIP-2930) transaction encoding: <code>0x01 || RLP([ChainID, AccountNonce, GasPrice, GasLimit, Recipient, Amount, Data, AccessList, V, R, S]</code>. <ul> <li>The V, R, S elements of this transaction represent a secp256k1 signature over <code>KECCAK_256(0x01 || RLP([ChainID, AccountNonce, GasPrice, GasLimit, Recipient, Amount, Data, AccessList])</code>.</li> <li><code>||</code> is the byte/byte-array concatenation operator.</li> </ul> </li> <li>Dynamic fee (EIP-1559) transaction encoding: <code>0x02 || RLP([ChainID, AccountNonce, GasTipCap, maxFeePerGas, GasFeeCap, Recipient, Amount, Data, AccessList, V, R, S]</code> <ul> <li>The V, R, S elements of this transaction represent a secp256k1 signature over <code>KECCAK_256(0x02 || RLP([ChainID, AccountNonce, GasTipCap, maxFeePerGas, GasFeeCap, Recipient, Amount, Data, AccessList]</code></li> </ul> </li> </ul> </li> <li>CID links to a <code>Transaction</code> use a KECCAK_256 multihash of the encoded transaction and the EthTx codec (0x93).</li> <li><code>Transaction</code> IPLDs are not referenced directly from an <code>Ethereum</code> header but are instead linked to from within the transaction trie whose root is referenced in the <code>Header</code> by the <code>TxRootCID</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># 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 transaction 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]</code></pre> <h2 id="receipt-ipld" tabindex="-1"><a class="header-anchor" href="#receipt-ipld">Receipt IPLD</a></h2> This is the IPLD schema for a canonical Ethereum receipt. It contains only the fields required for consensus. <ul> <li>The IPLD block is the consensus encoding of the receipt: <ul> <li>Legacy receipt encoding: <code>RLP([PostStateOrStatus, CumulativeGasUsed, Bloom, Logs])</code>. <ul> <li>Before EIP-658 (included in the Byzantium hardfork) <code>PostStateOrStatus</code> holds the PostState, a 32 byte intermediate state root hash</li> <li>After EIP-658 <code>PostStateOrStatus</code> holds the RLP encoded Status uint64 indicating if the tx succeeded or failed (0 - failed, 1 - successful)</li> </ul> </li> <li>Access list (EIP-2930) receipt encoding: <code>0x01 || RLP([PostStateOrStatus, CumulativeGasUsed, Bloom, Logs])</code>. <ul> <li><code>||</code> is the byte/byte-array concatenation operator.</li> </ul> </li> <li>Dynamic fee (EIP-1559) receipt encoding: <code>0x02 || RLP([PostStateOrStatus, CumulativeGasUsed, Bloom, Logs])</code></li> </ul> </li> <li>CID links to a <code>Receipt</code> use a KECCAK_256 multihash of the encoded receipt and the EthTxReceipt codec (0x95).</li> <li><code>Receipt</code> IPLDs are not referenced directly from an <code>Ethereum</code> header but are instead linked to from within the receipt trie whose root is referenced in the <code>Header</code> by the <code>RctRootCID</code>.</li> </ul> <pre class="language-ipldsch"><code class="language-ipldsch"># 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 successful 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]</code></pre> </div> </main> </body> </html>