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!

[GalRogozinski]

I personally think candidate A is acceptable.
Mainly because if an issue will rise there will always be a way to get the real history via archive nodes or portal network

So I think we should develop this solution first.

Nevertheless, if due to other reasons we need to change the contract we can add option B (if we see demand for it).
That is also questionable because not sure users will appreciate the increase in gas costs.

[diegomrsantos]

I agree Candidate A is probably the practical first version, especially if we want checkpoint sync without contract changes. I just think it would help to make the trust and recovery model a bit more explicit.

One thing I’d like to clarify is what we mean by an issue arising. A checkpoint can have valid signatures and metadata but still be incomplete or semantically wrong. In that case, a client may not know there is a problem unless some check catches it, another checkpoint source disagrees, or someone independently audits the checkpoint.

Historical replay can still be useful as an audit or recovery path once a checkpoint is questioned. But then we should describe it that way. If historical replay is reliable and practical enough for nodes to depend on, the motivation for checkpoint sync is weaker. If it is slow, expensive, rate limited, or operationally fragile, then it should not be the main safety argument for accepting trusted checkpoints.

I would also be careful with archive nodes here. Current SSV replay uses historical eth_getLogs; it does not need archive state. By archive state I mean old Ethereum account and contract storage state, which is needed for things like eth_call or eth_getStorageAt at block B. For plain SSV replay, the relevant question is whether we can reliably get the historical SSV event logs from deployment onward. Saying archive nodes does not by itself answer that.

Another limitation of Candidate A is that it keeps the current situation where nodes do not have a protocol commitment for the full public SSV network state at a given block. So two clients still cannot compare one compact value and know they reconstructed the same SSV state. Candidate B would solve that, but with the contract and gas costs already described.

I would not rely on Portal Network unless someone can point to a maintained production path for the exact SSV historical logs we need.

On Candidate B and demand, I think we should define concrete triggers: client teams not being comfortable with trusted signers, operators wanting untrusted checkpoint mirrors, conflicting or invalid checkpoint incidents, or a contract upgrade where the added gas cost is acceptable.

So I’m fine with Candidate A first, but the SIP should describe it as trusted checkpoints plus optional checks and separate audit/recovery. If we need untrusted import time validation, that is what Candidate B is for.

[GalRogozinski]

Very good points, thanks @diegomrsantos!
I meant archive RPC providers, thanks for the correction.

I think the main safety argument for accepting trusted checkpoints is that trust is enough in this case for most parties.
The incentives to inject a malicious state are weak, especially compared with blockchain scenarios.

All the triggers you mentioned are good for Candidate B.

[ColinkaMir]

Operator perspective from 17 months on mainnet (op 1039, Lido x SSV
Splendid Swan):

Strong +1 for Candidate A as the immediate fix. I went through a long
re-sync myself this month when I moved the operator infrastructure to
a new server in Czechia, and the historical event replay alone was a
multi-hour blocker. Without that path, the same move would have left
the operator offline indefinitely once pruning kicks in. Waiting on B
would leave that gap open for months.

One practical question on the trusted side: would the publisher set be
SSV Foundation plus Labs alone, or could it include a small set of
elected community operators? Liveness diversity matters more here than
adversarial resistance.

On concrete triggers for Candidate B: the one that would make me
personally want it is an incident where two checkpoint sources
disagreed and operators had no straightforward way to tell which one
matched real state. Until something like that happens, A seems like
the right balance against the added gas cost.

[GalRogozinski]

If there is a will from the community to participate that will be fantastic in my personal opinion.
I think one publisher but many signers/verifiers scheme will be good here.

[ColinkaMir]

Sounds like a strong fit. One publisher for liveness plus a wider
signer pool that can include community operators makes sense. Happy
to be in that pool if a process is opened. One thing worth defining
early: would signers attest the published snapshot matches their own
rebuilt state, or only confirm format? The first is stronger but
means signers maintain that infrastructure long-term.

[zhangyuting]

