---
eip: 2935
title: Serve historical block hashes from state
description: Store and serve last 8191 block hashes as storage slots of a system contract to allow for stateless execution
author: Vitalik Buterin (@vbuterin), Tomasz Stanczak (@tkstanczak), Guillaume Ballet (@gballet), Gajinder Singh (@g11tech), Tanishq Jasoria (@tanishqjasoria), Ignacio Hagopian (@jsign), Jochem Brouwer (@jochem-brouwer), Sina Mahmoodi (@s1na)
discussions-to: https://ethereum-magicians.org/t/eip-2935-save-historical-block-hashes-in-state/4565
status: Final
type: Standards Track
category: Core
created: 2020-09-03
---

## Abstract

Store last `HISTORY_SERVE_WINDOW` historical block hashes in the storage of a system contract as part of the block processing logic. Furthermore this EIP has no impact on `BLOCKHASH` resolution mechanism (and hence its range/costs etc).

## Motivation

EVM implicitly assumes the client has the recent block (hashes) at hand. This assumption is not future-proof given the prospect of stateless clients. Including the block hashes in the state will allow bundling these hashes in the witness provided to a stateless client. This is already possible in the MPT and will become more efficient post-Verkle.

Extending the range of blocks which `BLOCKHASH` can serve (`BLOCKHASH_SERVE_WINDOW`) would have been a semantics change. Using extending that via this contract storage would allow a soft-transition. Rollups can benefit from the longer history window through directly querying this contract.

A side benefit of this approach could be that it allows building/validating proofs related to last `HISTORY_SERVE_WINDOW` ancestors directly against the current state.

## Specification

| Parameter | Value |
| - | - |
| `BLOCKHASH_SERVE_WINDOW`  | `256` |
| `HISTORY_SERVE_WINDOW`    | `8191` |
| `SYSTEM_ADDRESS`          | `0xfffffffffffffffffffffffffffffffffffffffe` |
| `HISTORY_STORAGE_ADDRESS` | `0x0000F90827F1C53a10cb7A02335B175320002935` |

This EIP specifies for storing last `HISTORY_SERVE_WINDOW` block hashes in a ring buffer storage of `HISTORY_SERVE_WINDOW` length. Note that `HISTORY_SERVE_WINDOW` > `BLOCKHASH_SERVE_WINDOW` (which remains unchanged).

### Block processing

At the start of processing any block where this EIP is active (ie. before processing any transactions), call to `HISTORY_STORAGE_ADDRESS` as `SYSTEM_ADDRESS` with the 32-byte input of `block.parent.hash`, a gas limit of `30_000_000`, and `0` value. This will trigger the `set()` routine of the history contract. This is a system operation following the same convention as [EIP-4788](./eip-4788.md) and therefore:

* the call must execute to completion
* the call does not count against the block's gas limit
* the call does not follow the [EIP-1559](./eip-1559.md) burn semantics - no value should be transferred as part of the call
* if no code exists at `HISTORY_STORAGE_ADDRESS`, the call must fail silently

Note: Alternatively clients can choose to directly write to the storage of the contract but EVM calling the contract remains preferred. Refer to the rationale for more info.

Note that, it will take `HISTORY_SERVE_WINDOW` blocks after the EIP's activation to completely fill up the ring buffer. The contract will only contain the parent hash of the fork block and no hashes prior to that.


### EVM Changes

The `BLOCKHASH` opcode semantics remains the same as before.

### Block hash history contract

The history contract has two operations: `get` and `set`. The `set` operation is invoked only when the `caller` is equal to the `SYSTEM_ADDRESS` as per [EIP-4788](./eip-4788.md). Otherwise the `get` operation is performed.

#### `get`

It is used from the EVM for looking up block hashes.

* Callers provide the block number they are querying in a big-endian encoding.
* If calldata is not 32 bytes, revert.
* For any request outside the range of [block.number-`HISTORY_SERVE_WINDOW`, block.number-1], revert.

#### `set`

* Caller provides `block.parent.hash` as calldata to the contract.
* Set the storage value at `block.number-1 % HISTORY_SERVE_WINDOW` to be `calldata[0:32]`.

#### Bytecode

Exact evm assembly that can be used for the history contract:

```
// https://github.com/lightclient/sys-asm/blob/f1c13e285b6aeef2b19793995e00861bf0f32c9a/src/execution_hash/main.eas
caller
push20 0xfffffffffffffffffffffffffffffffffffffffe
eq
push1 0x46
jumpi
push1 0x20
calldatasize
sub
push1 0x42
jumpi
push0
calldataload
push1 0x01
number
sub
dup2
gt
push1 0x42
jumpi
push2 0x1fff
dup2
number
sub
gt
push1 0x42
jumpi
push2 0x1fff
swap1
mod
sload
push0
mstore
push1 0x20
push0
return
jumpdest
push0
push0
revert
jumpdest
push0
calldataload
push2 0x1fff
push1 0x01
number
sub
mod
sstore
stop
```

#### Deployment

A special synthetic address is generated by working backwards from the desired deployment transaction:

```json
{
  "type": "0x0",
  "nonce": "0x0",
  "to": null,
  "gas": "0x3d090",
  "gasPrice": "0xe8d4a51000",
  "maxPriorityFeePerGas": null,
  "maxFeePerGas": null,
  "value": "0x0",
  "input": "0x60538060095f395ff33373fffffffffffffffffffffffffffffffffffffffe14604657602036036042575f35600143038111604257611fff81430311604257611fff9006545f5260205ff35b5f5ffd5b5f35611fff60014303065500",
  "v": "0x1b",
  "r": "0x539",
  "s": "0xaa12693182426612186309f02cfe8a80a0000",
  "hash": "0x67139a552b0d3fffc30c0fa7d0c20d42144138c8fe07fc5691f09c1cce632e15"
}
```

