Struct LightClient 

pub struct LightClient { /* private fields */ }

Available on crate feature unstable only.

A light client that authenticates state against a trusted validator committee.

LightClient owns a Client for talking to a Sui gRPC endpoint and an EpochCache seeded with a starting committee. Each verification call advances the cache forward as far as needed (BLS-verifying each epoch transition along the way), verifies the response’s checkpoint summary against the now-cached committee, and finally verifies the returned proof against the trusted summary.

Implementations

impl LightClient

pub fn new(rpc: Client, starting_committee: ValidatorCommittee) -> Self

Build a new LightClient seeded with starting_committee.

The starting committee must be obtained out of band (e.g. baked into the application, or read from a trusted source). It need not be the genesis committee — a client that only cares about recent state can seed the cache with a known-trusted committee at a later epoch (see the bundled-trust-anchors feature) and skip ratcheting through every prior epoch.

pub fn with_ratchet_config(self, config: RatchetConfig) -> Self

Override the RatchetConfig used when this client advances its epoch cache. Defaults to RatchetConfig::default.

pub fn with_archive(self, archive: Client) -> Self

Attach an archive endpoint. The ratchet driver will prefer the archive for historical reads (GetEpoch during discovery and GetCheckpoint for end-of-epoch summaries) and fall back to the fullnode on any archive miss or error.

Archives serve historical data with higher availability and tighter latency than typical fullnodes; misses (newer checkpoints not yet archived) transparently fall back to the fullnode. Both clients are used read-only by the ratchet — nothing in the cache becomes trustworthy solely because the archive served it; every end-of-epoch summary is still BLS-verified against the cache’s current committee.

pub fn epoch_cache(&self) -> &EpochCache

Read-only access to the client’s epoch cache, for inspection.

pub fn rpc(&mut self) -> &mut Client

Mutable access to the underlying RPC client, for callers that want to issue additional gRPC requests through the same channel.

pub async fn latest_checkpoint_seq(&mut self) -> Result<u64, LightClientError>

Return the sequence number of the network’s most recent checkpoint, as reported by LedgerService.GetCheckpoint(latest).

The result is not trust-anchored — it’s a single read from the server with no signature verification. Streaming clients use it as a starting cursor (e.g., “begin reading events from the checkpoint after this one”); any subsequent claim about an object’s state at this checkpoint must still flow through Self::prove_object_at_checkpoint for cryptographic authentication.

pub async fn prove_object_at_checkpoint( &mut self, object_id: &Address, checkpoint_seq: u64, ) -> Result<CheckpointObjectProof, LightClientError>

Prove what (if anything) the checkpoint at checkpoint_seq did to object_id, returning a CheckpointObjectProof that distinguishes the four cases (created/mutated/unwrapped, deleted/wrapped, or not modified at all).

The full chain of trust:

1. Call the alpha ProofService.GetCheckpointObjectProof RPC with (object_id, checkpoint_seq).
2. Ratchet the epoch cache forward to cover the checkpoint whose summary the server returned, BLS-verifying each intervening end-of-epoch summary along the way.
3. BCS-decode the returned SignedCheckpointSummary, sanity-check that its sequence_number matches checkpoint_seq, and BLS-verify its aggregate signature against the now-trusted committee for that epoch.
4. Dispatch on the response’s proof oneof:
   • Inclusion: sanity-check the returned ObjectReference’s object id matches the request, verify the OCS inclusion proof against the trusted summary, and (when object_data is present) BCS-decode it and confirm its (id, version, digest) match the authenticated leaf. Absent object_data signals a deletion or wrap, in which case object is returned as None.
   • NonInclusion: verify the OCS non-inclusion proof against the trusted summary for object_id. The proof’s id-strict-bracketing rules out any leaf with object_id, proving the checkpoint did not modify it.

This method does not answer “what is the state of object_id at checkpoint checkpoint_seq?” — that question requires walking back to the most recent modification or an entirely different commitment scheme. See CheckpointObjectProof’s type-level documentation for details.