builder payments tracking

[pk910]

Full State Transition & Withdrawal Indexing for Fulu/Gloas

This branch implements a complete consensus-spec state transition engine and withdrawal indexing system for Fulu and Gloas (ePBS) forks, replacing the previous approach of loading epoch boundary states from the beacon API with local replay.

State Transition Engine (indexer/beacon/statetransition/)

New package implementing the full process_slots + process_block + process_epoch state transition for Fulu+ states. This allows dora to compute epoch boundary states locally by replaying blocks on top of a cached parent state, eliminating the dependency on beacon API state requests for every epoch.

Block processing (block.go):

• process_slots with per-slot state/block root caching
• Parent state root hint to skip expensive HTR computation (~2x speedup per block)
• process_block_header, process_withdrawals, process_randao, process_eth1_data
• process_execution_payload for Fulu (payload header caching) and Gloas (bid recording)
• process_sync_aggregate with proper BLS aggregate pubkey computation

Epoch processing (statetransition.go, and per-function files):

• All 17 Gloas epoch transition functions implemented:
  process_justification_and_finalization, process_inactivity_updates, process_rewards_and_penalties, process_registry_updates, process_slashings, process_eth1_data_reset, process_pending_deposits, process_pending_consolidations, process_builder_pending_payments, process_effective_balance_updates, process_slashings_reset, process_randao_mixes_reset, process_historical_summaries_update, process_participation_flag_updates, process_sync_committee_updates, process_proposer_lookahead, process_ptc_window

Operations (operations.go):

• Electra+ attestation processing with correct Deneb EIP-7045 participation flags (TIMELY_TARGET has no delay constraint)
• Gloas payload_matches and is_attestation_same_slot checks
• Gloas builder payment weight accumulation in process_attestation
• process_withdrawal_request with compute_exit_epoch_and_update_churn for partial withdrawals
• process_consolidation_request with switch_to_compounding_validator and queue_excess_active_balance

Withdrawals (withdrawals.go):

• Full Electra spec: is_fully_withdrawable_validator, is_partially_withdrawable_validator, is_eligible_for_partial_withdrawals
• get_balance_after_withdrawals to account for prior withdrawals in the same batch
• Correct pending partial withdrawal limit: min(prior + MAX_PENDING_PARTIALS_PER_WITHDRAWALS_SWEEP, MAX_WITHDRAWALS_PER_PAYLOAD - 1)
• Gloas builder pending/sweep withdrawals

Committees & shuffling (committees.go):

• Batch swap-or-not shuffle with per-round pivot caching
• Electra 16-bit sync committee sampling
• BLS aggregate pubkey computation via bls12-381-util

Architecture:

• StateTransition struct holds chain spec, dynamic-ssz encoder, and reusable caches
• All internal functions are methods on StateTransition -- no parameter threading
• stateAccessor provides unified field access across Fulu/Gloas state versions
• Caches auto-invalidate on epoch boundaries and after effective balance updates

State Cache (statecache/)

Optional file-system-backed cache for beacon states. States are stored as gzip-compressed SSZ files keyed by (dependentRoot, targetEpoch). Configurable max states with LRU eviction. Eliminates redundant beacon API state requests on restart.

Epoch State Loading (indexer/beacon/epochstate.go, epochcache.go)

Reworked epoch state loading to prefer local replay over API requests:

1. Load parent epoch's last-block state from cache or API
2. Replay all in-epoch blocks using the state transition engine
3. Apply epoch transition via PrepareEpochPreState
4. Cache the result for future use
5. Fall back to API on any failure

Gloas-specific: orphaned payloads are detected by checking next_block.bid.parent_block_hash before applying, ensuring only accepted payloads advance the state.

Withdrawal Indexing

Database schema (db/schema/):

• New withdrawals table with type classification, reference slot tracking, and account-based filtering
• Migration for ref_slot column addition

Withdrawal types (dbtypes/dbtypes.go):

• Type 1: Full withdrawal (exited + withdrawable)
• Type 2: Sweep withdrawal (excess balance)
• Type 3: Requested withdrawal (EIP-7002)
• Type 4: Builder full withdrawal (Gloas)
• Type 5: Builder direct payment (payload delivered)
• Type 6: Builder delayed payment (missed payload, quorum penalty)

State simulator (indexer/beacon/state_sim.go):

• Builder payment classification with per-entry RefSlot tracking
• Direct payments track source block UID through the queue via trackedBuilderWithdrawal
• Delayed payments resolved by scanning source epoch blocks in FIFO order
• Initial direct entries from epoch boundary resolved against previous epoch's delivered-payload blocks

Builder balances (indexer/beacon/indexer_getter.go):

• GetRecentBuilderBalances returns epoch-start balances adjusted for in-epoch builder withdrawals
• Builder detail page overrides stale cache balance with fresh computation

Bid extraction (indexer/beacon/writedb.go):

• Execution payload bids extracted from Gloas block bodies during DB write
• Previously bids were only captured via SSE events, causing 0-value display during sync

UI Pages

• Withdrawal list page with type/validator/address filters (handlers/withdrawals_list.go)
• Validator withdrawal tab (handlers/validator.go)
• Builder withdrawal tab, recent blocks with bid values, recent bids (handlers/builder.go)
• Slot page withdrawal section with type badges
• Builder balance display on list and detail pages