SSZ-QL: A Guide to Querying Ethereum’s BeaconState Using Offsets, Proofs, and G-Indexes

Today, consensus clients cannot easily provide individual pieces of data from the BeaconState together with the proofs needed to verify them. Ethereum’s Light Client system defines some proof paths, but there is no universal or standard way for clients to generate or serve these proofs. Downloading the entire BeaconState is not realistic—the state for slot 12,145,344 is around 271 MB, which is too large to send over the network quickly and puts unnecessary load on both the node and the user. The spec even warns that the debug endpoints used for fetching full states are meant only for diagnostics, not real-world use.

A much better solution is to use Merkle proofs or multiproofs, which allow the provider to send only a very small, verifiable part of the state. This is especially useful because most of the state size comes from validators (~232 MB) and balances (~15 MB); the rest of the fields are about ~24 MB. If a user needs only one small field, it’s wasteful to download the entire 271 MB state. Instead, a Merkle proof can deliver just the requested leaf plus its authentication path—usually only a few kilobytes.

Because of this, we need a general and standardized way for clients to request only the data they need, along with the proof required to verify it. This reduces bandwidth, reduces CPU load, and replaces today’s scattered and custom implementations (for example, Nimbus’s special handling of historical_summaries).

This work is also important for the future of Ethereum. SSZ is becoming more central to the protocol: Pureth (EIP-7919) proposes replacing RLP with SSZ, and the upcoming beam chain (also called the lean chain) will leverage SSZ as its only serialization format. So building a clean, efficient, and standard method for proof-based data access is a key step toward future protocol upgrades.

Proposed Solution: Introducing the SSZ Query Language (SSZ-QL)

The idea of SSZ-QL was originally proposed by Etan Kissling. His main question was straightforward but powerful:

“What if we had a standard way to request any SSZ field — together with a Merkle proof — directly from any consensus client?”

Today, consensus clients do not offer a general or standardized method to request specific SSZ data with proofs. Some ad-hoc solutions exist (for example, Nimbus’ basic queries used by the verifying web3signer), but there is no proper, universal SSZ query language available—and certainly nothing ready at the time this idea was written.

Etan’s proposal describes what an SSZ Query Language should allow:

• Requesting any subtree inside an SSZ object
• Choosing whether a field should be fully expanded or returned only as a hashtreeroot
• Filtering (for example, finding a transaction with a certain root)
• Using back-references (e.g., retrieving the receipt at the same index as a matching transaction)
• Specifying where the proof should be anchored
• Supporting forward compatibility so clients can safely ignore unknown future fields

This kind of API could be used by both consensus and execution clients. With forward-compatible SSZ types (like those from EIP-7495), request and response structures can even be generated automatically.

Building on this idea, the proposed solution by Jun and Fernando, who are developing this as part of their EPF project in prysm, is to add a new Beacon API endpoint that supports SSZ Query Language (SSZ-QL). This endpoint lets users fetch exactly the SSZ data they need—no more, no less—together with a Merkle proof that verifies its correctness. The initial version will offer a minimal but practical feature set, which already covers most real use cases. (The draft API specification is available for review.)

Beyond this minimal version, also plan to create a full SSZ-QL specification. This expanded version will support advanced features such as filtering, requesting data ranges, and choosing custom anchor points, all with Merkle proofs included. They intend to propose this richer specification for inclusion in the official consensus specifications, and an early draft is already available for review.

Understanding Generalized Indexes (GI) Before Diving Into SSZ-QL

In SSZ, every object — including the entire BeaconState — is represented as a binary Merkle tree. \n A generalized index (GI) is simply a number that uniquely identifies any node inside this tree.

The rules are very simple:

• Root node has generalized index: \n GI = 1
• For any node with index i: \n left child = 2*i, \n right child = 2*i + 1

So the whole tree is numbered like:

GI:1 / \ GI:2 GI:3 / \ / \ GI:4 GI:5 GI:6 GI:7 ...

