Skip to content

Commit

Permalink
Update EIP-4788: initial stab at v2
Browse files Browse the repository at this point in the history 
Merged by EIP-Bot.
  • Loading branch information
@lightclient
lightclient authored Aug 24, 2023
1 parent 7f50615 commit 46f8d5b
Showing 1 changed file with 149 additions and 59 deletions.
208 changes: 149 additions & 59 deletions EIPS/eip-4788.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,20 @@
eip: 4788
title: Beacon block root in the EVM
description: Expose beacon chain roots in the EVM
author: Alex Stokes (@ralexstokes), Ansgar Dietrichs (@adietrichs), Danny Ryan (@djrtwo)
author: Alex Stokes (@ralexstokes), Ansgar Dietrichs (@adietrichs), Danny Ryan (@djrtwo), Martin Holst Swende (@holiman), lightclient (@lightclient)
discussions-to: https://ethereum-magicians.org/t/eip-4788-beacon-root-in-evm/8281
status: Draft
type: Standards Track
category: Core
created: 2022-02-10
requires: 1559
---

## Abstract

Commit to the hash tree root of each beacon chain block in the corresponding execution payload header.

Store each of these roots in a stateful precompile.
Store each of these roots in a smart contract.

## Motivation

Expand All @@ -25,18 +26,19 @@ restaking constructions, smart contract bridges, MEV mitigations and more.

## Specification

| constants | value | units
|--- |--- |---
| constants | value |
|--- |--- |
| `FORK_TIMESTAMP` | TBD |
| `HISTORY_STORAGE_ADDRESS` | `Bytes20(0xB)` |
| `G_beacon_root` | 4200 | gas
| `HISTORICAL_ROOTS_MODULUS` | 98304 |
| `HISTORY_BUFFER_LENGTH` | `98304` |
| `SYSTEM_ADDRESS` | `0xfffffffffffffffffffffffffffffffffffffffe` |
| `BEACON_ROOTS_ADDRESS` | `0xbEac00dDB15f3B6d645C48263dC93862413A222D` |

### Background

The high-level idea is that each execution block contains the parent beacon block root. Even in the event of missed slots since the previous block root does not change,
The high-level idea is that each execution block contains the parent beacon block's root. Even in the event of missed slots since the previous block root does not change,
we only need a constant amount of space to represent this "oracle" in each execution block. To improve the usability of this oracle, a small history of block roots
are stored in a stateful precompile.
are stored in the contract.

To bound the amount of storage this construction consumes, a ring buffer is used that mirrors a block root accumulator on the consensus layer.

### Block structure and validity
Expand Down Expand Up @@ -77,76 +79,164 @@ When verifying a block, execution clients **MUST** ensure the root value in the

For a genesis block with no existing parent beacon block root the 32 zero bytes are used as a root placeholder.

### EVM changes
#### Beacon roots contract

#### Block processing
The beacon roots contract has two operations: `get` and `set`. The input itself is not used to determine which function to execute, for that the result of `caller` is used. If `caller` is equal to `SYSTEM_ADDRESS` then the operation to perform is `set`. Otherwise, `get`.

At the start of processing any execution block where `block.timestamp >= FORK_TIMESTAMP` (i.e. before processing any transactions),
write the parent beacon root provided in the block header into the storage of the contract at `HISTORY_STORAGE_ADDRESS`.
##### `get`

In order to bound the storage used by this precompile, two ring buffers are used: one to track the latest timestamp at a given index in the ring buffer and another to track
the latest root at a given index.
* Callers provide the `timestamp` they are querying encoded as 32 bytes in big-endian format.
* If the input is not exactly 32 bytes, the contract must revert.
* Given `timestamp`, the contract computes the storage index in which the timestamp is stored by computing the modulo `timestamp % HISTORY_BUFFER_LENGTH` and reads the value.
* If the `timestamp` does not match, the contract must revert.
* Finally, the beacon root associated with the timestamp is returned to the user. It is stored at `timestamp % HISTORY_BUFFER_LENGTH + HISTORY_BUFFER_LENGTH`.

