Enum LightClientError 

#[non_exhaustive]
pub enum LightClientError {
    Rpc(Status),
    Proto(TryFromProtoError),
    Bcs(Error),
    InvalidSignature(SignatureError),
    InvalidProof(ProofError),
    InvalidEpochAdvance {
        current: u64,
        provided: u64,
    },
    MissingEndOfEpochData {
        checkpoint: u64,
    },
    CheckpointMismatch {
        requested: u64,
        returned: u64,
    },
    NoCommitteeForEpoch {
        epoch: u64,
    },
    RatchetGapTooLarge {
        current: u64,
        target: u64,
        max: u64,
    },
    EpochNotFound {
        epoch: u64,
    },
    ObjectIdMismatch {
        requested: Address,
        returned: Address,
    },
    ObjectDataMismatch(Box<ObjectDataMismatch>),
    MmrMismatch(Box<MmrMismatch>),
    InvalidEventBatch(ApplyStreamError),
    UnexpectedObjectShape {
        reason: &'static str,
    },
}

Available on crate feature unstable only.

Errors returned by the crate::light_client APIs.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Rpc(Status)

A gRPC call returned a non-success status.

Proto(TryFromProtoError)

A protobuf message returned by the server was malformed.

Bcs(Error)

BCS decoding of a wire-format payload (e.g. the response’s checkpoint_summary bytes) failed.

InvalidSignature(SignatureError)

The BLS aggregate signature on a checkpoint summary failed to verify against the cached validator committee.

InvalidProof(ProofError)

The OCS proof failed to verify against the trusted checkpoint summary.

InvalidEpochAdvance

The cache was asked to apply a ratchet update with a new committee whose epoch was not exactly one greater than the current epoch.

Fields

current: u64

The current epoch held by the cache.

provided: u64

The advertised epoch of the new committee.

MissingEndOfEpochData

A checkpoint summary advertised as the last of an epoch had no end_of_epoch_data payload — the next epoch’s committee cannot be extracted.

Fields

checkpoint: u64

The checkpoint sequence number whose summary was missing the payload.

CheckpointMismatch

The server returned a proof anchored at a different checkpoint than the one the caller requested.

Fields

requested: u64

The checkpoint sequence number the caller asked for.

returned: u64

The checkpoint sequence number on the returned summary.

NoCommitteeForEpoch

After ratcheting forward, the cache still did not have a committee on file for the relevant epoch. This should not happen in practice and indicates either a bug or a malicious server response.

Fields

epoch: u64

The epoch number that has no committee on file.

RatchetGapTooLarge

The ratchet driver tried to advance through more epochs than the configured cap (see crate::light_client::RatchetConfig::max_ratchet_gap) allows in a single call. This guard exists to bound the work the client will do in response to a server that keeps reporting last_checkpoint < target_seq for every epoch, never letting the discovery walk terminate.

Fields

current: u64

The cache’s current epoch when the ratchet began.

target: u64

The epoch the discovery walk had reached when the cap was hit. The actual target epoch may be even further out.

max: u64

The configured maximum gap.

EpochNotFound

The fullnode reported NotFound for an epoch the ratchet needed to advance through. Distinguished from a generic Rpc(Status) so callers can differentiate “the network does not know about this epoch” (likely a bug or a request for an epoch past the chain’s tip) from a transport-level failure.

Fields

epoch: u64

The epoch number that the fullnode could not produce.

ObjectIdMismatch

The server returned an inclusion proof for a different object id than the caller asked about.

Fields

requested: Address

The object id the caller asked about.

returned: Address

The object id on the returned object reference.

ObjectDataMismatch(Box<ObjectDataMismatch>)

The object_data bytes the server returned did not BCS-decode to an Object whose (id, version, digest) match the authenticated ObjectReference. Without this check, a server could pass the proof verification step while still returning arbitrary bytes for the object’s contents.

Boxed because ObjectReference carries a 32-byte digest and a 32-byte address; keeping two of them inline would inflate every Result<_, LightClientError> slot by ~144 bytes for a case that’s exceedingly rare in practice.

MmrMismatch(Box<MmrMismatch>)

The locally-replayed EventStreamHead disagreed with the authenticated head fetched from chain at the given checkpoint. This is the streaming client’s terminal failure mode — once the MMRs diverge, every subsequent event would compound the divergence, so the stream is aborted with this error.

Boxed because EventStreamHead carries a Vec<U256> (each U256 is 32 bytes) and grows unbounded with checkpoint count; keeping two of them inline would inflate every Result<_, LightClientError> slot returned from the streaming task.

InvalidEventBatch(ApplyStreamError)

Folding a batch of received events into the local MMR violated the apply_stream_updates contract — empty batch, mismatched checkpoint_seq within a batch, or non-monotonic batch ordering. Surfaces a malformed server response that slipped past the per-event decode.

UnexpectedObjectShape

An object returned by the OCS inclusion proof flow did not match the shape the caller expected — for example, an EventStreamHead fetch returned a package instead of a Move struct, or the dynamic-field contents were too short to contain the expected value.

Fields

reason: &'static str

A short, human-readable description of what the caller was expecting versus what the object actually was.

Trait Implementations

impl Debug for LightClientError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for LightClientError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for LightClientError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<ApplyStreamError> for LightClientError

fn from(value: ApplyStreamError) -> Self

Converts to this type from the input type.

impl From<Error> for LightClientError

fn from(value: Error) -> Self

Converts to this type from the input type.

impl From<ProofError> for LightClientError

fn from(value: ProofError) -> Self

Converts to this type from the input type.

impl From<Error> for LightClientError

fn from(value: SignatureError) -> Self

Converts to this type from the input type.

impl From<Status> for LightClientError

fn from(value: Status) -> Self

Converts to this type from the input type.

impl From<TryFromProtoError> for LightClientError

fn from(value: TryFromProtoError) -> Self

Converts to this type from the input type.