This numbering makes Merkle proofs easy. If you know the generalized index of a leaf, you know exactly where it sits in the tree and which sibling hashes must be included to verify it.

Example with Beacon State:

0 GenesisTime string 1 GenesisValidatorsRoot string 2 Slot string 3 Fork *Fork 4 LatestBlockHeader *BeaconBlockHeader 5 BlockRoots []string 6 StateRoots []string 7 HistoricalRoots []string 8 Eth1Data *Eth1Data 9 Eth1DataVotes []*Eth1Data 10 Eth1DepositIndex string 11 Validators []*Validator ← (p = 11) 12 Balances []string 13 RandaoMixes []string 14 Slashings []string 15 PreviousEpochAttestations []*pendingAttestation 16 CurrentEpochAttestations []*pedningAttestation 17 JustificationBits string 18 PreviousJustifiedCheckpoint *Checkpoint 19 CurrentJustifiedCheckpoint *Checkpoint 20 FinalizedCheckpoint *Checkpoint

There are 21 top-level fields (indexed 0..20). To place these into a Merkle tree, SSZ pads them up to the next power of two (32).

\n 32 leaves → depth = 5. \n Top-level leaves occupy the GI range:

32 ... 63

We compute the GI for a top-level field using:

Formula:

GI_top = 2^depth + field_index

For .validators, field index = 11

So: \n GI_validators = 2^5 + 11 = 32 + 11 = 43.

This GI (43) is the leaf commitment of the entire validator’s subtree inside the global BeaconState tree.

Multi-Level Proof: Example With validators[42].withdrawal_credentials

Now, suppose we want a proof for:

BeaconState.validators[42].withdrawal_credentials

This requires two levels of proof:

\

1. Prove that the entire validator’s subtree is included in the BeaconState root

   We already know:

• Top-level GI for validators = 43

  Using GI 43, the consensus client collects the sibling hashes on the path from leaf 43 up to root (e.g., GI 43 → 21 → 10 → 5 → 2 → 1).

  This gives the proof:

validators_root ---> BeaconState_root

\

1. Prove that validator[42].withdrawal_credentials is inside the validator’s subtree

   Now treat the validators list as its own Merkle tree.

   Inside this subtree:

• Validator 42 is the 42-nd element → it maps to some leaf index (e.g. chunk k) inside this subtree.

• Withdrawal credentials lives inside one of the 32-byte SSZ chunks of validator #42 (for example chunk k = 128 — number doesn’t matter, just concept).

  We now generate:

  leaf (withdrawal_credentials chunk) ---> validators_root

  by collecting sibling hashes inside the local validator-subtree.

  Final Combined Proof

  You end up with:

1. Local Level Proof Proves withdrawal_credentials --> validator_root 2. Top-level branch proof Proves validator_root --> BeaconState_root

A verifier can now reconstruct the BeaconState root from only:

• the requested leaf

• the two lists of sibling nodes

• the known BeaconState root

  No full state download needed.

