SSV Checkpoint Sync Trust Model

[diegomrsantos]

SSV Checkpoint Sync Trust Model

Status: working decision note before SIP text or contract code.

Author: Diego Marin Santos (@diegomrsantos)

Goal

A client should be able to start from finalized Ethereum block B, download an SSV checkpoint snapshot, rebuild public SSV network state at B, and continue processing recent SSV events from B + 1.

The client should not need historical SSV logs from contract deployment.

Problem

Current SSV clients rebuild this state by replaying historical contract events. This means a new client needs old logs to sync.

A checkpoint snapshot removes that dependency, but the client still needs to know whether the snapshot is valid.

Today there is also no SSV contract value that represents the full public SSV network state at finalized block B. That means clients do not have a compact protocol commitment they can compare against to check whether they reconstructed the same state for B.

This document only decides how snapshot validity is established.

Design Choice

Question	Candidate A: trusted checkpoints	Candidate B: on-chain SSV state root
What authenticates the snapshot?	A configured publisher or signer set.	The SSV contract root at finalized block B.
Does it avoid old logs?	Yes.	Yes.
Can the client verify snapshot contents against the SSV contract?	Partially, through eth_call checks for fields the contract can read.	Yes, by comparing the full snapshot root.
Can clients compare one compact state commitment for block B?	No.	Yes.
Does it need contract changes?	No.	Yes.
Does it add gas to SSV contract writes?	No.	Yes.
Main trust assumption	The checkpoint publisher or signer set is honest for completeness and fields not covered by eth_call checks.	Ethereum finality plus correct SSV contract root logic, schema, and migration.
Use when	A checkpoint trust assumption is acceptable.	Snapshots should be verifiable from an untrusted source.

Both candidates can use the same SnapshotV1 format and the same deterministic snapshotRoot.

Candidate A: Trusted Checkpoints

Checkpoint publishers create SnapshotV1 at block B, compute snapshotRoot, and sign the checkpoint metadata.

A client verifies the configured signatures, imports the snapshot, then resumes event processing from B + 1.

This avoids old logs without changing the SSV contracts.

Candidate A can be hardened with eth_call checks at block B against the client's Ethereum endpoint. These checks compare snapshot fields with contract views for data the contract can read directly, such as global values, operator records, specific validator existence checks, and selected cluster tuple checks. This can catch many invalid snapshots, including snapshots produced from incomplete or buggy event data.

These checks are not a complete proof. They only cover what the contract can query at block B; they do not prove that the snapshot includes every public SSV record.

Advantages:

• no contract upgrade;
• no extra gas on SSV contract writes;

Limitations:

• the snapshot publisher is still trusted for completeness and fields the contract cannot check;
• optional eth_call checks reduce the risk of accepting an invalid snapshot but do not remove publisher trust;
• the protocol must define who can publish checkpoints, how many signatures are required, how publisher keys are rotated or revoked, and when a checkpoint is too old to use.

Candidate B: On-chain SSV State Root

The SSV contract stores a root for public SSV network state:

uint32  public ssvSnapshotSchemaVersion;
bytes32 public ssvPublicStateRoot;

A client accepts a snapshot only if its recomputed snapshotRoot equals the contract root at finalized block B.

This avoids trusting the snapshot source for contents. The snapshot source can serve bad data, but the client rejects it if the root does not match.

It also gives clients one compact value for public SSV network state at block B: ssvPublicStateRoot.

Advantages:

• snapshot contents can be checked against an SSV contract commitment;
• clients can compare one compact state commitment for block B;
• the snapshot source does not need to be trusted for contents.

Costs:

• requires a contract upgrade;
• adds gas to SSV contract writes that change checkpoint state;
• requires storage used to update the root;
• requires a one-time migration/backfill because mainnet state already exists before the root is introduced;
• requires every compliant client to implement the same root calculation;
• root schema, migration, and update logic must be audited carefully.

What these costs mean:

