Module validators 

Delta encoding and reconstruction for Ethereum validator registries.

This module computes compact ValidatorsDiff values between two validator registries and applies those deltas to reconstruct the target registry.

Validator records are fixed-width in their consensus SSZ representation, with VALIDATOR_SSZ_SIZE bytes per validator. The delta format avoids storing complete validator records when only individual fields have changed.

What is encoded

For validators present in both the base and target registries, the encoder stores patches only for fields whose values changed:

• ValidatorField::WithdrawalCredentials
• ValidatorField::EffectiveBalance
• ValidatorField::Slashed
• ValidatorField::ActivationEligibilityEpoch
• ValidatorField::ActivationEpoch
• ValidatorField::ExitEpoch
• ValidatorField::WithdrawableEpochSlashed

Validators that exist only in the target registry are stored as their raw SSZ representations in ValidatorsDiff::appended_validators.

The pubkey field is not patched because validator public keys are immutable after registration.

Withdrawable epoch

withdrawable_epoch is handled specially because its value is derivable for non-slashed validators. When exit_epoch changes on a non-slashed validator, the application side reconstructs:

withdrawable_epoch = exit_epoch + MIN_VALIDATOR_WITHDRAWABILITY_DELAY

For slashed validators, withdrawable_epoch is explicitly encoded because it is not reconstructed from exit_epoch alone.

This makes the delta smaller while preserving the target validator state.

Two integration APIs

The module provides two equivalent APIs for different validator storage layouts.

Contiguous SSZ storage

diff_validators and apply_validators operate directly on Vec<u8>/byte slices containing consecutive SSZ validator records.

This is useful for clients that keep their validator registry in a flat SSZ-compatible representation.

Native client storage

diff_validators_iter and apply_validators_iter operate through ValidatorSnapshot and ValidatorMutTarget.

This allows a consensus client to diff and reconstruct validators without first converting its native data structure into one large byte buffer.

The iterator API is particularly useful for clients whose validator registry is backed by persistent lists, trees, or other non-contiguous structures.

SSZ representation

The flat representation assumed by this module is the canonical consensus-layer validator SSZ layout:

Offset	Size	Field
0	48	pubkey
48	32	withdrawal_credentials
80	8	effective_balance
88	1	slashed
89	8	activation_eligibility_epoch
97	8	activation_epoch
105	8	exit_epoch
113	8	withdrawable_epoch

The total size is VALIDATOR_SSZ_SIZE bytes.

Complexity

Diffing is linear in the number of validators:

O(min(base_len, target_len) + appended_validators)

Applying a delta is linear in the number of patches plus the number of appended validators:

O(patches + appended_validators)

The contiguous byte implementation performs in-place mutation and does not require rebuilding the existing validator registry.

Delta validity

apply_validators and apply_validators_iter assume that the supplied delta was produced for the corresponding base validator registry. Application does not independently verify that every patch matches the expected base value.

Patch values are validated for the width required by their corresponding ValidatorField. Invalid patch data is reported as Error::MalformedDelta rather than causing reconstruction to panic.

A patch referring to a validator index that does not exist in the target collection is reported as Error::InvalidDelta.

Appended validator data must contain complete VALIDATOR_SSZ_SIZE-byte SSZ records.

ValidatorsDiff
ValidatorField
ValidatorSnapshot
ValidatorMut
ValidatorMutTarget
VALIDATOR_SSZ_SIZE
MIN_VALIDATOR_WITHDRAWABILITY_DELAY

Traits

ValidatorMut

Mutable view of a validator used during delta reconstruction.

ValidatorMutTarget

Mutable access to a validator collection used during reconstruction.

ValidatorSnapshot

Read-only view of a validator used by the delta encoder.

Functions

apply_validators

Applies a validator delta to a contiguous SSZ byte buffer in place.

apply_validators_iter

Applies a validator delta directly to a client’s native validator collection.

diff_validators

Computes a compact validator delta from two contiguous SSZ byte buffers.

diff_validators_iter

Computes a compact validator delta using client-provided validator views.