Note, the input in the transaction has a simple constructor prefixing the desired runtime code.

The sender of the transaction can be calculated as `0x3462413Af4609098e1E27A490f554f260213D685`. The address of the first contract deployed from the account is `rlp([sender, 0])` which equals `0x0000F90827F1C53a10cb7A02335B175320002935`. This is how `HISTORY_STORAGE_ADDRESS` is determined. Although this style of contract creation is not tied to any specific initcode like create2 is, the synthetic address is cryptographically bound to the input data of the transaction (e.g. the initcode).


Some activation scenarios:

 * For the fork to be activated at genesis, no history is written to the genesis state, and at the start of block `1`, genesis hash will be written as a normal operation to slot `0`.
 * for activation at block `1`, only genesis hash will be written at slot `0`.
 * for activation at block `32`, block `31`'s hash will be written to slot `31`. Every other slot will be `0`.

### [EIP-161](./eip-161.md) handling

The bytecode above will be deployed à la [EIP-4788](./eip-4788.md). As such the account at `HISTORY_STORAGE_ADDRESS` will have code and a nonce of 1, and will be exempt from EIP-161 cleanup.

### Gas costs

The system update at the beginning of the block, i.e. `process_block_hash_history` (or via system call to the contract with `SYSTEM_ADDRESS` caller), will not warm the `HISTORY_STORAGE_ADDRESS` account or its storage slots as per [EIP-2929](./eip-2929.md) rules. As such the first call to the contract will pay for warming up the account and storage slots it accesses.To clarify further any contract call to the `HISTORY_STORAGE_ADDRESS` will follow normal EVM execution semantics.

Since `BLOCKHASH` semantics doesn't change, this EIP has no impact on `BLOCKHASH` mechanism and costs.

## Rationale

Very similar ideas were proposed before. This EIP is a simplification, removing two sources of needless complexity:

1. Having a tree-like structure with multiple layers as opposed to a single list
2. Writing the EIP in EVM code
3. Serial unbounded storage of hashes for a deep access to the history

However after weighing pros and cons, we decided to go with just a limited ring buffer to only serve the requisite `HISTORY_SERVE_WINDOW` as [EIP-4788](./eip-4788.md) and beacon state accumulators allow (albeit a bit more complex) proof against any ancestor since merge.

Second concern was how to best transition the BLOCKHASH resolution logic post fork by:

1. Either waiting for  `HISTORY_SERVE_WINDOW` blocks for the entire relevant history to persist
2. Storing of all last `HISTORY_SERVE_WINDOW` block hashes on the fork block.

We choose to go with the former. It simplifies the logic greatly. It will take roughly a day to bootstrap the contract. Given that this is a new way of accessing history and no contract depends on it, it is deemed a favorable tradeoff.

### Inserting the parent block hash

Clients have generally two options for inserting the parent block hash into state:

1. Performing a system call to `HISTORY_STORAGE_ADDRESS` and letting that handle the storing in state.
2. Avoid EVM processing and directly write to the state trie.

The latter option is as follows:

```python
def process_block_hash_history(block: Block, state: State):
    if block.timestamp >= FORK_TIMESTAMP: // FORK_TIMESTAMP should be defined outside of the EIP
        state.insert_slot(HISTORY_STORAGE_ADDRESS, (block.number-1) % HISTORY_SERVE_WINDOW , block.parent.hash)
```

The first option is recommended until the Verkle fork, to stay consistent with [EIP-4788](./eip-4788.md) and to issues for misconfigured networks where this EIP is activated but history contract hasn't been deployed. The recommendation may be reconsidered at the Verkle fork if filtering the system contract code chunks is deemed too complex.

### Size of ring buffers

The ring buffer data structure is sized to hold 8191 hashes. In other system contracts a prime ring buffer size is chosen in because using a prime as the modulus ensures that no value is overwritten until the entire ring buffer has been saturated and thereafter, each value will be updated once per iteration, regardless of if some slot are missing or the slot time changes. However, in this EIP the block number is the value in the modulo operation and it only ever increases by 1 each iteration. Which means we can be confident that the ring buffer will always remain saturated.

For consistency with other system contracts, we have decided to retain the buffer size of 8191. Given the current mainnet values, 8191 roots provides about a day of coverage. This also gives users plenty of time to make a transaction with a verification against a specific hash and get the transaction included on-chain.

## Backwards Compatibility

This EIP introduces backwards incompatible changes to the block validation rule set. But neither of these changes break anything related to current user activity and experience.

## Test Cases

[EIP-2935 Execution Spec Tests](https://github.com/ethereum/execution-spec-tests/tree/3810d22f84f206866f66f4f6bf856187c2893ab1/tests/prague/eip2935_historical_block_hashes_from_state)

## Security Considerations

Having contracts (system or otherwise) with hot update paths (branches) poses a risk of "branch" poisoning attacks where attacker could sprinkle trivial amounts of eth around these hot paths (branches). But it has been deemed that cost of attack would escalate significantly to cause any meaningful slow down of state root updates.

## Copyright

Copyright and related rights waived via [CC0](../LICENSE.md).