Errors

This reference shows how each StateSync-GKR call reports a failure and describes every public error type: what each variant means, which functions return it and what to do about it. The variant names, fields and messages on this page are taken from the 1.1 source.

How failures are reported#

Not every failure is an error value. The facade's verification calls return bool, so a rejected proof never appears as an error type, and two batch calls return a vector without any error channel.

The rows without a module path are methods of StateSyncProver. The facade's verification calls return a verdict, so they return bool. The generic gkr::verify and sumcheck::verify return Result because their Ok value still leaves residual claims for the caller, as described in Custom frontends.

To find out why a facade verification call returned false, repeat its first checks yourself: Encoding and transport shows this for received bytes and Troubleshooting for typed results.

Debug assertions and panics#

• prove_sync_op_prepared and make_job_prepared assert in debug builds that the request has the preparation's operation kind. Release builds do not check it, and proving against a preparation of another kind can panic or produce a proof that verification rejects. Check request.operation.kind() against prepared.kind() first.
• wrap::commitment::full_circuit_commitment, which preparation and the fresh calls use, panics instead of reducing a structural value at or above the field order.
• gkr::prove expects the witness that gkr::evaluate_circuit returns for the same circuit and does not check it.
• sumcheck::MultilinearPoly::evaluate panics when the point has a different number of variables than the polynomial, and fix_first_var panics when no variable is left.

Working with error values#

• Every error type implements Debug and Clone. Only the host-only ReceiptRootPolicyError and Risc0RouteBManifestError also implement Display and std::error::Error, so format the others with {:?}.
• SyncError, GkrError and WrapError do not implement PartialEq. Use match or matches! on them instead of ==.
• None of the error enums is marked #[non_exhaustive]. An exhaustive match therefore compiles today and stops compiling if a later version adds a variant, which points you to the new case.

The function below turns every SyncError into a log line. Because the match is exhaustive, the compiler reports any variant it does not handle:

use statesync_gkr::SyncError;
use statesync_gkr::compiler::{CompileError, SmtError};
use statesync_gkr::primitives::hash::HashError;

/// One log line per variant. The match is exhaustive, so the compiler
/// reports any variant that is not handled here.
pub fn describe(error: &SyncError) -> String {
    match error {
        SyncError::Compile(CompileError::UnsupportedConfig { reason }) => {
            format!("configuration rejected: {reason}")
        }
        SyncError::Compile(CompileError::NonUnaryGate { layer, out }) => {
            format!("non-unary gate in layer {layer} at output wire {out}")
        }
        SyncError::Witness(SmtError::PathLengthMismatch { expected, found }) => {
            format!("path has {found} siblings, expected {expected}")
        }
        SyncError::Witness(SmtError::KeyOutOfRange { key, depth }) => {
            format!("key {} is outside a tree of depth {depth}", key.0)
        }
        SyncError::Witness(SmtError::LeafEncoding(HashError::EncodingTooLong { len, max })) => {
            format!("leaf encoding has {len} elements, the bound is {max}")
        }
        SyncError::Witness(SmtError::LeafEncoding(HashError::EmptyEncoding)) => {
            "leaf encoding is empty".to_owned()
        }
    }
}

SyncError#

statesync_gkr::SyncError is the error of the facade's preparation and proving calls.

Where a call has no Result, the same conditions show up differently: prove_batch returns an empty vector instead of SyncError::Compile, and the verification calls return false.

CompileError#

statesync_gkr::compiler::CompileError.

SmtError#

statesync_gkr::compiler::SmtError. It implements From<HashError>.

compiler::generate_witness also reports a failed circuit evaluation as PathLengthMismatch. In that case expected is the circuit's input width, 2^input_width_bits, rather than the tree depth. A preparation built by prepare for the request's own kind does not produce it; if you see it, report it with a reproduction.

HashError#

statesync_gkr::primitives::hash::HashError, also re-exported as statesync_gkr::primitives::HashError.

EncodeError#

statesync_gkr::wrap::encoding::EncodeError.

DecodeError#

statesync_gkr::wrap::encoding::DecodeError has one variant for each rejection rule of the decoder. verify_encoded_sync_op and wrap_relation decode internally and turn any DecodeError into false or None; call wrap::encoding::decode_inner_proof yourself to see the variant. Treat every variant as a rejection of the bytes. Wire format gives the exact rule behind each variant.

Byte offsets in the fields count from the start of the message.

