Crate eth_state_diff 

eth-state-diff

High-performance delta encoding and reconstruction for Ethereum consensus state.

This crate computes compact deltas between two beacon states and applies those deltas to reconstruct the target state without requiring the entire state to be serialized or rewritten.

The delta format is designed around the update semantics of individual Ethereum consensus-state fields. Depending on the field, the crate uses specialized representations such as sparse updates, append-only deltas, circular-buffer writes, FIFO queue deltas, and full replacements.

Overview

A state transition is represented by BeaconStateDelta. The transition has two stages:

1. create compares the base and target state through DiffSource and constructs a BeaconStateDelta.
2. apply applies the delta to a state through DiffTarget, producing the target state.

       base state ───────┐
                          │
                     [`create`]
                          │
                          ▼
                 [`BeaconStateDelta`]
                          │
                     serialize
                          │
                          ▼
                   transport / storage
                          │
                      deserialize
                          │
                          ▼
                 [`ArchivedBeaconStateDelta`]
                          │
                     [`apply`]
                          │
                          ▼
                      target state

The crate does not impose a particular beacon-state storage layout. DiffSource and DiffTarget provide the integration boundary between the delta algorithms and a consensus client’s state representation.

Delta representations

Each state component uses an encoding appropriate to its update pattern:

• Balances use packed 2-bit tags and compact difference encoding.
• Validators use field-level patches rather than rewriting complete validator records.
• Recent roots record only roots written to circular buffers during the diff window.
• RANDAO mixes record the mixes written as epochs advance.
• Slashings use sparse ring-buffer updates.
• Eth1 data votes use append/reset semantics.
• Historical roots and summaries use protocol-defined append intervals.
• Attestations use unchanged, append, or replacement representations.
• Participation flags use packed sparse updates and an all-zero fast path.
• Inactivity scores use sparse updates and an all-zero representation.
• Sync committees use unchanged/full-replacement encoding.
• Pending deposits, withdrawals, and consolidations use a validated FIFO representation with full-replacement fallback.

This specialization allows the delta to represent the state transition rather than treating the serialized beacon state as one opaque byte array.

Serialization

Delta structures derive rkyv::Archive, rkyv::Serialize, and rkyv::Deserialize and are therefore suitable for zero-copy or archived representations where appropriate.

The delta algorithms themselves operate on native Rust values and serialized SSZ byte sequences where field-level SSZ representation is required. Serialization is deliberately kept separate from the diff algorithms.

Fork handling

ForkName identifies the consensus fork associated with a delta.

Fork-specific fields are represented as Option<T> inside BeaconStateDelta. A field is populated only when it exists for the corresponding fork. apply validates these invariants before modifying the destination state and rejects fork mismatches or fields that are invalid for the delta’s fork.

Integration

Consensus clients integrate with this crate by implementing two traits:

• DiffSource exposes the base and target state components required to create a delta.
• DiffTarget exposes mutable access to the state components required to apply a delta.

Collection-specific integration can additionally use ListMutTarget for list-like collections and ValidatorMutTarget for validator registries.

The crate intentionally does not require a particular consensus-client implementation, allocation strategy, or state storage backend.

Modules

attestations

Delta encoding for Phase 0 pending attestation lists.

balances

Compact delta encoding and reconstruction for Ethereum validator balances.

error

eth1_data_votes

Delta encoding for the Eth1 data vote list.

historical_log

Delta encoding for append-only historical logs.

inactivity_scores

Delta encoding for validator inactivity scores.

participation

Compact delta encoding for Ethereum epoch participation flags.

pending_queue

Delta encoding for SSZ lists that behave as FIFO queues.

randao_mixes

Delta encoding for Ethereum RANDAO mix buffers.

recent_roots

Delta encoding for fixed-size Ethereum consensus root buffers.

slashings

Delta encoding for Ethereum slashing vectors.

sync_committee

Delta encoding for Ethereum sync committees.

types

Core data structures used by eth_state_diff.

validators

Delta encoding and reconstruction for Ethereum validator registries.

Structs

ArchivedBeaconStateDelta

An archived BeaconStateDelta

BeaconStateDelta

Complete compact representation of the transition between two beacon states.

BeaconStateDeltaResolver

The resolver for an archived BeaconStateDelta

Enums

ArchivedForkName

An archived ForkName

ForkName

Identifies the Ethereum consensus fork associated with a beacon state or state delta.

ForkNameResolver

The resolver for an archived ForkName

Traits

DiffSource

Read-only state interface used by create.

DiffTarget

Mutable state interface used by apply.

ListMutTarget

A mutable target for list-like collections of copyable values.

Functions

apply

Applies an archived BeaconStateDelta to a mutable beacon state.

create

Creates a BeaconStateDelta describing the transition between two beacon states.