┌───────────────────────────────┐ │ BeaconState Root │ └───────────────────────────────┘ ▲ │ (Top-level Merkle Proof) │ Sibling hashes for GI = 43 │ ┌─────────────────────────────────────────┐ │ validators_root (GI = 43) │ └─────────────────────────────────────────┘ ▲ │ (Local Subtree Proof) │ Proof inside validators list │ for index = 42 │ ┌─────────────────────────────────────────────────────────┐ │ Validator[42] Subtree (list element #42) │ └─────────────────────────────────────────────────────────┘ ▲ │ (Field-level Merkle Proof) │ Sibling hashes inside the │ validator struct │ ┌──────────────────────────────────────────┐ │ validator[42].withdrawal_credentials │ ← requested field └──────────────────────────────────────────┘

\

Understanding SSZ Serialization Before Computing Generalized Indices

To compute a correct generalized index, you must first understand how SSZ serializes and merklizes different data types. \n Generalized indices don’t exist in isolation—they are derived from the shape of the Merkle tree, and the shape of the tree depends entirely on how SSZ interprets the underlying Go struct fields.

In SSZ, each field can only be one of two categories:

\

1. Base Types (fixed-size values)

   uint64, Bytes32, Bytes20, uint256 etc. These are straightforward — they always serialize into a fixed number of bytes.

   \

2. Composite Types

   Container (like BeaconState), Vector[T, N] (fixed length), List[T, N] (variable length), Bitvector[N], Bitlist[N] And each of them is serialized in a slightly different way.

   To compute a generalized index (g-index) for any field inside a state, the SSZ tree must first know how that field is serialized. This is why the generated *.pb.go files include tags such as:

\

ssz-size:"8192,32" → Vector ssz-max:"16" → List ssz-size:"?,32" → List of Vector

\ To compute a generalized index for any field, we must first understand the SSZ structure of the object:

\

• which fields exist,
• whether each field is a List or Vector,
• how many chunks each field occupies,
• and how nested types should be traversed.

This is exactly what the AnalyzeObject function does in Prysm, located at encoding/ssz/query/analyzer.go

// AnalyzeObject analyzes given object and returns its SSZ information. func AnalyzeObject(obj SSZObject) (*SszInfo, error) { value := reflect.ValueOf(obj) info, err := analyzeType(value, nil) if err != nil { return nil, fmt.Errorf("could not analyze type %s: %w", value.Type().Name(), err) } // Populate variable-length information using the actual value. err = PopulateVariableLengthInfo(info, value) if err != nil { return nil, fmt.Errorf("could not populate variable length info for type %s: %w", value.Type().Name(), err) } return info, nil }

What analyzeType Does

analyzeType is the function that examines a Go value using reflection and figures out what kind of SSZ type it is. It is a pure type-analysis step — it does not depend on the actual runtime values, only on the Go type and the struct tags.

When you give it a field or struct, it:

• Checks the Go kind (uint, struct, slice, pointer, etc.)
• Reads SSZ-related struct tags like ssz-size and ssz-max
• Decides whether this field is:
• a basic SSZ type (uint64, uint32, bool)
• a Vector (ssz-size:"N")
• a List (ssz-max:"N")
• a Bitvector / Bitlist
• a Container (struct)
• Builds an SszInfo record that describes:
• the SSZ type (List, Vector, Container…)
• whether it is fixed-sized or variable-sized
• offsets of fields (for Containers)
• nested SSZ information for child fields

Think of analyzeType as the function that scans the type definition and produces a static SSZ layout blueprint for this type.

What PopulateVariableLengthInfo Does

While analyzeType studies the type, some SSZ objects cannot be fully described without the actual value. \n

Examples:

• Lists ([]T) need to know their current length
• Variable-sized container fields need their actual offset
• Nested lists need each element’s actual size

PopulateVariableLengthInfo fills in this missing runtime information.

\ It:

• Looks at the SszInfo blueprint created by analyzeType
• Looks at the actual value of the object passed
• Computes values that can only be known at runtime:
• length of Lists
• sizes of nested variable elements
• offsets of variable-sized fields inside Containers
• bitlist length from bytes

It processes everything recursively — for example, a Container with a List containing structs with Lists will all be filled in.

Think of PopulateVariableLengthInfo as the function that takes the blueprint from analyzeType and fills in the real measurements based on the actual value you pass.

Example:

Let's test this function with a passing BeaconState struct

type BeaconState struct { state protoimpl.MessageState `protogen:"open.v1"` GenesisTime uint64 `protobuf:"varint,1001,opt,name=genesis_time,json=genesisTime,proto3" json:"genesis_time,omitempty"` GenesisValidatorsRoot []byte `protobuf:"bytes,1002,opt,name=genesis_validators_root,json=genesisValidatorsRoot,proto3" json:"genesis_validators_root,omitempty" ssz-size:"32"` Slot github_com_OffchainLabs_prysm_v7_consensus_types_primitives.Slot `protobuf:"varint,1003,opt,name=slot,proto3" json:"slot,omitempty" cast-type:"github.com/OffchainLabs/prysm/v7/consensus-types/primitives.Slot"` Fork *Fork `protobuf:"bytes,1004,opt,name=fork,proto3" json:"fork,omitempty"` LatestBlockHeader *BeaconBlockHeader `protobuf:"bytes,2001,opt,name=latest_block_header,json=latestBlockHeader,proto3" json:"latest_block_header,omitempty"` BlockRoots [][]byte `protobuf:"bytes,2002,rep,name=block_roots,json=blockRoots,proto3" json:"block_roots,omitempty" ssz-size:"8192,32"` StateRoots [][]byte `protobuf:"bytes,2003,rep,name=state_roots,json=stateRoots,proto3" json:"state_roots,omitempty" ssz-size:"8192,32"` HistoricalRoots [][]byte `protobuf:"bytes,2004,rep,name=historical_roots,json=historicalRoots,proto3" json:"historical_roots,omitempty" ssz-max:"16777216" ssz-size:"?,32"` Eth1Data *Eth1Data `protobuf:"bytes,3001,opt,name=eth1_data,json=eth1Data,proto3" json:"eth1_data,omitempty"` Eth1DataVotes []*Eth1Data `protobuf:"bytes,3002,rep,name=eth1_data_votes,json=eth1DataVotes,proto3" json:"eth1_data_votes,omitempty" ssz-max:"2048"` Eth1DepositIndex uint64 `protobuf:"varint,3003,opt,name=eth1_deposit_index,json=eth1DepositIndex,proto3" json:"eth1_deposit_index,omitempty"` Validators []*Validator `protobuf:"bytes,4001,rep,name=validators,proto3" json:"validators,omitempty" ssz-max:"1099511627776"` Balances []uint64 `protobuf:"varint,4002,rep,packed,name=balances,proto3" json:"balances,omitempty" ssz-max:"1099511627776"` RandaoMixes [][]byte `protobuf:"bytes,5001,rep,name=randao_mixes,json=randaoMixes,proto3" json:"randao_mixes,omitempty" ssz-size:"65536,32"` Slashings []uint64 `protobuf:"varint,6001,rep,packed,name=slashings,proto3" json:"slashings,omitempty" ssz-size:"8192"` PreviousEpochAttestations []*PendingAttestation `protobuf:"bytes,7001,rep,name=previous_epoch_attestations,json=previousEpochAttestations,proto3" json:"previous_epoch_attestations,omitempty" ssz-max:"4096"` CurrentEpochAttestations []*PendingAttestation `protobuf:"bytes,7002,rep,name=current_epoch_attestations,json=currentEpochAttestations,proto3" json:"current_epoch_attestations,omitempty" ssz-max:"4096"` JustificationBits github_com_OffchainLabs_go_bitfield.Bitvector4 `protobuf:"bytes,8001,opt,name=justification_bits,json=justificationBits,proto3" json:"justification_bits,omitempty" cast-type:"github.com/OffchainLabs/go-bitfield.Bitvector4" ssz-size:"1"` PreviousJustifiedCheckpoint *Checkpoint `protobuf:"bytes,8002,opt,name=previous_justified_checkpoint,json=previousJustifiedCheckpoint,proto3" json:"previous_justified_checkpoint,omitempty"` CurrentJustifiedCheckpoint *Checkpoint `protobuf:"bytes,8003,opt,name=current_justified_checkpoint,json=currentJustifiedCheckpoint,proto3" json:"current_justified_checkpoint,omitempty"` FinalizedCheckpoint *Checkpoint `protobuf:"bytes,8004,opt,name=finalized_checkpoint,json=finalizedCheckpoint,proto3" json:"finalized_checkpoint,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache }

package main import ( "fmt" "github.com/OffchainLabs/prysm/v7/encoding/ssz/query" eth "github.com/OffchainLabs/prysm/v7/proto/prysm/v1alpha1" ) func main() { v := ð.BeaconState{} // Analyze it with Prysm’s existing SSZ analyzer info, _ := query.AnalyzeObject(v) fmt.Println(info.Print()) }

Output:

BeaconState (Variable-size / size: 2687377) ├─ genesis_time (offset: 0) uint64 (Fixed-size / size: 8) ├─ genesis_validators_root (offset: 8) Bytes32 (Fixed-size / size: 32) ├─ slot (offset: 40) Slot (Fixed-size / size: 8) ├─ fork (offset: 48) Fork (Fixed-size / size: 16) │ ├─ previous_version (offset: 0) Bytes4 (Fixed-size / size: 4) │ ├─ current_version (offset: 4) Bytes4 (Fixed-size / size: 4) │ └─ epoch (offset: 8) Epoch (Fixed-size / size: 8) ├─ latest_block_header (offset: 64) BeaconBlockHeader (Fixed-size / size: 112) │ ├─ slot (offset: 0) Slot (Fixed-size / size: 8) │ ├─ proposer_index (offset: 8) ValidatorIndex (Fixed-size / size: 8) │ ├─ parent_root (offset: 16) Bytes32 (Fixed-size / size: 32) │ ├─ state_root (offset: 48) Bytes32 (Fixed-size / size: 32) │ └─ body_root (offset: 80) Bytes32 (Fixed-size / size: 32) ├─ block_roots (offset: 176) Vector[Bytes32, 8192] (Fixed-size / size: 262144) ├─ state_roots (offset: 262320) Vector[Bytes32, 8192] (Fixed-size / size: 262144) ├─ historical_roots (offset: 2687377) List[Bytes32, 16777216] (Variable-size / length: 0, size: 0) ├─ eth1_data (offset: 524468) Eth1Data (Fixed-size / size: 72) │ ├─ deposit_root (offset: 0) Bytes32 (Fixed-size / size: 32) │ ├─ deposit_count (offset: 32) uint64 (Fixed-size / size: 8) │ └─ block_hash (offset: 40) Bytes32 (Fixed-size / size: 32) ├─ eth1_data_votes (offset: 2687377) List[Eth1Data, 2048] (Variable-size / length: 0, size: 0) ├─ eth1_deposit_index (offset: 524544) uint64 (Fixed-size / size: 8) ├─ validators (offset: 2687377) List[Validator, 1099511627776] (Variable-size / length: 0, size: 0) ├─ balances (offset: 2687377) List[uint64, 1099511627776] (Variable-size / length: 0, size: 0) ├─ randao_mixes (offset: 524560) Vector[Bytes32, 65536] (Fixed-size / size: 2097152) ├─ slashings (offset: 2621712) Vector[uint64, 8192] (Fixed-size / size: 65536) ├─ previous_epoch_attestations (offset: 2687377) List[PendingAttestation, 4096] (Variable-size / length: 0, size: 0) ├─ current_epoch_attestations (offset: 2687377) List[PendingAttestation, 4096] (Variable-size / length: 0, size: 0) ├─ justification_bits (offset: 2687256) Bitvector[8] (Fixed-size / size: 1) ├─ previous_justified_checkpoint (offset: 2687257) Checkpoint (Fixed-size / size: 40) │ ├─ epoch (offset: 0) Epoch (Fixed-size / size: 8) │ └─ root (offset: 8) Bytes32 (Fixed-size / size: 32) ├─ current_justified_checkpoint (offset: 2687297) Checkpoint (Fixed-size / size: 40) │ ├─ epoch (offset: 0) Epoch (Fixed-size / size: 8) │ └─ root (offset: 8) Bytes32 (Fixed-size / size: 32) └─ finalized_checkpoint (offset: 2687337) Checkpoint (Fixed-size / size: 40) ├─ epoch (offset: 0) Epoch (Fixed-size / size: 8) └─ root (offset: 8) Bytes32 (Fixed-size / size: 32)

In the SSZ analyzer output, the offset shown for each field represents the exact byte position where that field begins when the entire struct is serialized according to SSZ rules. SSZ serialization lays out all fixed-size fields first, tightly packed one after another, and the offset tells you where each of these fields starts within that packed byte stream. For example, in the line root (offset: 8) Bytes32 (Fixed-size / size: 32), the field root is a 32-byte fixed-size value, and its serialized bytes begin at position 8 in the SSZ-encoded byte array. The size indicates how many bytes the field contributes to the serialized output (32 bytes in this case). For fixed-size types, the size is predetermined, while for variable-size types, the analyzer computes the size based on the actual value. Together, the offset and size show exactly how the SSZ layout is organized in memory when the struct is serialized.

Example: Finding the Merkle Leaf for a Field Using the Offset

Let’s take a real field from the SSZ Analyzer Output:

├─ fork (offset: 48) Fork (Fixed-size / size: 16) │ ├─ previous_version (offset: 0) Bytes4 (Fixed-size / size: 4) │ ├─ current_version (offset: 4) Bytes4 (Fixed-size / size: 4) │ └─ epoch (offset: 8) Epoch (Fixed-size / size: 8)

We want to prove the field:

fork.epoch

The “fork” field in BeaconState starts at offset 48 in the serialized byte stream.

Inside fork, the epoch field starts at offset 8 (relative to the start of Fork).

So:

absolute_offset = base_offset_of_fork + offset_of_epoch_inside_fork absolute_offset = 48 + 8 = 56 bytes

fork.epoch begins at byte 56 of the full serialized BeaconState.

SSZ divides serialization into 32-byte chunks:

• Chunk 0 → bytes 0–31
• Chunk 1 → bytes 32–63
• Chunk 2 → bytes 64–95
• …

Now find which chunk contains byte 56:

chunk_index = floor(56 / 32) = 1

So:

The leaf containing fork.epoch is Leaf / Chunk 1.

fork.epoch is an 8-byte integer

Within chunk 1 (bytes 32–63):

local_offset = 56 - 32 = 24

So inside the 32-byte leaf, the bytes look like:

[ 0 … 23 ] → unrelated fields [ 24 … 31 ] → fork.epoch (8 bytes)

To prove this value, you:

1. Take chunk 1 → this is your leaf.
2. When hashing up the tree, at each level:

• If chunk is a left child → record the right sibling hash.
• If chunk is a right child → record the left sibling hash.

1. Continue until you reach the top Merkle root.

The collected sibling hashes form your:

➡ SSZ Merkle proof branch for fork.epoch

Anyone can verify this by recomputing:

hash_tree_root(leaf + all_siblings) == state_root

This introduces two new endpoints that expose the initial version of SSZ Query Language (SSZ-QL) in Prysm:

/prysm/v1/beacon/states/{state_id}/query /prysm/v1/beacon/blocks/{block_id}/query

\ Both endpoints follow the SSZ-QL endpoint specification and allow clients to request specific fields inside a BeaconState or BeaconBlock using a query string. The server returns the requested SSZ field encoded as raw SSZ bytes. For now, at the time of writing this, the feature supports only a single query per request, and the include_proof flag is ignored — the PR always returns responses without Merkle proofs.

The request structure is:

type SSZQueryRequest struct { Query string `json:"query"` IncludeProof bool `json:"include_proof,omitempty"` }

And both endpoints return an SSZ-encoded response of this form:

type SSZQueryResponse struct { state protoimpl.MessageState `protogen:"open.v1"` Root []byte `protobuf:"bytes,1,opt,name=root,proto3" json:"root,omitempty" ssz-size:"32"` Result []byte `protobuf:"bytes,2,opt,name=result,proto3" json:"result,omitempty" ssz-max:"1073741824"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache }

For the full specification and examples, you can refer to this link

For now, the implementation locates the requested field using the computed offset and size information from the SSZ analyzer, rather than using a generalized index.

:::tip For more information, you can check out Jun Song’s work — implemented together with Fernando as part of their EPF project in prysm.

:::

\