History Network

Note that this network is not yet fully production-ready

The chain history data consists of historical block headers, block bodies (transactions and ommer) and block receipts. It is expected that this network will one day allow clients that have pruned historical blocks to retrieve them on-demand from this network, and nodes may be able to use blocks downloaded from the History Network to sync, rather than maintaining a local copy of the blockchain.

The History Network is a Kademlia DHT that uses the Portal Wire Protocol to establish an overlay network on top of the Discovery v5 protocol.

The History Network also provides a hash accumulator that enables clients to verify that a header is at a particular block number in the pre-merge Ethereum mainnet chain.

Data

Portal clients can retrieve the following data types from the History Network:

Block headers
Block bodies
- Transactions
- Ommers
Receipts
Header epoch accumulators (pre-merge only)

Data Types

Block Header

Block header data can include:

A BlockHeaderWithProof
A BlockHeaderProof
An AccumulatorProof

The BlockHeaderWithProof is the actual block header data wrapped in a higher level structure with a Merkle proof demonstrating its inclusion in the canonical Ethereum chain. The proof is of type BlockHeaderProof, which is a Union that can be either None or AccumulatorProof. The header field in BlockHeaderWithProof contains the RLP encoded header encoded as an SSZ bytelist.

For pre-merge headers, clients SHOULD NOT accept headers without a proof as there is the AccumulatorProof solution available. For post-merge headers, clients SHOULD accept headers without a proof, and determine validity using the Beacon network.

Block headers are retrieved from the network by specifying a content key generated by concatenating the identifier 0x00 and the target block hash.

Block Body

The block body contains the complete list of transactions that were included in the block and the list of ommers (blocks produced simultaneously but not included in the canonical chain). The encoding for block bodies changed at the Shanghai upgrade (see EIP-4895 (opens in a new tab)), meaning Portal clients now have to detect whether a block is pre-Shanghai or post-Shanghai to determine how they should be decoded. Clients that request block bodies from the History Network execute this sequence of operations:

Receive raw block body content.
Fetch the block's header from the network.
Compare header timestamp against SHANGHAI_TIMESTAMP.
Decode the block body using either pre-shanghai or post-shanghai encoding.
Validate the decoded block body against the roots in the header.

Block bodies are retrieved from the network by specifying a content key generated by concatenating the identifier 0x01 and the target block hash.

Receipts

Receipts record the outcome of transactions, including transaction logs. Portal provides RLP-encoded receipts as SSZ bytelists.

Receipts are retrieved from the network by specifying a content key generated by concatenating the identifier 0x02 and the target block hash.

See section 4.3.1 in the yellow paper (opens in a new tab)

Epoch Accumulator

Portal clients can request the accumulator hash for any epoch. This is the root hash for a Merkle trie with blocks as leaves and is unique to a specific epoch. Proofs are generated by generating a path from an individual block hash to the epoch root hash. The epoch hashes are added as leaves in a master accumulator.

Epoch accumulator hashes are retrieved from the network by specifying a content key generated by concatenating the identifier 0x03 and the target epoch hash.

Data Retrieval

The network supports the following mechanisms for data retrieval:

Block header by block header hash
Block body by block header hash
Block receipts by block header hash
Header epoch accumulator by epoch accumulator hash

This sub-protocol does not support retrieval of transactions by hash, only the full set of transactions for a given block. See the "Canonical Transaction Index" sub-protocol of the Portal Network for more information on how the portal network implements lookup of transactions by their individual hashes.

Specification

You can find the History Network specification on the Portal Network Github (opens in a new tab).

Portal Sub-protocols Beacon