Troubleshooting

Each table on this page pairs a symptom with its usual cause and the action that resolves it. Installation problems are also covered in Installation, and mistakes in building requests in Proving state operations.

Before you start#

• Print errors with {:?}. Most error types implement only Debug, and the variant with its fields usually names the cause.
• Note whether the problem is a failed proving call or a false from verification. They have different causes and are covered in different sections below.
• Record the source revision you build (for example the commit your Cargo.lock pins), the configuration, the operating system, the toolchain and the exact command. Every report needs them.

Build and toolchain#

Preparation and proving errors#

A configuration error returns the same error on every attempt, so fix the configuration instead of retrying. Errors describes every variant and the calls that return it.

Verification returns false#

The facade's verification calls report every failure as false. Work through these causes in order:

Narrow down a rejected result#

The function below repeats the cheap checks, in a useful order, for a typed result that verify_sync_op_prepared rejected. It is a diagnostic: the reference check at the end recompiles the circuit, so keep the function off the request path, and keep the verifier's false as the verdict.

use statesync_gkr::compiler::smt_valid_native;
use statesync_gkr::primitives::hash::Poseidon2Gadget;
use statesync_gkr::{PreparedSync, StateSyncProver, SyncRequest, SyncResult};

/// Narrow down why `verify_sync_op_prepared` returned `false`. Diagnostics only.
pub fn explain_rejection(
    prover: &StateSyncProver,
    prepared: &PreparedSync,
    request: &SyncRequest,
    result: &SyncResult,
) -> String {
    if request.operation.kind() != prepared.kind() {
        return "the request's operation kind differs from the preparation's".to_owned();
    }
    if result.public_inputs != request.public_inputs {
        return "the result carries different public inputs than the request".to_owned();
    }
    let params = &prover.config.smt;
    let hasher = Poseidon2Gadget::new(params.leaf_max_fields as usize);
    match smt_valid_native(
        &hasher,
        params,
        &request.operation,
        &request.public_inputs.old_root,
        &request.public_inputs.new_root,
        &request.witness,
    ) {
        Err(error) => return format!("the request is malformed: {error:?}"),
        Ok(false) => return "the operation does not hold for these roots and this witness".to_owned(),
        Ok(true) => {}
    }
    if prover.verify_sync_op_reference(request, result) {
        return "the reference verifier accepts: the preparation does not match this \
                prover's configuration, or the two verifiers disagree (report it)"
            .to_owned();
    }
    "the operation holds natively: check op_kind_tag, asset_id and value_digest, \
     then the proof itself"
        .to_owned()
}

smt_valid_native checks the path, the leaf condition and the root equations, but not op_kind_tag, asset_id or value_digest. When it returns true and verification still fails, those three fields or the proof itself are the likely cause.

Encoding and received bytes#

Performance#

Proof bytes differ between builds#

Report a problem#

• For a reproducible defect or a documentation error, open a public issue (opens in a new tab) with the revision, operating system, toolchain, command, expected and observed output and a minimal reproduction.
• For a suspected vulnerability, including any accepted tampered proof, follow the Security policy and never use a public issue.
• For support with a production deployment, contact Oraclizer Labs through StateSync-GKR licensing.

Next steps#

• Errors: every error type and variant.
• Encoding and transport: diagnose received bytes.
• Performance tuning: choose and confirm operating settings.