From 9cbf63e56ff90a505fc8c4a1ead4b1a1664cca97 Mon Sep 17 00:00:00 2001 From: Zyra-V21 Date: Tue, 9 Jun 2026 11:21:26 +0200 Subject: [PATCH] Clarify pre-activation validator statuses and document deposit_inqueue Rename pending_initialized -> pending_minBalance and pending_queued -> pending_lookahead in the ValidatorStatus enum, correcting their descriptions for the post-Electra (EIP-6110/EIP-7251) deposit pipeline: pending_minBalance is the pre-eligibility state (effective balance < MIN_ACTIVATION_BALANCE) and pending_lookahead is the fixed 1 + MAX_SEED_LOOKAHEAD delay (no longer a churn-limited queue). Document deposit_inqueue, the deposit-pipeline state for deposits in state.pending_deposits that are not yet validators, observable via getPendingDeposits. --- apis/beacon/states/pending_deposits.yaml | 2 ++ types/api.yaml | 8 +++++--- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/apis/beacon/states/pending_deposits.yaml b/apis/beacon/states/pending_deposits.yaml index a963c434..0cf7cfcc 100644 --- a/apis/beacon/states/pending_deposits.yaml +++ b/apis/beacon/states/pending_deposits.yaml @@ -3,6 +3,8 @@ get: summary: "Get State Pending Deposits" description: | Returns pending deposits for state with given 'stateId'. Should return 400 if the state retrieved is prior to Electra. + + A pubkey present here but absent from `state.validators` is in the deposit-pipeline state `deposit_inqueue`, it has no `ValidatorStatus` yet. This is the real churn-limited wait before a deposit becomes a validator. tags: - Beacon parameters: diff --git a/types/api.yaml b/types/api.yaml index 356fb4e6..61776fc5 100644 --- a/types/api.yaml +++ b/types/api.yaml @@ -43,8 +43,8 @@ ValidatorIdentityResponse: ValidatorStatus: description: | Possible statuses: - - **pending_initialized** - When the first deposit is processed, but not enough funds are available (or not yet the end of the first epoch) to get validator into the activation queue. - - **pending_queued** - When validator is waiting to get activated, and have enough funds etc. while in the queue, validator activation epoch keeps changing until it gets to the front and make it through (finalization is a requirement here too). + - **pending_minBalance** - The validator exists in `state.validators` but its effective balance has not reached `MIN_ACTIVATION_BALANCE` (32 ETH), so it is not yet eligible for activation. Condition: `activation_eligibility_epoch == FAR_FUTURE_EPOCH`. (Formerly `pending_initialized`.) + - **pending_lookahead** - The validator is eligible (`activation_eligibility_epoch` is set and finalized) and its `activation_epoch` is assigned but in the future. Post-Electra (EIP-7251) this is a fixed `1 + MAX_SEED_LOOKAHEAD` delay, not a churn-limited queue: the `activation_epoch` does not change. Condition: `(activation_eligibility_epoch < FAR_FUTURE_EPOCH) and (activation_epoch > current_epoch)`. (Formerly `pending_queued`.) - **active_ongoing** - When validator must be attesting, and have not initiated any exit. - **active_exiting** - When validator is still active, but filed a voluntary request to exit. - **active_slashed** - When validator is still active, but have a slashed status and is scheduled to exit. @@ -53,8 +53,10 @@ ValidatorStatus: - **withdrawal_possible** - After validator has exited, a while later is permitted to move funds, and is truly out of the system. - **withdrawal_done** - (not possible in phase0, except slashing full balance) - actually having moved funds away + Note: post-Electra (EIP-6110), a deposit that is in `state.pending_deposits` but not yet in `state.validators` is not represented by a `ValidatorStatus` (there is no validator object yet). This deposit-pipeline state — referred to as `deposit_inqueue` — is the real churn-limited wait and is observable via the `getPendingDeposits` endpoint, not via this enum. + [Validator status specification](https://hackmd.io/ofFJ5gOmQpu1jjHilHbdQQ) - enum: ["pending_initialized", "pending_queued", "active_ongoing", "active_exiting", "active_slashed", "exited_unslashed", "exited_slashed", "withdrawal_possible", "withdrawal_done"] + enum: ["pending_minBalance", "pending_lookahead", "active_ongoing", "active_exiting", "active_slashed", "exited_unslashed", "exited_slashed", "withdrawal_possible", "withdrawal_done"] example: "active_ongoing"