To derive the index `timestamp_index` into the timestamp ring buffer, the timestamp (a 64-bit unsigned integer value) is reduced modulo `HISTORICAL_ROOTS_MODULUS`.
To derive the index `root_index` into the root ring buffer, add `HISTORICAL_ROOTS_MODULUS` to the index into the timestamp ring buffer.
Both resulting 64-bit unsigned integers should be encoded as 32 bytes in big-endian format when writing to the storage.
##### `set`

The timestamp from the header, encoded as 32 bytes in big-endian format, is the value to write behind the `timestamp_index`.
The 32 bytes of the `parent_beacon_block_root` (as provided) are the value to write behind the `root_index`.
* Caller provides the parent beacon block root as calldata to the contract.
* Set the storage value at `header.timestamp % HISTORY_BUFFER_LENGTH` to be `header.timestamp`
* Set the storage value at `header.timestamp % HISTORY_BUFFER_LENGTH + HISTORY_BUFFER_LENGTH` to be `calldata[0:32]`

In Python pseudocode:
##### Pseudocode

```python
timestamp_reduced = block_header.timestamp % HISTORICAL_ROOTS_MODULUS
timestamp_extended = timestamp_reduced + HISTORICAL_ROOTS_MODULUS
timestamp_index = to_uint256_be(timestamp_reduced)
root_index = to_uint256_be(timestamp_extended)
if evm.caller == SYSTEM_ADDRESS:
set()
else:
get()

timestamp_as_uint256 = to_uint256_be(block_header.timestamp)
parent_beacon_block_root = block_header.parent_beacon_block_root
def get():
if len(evm.calldata) != 32:
evm.revert()

sstore(HISTORY_STORAGE_ADDRESS, timestamp_index, timestamp_as_uint256)
sstore(HISTORY_STORAGE_ADDRESS, root_index, parent_beacon_block_root)
```
timestamp_idx = to_uint256_be(evm.calldata) % HISTORY_BUFFER_LENGTH
timestamp = storage.get(timestamp_idx)

#### New stateful precompile
if timestamp != evm.calldata:
evm.revert()

Beginning at the execution timestamp `FORK_TIMESTAMP`, a "stateful" precompile is deployed at `HISTORY_STORAGE_ADDRESS`.
root_idx = timestamp_idx + HISTORY_BUFFER_LENGTH
root = storage.get(root_idx)

evm.return(root)

Callers of the precompile should provide the `timestamp` they are querying encoded as 32 bytes in big-endian format.
Clients **MUST** sanitize this input call data to the precompile.
If the input is _more_ than 32 bytes, the precompile only takes the first 32 bytes of the input buffer and ignores the rest.
If the input is _less_ than 32 bytes, the precompile should revert.
def set():
timestamp_idx = to_uint256_be(evm.timestamp) % HISTORY_BUFFER_LENGTH
root_idx = timestamp_idx + HISTORY_BUFFER_LENGTH

