FAQ

Short answers to common questions about StateSync-GKR. Each answer links to the page with the details. To cite the project, see Citing StateSync-GKR.

Using StateSync-GKR#

What is StateSync-GKR for?#

It uses the GKR protocol to prove and verify statements about state held in a sparse Merkle tree. An application can prove that a record is present, that a record is absent or that one leaf changed from an old root to a new root, and a verifier can check that proof. The sumcheck and GKR core can also serve other arithmetic-circuit frontends. See the Introduction.

Which state operations can it prove?#

Membership, non-membership and a single-leaf update. Leaves are empty, occupied or tombstone, so a slot that was never used and a slot that was deleted stay distinct, and either one satisfies non-membership. An update covers insertion, replacement, deletion and restoration under one sibling path. Atomic updates of several leaves in one transition are not supported. See Sparse-Merkle state and Proving state operations.

Is the proof zero-knowledge?#

No. The inner GKR proof is built for integrity: the verifying side holds the record and its path, as the next answer explains. The repository also records one external route, which wraps a fixed depth-24 membership example in a RISC Zero proof. See Trust boundaries.

Does the verifier need the private witness?#

Yes. The current sparse-Merkle verifier takes the private leaf and the full sibling path and recomputes their Poseidon2 hashes before it checks the GKR proof. An encoded proof never contains the witness, so the verifying side must already hold it. See Trust boundaries.

Does batching produce one aggregate proof?#

No. A batch is a set of independent jobs that share one prepared circuit. Each job produces its own proof, and the parallel batch API returns one proof per job in input order. Proof bytes do not depend on the worker count. See Batching and parallelism.

Can I use the engine for circuits other than sparse Merkle trees?#

Yes, through the sumcheck and gkr modules, which do not depend on the sparse-Merkle compiler. Your frontend supplies its own circuit, witness, output claim and transcript conventions, and it must discharge the residual input claims that the verifier returns. The shipped entry points use KoalaBear circuit values, a degree-four extension field for challenges and Poseidon2. There is no bundled compiler for arbitrary Rust programs and no runtime field or hash selection. See Custom frontends.

Which platforms and toolchains are supported?#

The tested host paths are x86-64 Linux, used in CI and in the controlled CPU studies, and Windows 11 with the x86-64 GNU Rust target. The repository pins Rust 1.96.1 and needs a normal Rust linker and build environment. Release-surface and codec tools need Python 3.11 or later. Always build in release mode, because the proving paths are impractically slow in a debug build. See Installation.

Is StateSync-GKR published on crates.io?#

No. Every package has version 0.1.0-dev and sets publish = false. Add StateSync-GKR as a Git dependency pinned to an exact commit. See Versioning.

Performance#

What do the published speedups compare?#

Each ratio compares StateSync-GKR with its own reference implementation under the same conditions, so each gain belongs to one design choice: the dense prover layout, table wiring, the fresh proving path and serial output processing. Plonky3 0.4.3 supplies the field, hash and challenger primitives. See Benchmark methodology.

How many requests per second can it serve?#

That depends on your hardware, your operation mix and how your service batches and returns proofs. In the recorded studies, a 48-core VM accepted 500 balanced requests per second for 15 minutes with every request accepted within 500 ms, and a 192-core VM accepted 1,000 requests per second with every request accepted within one second in three 60-second runs. These figures end at inner-proof acceptance and exclude database commits and consensus. See Benchmark results and Performance tuning.

Security and assurance#

What do the formal proofs cover?#

The compiler and protocol models are machine-checked in Isabelle/HOL: compiler correctness, a GKR assembly soundness bound, their composition, batching agreement and the transfer of the bound to the exact KoalaBear degree-four extension field. A refinement theorem connects the shipped Rust verifier to the model under stated conditions, and Creusot contracts cover the compiler, protocol and verification code in four scopes. Formal verification lists the assumptions behind each result.

How do I report a security vulnerability?#

Privately, by email to [email protected] or through GitHub private vulnerability reporting on the Security tab of the source repository. Do not open a public issue. See the Security policy.

Licensing#

Can I use StateSync-GKR in production?#

Yes, with a commercial license for proving. Production use that generates proofs, embeds proving functionality in a product or service or offers proof generation to third parties needs a commercial license, while production use solely to verify proofs is free. Production integration describes what your service provides around the engine, and Licensing gives the terms.

Is verification-only use free, and when do I need a commercial license?#

Non-production use is free, and the Additional Use Grant permits production use solely to verify proofs, including embedding or distributing the verification functionality for that purpose. You need a commercial license to generate proofs in production, to include proving functionality in a product or service or to offer proof generation to third parties. To ask about one, contact us through StateSync-GKR licensing. Details are in Licensing.

Contributing#

How can I contribute?#

The most useful contributions are reproduction reports on hardware or operating systems that have not been tested, defects in the sparse-Merkle semantics, compilation or GKR verification path, independent review of the claim boundaries and fixes to documentation that was wrong or unclear. Open an issue before a large change, comment on an issue before you start work on it and run the checks listed in CONTRIBUTING.md (opens in a new tab). Contributions are licensed under the Business Source License 1.1 with an additional grant to Oraclizer Labs, Inc., described in Licensing.