Skip to content

Add build_consensus_validators builder - #815

Merged
evgeny-stakewise merged 6 commits into
masterfrom
extend-validator
Aug 19, 2026
Merged

Add build_consensus_validators builder#815
evgeny-stakewise merged 6 commits into
masterfrom
extend-validator

Conversation

@evgeny-stakewise

@evgeny-stakewise evgeny-stakewise commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Introduces build_consensus_validators — a single builder that fetches the vault's consensus validators and enriches them with pending deposits and pending consolidations from one consistent chain snapshot. Callers now read that data off ConsensusValidator instead of threading parallel dicts and index sets around.

ConsensusValidator

Four new optional fields, populated only when the corresponding flag is passed:

  • pending_balance — total amount queued for the validator in the pending deposit queue
  • target_consolidation_balance — balance incoming from the validator's pending consolidation sources
  • is_consolidation_source, is_consolidation_target

build_consensus_validators

await build_consensus_validators(
    public_keys, chain_head=None,
    with_pending_deposits=False, with_consolidations=False, compounding_deposits_only=False,
)
  • with_pending_deposits fills pending_balance and additionally returns validators that are not in the beacon state yet but already have pending deposits. Those get UNKNOWN_VALIDATOR_INDEX and take their withdrawal credentials from the deposit.
  • compounding_deposits_only counts only 0x02 deposits, which is what the funding path needs.
  • with_consolidations sets the consolidation flags. target_consolidation_balance stays None when any of a target's sources is outside the fetched set, i.e. its balance is unknown — previously this exclusion was order-dependent inside the loop, now it is not.

Callers

fetch_funding_validators_balances is reduced to an eligibility filter plus a sum over the built validators. Behavior is unchanged.

The withdrawal task drops get_pending_consolidations / fetch_pending_deposits_amounts and their derived arguments:

  • get_queued_assets(consolidations=...) and _calculate_validators_exits_amount(source_consolidations_indexes=...)is_consolidation_source
  • _get_withdrawals / _filter_exitable_validators lose consolidation_target_indexes, consolidation_source_indexes and pending_deposits → flags and pending_balance

The pending deposit queue is still fetched lazily, only once a withdrawal is known to be needed, via the now-public apply_pending_deposits. Fetching it as part of the initial build would pull the whole queue on every interval tick, including the common case where the task returns early.

Non-mutating helpers

Neither enrichment step touches the validators it is given:

  • _apply_pending_consolidations returns a copy of the list, in the original order, with the consolidation fields filled in
  • apply_pending_deposits returns a tuple of (a copy of the list with pending_balance filled in, the validators that are missing from the beacon state but present in the pending deposit queue)

fetch_pending_deposits_amounts had no callers left and is removed.

Comment thread src/withdrawals/tasks.py
Comment thread src/validators/consensus.py Outdated
cyc60
cyc60 previously approved these changes Aug 19, 2026
@evgeny-stakewise
evgeny-stakewise merged commit a7d6fff into master Aug 19, 2026
10 checks passed
@evgeny-stakewise
evgeny-stakewise deleted the extend-validator branch August 19, 2026 09:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants