From 1465007b49a9ca7fb555ab573a2b47fa127d77a8 Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Fri, 8 Mar 2024 11:41:20 +0800 Subject: [PATCH] Add EIP-7251 spec Co-authored-by: fradamt <104826920+fradamt@users.noreply.github.com> --- configs/mainnet.yaml | 8 + configs/minimal.yaml | 7 + presets/mainnet/eip7251.yaml | 23 + presets/minimal/eip7251.yaml | 25 + pysetup/constants.py | 1 + pysetup/md_doc_paths.py | 2 + pysetup/spec_builders/__init__.py | 3 +- pysetup/spec_builders/eip7251.py | 24 + specs/_features/eip7251/beacon-chain.md | 819 ++++++++++++++++++ specs/_features/eip7251/fork.md | 131 +++ .../pyspec/eth2spec/test/helpers/constants.py | 3 + 11 files changed, 1045 insertions(+), 1 deletion(-) create mode 100644 presets/mainnet/eip7251.yaml create mode 100644 presets/minimal/eip7251.yaml create mode 100644 pysetup/spec_builders/eip7251.py create mode 100644 specs/_features/eip7251/beacon-chain.md create mode 100644 specs/_features/eip7251/fork.md diff --git a/configs/mainnet.yaml b/configs/mainnet.yaml index 317daa1a45..3d54befbf3 100644 --- a/configs/mainnet.yaml +++ b/configs/mainnet.yaml @@ -56,6 +56,9 @@ EIP6110_FORK_EPOCH: 18446744073709551615 # EIP7002 EIP7002_FORK_VERSION: 0x05000000 # temporary stub EIP7002_FORK_EPOCH: 18446744073709551615 +# EIP7251 +EIP7251_FORK_VERSION: 0x06000000 # temporary stub +EIP7251_FORK_EPOCH: 18446744073709551615 # WHISK WHISK_FORK_VERSION: 0x06000000 # temporary stub WHISK_FORK_EPOCH: 18446744073709551615 @@ -158,3 +161,8 @@ WHISK_PROPOSER_SELECTION_GAP: 2 # EIP7594 EIP7594_FORK_VERSION: 0x06000001 EIP7594_FORK_EPOCH: 18446744073709551615 + +# [New in EIP7251] +MIN_PER_EPOCH_CHURN_LIMIT_EIP7251: 128000000000 # 2**7 * 10**9 (= 128,000,000,000) +MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT: 256000000000 # 2**8 * 10**9 (= 256,000,000,000) + diff --git a/configs/minimal.yaml b/configs/minimal.yaml index 6b2da84fdb..f565dee9fa 100644 --- a/configs/minimal.yaml +++ b/configs/minimal.yaml @@ -55,6 +55,9 @@ EIP6110_FORK_EPOCH: 18446744073709551615 # EIP7002 EIP7002_FORK_VERSION: 0x05000001 EIP7002_FORK_EPOCH: 18446744073709551615 +# EIP7251 +EIP7251_FORK_VERSION: 0x06000000 # temporary stub +EIP7251_FORK_EPOCH: 18446744073709551615 # WHISK WHISK_FORK_VERSION: 0x06000001 WHISK_FORK_EPOCH: 18446744073709551615 @@ -157,3 +160,7 @@ WHISK_PROPOSER_SELECTION_GAP: 1 # EIP7594 EIP7594_FORK_VERSION: 0x06000001 EIP7594_FORK_EPOCH: 18446744073709551615 + +# [New in EIP7251] +MIN_PER_EPOCH_CHURN_LIMIT_EIP7251: 64000000000 # 2**6 * 10**9 (= 64,000,000,000) +MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT: 128000000000 # 2**7 * 10**9 (= 128,000,000,000) diff --git a/presets/mainnet/eip7251.yaml b/presets/mainnet/eip7251.yaml new file mode 100644 index 0000000000..cde13a5f4b --- /dev/null +++ b/presets/mainnet/eip7251.yaml @@ -0,0 +1,23 @@ +# Mainnet preset - EIP7251 + +# Gwei values +# --------------------------------------------------------------- +# 2**5 * 10**9 (= 32,000,000,000) Gwei +MIN_ACTIVATION_BALANCE: 32000000000 +# 2**11 * 10**9 (= 2,048,000,000,000) Gwei +MAX_EFFECTIVE_BALANCE_EIP7251: 2048000000000 + +# State list lengths +# --------------------------------------------------------------- +PENDING_BALANCE_DEPOSITS_LIMIT: 134217728 +PENDING_PARTIAL_WITHDRAWALS_LIMIT: 134217728 +PENDING_CONSOLIDATIONS_LIMIT: 262144 + +# Reward and penalty quotients +# --------------------------------------------------------------- +MIN_SLASHING_PENALTY_QUOTIENT_EIP7251: 65536 + +# Max operations per block +# --------------------------------------------------------------- +MAX_CONSOLIDATIONS: 1 + diff --git a/presets/minimal/eip7251.yaml b/presets/minimal/eip7251.yaml new file mode 100644 index 0000000000..cea46c17ee --- /dev/null +++ b/presets/minimal/eip7251.yaml @@ -0,0 +1,25 @@ +# Minimal preset - EIP7251 + +# Gwei values +# --------------------------------------------------------------- +# 2**5 * 10**9 (= 32,000,000,000) Gwei +MIN_ACTIVATION_BALANCE: 32000000000 +# 2**11 * 10**9 (= 2,048,000,000,000) Gwei +MAX_EFFECTIVE_BALANCE_EIP7251: 2048000000000 + +# State list lengths +# --------------------------------------------------------------- +PENDING_BALANCE_DEPOSITS_LIMIT: 134217728 +# [customized] smaller queue +PENDING_PARTIAL_WITHDRAWALS_LIMIT: 64 +# [customized] smaller queue +PENDING_CONSOLIDATIONS_LIMIT: 64 + +# Reward and penalty quotients +# --------------------------------------------------------------- +MIN_SLASHING_PENALTY_QUOTIENT_EIP7251: 65536 + +# Max operations per block +# --------------------------------------------------------------- +MAX_CONSOLIDATIONS: 1 + diff --git a/pysetup/constants.py b/pysetup/constants.py index 238b3b02ce..28da7efa68 100644 --- a/pysetup/constants.py +++ b/pysetup/constants.py @@ -6,6 +6,7 @@ DENEB = 'deneb' EIP6110 = 'eip6110' EIP7002 = 'eip7002' +EIP7251 = 'eip7251' WHISK = 'whisk' EIP7594 = 'eip7594' diff --git a/pysetup/md_doc_paths.py b/pysetup/md_doc_paths.py index c93c0c0321..be0730c2d6 100644 --- a/pysetup/md_doc_paths.py +++ b/pysetup/md_doc_paths.py @@ -9,6 +9,7 @@ EIP6110, WHISK, EIP7002, + EIP7251, EIP7594, ) @@ -22,6 +23,7 @@ EIP6110: DENEB, WHISK: CAPELLA, EIP7002: CAPELLA, + EIP7251: DENEB, EIP7594: DENEB, } diff --git a/pysetup/spec_builders/__init__.py b/pysetup/spec_builders/__init__.py index 061d11626d..9982cbb6e3 100644 --- a/pysetup/spec_builders/__init__.py +++ b/pysetup/spec_builders/__init__.py @@ -6,6 +6,7 @@ from .eip6110 import EIP6110SpecBuilder from .eip7002 import EIP7002SpecBuilder from .whisk import WhiskSpecBuilder +from .eip7251 import EIP7251SpecBuilder from .eip7594 import EIP7594SpecBuilder @@ -13,6 +14,6 @@ builder.fork: builder for builder in ( Phase0SpecBuilder, AltairSpecBuilder, BellatrixSpecBuilder, CapellaSpecBuilder, DenebSpecBuilder, - EIP6110SpecBuilder, EIP7002SpecBuilder, WhiskSpecBuilder, EIP7594SpecBuilder, + EIP6110SpecBuilder, EIP7002SpecBuilder, WhiskSpecBuilder, EIP7251SpecBuilder, EIP7594SpecBuilder, ) } diff --git a/pysetup/spec_builders/eip7251.py b/pysetup/spec_builders/eip7251.py new file mode 100644 index 0000000000..6d9056e5ff --- /dev/null +++ b/pysetup/spec_builders/eip7251.py @@ -0,0 +1,24 @@ +from typing import Dict + +from .base import BaseSpecBuilder +from ..constants import EIP7251 + + +class EIP7251SpecBuilder(BaseSpecBuilder): + fork: str = EIP7251 + + @classmethod + def imports(cls, preset_name: str): + return super().imports(preset_name) + f''' +from eth2spec.deneb import {preset_name} as deneb +''' + +## TODO: deal with changed gindices + + @classmethod + def hardcoded_ssz_dep_constants(cls) -> Dict[str, str]: + return { + 'FINALIZED_ROOT_GINDEX': 'GeneralizedIndex(169)', + 'CURRENT_SYNC_COMMITTEE_GINDEX': 'GeneralizedIndex(86)', + 'NEXT_SYNC_COMMITTEE_GINDEX': 'GeneralizedIndex(87)', + } diff --git a/specs/_features/eip7251/beacon-chain.md b/specs/_features/eip7251/beacon-chain.md new file mode 100644 index 0000000000..3879577ad0 --- /dev/null +++ b/specs/_features/eip7251/beacon-chain.md @@ -0,0 +1,819 @@ +# EIP7251 - Spec + +## Table of contents + + + + + +- [Introduction](#introduction) +- [Constants](#constants) + - [Withdrawal prefixes](#withdrawal-prefixes) + - [Domains](#domains) +- [Presets](#presets) + - [Gwei values](#gwei-values) + - [Rewards and penalties](#rewards-and-penalties) + - [Max operations per block](#max-operations-per-block) + - [State list lengths](#state-list-lengths) +- [Configuration](#configuration) + - [Validator cycle](#validator-cycle) +- [Containers](#containers) + - [New containers](#new-containers) + - [New `PendingBalanceDeposit`](#new-pendingbalancedeposit) + - [New `PartialWithdrawal`](#new-partialwithdrawal) + - [New `ExecutionLayerWithdrawRequest`](#new-executionlayerwithdrawrequest) + - [New `Consolidation`](#new-consolidation) + - [New `SignedConsolidation`](#new-signedconsolidation) + - [New `PendingConsolidation`](#new-pendingconsolidation) + - [Extended Containers](#extended-containers) + - [`BeaconState`](#beaconstate) + - [`BeaconBlockBody`](#beaconblockbody) +- [Helpers](#helpers) + - [Predicates](#predicates) + - [Updated `is_eligible_for_activation_queue`](#updated-is_eligible_for_activation_queue) + - [New `has_compounding_withdrawal_credential`](#new-has_compounding_withdrawal_credential) + - [New `has_execution_withdrawal_credential`](#new-has_execution_withdrawal_credential) + - [Updated `is_fully_withdrawable_validator`](#updated-is_fully_withdrawable_validator) + - [Updated `is_partially_withdrawable_validator`](#updated-is_partially_withdrawable_validator) + - [Beacon state accessors](#beacon-state-accessors) + - [New `get_validator_excess_balance`](#new-get_validator_excess_balance) + - [New `get_churn_limit`](#new-get_churn_limit) + - [New `get_activation_exit_churn_limit`](#new-get_activation_exit_churn_limit) + - [New `get_consolidation_churn_limit`](#new-get_consolidation_churn_limit) + - [New `get_active_balance`](#new-get_active_balance) + - [Beacon state mutators](#beacon-state-mutators) + - [Updated `initiate_validator_exit`](#updated--initiate_validator_exit) + - [New `compute_exit_epoch_and_update_churn`](#new-compute_exit_epoch_and_update_churn) + - [New `compute_consolidation_epoch_and_update_churn`](#new-compute_consolidation_epoch_and_update_churn) + - [Updated `slash_validator`](#updated-slash_validator) +- [Beacon chain state transition function](#beacon-chain-state-transition-function) + - [Epoch processing](#epoch-processing) + - [Updated `process_epoch`](#updated-process_epoch) + - [Updated `process_registry_updates`](#updated--process_registry_updates) + - [New `process_pending_balance_deposits`](#new-process_pending_balance_deposits) + - [New `process_pending_consolidations`](#new-process_pending_consolidations) + - [Updated `process_effective_balance_updates`](#updated-process_effective_balance_updates) + - [Block processing](#block-processing) + - [Operations](#operations) + - [Updated `process_operations`](#updated-process_operations) + - [Deposits](#deposits) + - [Updated `apply_deposit`](#updated--apply_deposit) + - [Updated `get_validator_from_deposit`](#updated-get_validator_from_deposit) + - [Withdrawals](#withdrawals) + - [New `process_execution_layer_withdraw_request`](#new-process_execution_layer_withdraw_request) + - [Updated `get_expected_withdrawals`](#updated--get_expected_withdrawals) + - [Consolidations](#consolidations) + - [New `process_consolidation`](#new-process_consolidation) + + + + +## Introduction + +See [a modest proposal](https://notes.ethereum.org/@mikeneuder/increase-maxeb), the [diff view](https://github.com/michaelneuder/consensus-specs/pull/3/files) and +[security considerations](https://notes.ethereum.org/@fradamt/meb-increase-security). + +*Note:* This specification is built upon [Deneb](../../deneb/beacon-chain.md). + +## Constants + +The following values are (non-configurable) constants used throughout the specification. + +### Withdrawal prefixes + +| Name | Value | +| - | - | +| `BLS_WITHDRAWAL_PREFIX` | `Bytes1('0x00')` | +| `ETH1_ADDRESS_WITHDRAWAL_PREFIX` | `Bytes1('0x01')` | +| `COMPOUNDING_WITHDRAWAL_PREFIX` | `Bytes1('0x02')` | + +### Domains + +| Name | Value | +| - | - | +| `DOMAIN_CONSOLIDATION` | `DomainType('0x0B000000')` | + +## Presets + +### Gwei values + +| Name | Value | +| - | - | +| `MIN_ACTIVATION_BALANCE` | `Gwei(2**5 * 10**9)` (= 32,000,000,000) | +| `MAX_EFFECTIVE_BALANCE_EIP7251` | `Gwei(2**11 * 10**9)` (= 2048,000,000,000) | + +### Rewards and penalties + +| Name | Value | +| - | - | +| `MIN_SLASHING_PENALTY_QUOTIENT_EIP7251` | `Gwei(2**16)` (= 65,536) | + +### Max operations per block + +| Name | Value | +| - | - | +| `MAX_CONSOLIDATIONS` | `uint64(1)` | + +### State list lengths + +| Name | Value | Unit | Duration | +| - | - | :-: | :-: | +| `PENDING_BALANCE_DEPOSITS_LIMIT` | `uint64(2**27)` (= 134,217,728) | pending balance deposits | | +| `PENDING_PARTIAL_WITHDRAWALS_LIMIT` | `uint64(2**27)` (= 134,217,728) | pending partial withdrawals | | +| `PENDING_CONSOLIDATIONS_LIMIT` | `uint64(2**18)` (= 262,144) | pending consolidations | | + + +## Configuration + +### Validator cycle + +| Name | Value | +| - | - | +| `MIN_PER_EPOCH_CHURN_LIMIT_EIP7251` | `Gwei(2**7 * 10**9)` (= 128,000,000,000) | # Equivalent to 4 32 ETH validators +| `MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT` | `Gwei(2**8 * 10**9)` (256,000,000,000) | + + +## Containers + +### New containers + +#### New `PendingBalanceDeposit` + +```python +class PendingBalanceDeposit(Container): + index: ValidatorIndex + amount: Gwei +``` + +#### New `PartialWithdrawal` + +```python +class PartialWithdrawal(Container): + index: ValidatorIndex + amount: Gwei + withdrawable_epoch: Epoch +``` +#### New `ExecutionLayerWithdrawRequest` + +```python +class ExecutionLayerWithdrawRequest(Container): + source_address: ExecutionAddress + validator_pubkey: BLSPubkey + amount: Gwei +``` + +#### New `Consolidation` + +```python +class Consolidation(Container): + source_index: ValidatorIndex + target_index: ValidatorIndex + epoch: Epoch +``` + +#### New `SignedConsolidation` +```python +class SignedConsolidation(Container): + message: Consolidation + signature: BLSSignature +``` + +#### New `PendingConsolidation` +```python +class PendingConsolidation(Container): + source_index: ValidatorIndex + target_index: ValidatorIndex +``` + +### Extended Containers + +#### `BeaconState` + +```python +class BeaconState(Container): + # Versioning + genesis_time: uint64 + genesis_validators_root: Root + slot: Slot + fork: Fork + # History + latest_block_header: BeaconBlockHeader + block_roots: Vector[Root, SLOTS_PER_HISTORICAL_ROOT] + state_roots: Vector[Root, SLOTS_PER_HISTORICAL_ROOT] + historical_roots: List[Root, HISTORICAL_ROOTS_LIMIT] + # Eth1 + eth1_data: Eth1Data + eth1_data_votes: List[Eth1Data, EPOCHS_PER_ETH1_VOTING_PERIOD * SLOTS_PER_EPOCH] + eth1_deposit_index: uint64 + # Registry + validators: List[Validator, VALIDATOR_REGISTRY_LIMIT] + balances: List[Gwei, VALIDATOR_REGISTRY_LIMIT] + # Randomness + randao_mixes: Vector[Bytes32, EPOCHS_PER_HISTORICAL_VECTOR] + # Slashings + slashings: Vector[Gwei, EPOCHS_PER_SLASHINGS_VECTOR] # Per-epoch sums of slashed effective balances + # Participation + previous_epoch_participation: List[ParticipationFlags, VALIDATOR_REGISTRY_LIMIT] + current_epoch_participation: List[ParticipationFlags, VALIDATOR_REGISTRY_LIMIT] + # Finality + justification_bits: Bitvector[JUSTIFICATION_BITS_LENGTH] # Bit set for every recent justified epoch + previous_justified_checkpoint: Checkpoint + current_justified_checkpoint: Checkpoint + finalized_checkpoint: Checkpoint + # Inactivity + inactivity_scores: List[uint64, VALIDATOR_REGISTRY_LIMIT] + # Sync + current_sync_committee: SyncCommittee + next_sync_committee: SyncCommittee + # Execution + latest_execution_payload_header: ExecutionPayloadHeader + # Withdrawals + next_withdrawal_index: WithdrawalIndex + next_withdrawal_validator_index: ValidatorIndex + # Deep history valid from Capella onwards + historical_summaries: List[HistoricalSummary, HISTORICAL_ROOTS_LIMIT] + # EIP-7251 + deposit_balance_to_consume: Gwei # [New in EIP-7251] + exit_balance_to_consume: Gwei # [New in EIP-7251] + earliest_exit_epoch: Epoch # [New in EIP-7251] + consolidation_balance_to_consume: Gwei # [New in EIP-7251] + earliest_consolidation_epoch: Epoch # [New in EIP-7251] + pending_balance_deposits: List[PendingBalanceDeposit, PENDING_BALANCE_DEPOSITS_LIMIT] # [New in EIP-7251] + pending_partial_withdrawals: List[PartialWithdrawal, PENDING_PARTIAL_WITHDRAWALS_LIMIT] # [New in EIP-7251] + pending_consolidations: List[PendingConsolidation, PENDING_CONSOLIDATIONS_LIMIT] # [New in EIP-7251] +``` + +### `BeaconBlockBody` + +```python +class BeaconBlockBody(Container): + randao_reveal: BLSSignature + eth1_data: Eth1Data # Eth1 data vote + graffiti: Bytes32 # Arbitrary data + # Operations + proposer_slashings: List[ProposerSlashing, MAX_PROPOSER_SLASHINGS] + attester_slashings: List[AttesterSlashing, MAX_ATTESTER_SLASHINGS] + attestations: List[Attestation, MAX_ATTESTATIONS] + deposits: List[Deposit, MAX_DEPOSITS] + voluntary_exits: List[SignedVoluntaryExit, MAX_VOLUNTARY_EXITS] + sync_aggregate: SyncAggregate + # Execution + execution_payload: ExecutionPayload + bls_to_execution_changes: List[SignedBLSToExecutionChange, MAX_BLS_TO_EXECUTION_CHANGES] + blob_kzg_commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK] + consolidations: List[SignedConsolidation, MAX_CONSOLIDATIONS] # [New in EIP-7251] +``` + +## Helpers + +### Predicates + +#### Updated `is_eligible_for_activation_queue` + +```python +def is_eligible_for_activation_queue(validator: Validator) -> bool: + """ + Check if ``validator`` is eligible to be placed into the activation queue. + """ + return ( + validator.activation_eligibility_epoch == FAR_FUTURE_EPOCH + and validator.effective_balance >= MIN_ACTIVATION_BALANCE # [Modified in EIP7251] + ) +``` + +#### New `has_compounding_withdrawal_credential` + +```python +def has_compounding_withdrawal_credential(validator: Validator) -> bool: + """ + Check if ``validator`` has an 0x02 prefixed "compounding" withdrawal credential. + """ + return validator.withdrawal_credentials[:1] == COMPOUNDING_WITHDRAWAL_PREFIX +``` + +#### New `has_execution_withdrawal_credential` + +```python +def has_execution_withdrawal_credential(validator: Validator) -> bool: + """ + Check if ``validator`` has a 0x01 or 0x02 prefixed withdrawal credential. + """ + return has_compounding_withdrawal_credential(validator) or has_eth1_withdrawal_credential(validator) +``` + +#### Updated `is_fully_withdrawable_validator` + +```python +def is_fully_withdrawable_validator(validator: Validator, balance: Gwei, epoch: Epoch) -> bool: + """ + Check if ``validator`` is fully withdrawable. + """ + return ( + has_execution_withdrawal_credential(validator) # [Modified in EIP7251] + and validator.withdrawable_epoch <= epoch + and balance > 0 + ) +``` + +#### Updated `is_partially_withdrawable_validator` + +```python +def is_partially_withdrawable_validator(validator: Validator, balance: Gwei) -> bool: + """ + Check if ``validator`` is partially withdrawable. + """ + return ( + has_execution_withdrawal_credential(validator) + and get_validator_excess_balance(validator, balance) > 0 + ) +``` + +### Beacon state accessors + +#### New `get_validator_excess_balance` + +```python +def get_validator_excess_balance(validator: Validator, balance: Gwei) -> Gwei: + """ + Get excess balance for partial withdrawals for ``validator``. + """ + if has_compounding_withdrawal_credential(validator) and balance > MAX_EFFECTIVE_BALANCE_EIP7251: + return balance - MAX_EFFECTIVE_BALANCE_EIP7251 + elif has_eth1_withdrawal_credential(validator) and balance > MIN_ACTIVATION_BALANCE: + return balance - MIN_ACTIVATION_BALANCE + return Gwei(0) +``` + +#### New `get_churn_limit` + +```python +def get_churn_limit(state: BeaconState) -> Gwei: + """ + Return the churn limit for the current epoch. + """ + churn = max( + MIN_PER_EPOCH_CHURN_LIMIT_EIP7251, + get_total_active_balance(state) // CHURN_LIMIT_QUOTIENT + ) + return churn - churn % EFFECTIVE_BALANCE_INCREMENT +``` + +#### New `get_activation_exit_churn_limit` + +```python +def get_activation_exit_churn_limit(state: BeaconState) -> Gwei: + """ + Return the churn limit for the current epoch dedicated to activations and exits. + """ + return min(MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT, get_churn_limit(state)) +``` + +#### New `get_consolidation_churn_limit` + +```python +def get_consolidation_churn_limit(state: BeaconState) -> Gwei: + return get_churn_limit(state) - get_activation_exit_churn_limit(state) +``` + +#### New `get_active_balance` + +```python +def get_active_balance(state: BeaconState, validator_index: ValidatorIndex) -> Gwei: + active_balance_ceil = ( + MIN_ACTIVATION_BALANCE + if has_eth1_withdrawal_credential(state.validators[validator_index]) + else MAX_EFFECTIVE_BALANCE_EIP7251 + ) + return min(state.balances[validator_index], active_balance_ceil) +``` + +### Beacon state mutators + +#### Updated `initiate_validator_exit` + +```python +def initiate_validator_exit(state: BeaconState, index: ValidatorIndex) -> None: + """ + Initiate the exit of the validator with index ``index``. + """ + # Return if validator already initiated exit + validator = state.validators[index] + if validator.exit_epoch != FAR_FUTURE_EPOCH: + return + + # Compute exit queue epoch [Modified in EIP 7251] + exit_queue_epoch = compute_exit_epoch_and_update_churn(state, validator.effective_balance) + + # Set validator exit epoch and withdrawable epoch + validator.exit_epoch = exit_queue_epoch + validator.withdrawable_epoch = Epoch(validator.exit_epoch + MIN_VALIDATOR_WITHDRAWABILITY_DELAY) +``` + +#### New `compute_exit_epoch_and_update_churn` + + +```python +def compute_exit_epoch_and_update_churn(state: BeaconState, exit_balance: Gwei) -> Epoch: + earliest_exit_epoch = compute_activation_exit_epoch(get_current_epoch(state)) + per_epoch_churn = get_activation_exit_churn_limit(state) + # New epoch for exits. + if state.earliest_exit_epoch < earliest_exit_epoch: + state.earliest_exit_epoch = earliest_exit_epoch + state.exit_balance_to_consume = per_epoch_churn + + if exit_balance <= state.exit_balance_to_consume: + # Exit fits in the current earliest epoch. + state.exit_balance_to_consume -= exit_balance + else: + # Exit doesn't fit in the current earliest epoch. + balance_to_process = exit_balance - state.exit_balance_to_consume + additional_epochs, remainder = divmod(balance_to_process, per_epoch_churn) + state.earliest_exit_epoch += additional_epochs + 1 + state.exit_balance_to_consume = per_epoch_churn - remainder + + return state.earliest_exit_epoch +``` + +#### New `compute_consolidation_epoch_and_update_churn` + +```python +def compute_consolidation_epoch_and_update_churn(state: BeaconState, consolidation_balance: Gwei) -> Epoch: + earliest_consolidation_epoch = compute_activation_exit_epoch(get_current_epoch(state)) + per_epoch_consolidation_churn = get_consolidation_churn_limit(state) + # New epoch for consolidations. + if state.earliest_consolidation_epoch < earliest_consolidation_epoch: + state.earliest_consolidation_epoch = earliest_consolidation_epoch + state.consolidation_balance_to_consume = per_epoch_consolidation_churn + + if consolidation_balance <= state.consolidation_balance_to_consume: + # Consolidation fits in the current earliest consolidation epoch. + state.consolidation_balance_to_consume -= consolidation_balance + else: + # Consolidation doesn't fit in the current earliest epoch. + balance_to_process = consolidation_balance - state.consolidation_balance_to_consume + additional_epochs, remainder = divmod(balance_to_process, per_epoch_consolidation_churn) + state.earliest_consolidation_epoch += additional_epochs + 1 + state.consolidation_balance_to_consume = per_epoch_consolidation_churn - remainder + + return state.earliest_consolidation_epoch +``` + +#### Updated `slash_validator` + +```python +def slash_validator(state: BeaconState, + slashed_index: ValidatorIndex, + whistleblower_index: ValidatorIndex=None) -> None: + """ + Slash the validator with index ``slashed_index``. + """ + epoch = get_current_epoch(state) + initiate_validator_exit(state, slashed_index) + validator = state.validators[slashed_index] + validator.slashed = True + validator.withdrawable_epoch = max(validator.withdrawable_epoch, Epoch(epoch + EPOCHS_PER_SLASHINGS_VECTOR)) + state.slashings[epoch % EPOCHS_PER_SLASHINGS_VECTOR] += validator.effective_balance + slashing_penalty = validator.effective_balance // MIN_SLASHING_PENALTY_QUOTIENT_EIP7251 # [Modified in EIP7251] + decrease_balance(state, slashed_index, slashing_penalty) +``` + + +## Beacon chain state transition function + +### Epoch processing + +#### Updated `process_epoch` +```python +def process_epoch(state: BeaconState) -> None: + process_justification_and_finalization(state) + process_inactivity_updates(state) + process_rewards_and_penalties(state) + process_registry_updates(state) + process_slashings(state) + process_eth1_data_reset(state) + process_pending_balance_deposits(state) # New in EIP7251 + process_pending_consolidations(state) # New in EIP7251 + process_effective_balance_updates(state) + process_slashings_reset(state) + process_randao_mixes_reset(state) +``` + +#### Updated `process_registry_updates` + +```python +def process_registry_updates(state: BeaconState) -> None: + # Process activation eligibility and ejections + for index, validator in enumerate(state.validators): + if is_eligible_for_activation_queue(validator): + validator.activation_eligibility_epoch = get_current_epoch(state) + 1 + if ( + is_active_validator(validator, get_current_epoch(state)) + and validator.effective_balance <= EJECTION_BALANCE + ): + initiate_validator_exit(state, ValidatorIndex(index)) + + # Activate all eligible validators + activation_epoch = compute_activation_exit_epoch(get_current_epoch(state)) + for validator in state.validators: + if is_eligible_for_activation(state, validator): + validator.activation_epoch = activation_epoch +``` + +#### New `process_pending_balance_deposits` + +```python +def process_pending_balance_deposits(state: BeaconState) -> None: + state.deposit_balance_to_consume += get_activation_exit_churn_limit(state) + next_pending_deposit_index = 0 + for pending_balance_deposit in state.pending_balance_deposits: + if state.deposit_balance_to_consume < pending_balance_deposit.amount: + break + + state.deposit_balance_to_consume -= pending_balance_deposit.amount + increase_balance(state, pending_balance_deposit.index, pending_balance_deposit.amount) + next_pending_deposit_index += 1 + + state.pending_balance_deposits = state.pending_balance_deposits[next_pending_deposit_index:] +``` + +#### New `process_pending_consolidations` + +```python +def process_pending_consolidations(state: BeaconState) -> None: + next_pending_consolidation = 0 + for pending_consolidation in state.pending_consolidations: + source_validator = state.validators[pending_consolidation.source_index] + if source_validator.slashed: + next_pending_consolidation += 1 + continue + if source_validator.withdrawable_epoch > get_current_epoch(state): + break + + next_pending_consolidation += 1 + # Move active balance to target. Excess balance is withdrawable. + active_balance = get_active_balance(state, pending_consolidation.source_index) + state.balances[pending_consolidation.source_index] -= active_balance + state.balances[pending_consolidation.target_index] += active_balance + + state.pending_consolidations = state.pending_consolidations[next_pending_consolidation:] +``` + +#### Updated `process_effective_balance_updates` + +```python +def process_effective_balance_updates(state: BeaconState) -> None: + # Update effective balances with hysteresis + for index, validator in enumerate(state.validators): + balance = state.balances[index] + HYSTERESIS_INCREMENT = uint64(EFFECTIVE_BALANCE_INCREMENT // HYSTERESIS_QUOTIENT) + DOWNWARD_THRESHOLD = HYSTERESIS_INCREMENT * HYSTERESIS_DOWNWARD_MULTIPLIER + UPWARD_THRESHOLD = HYSTERESIS_INCREMENT * HYSTERESIS_UPWARD_MULTIPLIER + EFFECTIVE_BALANCE_LIMIT = ( + MAX_EFFECTIVE_BALANCE_EIP7251 if has_compounding_withdrawal_credential(validator) + else MIN_ACTIVATION_BALANCE + ) + + if ( + balance + DOWNWARD_THRESHOLD < validator.effective_balance + or validator.effective_balance + UPWARD_THRESHOLD < balance + ): + validator.effective_balance = min(balance - balance % EFFECTIVE_BALANCE_INCREMENT, EFFECTIVE_BALANCE_LIMIT) +``` + +### Block processing + +#### Operations + +##### Updated `process_operations` + +```python +def process_operations(state: BeaconState, body: BeaconBlockBody) -> None: + # Verify that outstanding deposits are processed up to the maximum number of deposits + assert len(body.deposits) == min(MAX_DEPOSITS, state.eth1_data.deposit_count - state.eth1_deposit_index) + + def for_ops(operations: Sequence[Any], fn: Callable[[BeaconState, Any], None]) -> None: + for operation in operations: + fn(state, operation) + + for_ops(body.proposer_slashings, process_proposer_slashing) + for_ops(body.attester_slashings, process_attester_slashing) + for_ops(body.attestations, process_attestation) + for_ops(body.deposits, process_deposit) + for_ops(body.voluntary_exits, process_voluntary_exit) + for_ops(body.bls_to_execution_changes, process_bls_to_execution_change) + for_ops(body.execution_payload.withdraw_requests, process_execution_layer_withdraw_request) # New in EIP7251 + for_ops(body.consolidations, process_consolidation) # New in EIP7251 +``` + +##### Deposits + +###### Updated `apply_deposit` + +```python +def apply_deposit(state: BeaconState, + pubkey: BLSPubkey, + withdrawal_credentials: Bytes32, + amount: uint64, + signature: BLSSignature) -> None: + validator_pubkeys = [validator.pubkey for validator in state.validators] + if pubkey not in validator_pubkeys: + # Verify the deposit signature (proof of possession) which is not checked by the deposit contract + deposit_message = DepositMessage( + pubkey=pubkey, + withdrawal_credentials=withdrawal_credentials, + amount=amount, + ) + domain = compute_domain(DOMAIN_DEPOSIT) # Fork-agnostic domain since deposits are valid across forks + signing_root = compute_signing_root(deposit_message, domain) + # Initialize validator if the deposit signature is valid + if bls.Verify(pubkey, signing_root, signature): + state.validators.append(get_validator_from_deposit(pubkey, withdrawal_credentials)) + state.balances.append(0) # [Modified in EIP-7251] + state.previous_epoch_participation.append(ParticipationFlags(0b0000_0000)) + state.current_epoch_participation.append(ParticipationFlags(0b0000_0000)) + state.inactivity_scores.append(uint64(0)) + index = len(state.validators) - 1 + state.pending_balance_deposits.append(PendingBalanceDeposit(index, amount)) # [Modified in EIP-7251] + else: + index = ValidatorIndex(validator_pubkeys.index(pubkey)) + state.pending_balance_deposits.append(PendingBalanceDeposit(index, amount)) +``` + +###### Updated `get_validator_from_deposit` + +```python +def get_validator_from_deposit(pubkey: BLSPubkey, withdrawal_credentials: Bytes32) -> Validator: + return Validator( + pubkey=pubkey, + withdrawal_credentials=withdrawal_credentials, + activation_eligibility_epoch=FAR_FUTURE_EPOCH, + activation_epoch=FAR_FUTURE_EPOCH, + exit_epoch=FAR_FUTURE_EPOCH, + withdrawable_epoch=FAR_FUTURE_EPOCH, + effective_balance=0, # [Modified in EIP7251] + ) +``` + +##### Withdrawals + +###### New `process_execution_layer_withdraw_request` + +```python +def process_execution_layer_withdraw_request( + state: BeaconState, + execution_layer_withdraw_request: ExecutionLayerWithdrawRequest +) -> None: + amount = execution_layer_withdraw_request.amount + is_full_exit_request = amount == 0 + # If partial withdrawal queue is full, only full exits are processed + if not (is_full_exit_request or len(state.pending_consolidations) < PENDING_PARTIAL_WITHDRAWALS_LIMIT): + return + + validator_pubkeys = [v.pubkey for v in state.validators] + validator_index = ValidatorIndex(validator_pubkeys.index(execution_layer_withdraw_request.validator_pubkey)) + validator = state.validators[validator_index] + + # Same conditions as in EIP-7002 + # Verify withdrawal credentials + is_execution_address = has_eth1_withdrawal_credential(validator) or has_compounding_withdrawal_credential(validator) + is_correct_source_address = validator.withdrawal_credentials[12:] == execution_layer_withdraw_request.source_address + if not (is_execution_address and is_correct_source_address): + return + # Verify the validator is active + if not is_active_validator(validator, get_current_epoch(state)): + return + # Verify exit has not been initiated, and slashed + if validator.exit_epoch != FAR_FUTURE_EPOCH: + return + # Verify the validator has been active long enough + if get_current_epoch(state) < validator.activation_epoch + SHARD_COMMITTEE_PERIOD: + return + + # New condition: only allow partial withdrawals with compounding withdrawal credentials + if not (is_full_exit_request or has_compounding_withdrawal_credential(validator)): + return + + pending_balance_to_withdraw = sum( + item.amount for item in state.pending_partial_withdrawals if item.index == validator_index + ) + # only exit validator if it has no pending withdrawals in the queue + if is_full_exit_request and pending_balance_to_withdraw == 0: + initiate_validator_exit(state, validator_index) + elif state.balances[validator_index] > MIN_ACTIVATION_BALANCE + pending_balance_to_withdraw: + to_withdraw = min( + state.balances[validator_index] - MIN_ACTIVATION_BALANCE - pending_balance_to_withdraw, + amount + ) + exit_queue_epoch = compute_exit_epoch_and_update_churn(state, to_withdraw) + withdrawable_epoch = Epoch(exit_queue_epoch + MIN_VALIDATOR_WITHDRAWABILITY_DELAY) + state.pending_partial_withdrawals.append(PartialWithdrawal( + index=validator_index, + amount=to_withdraw, + withdrawable_epoch=withdrawable_epoch, + )) +``` + +###### Updated `get_expected_withdrawals` + +```python +def get_expected_withdrawals(state: BeaconState) -> Sequence[Withdrawal]: + epoch = get_current_epoch(state) + withdrawal_index = state.next_withdrawal_index + validator_index = state.next_withdrawal_validator_index + withdrawals: List[Withdrawal] = [] + consumed = 0 + for withdrawal in state.pending_partial_withdrawals: + if withdrawal.withdrawable_epoch > epoch or len(withdrawals) == MAX_WITHDRAWALS_PER_PAYLOAD // 2: + break + + validator = state.validators[withdrawal.index] + if validator.exit_epoch == FAR_FUTURE_EPOCH and state.balances[withdrawal.index] > MIN_ACTIVATION_BALANCE: + withdrawable_balance = min(state.balances[withdrawal.index] - MIN_ACTIVATION_BALANCE, withdrawal.amount) + withdrawals.append(Withdrawal( + index=withdrawal_index, + validator_index=withdrawal.index, + address=ExecutionAddress(validator.withdrawal_credentials[12:]), + amount=withdrawable_balance, + )) + withdrawal_index += WithdrawalIndex(1) + consumed += 1 + + state.pending_partial_withdrawals = state.pending_partial_withdrawals[consumed:] + + # Sweep for remaining. + bound = min(len(state.validators), MAX_VALIDATORS_PER_WITHDRAWALS_SWEEP) + for _ in range(bound): + validator = state.validators[validator_index] + balance = state.balances[validator_index] + if is_fully_withdrawable_validator(validator, balance, epoch): + withdrawals.append(Withdrawal( + index=withdrawal_index, + validator_index=validator_index, + address=ExecutionAddress(validator.withdrawal_credentials[12:]), + amount=balance, + )) + withdrawal_index += WithdrawalIndex(1) + elif is_partially_withdrawable_validator(validator, balance): + withdrawals.append(Withdrawal( + index=withdrawal_index, + validator_index=validator_index, + address=ExecutionAddress(validator.withdrawal_credentials[12:]), + amount=get_validator_excess_balance(validator, balance), + )) + withdrawal_index += WithdrawalIndex(1) + if len(withdrawals) == MAX_WITHDRAWALS_PER_PAYLOAD: + break + validator_index = ValidatorIndex((validator_index + 1) % len(state.validators)) + return withdrawals +``` + +##### Consolidations + +###### New `process_consolidation` + +```python +def process_consolidation(state: BeaconState, signed_consolidation: SignedConsolidation) -> None: + # If the pending consolidations queue is full, no consolidations are allowed in the block + assert len(state.pending_consolidations) < PENDING_CONSOLIDATIONS_LIMIT + # If there is too little available consolidation churn limit, no consolidations are allowed in the block + assert get_consolidation_churn_limit(state) > MIN_ACTIVATION_BALANCE + consolidation = signed_consolidation.message + # Verify that source != target, so a consolidation cannot be used as an exit. + assert consolidation.source_index != consolidation.target_index + + source_validator = state.validators[consolidation.source_index] + target_validator = state.validators[consolidation.target_index] + # Verify the source and the target are active + current_epoch = get_current_epoch(state) + assert is_active_validator(source_validator, current_epoch) + assert is_active_validator(target_validator, current_epoch) + # Verify exits for source and target have not been initiated + assert source_validator.exit_epoch == FAR_FUTURE_EPOCH + assert target_validator.exit_epoch == FAR_FUTURE_EPOCH + # Consolidations must specify an epoch when they become valid; they are not valid before then + assert current_epoch >= consolidation.epoch + + # Verify the source and the target have Execution layer withdrawal credentials + assert has_execution_withdrawal_credential(source_validator) + assert has_execution_withdrawal_credential(target_validator) + # Verify the same withdrawal address + assert source_validator.withdrawal_credentials[1:] == target_validator.withdrawal_credentials[1:] + + # Verify consolidation is signed by the source and the target + domain = compute_domain(DOMAIN_CONSOLIDATION, genesis_validators_root=state.genesis_validators_root) + signing_root = compute_signing_root(consolidation, domain) + pubkeys = [source_validator.pubkey, target_validator.pubkey] + assert bls.FastAggregateVerify(pubkeys, signing_root, signed_consolidation.signature) + + # Initiate source validator exit and append pending consolidation + active_balance = get_active_balance(state, consolidation.source_index) + source_validator.exit_epoch = compute_consolidation_epoch_and_update_churn(state, active_balance) + source_validator.withdrawable_epoch = Epoch( + source_validator.exit_epoch + MIN_VALIDATOR_WITHDRAWABILITY_DELAY + ) + state.pending_consolidations.append(PendingConsolidation( + source_index=consolidation.source_index, + target_index=consolidation.target_index + )) +``` + diff --git a/specs/_features/eip7251/fork.md b/specs/_features/eip7251/fork.md new file mode 100644 index 0000000000..666c7c3684 --- /dev/null +++ b/specs/_features/eip7251/fork.md @@ -0,0 +1,131 @@ +# EIP7251 -- Fork Logic + +**Notice**: This document is a work-in-progress for researchers and implementers. + +## Table of contents + + + + +- [Introduction](#introduction) +- [Configuration](#configuration) +- [Helper functions](#helper-functions) + - [Misc](#misc) + - [Modified `compute_fork_version`](#modified-compute_fork_version) +- [Fork to EIP7251](#fork-to-eip7251) + - [Fork trigger](#fork-trigger) + - [Upgrading the state](#upgrading-the-state) + + + +## Introduction + +This document describes the process of the EIP7251 upgrade. + +## Configuration + +Warning: this configuration is not definitive. + +| Name | Value | +| - | - | +| `EIP7251_FORK_VERSION` | `Version('0x06000000')` | +| `EIP7251_FORK_EPOCH` | `Epoch(18446744073709551615)` **TBD** | + +## Helper functions + +### Misc + +#### Modified `compute_fork_version` + +```python +def compute_fork_version(epoch: Epoch) -> Version: + """ + Return the fork version at the given ``epoch``. + """ + if epoch >= EIP7251_FORK_EPOCH: + return EIP7251_FORK_VERSION + if epoch >= DENEB_FORK_EPOCH: + return DENEB_FORK_VERSION + if epoch >= CAPELLA_FORK_EPOCH: + return CAPELLA_FORK_VERSION + if epoch >= BELLATRIX_FORK_EPOCH: + return BELLATRIX_FORK_VERSION + if epoch >= ALTAIR_FORK_EPOCH: + return ALTAIR_FORK_VERSION + return GENESIS_FORK_VERSION +``` + +## Fork to EIP7251 + +### Fork trigger + +TBD. This fork is defined for testing purposes, the EIP may be combined with other consensus-layer upgrade. +For now, we assume the condition will be triggered at epoch `EIP7251_FORK_EPOCH`. + +Note that for the pure EIP7251 networks, we don't apply `upgrade_to_eip7251` since it starts with EIP7251 version logic. + +### Upgrading the state + +If `state.slot % SLOTS_PER_EPOCH == 0` and `compute_epoch_at_slot(state.slot) == EIP7251_FORK_EPOCH`, +an irregular state change is made to upgrade to EIP7251. + +```python +def upgrade_to_eip7251(pre: deneb.BeaconState) -> BeaconState: + post = BeaconState( + # Versioning + genesis_time=pre.genesis_time, + genesis_validators_root=pre.genesis_validators_root, + slot=pre.slot, + fork=Fork( + previous_version=pre.fork.current_version, + current_version=EIP7251_FORK_VERSION, + epoch=deneb.get_current_epoch(pre), + ), + # History + latest_block_header=pre.latest_block_header, + block_roots=pre.block_roots, + state_roots=pre.state_roots, + historical_roots=pre.historical_roots, + # Eth1 + eth1_data=pre.eth1_data, + eth1_data_votes=pre.eth1_data_votes, + eth1_deposit_index=pre.eth1_deposit_index, + # Registry + validators=pre.validators, + balances=pre.balances, + # Randomness + randao_mixes=pre.randao_mixes, + # Slashings + slashings=pre.slashings, + # Participation + previous_epoch_participation=pre.previous_epoch_participation, + current_epoch_participation=pre.current_epoch_participation, + # Finality + justification_bits=pre.justification_bits, + previous_justified_checkpoint=pre.previous_justified_checkpoint, + current_justified_checkpoint=pre.current_justified_checkpoint, + finalized_checkpoint=pre.finalized_checkpoint, + # Inactivity + inactivity_scores=pre.inactivity_scores, + # Sync + current_sync_committee=pre.current_sync_committee, + next_sync_committee=pre.next_sync_committee, + # Execution-layer + latest_execution_payload_header=pre.latest_execution_payload_header, + # Withdrawals + next_withdrawal_index=pre.next_withdrawal_index, + next_withdrawal_validator_index=pre.next_withdrawal_validator_index, + # Deep history valid from Capella onwards + historical_summaries=pre.historical_summaries, + # [New in EIP7251] + deposit_balance_to_consume=0, + exit_balance_to_consume=get_activation_exit_churn_limit(pre), + earliest_exit_epoch=max([v.exit_epoch for v in pre.validators if v.exit_epoch != FAR_FUTURE_EPOCH]) + 1, + consolidation_balance_to_consume=get_consolidation_churn_limit(pre), + earliest_consolidation_epoch=compute_activation_exit_epoch(get_current_epoch(pre)), + pending_balance_deposits=[], + pending_partial_withdrawals=[], + pending_consolidations=[], + ) + return post +``` diff --git a/tests/core/pyspec/eth2spec/test/helpers/constants.py b/tests/core/pyspec/eth2spec/test/helpers/constants.py index a51201906c..46323278d5 100644 --- a/tests/core/pyspec/eth2spec/test/helpers/constants.py +++ b/tests/core/pyspec/eth2spec/test/helpers/constants.py @@ -19,6 +19,7 @@ EIP6110 = SpecForkName('eip6110') EIP7002 = SpecForkName('eip7002') WHISK = SpecForkName('whisk') +EIP7251 = SpecForkName('eip7251') EIP7594 = SpecForkName('eip7594') # @@ -38,6 +39,7 @@ # Experimental patches EIP6110, EIP7002, + EIP7251, EIP7594, ) # The forks that have light client specs @@ -59,6 +61,7 @@ EIP6110: DENEB, WHISK: CAPELLA, EIP7002: CAPELLA, + EIP7251: DENEB, EIP7594: DENEB, }