Since the metadata volume of the SSV network is now very large, with a massive number of validators and expectations of significant future growth, choosing Option B seems completely unreasonable. It poses a major challenge to contract storage and gas costs. I agree with using Option A, even as a long-term solution, but I recommend mandating verification via eth_call to avoid bugs in the publisher.

[diegomrsantos]

Since the metadata volume of the SSV network is now very large, with a massive number of validators and expectations of significant future growth, choosing Option B seems completely unreasonable. It poses a major challenge to contract storage and gas costs. I agree with using Option A, even as a long-term solution, but I recommend mandating verification via eth_call to avoid bugs in the publisher.

I agree Candidate B adds gas and storage, but I do not think “completely unreasonable” follows without a prototype.

The size of SSV metadata alone does not decide the cost. A commitment design should update only the affected owner, operator, cluster, and validator leaves. The real question is the chosen tree structure, the auxiliary state needed to maintain the root, and the gas delta on register, remove, liquidate, and reactivate paths.

Also, Candidate B does not mean storing the full snapshot payload on chain. The snapshot can carry preimages while the contract stores the public state root, schema version, and whatever maintenance state is needed to update the root. Some fields are already contract state, and some log only fields would need to be added or committed to, so this needs measurement rather than a blanket rejection.

I agree Candidate A is probably the practical first version, and mandatory eth_call consistency checks are useful. But eth_call checks harden trusted checkpoints; they do not prove completeness unless the contract exposes or commits to the full public state.

[diegomrsantos]

The context here is Candidate A from the SIP discussion (trusted checkpoints). The weakness A leaves open is completeness. A checkpoint can carry valid signatures and correct metadata and still be missing or wrong about part of the state, and the eth_call hardening we discussed can confirm records we already know about but can't prove that nothing was omitted. The way to close that gap is a commitment over the complete state — a state root that two independent clients compute the same way. Here's a path that reduces the completeness trust assumption step by step.

