Light clients

A light client can verify a Witness result without storing the complete attestation or batch history. It needs the object being verified and a trusted, secret-free network configuration containing witness IDs, public keys, signature scheme, and threshold.

Attestation path

For a basic result, the client verifies the threshold-signed attestation against NetworkVerificationConfig. For a batched result, it additionally fetches an inclusion proof from GET /v1/proof/:hash (or a full bundle from GET /v1/bundle/:hash) and checks the leaf, index, tree size, sibling path, and batch root using RFC 9162 rules.

Log path

The gateway exposes the latest or size-specific Signed Tree Head and consistency proof endpoints under /v1/log/. A client or the independent witness-auditor can verify the STH threshold signature and then verify that a later STH extends the earlier tree without rewriting its prefix. This requires retaining or otherwise trusting the earlier STH; fetching only the latest state cannot by itself demonstrate historical continuity.

The CLI supports local verification of attestations, proof bundles, STHs, and consistency proofs. In online mode it can fetch the home network configuration and referenced peer configurations. For stronger trust, use a locally pinned or independently reviewed configuration rather than blindly accepting a gateway's configuration.

Implemented behavior

Verification is fail-closed for invalid signatures, wrong network IDs, unknown or duplicate signers, invalid indexes, wrong roots, and malformed proof shapes. The public verification projection intentionally omits witness endpoints and bearer tokens.

Assumptions

The client has an authentic initial network configuration and can obtain the proof bytes without them being altered after retrieval; cryptographic checks detect alteration of signed/committed values.

Non-goals

“Light” means less history and storage, not anonymous transport or zero trust. A client still trusts its initial configuration and the cryptographic assumptions of Ed25519/BLS and SHA-256. A proof does not recover the original content from its hash.

TODO — maintainer review

Document a stable light-client retrieval sequence, including how clients pin an initial configuration and retain STH checkpoints across gateway changes.