storage.set(timestamp_idx, evm.timestamp)
storage.set(root_idx, evm.calldata)
```

Given this input, the precompile reduces the `timestamp` in the same way during the write routine and first checks if
the `timestamp` recorded in the ring buffer matches the one supplied by the caller.
##### Bytecode

The exact initcode to deploy is shared below.

```asm
push1 0x58
dup1
push1 0x09
push0
codecopy
push0
return
caller
push20 0xfffffffffffffffffffffffffffffffffffffffe
eq
push1 0x44
jumpi
push1 0x20
calldatasize
eq
push1 0x24
jumpi
push0
push0
revert
jumpdest
push3 0x018000
push0
calldataload
mod
dup1
sload
push0
calldataload
eq
push1 0x37
jumpi
push0
push0
revert
jumpdest
push3 0x018000
add
sload
push0
mstore
push1 0x20
push0
return
jumpdest
push3 0x018000
timestamp
mod
timestamp
dup2
sstore
push0
calldataload
swap1
push3 0x018000
add
sstore
stop
```

If the `timestamp` **does NOT** match, the client **MUST** return the "zero" word -- the 32-byte value where each byte is `0x00`.
#### Deployment

The beacon roots contract is deployed like any other smart contract. A special synthetic address is generated
by working backwards from the desired deployment transaction:

```json
{
"type": "0x0",
"nonce": "0x0",
"to": null,
"gas": "0x27eac",
"gasPrice": "0xe8d4a51000",
"maxPriorityFeePerGas": null,
"maxFeePerGas": null,
"value": "0x0",
"input": "0x60588060095f395ff33373fffffffffffffffffffffffffffffffffffffffe14604457602036146024575f5ffd5b620180005f350680545f35146037575f5ffd5b6201800001545f5260205ff35b6201800042064281555f359062018000015500",
"v": "0x1b",
"r": "0x539",
"s": "0x133700f3a77843802897db",
"hash": "0x14789a20c0508b81ab7a0287a12a3a41ca960aa18244af8e98689e37ed569f07"
}
```

If the `timestamp` **does** match, the client **MUST** read the root from the contract storage and return those 32 bytes in the caller's return buffer.
The sender of the transaction can be calculated as `0x3e266d3c3a70c238bdddafef1ba06fbd58958d70`. The address of the first contract deployed from the account is `rlp([sender, 0])` which equals `0xbEac00dDB15f3B6d645C48263dC93862413A222D`. This is how `BEACON_ROOTS_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).

In pseudocode:
### Block processing

```python
timestamp = evm.calldata[:32]
if len(timestamp) != 32:
evm.revert()
return
At the start of processing any execution block where `block.timestamp >= FORK_TIMESTAMP` (i.e. before processing any transactions), call `BEACON_ROOTS_ADDRESS` as `SYSTEM_ADDRESS` with the 32-byte input of `header.parent_beacon_block_root`, a gas limit of `30_000_000`, and `0` value. This will trigger the `set()` routine of the beacon roots contract. This is a system operation and therefore:

timestamp_reduced = to_uint64_be(timestamp) % HISTORICAL_ROOTS_MODULUS
timestamp_index = to_uint256_be(timestamp_reduced)
* 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 `BEACON_ROOTS_ADDRESS`, the call must fail silently

recorded_timestamp = sload(HISTORY_STORAGE_ADDRESS, timestamp_index)
if recorded_timestamp != timestamp:
evm.returndata[:32].set(uint256(0))
else:
timestamp_extended = timestamp_reduced + HISTORICAL_ROOTS_MODULUS
root_index = to_uint256_be(timestamp_extended)
root = sload(HISTORY_STORAGE_ADDRESS, root_index)
evm.returndata[:32].set(root)
```
Clients may decide to omit an explicit EVM call and directly set the storage values. Note: While this is a valid optimization for Ethereum mainnet, it could be problematic on non-mainnet situations in case a different contract is used.

The precompile costs `G_beacon_root` gas to reflect the two (2) implicit `SLOAD`s from the precompile's state.
If this EIP is active in a genesis block, the genesis header's `parent_beacon_block_root` must be `0x0` and no system transaction may occur.

## Rationale

Expand All @@ -170,7 +260,7 @@ e.g. with a singleton state root contract that caches the proof per slot).

### Why two ring buffers?

The first ring buffer only tracks `HISTORICAL_ROOTS_MODULUS` worth of roots and so for all possible timestamp values would consume a constant amount of storage.
The first ring buffer only tracks `HISTORY_BUFFER_LENGTH` worth of roots and so for all possible timestamp values would consume a constant amount of storage.
However, this design opens the precompile to an attack where a skipped slot that has the same value modulo the ring buffer length would return an old root value,
rather than the most recent one.

Expand Down

0 comments on commit 46f8d5b

Please sign in to comment.