diff --git a/specs/merge/beacon-chain.md b/specs/merge/beacon-chain.md index 01c54e017..8837c0ea3 100644 --- a/specs/merge/beacon-chain.md +++ b/specs/merge/beacon-chain.md @@ -12,6 +12,8 @@ - [Custom types](#custom-types) - [Constants](#constants) - [Execution](#execution) +- [Configuration](#configuration) + - [Genesis testing settings](#genesis-testing-settings) - [Containers](#containers) - [Extended containers](#extended-containers) - [`BeaconBlockBody`](#beaconblockbody) @@ -31,6 +33,8 @@ - [`on_payload`](#on_payload) - [Block processing](#block-processing) - [Execution payload processing](#execution-payload-processing) + - [`is_valid_gas_limit`](#is_valid_gas_limit) + - [`compute_base_fee_per_gas`](#compute_base_fee_per_gas) - [`process_execution_payload`](#process_execution_payload) - [Testing](#testing) @@ -59,6 +63,21 @@ This patch adds transaction execution to the beacon chain as part of the Merge f | `MAX_BYTES_PER_OPAQUE_TRANSACTION` | `uint64(2**20)` (= 1,048,576) | | `MAX_TRANSACTIONS_PER_PAYLOAD` | `uint64(2**14)` (= 16,384) | | `BYTES_PER_LOGS_BLOOM` | `uint64(2**8)` (= 256) | +| `GAS_LIMIT_DENOMINATOR` | `uint64(2**10)` (= 1,024) | +| `MIN_GAS_LIMIT` | `uint64(5000)` (= 5,000) | +| `BASE_FEE_MAX_CHANGE_DENOMINATOR` | `uint64(2**3)` (= 8) | +| `ELASTICITY_MULTIPLIER` | `uint64(2**1)` (= 2) | + +## Configuration + +### Genesis testing settings + +*Note*: These configuration settings do not apply to the mainnet and are utilized only by pure Merge testing. + +| Name | Value | +| - | - | +| `GENESIS_GAS_LIMIT` | `uint64(30000000)` (= 30,000,000) | +| `GENESIS_BASE_FEE_PER_GAS` | `uint64(1000000000)` (= 1,000,000,000) | ## Containers @@ -141,6 +160,7 @@ class ExecutionPayload(Container): gas_limit: uint64 gas_used: uint64 timestamp: uint64 + base_fee_per_gas: uint64 # base fee introduced in EIP-1559 # Extra payload fields block_hash: Hash32 # Hash of execution block transactions: List[Transaction, MAX_TRANSACTIONS_PER_PAYLOAD] @@ -161,6 +181,7 @@ class ExecutionPayloadHeader(Container): gas_limit: uint64 gas_used: uint64 timestamp: uint64 + base_fee_per_gas: uint64 # Extra payload fields block_hash: Hash32 # Hash of execution block transactions_root: Root @@ -239,17 +260,67 @@ def process_block(state: BeaconState, block: BeaconBlock) -> None: ### Execution payload processing +#### `is_valid_gas_limit` + +```python +def is_valid_gas_limit(payload: ExecutionPayload, parent: ExecutionPayloadHeader) -> bool: + parent_gas_limit = parent.gas_limit + + # Check if the payload used too much gas + if payload.gas_used > payload.gas_limit: + return False + + # Check if the payload changed the gas limit too much + if payload.gas_limit >= parent_gas_limit + parent_gas_limit // GAS_LIMIT_DENOMINATOR: + return False + if payload.gas_limit <= parent_gas_limit - parent_gas_limit // GAS_LIMIT_DENOMINATOR: + return False + + # Check if the gas limit is at least the minimum gas limit + if payload.gas_limit < MIN_GAS_LIMIT: + return False + + return True +``` + +#### `compute_base_fee_per_gas` + +```python +def compute_base_fee_per_gas(payload: ExecutionPayload, parent: ExecutionPayloadHeader) -> uint64: + parent_gas_target = parent.gas_limit // ELASTICITY_MULTIPLIER + parent_base_fee_per_gas = parent.base_fee_per_gas + parent_gas_used = payload.gas_used + + if parent_gas_used == parent_gas_target: + return parent_base_fee_per_gas + elif parent_gas_used > parent_gas_target: + gas_used_delta = parent_gas_used - parent_gas_target + base_fee_per_gas_delta = max( + parent_base_fee_per_gas * gas_used_delta // parent_gas_target // BASE_FEE_MAX_CHANGE_DENOMINATOR, + 1, + ) + return parent_base_fee_per_gas + base_fee_per_gas_delta + else: + gas_used_delta = parent_gas_target - parent_gas_used + base_fee_per_gas_delta = ( + parent_base_fee_per_gas * gas_used_delta // parent_gas_target // BASE_FEE_MAX_CHANGE_DENOMINATOR + ) + return parent_base_fee_per_gas - base_fee_per_gas_delta # This subtraction can't underflow +``` + #### `process_execution_payload` *Note:* This function depends on `process_randao` function call as it retrieves the most recent randao mix from the `state`. Implementations that are considering parallel processing of execution payload with respect to beacon chain state transition function should work around this dependency. ```python def process_execution_payload(state: BeaconState, payload: ExecutionPayload, execution_engine: ExecutionEngine) -> None: - # Verify consistency of the parent hash, block number and random + # Verify consistency of the parent hash, block number, random, base fee per gas and gas limit if is_merge_complete(state): assert payload.parent_hash == state.latest_execution_payload_header.block_hash assert payload.block_number == state.latest_execution_payload_header.block_number + uint64(1) assert payload.random == get_randao_mix(state, get_current_epoch(state)) + assert payload.base_fee_per_gas == compute_base_fee_per_gas(payload, state.latest_execution_payload_header) + assert is_valid_gas_limit(payload, state.latest_execution_payload_header) # Verify timestamp assert payload.timestamp == compute_timestamp_at_slot(state, state.slot) # Verify the execution payload is valid @@ -266,6 +337,7 @@ def process_execution_payload(state: BeaconState, payload: ExecutionPayload, exe gas_limit=payload.gas_limit, gas_used=payload.gas_used, timestamp=payload.timestamp, + base_fee_per_gas=payload.base_fee_per_gas, block_hash=payload.block_hash, transactions_root=hash_tree_root(payload.transactions), ) @@ -321,6 +393,8 @@ def initialize_beacon_state_from_eth1(eth1_block_hash: Bytes32, state.latest_execution_payload_header.block_hash = eth1_block_hash state.latest_execution_payload_header.timestamp = eth1_timestamp state.latest_execution_payload_header.random = eth1_block_hash + state.latest_execution_payload_header.gas_limit = GENESIS_GAS_LIMIT + state.latest_execution_payload_header.base_fee_per_gas = GENESIS_BASE_FEE_PER_GAS return state ``` diff --git a/tests/core/pyspec/eth2spec/test/helpers/execution_payload.py b/tests/core/pyspec/eth2spec/test/helpers/execution_payload.py index c41a05079..ce653a986 100644 --- a/tests/core/pyspec/eth2spec/test/helpers/execution_payload.py +++ b/tests/core/pyspec/eth2spec/test/helpers/execution_payload.py @@ -20,9 +20,11 @@ def build_empty_execution_payload(spec, state, randao_mix=None): gas_limit=latest.gas_limit, # retain same limit gas_used=0, # empty block, 0 gas timestamp=timestamp, + base_fee_per_gas=spec.uint64(0), block_hash=spec.Hash32(), transactions=empty_txs, ) + payload.base_fee_per_gas = spec.compute_base_fee_per_gas(payload, latest) # TODO: real RLP + block hash logic would be nice, requires RLP and keccak256 dependency however. payload.block_hash = spec.Hash32(spec.hash(payload.hash_tree_root() + b"FAKE RLP HASH")) @@ -41,6 +43,7 @@ def get_execution_payload_header(spec, execution_payload): gas_limit=execution_payload.gas_limit, gas_used=execution_payload.gas_used, timestamp=execution_payload.timestamp, + base_fee_per_gas=execution_payload.base_fee_per_gas, block_hash=execution_payload.block_hash, transactions_root=spec.hash_tree_root(execution_payload.transactions) ) diff --git a/tests/core/pyspec/eth2spec/test/helpers/genesis.py b/tests/core/pyspec/eth2spec/test/helpers/genesis.py index a9eb59f67..0e9af4cff 100644 --- a/tests/core/pyspec/eth2spec/test/helpers/genesis.py +++ b/tests/core/pyspec/eth2spec/test/helpers/genesis.py @@ -78,5 +78,7 @@ def create_genesis_state(spec, validator_balances, activation_threshold): # Initialize the execution payload header (with block number and genesis time set to 0) state.latest_execution_payload_header.block_hash = eth1_block_hash state.latest_execution_payload_header.random = eth1_block_hash + state.latest_execution_payload_header.gas_limit = spec.GENESIS_GAS_LIMIT + state.latest_execution_payload_header.base_fee_per_gas = spec.GENESIS_BASE_FEE_PER_GAS return state