EIP-7917: Deterministic proposer lookahead

specs/fulu/beacon-chain.md

@@ -13,6 +13,18 @@
   - [Execution](#execution)
     - [Execution payload](#execution-payload)
       - [Modified `process_execution_payload`](#modified-process_execution_payload)
+- [Containers](#containers)
+  - [Extended Containers](#extended-containers)
+    - [`BeaconState`](#beaconstate)
+- [Helper functions](#helper-functions)
+  - [Misc](#misc)
+    - [New `compute_proposer_indices`](#new-compute_proposer_indices)
+    - [New `compute_proposer_lookahead`](#new-compute_proposer_lookahead)
+  - [Beacon state accessors](#beacon-state-accessors)
+    - [Modified `get_beacon_proposer_index`](#modified-get_beacon_proposer_index)
+  - [Epoch processing](#epoch-processing)
+    - [Modified `process_epoch`](#modified-process_epoch)
+    - [New `process_proposer_lookahead`](#new-process_proposer_lookahead)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- /TOC -->
@@ -76,3 +88,156 @@ def process_execution_payload(state: BeaconState, body: BeaconBlockBody, executi
         excess_blob_gas=payload.excess_blob_gas,
     )
 ```
+
+## Containers
+
+### Extended Containers
+
+#### `BeaconState`
+
+*Note*: The `BeaconState` container is extended with the `proposer_lookahead` field, which is a list of validator indices covering the full lookahead period, starting from the beginning of the current epoch. For example, `proposer_lookahead[0]` is the validator index for the first proposer in the current epoch, `proposer_lookahead[1]` is the validator index for the next proposer in the current epoch, and so forth. The length of the `proposer_lookahead` list is `(MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH`, reflecting how far ahead proposer indices are computed based on the `MIN_SEED_LOOKAHEAD` parameter.
+
+```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]
+    deposit_requests_start_index: uint64
+    deposit_balance_to_consume: Gwei
+    exit_balance_to_consume: Gwei
+    earliest_exit_epoch: Epoch
+    consolidation_balance_to_consume: Gwei
+    earliest_consolidation_epoch: Epoch
+    pending_deposits: List[PendingDeposit, PENDING_DEPOSITS_LIMIT]
+    pending_partial_withdrawals: List[PendingPartialWithdrawal, PENDING_PARTIAL_WITHDRAWALS_LIMIT]
+    pending_consolidations: List[PendingConsolidation, PENDING_CONSOLIDATIONS_LIMIT]
+    proposer_lookahead: List[ValidatorIndex, (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH]  # [New in Fulu:EIPXXXX]
+```
+
+## Helper functions
+
+### Misc
+
+#### New `compute_proposer_indices`
+
+```python
+def compute_proposer_indices(state: BeaconState, epoch: Epoch) -> List[ValidatorIndex, SLOTS_PER_EPOCH]:
+    """
+    Return the proposer indices for the given ``epoch``.
+    """
+    proposer_indices = []
+    indices = get_active_validator_indices(state, epoch)
+    start_slot = compute_start_slot_at_epoch(epoch)
+    for slot in range(start_slot, start_slot + SLOTS_PER_EPOCH):
+        seed = hash(get_seed(state, epoch, DOMAIN_BEACON_PROPOSER) + uint_to_bytes(Slot(slot)))
+        proposer_indices.append(compute_proposer_index(state, indices, seed))
+    return proposer_indices
+```
+
+#### New `compute_proposer_lookahead`
+
+```python
+def compute_proposer_lookahead(state: BeaconState) -> List[ValidatorIndex, (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH]:
+    """
+    Return the proposer indices for the full available lookahead starting from current epoch.
+    """
+    current_epoch = get_current_epoch(state)
+    lookahead = []
+    for i in range(MIN_SEED_LOOKAHEAD + 1):
+        proposer_indices = compute_proposer_indices(state, Epoch(current_epoch + i))
+        lookahead.extend(proposer_indices)
+    return lookahead        
+```
+
+
+### Beacon state accessors
+
+#### Modified `get_beacon_proposer_index`
+
+*Note*: The function `get_beacon_proposer_index` is modified to use the pre-calculated `current_proposer_lookahead` instead of calculating it on-demand.
+
+```python
+def get_beacon_proposer_index(state: BeaconState) -> ValidatorIndex:
+    """
+    Return the beacon proposer index at the current slot.
+    """
+    slot_offset = state.slot - compute_start_slot_at_epoch(get_current_epoch(state))
+    return state.proposer_lookahead[slot_offset]
+```
+
+### Epoch processing
+
+#### Modified `process_epoch`
+
+*Note*: The function `process_epoch` is modified in Fulu to call `process_proposer_lookahead` to update the `proposer_lookahead` in the beacon state.
+
+```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_deposits(state)
+    process_pending_consolidations(state)
+    process_effective_balance_updates(state)
+    process_slashings_reset(state)
+    process_randao_mixes_reset(state)
+    process_historical_summaries_update(state)
+    process_participation_flag_updates(state)
+    process_sync_committee_updates(state)
+    process_proposer_lookahead(state)  # [New in Fulu:EIPXXXX]
+```
+
+#### New `process_proposer_lookahead`
+
+*Note*: This function updates the proposer_lookahead in the beacon state by shifting out proposer indices from the earliest epoch and appending new proposer indices for the latest epoch. With `MIN_SEED_LOOKAHEAD` set to `1`, this means that at the start of epoch `N`, the proposer lookahead for epoch `N+1` will be computed and included in the beacon state's lookahead.
+
+```python
+def process_proposer_lookahead(state: BeaconState) -> None:
+    last_epoch_start = len(state.proposer_lookahead) - SLOTS_PER_EPOCH
+    # Shift out proposers in the first epoch.
+    state.proposer_lookahead[:last_epoch_start] = state.proposer_lookahead[SLOTS_PER_EPOCH:]
+    # Fill in the last epoch with new proposer indices.
+    last_epoch_proposers = compute_proposer_indices(state, Epoch(get_current_epoch(state) + MIN_SEED_LOOKAHEAD))
+    state.proposer_lookahead[last_epoch_start:] = last_epoch_proposers
+```

specs/fulu/fork.md

@@ -133,6 +133,7 @@ def upgrade_to_fulu(pre: electra.BeaconState) -> BeaconState:
         pending_deposits=pre.pending_deposits,
         pending_partial_withdrawals=pre.pending_partial_withdrawals,
         pending_consolidations=pre.pending_consolidations,
+        proposer_lookahead=compute_proposer_lookahead(pre),  # [New in Fulu:EIPXXXX]
     )
 
     return post

tests/core/pyspec/eth2spec/test/fulu/epoch_processing/test_process_proposer_lookahead.py

@@ -0,0 +1,36 @@
+from eth2spec.test.context import spec_state_test, with_fulu_and_later
+from eth2spec.test.helpers.epoch_processing import run_epoch_processing_with
+from eth2spec.test.helpers.state import next_epoch
+
+
+@with_fulu_and_later
+@spec_state_test
+def test_next_epoch_proposer_lookahead_shifted_to_front(spec, state):
+    """Test that the next epoch proposer lookahead is shifted to the front at epoch transition."""
+    # Transition few epochs to pass the MIN_SEED_LOOKAHEAD
+    next_epoch(spec, state)
+    next_epoch(spec, state)
+    # Get initial lookahead
+    initial_lookahead = state.proposer_lookahead.copy()
+
+    # Run epoch processing
+    yield from run_epoch_processing_with(spec, state, 'process_proposer_lookahead')
+
+    # Verify lookahead was shifted correctly
+    assert state.proposer_lookahead[:spec.SLOTS_PER_EPOCH] == initial_lookahead[spec.SLOTS_PER_EPOCH:]
+
+
+@with_fulu_and_later
+@spec_state_test
+def test_proposer_lookahead_in_state_matches_computed_lookahead(spec, state):
+    """Test that the proposer lookahead in the state matches the lookahead computed on the fly."""
+    # Transition few epochs to pass the MIN_SEED_LOOKAHEAD
+    next_epoch(spec, state)
+    next_epoch(spec, state)
+
+    # Run epoch processing
+    yield from run_epoch_processing_with(spec, state, 'process_proposer_lookahead')
+
+    # Verify lookahead in state matches the lookahead computed on the fly
+    computed_lookahead = spec.compute_proposer_lookahead(state)
+    assert state.proposer_lookahead == computed_lookahead

tests/core/pyspec/eth2spec/test/helpers/genesis.py

@@ -176,6 +176,8 @@ def create_genesis_state(spec, validator_balances, activation_threshold):
 
     if is_post_electra(spec):
         state.deposit_requests_start_index = spec.UNSET_DEPOSIT_REQUESTS_START_INDEX
+        # Initialize proposer lookahead list
+        state.proposer_lookahead = spec.compute_proposer_lookahead(state)
 
     if is_post_eip7441(spec):
         vc = len(state.validators)