Installation

StateSync-GKR is distributed as Rust source. This page puts a checkout on your machine, confirms that it builds and passes its tests with the pinned toolchain, and shows how to depend on it from your own Cargo project. When you finish, continue with the Quickstart to produce your first proof.

Requirements#

Tested platforms#

A build on an untested platform is useful information. The contributing guide (opens in a new tab) counts reproduction reports from new hardware and operating systems among the most helpful contributions, and the reproduction guide (opens in a new tab) explains how to file one.

Get the source#

git clone https://github.com/Oraclizer/statesync-gkr.git
cd statesync-gkr

The clone checks out the maintained branch. Record the commit you build, for example with git rev-parse HEAD, whenever you report a result or pin a dependency.

Install the pinned toolchain#

The repository root contains this file:

# Pinned for reproducible builds (edition 2024 requires >= 1.85).
[toolchain]
channel = "1.96.1"
components = ["clippy", "rustfmt"]

Rustup applies it to every cargo and rustc command you run inside the checkout. Whether rustup installs a missing pinned toolchain on first use depends on your rustup version and settings: rustup 1.28.0 stopped installing it automatically, and rustup 1.28.1 restored automatic installation as the default. Install it explicitly from the repository root so the result does not depend on your rustup version:

rustup show active-toolchain || rustup toolchain install

The command installs nothing when 1.96.1 is already present. In a Windows PowerShell version without the || operator, use:

rustup show active-toolchain; if ($LASTEXITCODE -ne 0) { rustup toolchain install }

Then run rustup show and check that the active toolchain is 1.96.1, selected by rust-toolchain.toml. A +<toolchain> argument on the command line, the RUSTUP_TOOLCHAIN environment variable and a closer directory override all take precedence over the file. Remove them if a different version appears.

Build and run the tests#

cargo test --workspace --release --locked

This builds every crate in the workspace and runs its unit, integration, differential, adversarial, codec and proof-digest tests. The first build from a fresh clone compiles every dependency and takes substantially longer than later runs.

Two flags appear in the documented build, test and run commands:

• --release builds with optimizations. The proving paths are impractically slow in a debug build.
• --locked makes Cargo use the checked-in Cargo.lock. If Cargo reports that the lock file needs to change, do not regenerate it; find the manifest or toolchain difference behind the request first.

Contributors also run the formatting and lint checks from the CI sequence:

cargo fmt --all --check
cargo clippy --workspace --all-targets --locked -- -D warnings

The contributing guide (opens in a new tab) lists every check that a pull request must pass.

Use StateSync-GKR as a dependency#

The packages are not published to crates.io; every manifest in the workspace sets publish = false. Depend on the source through Git or a local path, and import everything through the root package, statesync-gkr. Its modules re-export the member crates, so your manifest needs this one dependency. Project layout lists the modules.

Git dependency#

[package]
name = "my-state-prover"
version = "0.1.0"
edition = "2024"
publish = false

[dependencies]
statesync-gkr = { git = "https://github.com/Oraclizer/statesync-gkr.git", branch = "main" }

branch = "main" follows the maintained branch, which suits evaluation. For a build you can reproduce, replace it with rev = "<full commit hash>" naming the commit you reviewed, and commit your project's Cargo.lock.

Path dependency#

To develop against a local checkout:

[dependencies]
statesync-gkr = { path = "../statesync-gkr" }

Keep your project outside the statesync-gkr directory. Cargo searches parent directories for an enclosing workspace and reports an error for a package that the workspace does not list as a member.

Pin the toolchain in your project#

A dependency's rust-toolchain.toml has no effect on your build, because rustup looks for the file from your own working directory upward. Add the same file to your project root:

[toolchain]
channel = "1.96.1"
components = ["clippy", "rustfmt"]

Alternatively, name the toolchain on each command, for example cargo +1.96.1 run --release.

Keep your lock file#

Your first build creates your project's own Cargo.lock. Keep it under version control and build with --locked afterwards. The repository's lock file governs only the repository's own tests and release reproduction. The library pins most of its direct dependencies to exact versions, including the Plonky3 crates at =0.4.3; your lock file fixes the rest of the graph your project resolves.

Features#

Keep the default features in a host application. Turning them off with default-features = false exists for zkVM guest builds and removes the parallel batch API. If you run prove_batch_parallel inside your own thread pool, also add rayon to your dependencies, as Batching and parallelism describes.

Version numbers you will see#

Your Cargo.lock lists the workspace packages at version 0.1.0-dev. That is the unpublished Cargo package version shared by every package in the workspace, and it is unrelated to the 1.1 component release line that these docs describe. Versioning explains both numbers.

Before you ship#

• Read Licensing. The source is distributed under the Business Source License 1.1. Production use that generates proofs, embeds or redistributes the proving functionality in a product or service, or offers proof generation to third parties requires a commercial license.
• Read Trust boundaries to see what a verification result establishes and what your system must provide around it.
• Follow the Security policy to report a suspected vulnerability.

Platform notes#

CPU features#

The controlled CPU studies were built with -Ctarget-cpu=native on a two-socket AMD EPYC 9R45 host. Proof bytes must not depend on CPU features, and CI checks this by comparing the output of the proof_digest binary from a baseline x86-64 build with the output from a native build. You can repeat the check on a Linux host:

cargo run --release --locked --bin proof_digest > baseline.txt
RUSTFLAGS="-Ctarget-cpu=native" cargo run --release --locked --bin proof_digest > native.txt
diff baseline.txt native.txt

diff must print nothing. Changing RUSTFLAGS makes Cargo rebuild the workspace, so the second command takes longer. A difference means that proof bytes depend on the build; report it as an issue (opens in a new tab) with the commit, the host and both outputs.

Windows#

The tested Windows configuration uses Rust's x86-64 GNU target. The shell examples on this page use POSIX syntax, so set environment variables such as RUSTFLAGS with your own shell's syntax.

Formal and zkVM builds#

Building the Isabelle sessions and reproducing the selected zkVM program identity are separate profiles with their own requirements. Neither is needed to build, test or use the library. See Formal verification and the reproduction guide (opens in a new tab).

Troubleshooting#

Troubleshooting covers problems that appear after installation.

Next steps#

• Quickstart: prove and verify your first request.
• Project layout: what each crate owns and which entry points to use.
• Proving state operations: build membership, non-membership and update requests.