• Contract upgrade: the SSV contracts must add the root, schema version, and root update logic.
• Write gas: every contract call that changes checkpoint state must also update the root. The exact gas cost needs a prototype; it becomes a permanent cost for those writes.
• Storage: the contract needs enough stored state to replace old records with new records when the root changes. Without that state, normal writes would need to provide the previous record.
• Root construction: the SIP must define how record hashes are combined into one root.
• Client implementation: every SSV client needs a compatible Merkle implementation that follows the same leaf encoding, sorting or indexing rules, empty leaf rules, and root calculation as the contract. Existing libraries may reduce this cost, for example Parity's binary-merkle-tree or Nervos's sparse-merkle-tree in Rust, and Go Merkle libraries or go-ethereum trie code if they match the final root design.
• Migration/backfill: existing mainnet state was created before the root existed. The initial root must be built from the existing state before clients can use it.
• Initial root agreement: the migration block root should be computed and checked by multiple independent parties before activation. This is especially important for fields that currently require historical events to reconstruct.
• Audit scope: bugs in encoding, migration, or contract update logic could make a valid snapshot fail verification or make an invalid snapshot appear valid.
• Compatibility: future SSV contract changes that affect public network state must either preserve the existing root schema or introduce a new schema version and migration path.

Candidate B does not replace Ethereum finality or weak subjectivity. It only lets the client check that the snapshot matches the SSV root stored at block B, and lets implementations compare that root when they need to check whether they reconstructed the same public SSV state.

Root Construction

The root construction is the main technical choice inside Candidate B. It defines how many public state records become one ssvPublicStateRoot, and how that root changes when one record is added, updated, or removed.

The safe family of choices is Merkle commitments based on hash functions. They are standard, auditable, and avoid RSA, pairing, and elliptic curve assumptions. That matters for a future migration to post quantum cryptography: the root would rely on hash security rather than factoring or discrete log assumptions.

Two Merkle designs are worth evaluating first:

Design	How records are addressed	Update cost	Main benefit	Main cost
Indexed Merkle trees with fixed capacity	Each record gets a stable numeric index inside a domain tree.	O(log capacity)	Cheaper than a 256-level sparse tree when capacities are bounded.	Requires index assignment, capacity planning, and rules for removed records.
Sparse Merkle Tree	Each record is keyed by a canonical ID, such as H(domain, owner, validatorPubkey).	O(log keyspace), typically much deeper	Simpler keying; no separate index assignment.	Higher gas/storage for updates unless heavily optimized.

The likely first prototype should be indexed Merkle trees with fixed capacity, because SSV state has natural domains such as operators, owners, clusters, and validators. That design only works if stable indices and capacity limits are acceptable. If index management becomes too complex or fragile, Sparse Merkle Tree is the conservative fallback.

The SIP should not choose a root construction by intuition. It needs a prototype that measures gas for the affected write paths and verifies that independent implementations compute the same root from the same snapshot.

Decision Criteria

Choose Candidate A if the goal is practical checkpoint sync and the protocol is comfortable trusting configured checkpoint publishers.

Choose Candidate B if the snapshot should be verifiable from an untrusted source by comparing it with a commitment in the SSV contract, or if SSV needs a compact state commitment for finalized block B.

The main decision is whether the extra security of Candidate B is worth those costs.

Open Questions

1. Should checkpoint validity rely on trusted publishers, optionally hardened with eth_call checks, or on a state root maintained by the SSV contract?
2. If Candidate A is acceptable, who should be allowed to publish checkpoints, and what signature threshold should clients require?
3. If Candidate B is required, is SSV willing to accept the ongoing gas cost, extra storage, client implementation work, and migration ceremony?
4. For Candidate B, should the root use indexed Merkle trees with fixed capacity or a Sparse Merkle Tree? The current recommendation is to prototype indexed Merkle trees first, and fall back to a Sparse Merkle Tree if index management or capacity limits are not acceptable.
5. Checkpoint cadence should be driven by two limits: maximum events since the last checkpoint and maximum checkpoint age. Initial values should be based on recent mainnet event counts, the largest observed event bursts, snapshot import time, and the time required to process events after a checkpoint.

[GalRogozinski]

Just want to say it is nice you gave an extra option besides B, which was the only solution I had in mind!