SpectreImplementation

Light client

Components · 1 of 2 — the on-chain verifier and root of trust for Cosmos consensus.

Overview

The Spectre client is our ICS-07 Tendermint light client, built on the generic ICS-02 client interface — and it does exactly what those specs define: hold a trusted view of the Cosmos chain's consensus, advance it on updateClient, answer verifyMembership / verifyNonMembership, and freeze on misbehaviour.

The one place we re-design is updateClient — we split it in two:

  • UpdateConsensusState — advance the validator set. The expensive, signature-heavy update; it carries and verifies the Groth16 proof that the trusted validators' Ed25519 signatures over the header are valid.
  • UpdateApplicationState — advance the block state (the header's appHash) against the already-trusted validator set. Lighter — it still verifies the signature proof, but skips re-storing the set.

The point of the split is the asymmetry: a validator set rarely changes meaningfully, while the block changes every height — so we do the heavy validator-set re-verification only when the set has a major update, and advance block state cheaply the rest of the time. (Every update still verifies the per-block signature proof.) The full rationale is in Design choices.

Component structure

SpectreClient implements the ICS-07 Tendermint client interface — it's the coordinator every call enters through, and the only stateful piece (it owns the Store). The real work goes to small, single-purpose, stateless helpers, each verifying one kind of claim.

spectre-client-structure
#ComponentResponsibility
1SpectreClient (orchestrator)Implements the ICS-07 / ILightClient interface — the entry point that routes every call to the helpers below. Owns the Store, hands the pinned set to UpdateClient, and performs the state writes (re-pin / consensus / appHash).
└─Store (inside SpectreClient)The client's on-chain state — consensus states, the validator-set cache, and snapshots (detailed below).
2UpdateClientVerifies a header is valid and signed — the basic checks (chain-id, trusting period, monotonic time, increasing height, header-hash), the batch signature check via its nested SignatureVerifier, and the ⅔ voting-power quorum summed off-circuit against the trusted set SpectreClient hands in.
└─SignatureVerifier (inside UpdateClient)The ZK layer — verifies the Groth16 pairing that the submitted validators' Ed25519 signatures over the header are valid.
3MembershipVerifies ICS-23 membership and non-membership proofs — whether a packet commitment is present under the trusted root.
4MisbehaviourDetects conflicting headers — two distinct blocks signed at the same height — and freezes the client.

Detailed design

1. SpectreClient

SpectreClient is the ICS-07 orchestrator and the only stateful piece. It exposes the light-client API, owns the Store, and routes each call to the helper that handles it.

  • updateClient goes to UpdateClient, for both UpdateConsensusState and UpdateApplicationState.
  • verifyMembership and verifyNonMembership go to Membership.
  • misbehaviour goes to Misbehaviour.

Only SpectreClient holds state. The helpers are stateless, reading and writing the trusted consensus data through its Store.

Store

The Store keeps three pieces of on-chain state:

FieldWhat it holdsHow it's stored
Consensus statesThe trusted appHash root, timestamp, and nextValidatorsHash, per height.mapping(height → keccak256(consensusState)).
Validator-set cacheThe current set (packed index ‖ votingPower ‖ pubkey entries, up to 180 validators), keyed by validatorsHash, with total voting power alongside.Written via SSTORE2. Reading is cheap, and the heavy set never sits in ordinary storage slots.
SnapshotsA per-height snapshot of {validatorsHash, pointer, totalVotingPower}.Binary-searched by height, so a proof anchored at a past trusted height resolves against the set that was trusted then.

2. UpdateClient

UpdateClient advances the client only when a header is both valid and signed. It serves both split calls — UpdateConsensusState and UpdateApplicationState (per-call flows in § Flow) — running the identical header verification; the two differ only in what SpectreClient writes afterward (re-pin a new set vs. advance appHash alone).

Verification splits across two halves:

  • Off-circuit (Solidity). The non-signature checks: basic validation (chain-id matches, the header sits within the trusting period, its hash matches the commit's block ID, and so on) and the finality threshold — the signing validators' voting power must exceed ⅔ of the trusted set.
  • On-circuit (SignatureVerifier). The Ed25519 signature verification via ZK, batch-verified.

Both halves read the same header fields; input binding enforces that these fields are consistent across the two halves (see Input binding).

spectre-input-binding

SignatureVerifier

Because a static circuit has a fixed-size witness, the number of signatures it can verify is fixed at compile time. We therefore compile a separate circuit for each of a fixed set of sizes, which we call buckets (one circuit that verifies 8 signatures, another for 16, and so on). To minimize the number of signatures we must prove to reach ⅔ stake, the relayer packs the biggest-stake validators that signed the block, reaching the threshold with as few signatures as possible.

SignatureVerifier is the on-chain Groth16 verifier contract that checks these buckets. It holds a (pk, vk) map, one entry per bucket-size circuit, and verifies each proof against the entry for its bucket.

SignatureCircuit

The circuit has only one public witness, hash(exposed input). Every other input it needs, for both input binding and the signature check, is private witness. Its constraints prove two statements:

  • Signature check. The N signatures for the bucket, Header.Signature[N], are valid signatures for Header.Content, verified in batch. The batch verification is transformed into MSM (multi-scalar-multiplication) which is solved inside the circuit via ECIP (see Optimizations for more details).
  • Input binding. The circuit checks that hash(exposed input) = H.

Input binding

For the circuit, more public witness means more gas, so it is optimal to keep every input private. But some inputs, like header.content and header.signature.pubkey[], are also needed by the off-circuit logic. To enforce that a single instance of header.content and header.signature.pubkey[] satisfies both the on-circuit check and the off-circuit check, the circuit would need to expose these inputs as public witness, so that we know off-circuit(exposed inputs) = on-circuit(exposed inputs). But that is gas-expensive, as noted above.

The gas-efficient way keeps the exposed inputs private: the off-circuit side (Solidity) computes H = hash(exposed input) and passes it in as the circuit's single public witness; the circuit recomputes the hash over its own private copy of those inputs and asserts it equals H. That one public value binds both sides to the same inputs, at the cost of a single public witness.

Flow

UpdateConsensusState — rotate the validator set

spectre-update-consensus-state

The heavy update, run every 24 hours to rotate the validator set:

  1. Header checks (UpdateClient). Validate the header: chain-id, trusting period, monotonic BFT time (not from the future), increasing height, and header-hash matching the commit's block ID.
  2. Signature verification (SignatureVerifier, nested in UpdateClient). Verify the Groth16 batch proof that the currently-trusted validators' Ed25519 signatures over the header are valid. This step checks signatures only and has nothing to do with the quorum.
  3. Finality threshold (UpdateClient, off-circuit). Sum the signers' voting power against the pinned set SpectreClient handed in, requiring it to exceed ⅔ of the total.
  4. Verify the new set (SpectreClient). Hash the supplied validator set and require it equals the header's nextValidatorsHash, so the set being pinned is the one the verified header commits to.
  5. Re-pin (SpectreClient). Store the verified set and advance the consensus state in the Store.

UpdateApplicationState — advance the block state

spectre-update-application-state

This advances the header's appHash while the validator set is unchanged. It still verifies the block's signature proof against the already-trusted set. The only difference from updateConsensusState is that it doesn't re-store a new validator set.

3. Membership

Membership is the block-inclusion verifier — the second half of every message check, implemented in plain Solidity with no ZK. It exposes two calls, each evaluated as an ICS-23 proof against the trusted appHash root:

  • verifyMembership confirms that a key–value pair (a packet commitment) is present under the root.
  • verifyNonMembership confirms that a key is absent — used for timeouts.

Each is checked as an ICS-23 existence or non-existence proof against the leaf and inner-node op specs.

4. Misbehaviour

Misbehaviour takes two headers at the same height, proves they conflict, and freezes the client. It accepts the evidence only when all of the following hold:

  • Both headers are individually valid — matching chain-id, equal height, header-hash matching the commit, within the trusting period, monotonic time, and bounded clock drift.
  • Both are signed by a quorum of the trusted validator set.
  • Their block IDs differ — two distinct blocks were signed at the same height.

On this page