EIP-4881 Deposit Contract Snapshot Interface

Final · Networking & nodes · EIP status Final · created 2021-01-29

Defines a standard format and API endpoint that lets a consensus client starting a fresh sync quickly restore the deposit tree from a compressed Merkle tree snapshot, instead of downloading the entire history of past deposit records.

Why it is needed

To become a validator on Ethereum, you deposit ETH into the deposit contract, and the beacon chain verifies that record using a data structure called a Merkle tree. However, to rebuild this tree, most clients have to download and store every deposit log since the contract was created. This means they hold far more data than is actually needed to participate in consensus, and it lengthens the sync time for new nodes. This delay is especially pronounced in weak subjectivity sync, which starts directly from a recent checkpoint. It also blocks discussions about pruning old contract logs from full nodes to reduce state size, since every node has to keep holding onto the past logs. This EIP solves the problem by letting the tree be restored from a single compressed snapshot of deposits that have already been finalized.

What changes

Today

After EIP-4881

Who is affected

In depth

DepositTreeSnapshot structure

The snapshot consists of five fields. finalized is a variable-length list (up to DEPOSIT_CONTRACT_DEPTH) holding the hashes of finalized subtrees. deposit_root, deposit_count, and execution_block_hash carry the same information as the Eth1Data at that point, and execution_block_height is the execution block height corresponding to that block hash. Clients are free (MAY) to implement the tree internally however they like, but when transmitting to a newly syncing node they must (MUST) use this format.

Beacon Node API endpoint

Consensus clients must (MUST) serve this structure at the /eth/v1/beacon/deposit_snapshot endpoint. A newly syncing node obtains all the information it needs to restore the tree from this single endpoint.

Deposit finalization flow and pruning

When the beacon chain processes a deposit, it requires a Merkle path up to the deposit root, which is needed exactly once per deposit. Once a deposit has been processed and the finalization conditions are met, many of the hashes along the path to the root are never used again to generate an on-chain Merkle proof. These unnecessary hashes may (MAY) be deleted. In the reference implementation, calling tree.finalize() prunes the tree by folding the finalized subtree into a Finalized node (a count and a single hash).

Two finalization conditions

Deposits not yet fully included under a finalized checkpoint must not be placed in the snapshot. Treating a given Eth1Data (eth1data) as finalized requires meeting both (MUST) of the following conditions. First, there must exist a finalized checkpoint whose state satisfies state.eth1_data == eth1data. Second, there must exist a finalized checkpoint whose state satisfies state.eth1_deposit_index >= eth1data.deposit_count. Under normal operation, state.eth1_data is replaced every EPOCHS_PER_ETH1_VOTING_PERIOD epochs, so tree finalization also proceeds in that unit. Once the conditions are met, the tree can be pruned via tree.finalize(eth1data, execution_block_height).

Why not restore directly from the contract or the beacon chain

The deposit contract can only provide the tree as of the chain head. The deposit contract view seen by the beacon chain lags the execution chain by ETH1_FOLLOW_DISTANCE, so there is almost always an unincluded deposit that requires a proof built against an earlier version of the tree than the head. There is also a method of working backward from the beacon chain's Deposit, but it has many edge cases in finding a deposit to anchor on, making implementation difficult, turns block backfill into a prerequisite for block production, and is inherently slower than receiving directly from a weak subjectivity checkpoint.

Why fields that look redundant are included

Strictly speaking, only one of execution_block_hash and execution_block_height is necessary, but different clients design their block caches around one or the other. If only one is sent, some clients would have to query the execution engine for the rest, and during a fresh sync the execution engine is also likely not yet synced (especially post-Merge). deposit_root is not strictly required either, but including it lets the receiving client self-verify the snapshot with calculate_root().

Weak subjectivity assumptions and the reference implementation

This proposal relies on the assumption that, because of long-range attacks, a new node bootstraps from a valid weak subjectivity checkpoint. It presumes the node does not start from an incorrect checkpoint. In the reference implementation, a snapshot is created with tree.get_snapshot() and the tree is recovered with DepositTree.from_snapshot(). Proofs against earlier versions of the tree can also be generated quickly by appending the remaining deposits to a copy of the snapshot via push_leaf and then calling get_proof(index). Test cases (test_cases.yaml) and execution code are provided together and can be run with pytest. This EIP's status is Final, meaning the specification is settled.

Original EIP · ← EIPs