1. Fix the existing divergence between Anchor and go-ssv. Today the two clients can build different state from the same logs. The current instance is operator key decoding (Anchor #972 — details there). This matters beyond the bug itself: it's direct evidence that we don't yet share a single definition of network state, which is the precondition for everything below.

2. Define a canonical spec for the global state. Both clients must produce the same root from the same logs, so we need to pin down what goes into the state and exactly how it is encoded. That means deciding what is in scope (global, on-chain-derived state) and what is out (data local to a node such as a node's own validator shares, data local to a client such as graffiti, and the block height, which is a reference point rather than state), plus the canonical ordering and encoding of every record and any derived value such as cluster IDs. #972 is one landmine here; there are others, including record ordering, address formatting, and default fallbacks.

3. Add a differential root check between the clients first. Once Anchor and go-ssv can each emit a root, we diff them across history. This is useful on its own as a conformance check before any checkpoint feature exists — it would have surfaced #972 automatically as a root mismatch, instead of a sync that wedges several blocks later. A disagreement means one client has a bug, caught early.

4. Produce and sign checkpoints. A signer-set node, on a cadence (every N blocks, or driven by event volume and a max age — this is an open question in the SIP), independently rebuilds the state, computes the root, and signs a small manifest with a post-quantum key (ML-DSA-65 is a natural candidate). The signature means "I rebuilt this state myself and got this root," not "I saw this file." The signed manifest and the snapshot data are published; where they are hosted is a separate question from trust, since hosting only provides availability.

5. Accept by comparing signatures. A new node imports a checkpoint when it sees enough matching signatures over the same manifest. Validity is X of Y matching signatures — but with a constraint that the agreeing set spans both client implementations (at least one Anchor and at least one go-ssv signer), not just X distinct keys. A flat threshold defends against a malicious or offline signer; the cross-implementation requirement is what defends against a reconstruction bug, where every signer running the same client would otherwise compute and agree on the same wrong root (#972 is exactly this failure mode). When the implementations disagree on the root for a block, no checkpoint is published and we investigate. The trade-off is a liveness dependency on each implementation having a signer online, which is acceptable because the fallback for a missing checkpoint is a full sync, while the cost of a wrong checkpoint is a corrupted node.

6. What the importing node trusts. A node syncing for the first time, or one whose last sync is older than the max age, trusts the checkpoint for the state itself — verifying completeness would mean folding the logs, which is the thing we're avoiding. The only cheap checks left are sanity bindings: right network and SSV contract, block B is real and finalized, and (for a stale resync) the checkpoint is newer than the node's current state. Full sync from genesis stays available as the trustless fallback and audit path, which is also why this signer layer is an accelerator rather than a new permanent trust root.

[GalRogozinski]

1. I agree this should be in priority. Tagging @Tom-ssvlabs for eth: historical sync rejects hex-encoded OperatorAdded keys and later aborts on OperatorRemoved sigp/anchor#972.

2. Definitely. I think just write your own proposal in the SIP. Then we will see if @momosh-ssv will want something changed. From my perspective we just need the implementation to agree,

3. You mean a manual step if we see the implementations disagree when trying to create a checkpoint? I also am not we want to use MMR constructions to preserve proof of inclusion capabilities. We can if it isn't hard. But I am guessing that in case of a root mismatch we can use binary search techniques to find the culprit.

4. I am not sure the cadence should be on the SIP, since this is not a strict standard nodes should follow. Per your point 6, the whole process is not part of the core protocol. Also not sure why we need PQ scheme at this point. By the time we migrate with Ethereum maybe we switch to candidate B? If we want the community to be part of the process (not sure that will happen) maybe we need to support current Operator keys? But we can iron this later.

5. For the exact operation of the process (which shouldn't be in the SIP) I think we need to define a process together with @zktaiga and @momosh-ssv (cc @Tom-ssvlabs) of where we upload the checkpoint and how certified parties can validate it. One we have X of Y validations, the checkpoint becomes available for the public to download
   (together with the certificates).
   Disagreements should be resolved manually.

6. Right, so what I draw from this that it suffices that we first write a SIP that defines the canonical state, checkpoint format, and certificates.

[diegomrsantos]

1. Agreed, this should be a priority. Thanks for tagging Tom.

2. Sounds good, I'll write it up in the SIP. We can adjust once there's a draft and see if momosh wants anything changed. Agreed the core of it is just getting the two implementations to produce the same state.

3. Good point on the question of whether root generation is manual. Generating the roots is automated. What can be manual is the comparison.

It helps to split this into two things we'd actually run.

The first is a CI test. We capture a fixed slice of real history into a file, with the expected roots written in. On every code change, both clients replay that file in CI and assert their roots match. That part is fully automated, comparison included, but it only covers the history baked into the file.

The second is a cross-client replay run. We start each client at the first SSV block, process all of history, and have each one emit a record every N blocks. Generating those records is automatic. Comparing the two clients' records is a separate step, and that's the part that's manual unless we build a small diff tool for it.

At each of those sampling points (every N blocks) each client emits three values: the block number, a hash of the logs it consumed up to that block, and the state root. The log hash is there because the comparison only means something if both clients read the same events, and RPC providers can differ in indexing, retention, or gaps. So we compare the log hash first. If the log hashes differ, that's a data-source problem, not a client bug. Only matching log hashes with differing state roots point to a real reconstruction divergence.

One thing worth calling out about clients that are already running. A deployed client synced to the tip keeps only current state and has discarded the earlier history, so it can emit those three values only from its deploy point forward, not for blocks before it started. That's still useful in two ways. Any running client, on either implementation, can emit the same three values as it follows the chain, so we get an ongoing stream of roots over new history without a dedicated replay run. And it gives us the production check directly: when we produce a checkpoint at a given block, the running clients on each implementation emit their root at that block, and those have to agree before we accept it.

So the replay run from the first SSV block is the one that catches a historical bug like #972, where (per #972) the two clients decoded an operator key differently. The root mismatch would have shown up right at that block.