GkrError#

statesync_gkr::gkr::GkrError, returned by gkr::verify. The facade's verification calls turn it into false.

An Ok(InputClaim) from gkr::verify is not yet acceptance: compare both residual input claims with the input vector.

SumcheckError#

statesync_gkr::sumcheck::SumcheckError, returned by sumcheck::verify and carried inside GkrError::Sumcheck.

Each variant rejects the proof. An Ok(Subclaim) still requires the caller to evaluate the polynomial at subclaim.point and compare it with subclaim.expected_eval.

CircuitError#

statesync_gkr::gkr::CircuitError, returned by gkr::evaluate_circuit.

PolyError#

statesync_gkr::sumcheck::PolyError, returned by sumcheck::MultilinearPoly::from_evals.

WrapError#

statesync_gkr::wrap::WrapError.

MockWrapBackend returns the fixed bytes MOCK-WRAP-NOT-A-PROOF and carries no cryptographic content. The published outer proof covers one fixed depth-24 membership example; see Trust boundaries.

PreparedMaterialError#

statesync_gkr::wrap::prepared::PreparedMaterialError is returned by prepare_pinned_d24_a_membership and by the wrap::prepared functions that build, encode, decode and validate the reviewed prepared material for depth 24, strategy A, the default leaf bound and the Membership kind. PreparedProfileAxis names the axis in two of the variants: Protocol, Circuit, Leaf, Field, Hash or Pcs.

prepare_pinned_d24_a_membership checks the prover's configuration first and returns ConfigMismatch unless it is depth 24, leaf bound 31 and strategy A. Every variant is a rejection, and none of these functions falls back to compiling or to unvalidated material. For any other profile, build the preparation with prepare. For the same audit binding, only RouteNotEffective can pass at a later acceptance height.

External route reference models#

The modules wrap::settlement, wrap::risc0_destination_policy and wrap::risc0_route_b_manifest require the default host feature. They are reference models for the recorded external proof route: they fix canonical bytes and fail-closed checks, and they do not authenticate live finality, read a chain or act as deployed contracts. Their errors reject the input they describe.

ContractError#

statesync_gkr::wrap::settlement::ContractError is returned by CanonicalRawStatement::from_statement, from_bytes and action_kind, by ReferenceSettlementConsumer::register_route, set_lifecycle, verify_historical and authorize_new, and by wrap::risc0_destination_policy::validate_receipt_attachment. In the table, a settlement attempt means verify_historical or authorize_new.

Some checks read state that can change between attempts: registered routes, lifecycle entries and the answers of the PrimaryFinalityVerifier and FinalizedReceiptRootSource you supply. SourceBlockNotFinalized, for example, can pass on a later attempt once the receipt's block is finalized. ClaimAlreadySeen and SettlementAlreadyConsumed are the replay checks of authorize_new and do not pass again for the same claim.

ReceiptRootPolicyError#

statesync_gkr::wrap::risc0_destination_policy::ReceiptRootPolicyError implements Display and std::error::Error. It is returned by ReferenceReceiptRootRegistry::new, register and register_signatures, and by recover_evm_signer.

register_signatures recovers each signer with recover_evm_signer and then calls register, so it can return every variant.

DestinationReplayError#

statesync_gkr::wrap::risc0_destination_policy::DestinationReplayError is returned by ReferenceDestinationReplayRegistry::consume, which checks both keys before it inserts either.

Risc0RouteBManifestError#

statesync_gkr::wrap::risc0_route_b_manifest::Risc0RouteBManifestError is a struct that carries a message and implements Display and std::error::Error. Risc0RouteBManifestV1::from_json, canonical_bytes and route_id, and Risc0RouteBManifestVectorV1::from_json, compute and transcript return it when strict parsing, canonical encoding or a vector check fails. Log the message and reject the manifest or vector.

Helpers with string errors#

wrap::risc0_destination_policy::source_runtime_id, which derives a runtime identity from version fields and a code hash, returns Result<Hash32, String>. The methods of ReceiptRootQuorumVectorV1, a strict cross-language test vector, also return string errors: from_json, settlement_raw_statement, replay_keys, verify_negative_cases, negative_case_observations, compute and verify_expected.

Next steps#

• Troubleshooting: symptoms, causes and fixes, including rejected proofs.
• Encoding and transport: diagnose received bytes that fail verification.
• API reference: signatures of every function named on this page.