Project layout

The repository is one Cargo workspace. Application code depends on a single package, the root facade statesync-gkr, which re-exports the eight member crates under crates/ as modules. This page maps those crates, the rules that keep them apart, and the parts of the API you are most likely to need.

Repository map#

Workspace crates#

Two import paths differ from the crate names: ssgkr-protocol is imported as gkr, and ssgkr-commitment is reached through wrap::commitment. The verification crate is not a module of the facade; its public types are re-exported at the root instead. These are the root-level items:

use statesync_gkr::{
    DOMAIN_TAG_V01, MockOssCore, OssCoreInterface, PreparedSync, StateSyncGkrConfig,
    StateSyncProver, SyncError, SyncRequest, SyncResult,
};

Dependency direction#

ssgkr-primitives -> ssgkr-sumcheck -> ssgkr-protocol -> ssgkr-compiler
     -> {ssgkr-batching, ssgkr-commitment}
          -> {ssgkr-verification, ssgkr-wrap}
               -> statesync-gkr facade

Each arrow points from a crate to the crates built on it. The workspace manifest records this graph as a design boundary, and a change to it goes through design review rather than an ordinary edit. Three rules follow from it:

• ssgkr-sumcheck and ssgkr-protocol never depend on ssgkr-compiler. They carry no sparse-Merkle assumptions, so another arithmetic-circuit frontend can build on them; see Custom frontends.
• Only ssgkr-primitives may name a Plonky3 crate. Plonky3 is pinned to exactly 0.4.3, and moving that pin touches this one adapter crate.
• ssgkr-verification and ssgkr-wrap have no edge between them. Both consume ssgkr-commitment.

The direct dependencies inside the workspace, as each manifest declares them:

Frozen interfaces#

The current release line binds its published external proof to an exact program identity, and six compatibility surfaces are frozen with that identity. Source comments label them SEAL[S-1] through SEAL[S-6]:

For application code, these surfaces stay fixed for the current release line. For contributors, changing a protected byte, even a comment, produces a different candidate identity, and that is never resolved by updating an expected hash. The labels are historical annotations kept byte for byte; they are not runtime checks or approvals. In 1.1.1 the root Cargo license field is the one recorded change among the protected files, and the published external proof remains evidence for its recorded 1.1 program only.

Entry points for application code#

Other public items serve audits, tests and the recorded external-proof route. Examples are verify_sync_op_reference, a slower reference verifier that uses fully materialized wiring, the wrap::prepared codec, and the route and settlement records under wrap. Ordinary proving does not need them. The API reference covers the full surface.

Workspace conventions#

• unsafe code is forbidden in every workspace crate.
• Workspace lints warn on missing documentation and on unwrap, expect and panic, and CI runs Clippy with warnings denied.
• Every package uses edition 2024, declares Rust 1.85 as its minimum version and is built with the pinned 1.96.1.
• The contract crate for the Creusot verifier is declared only for cfg(creusot). Normal builds on every platform never compile it.

Versions#

Every package in the workspace carries the Cargo version 0.1.0-dev and sets publish = false. These docs describe the 1.1 component release line, which is numbered separately from the Cargo packages. Versioning explains how the two relate.

Next steps#

• Proving state operations: build and verify requests for all three operations.
• Circuits and layers: what the compiler produces and the protocol crate consumes.
• API reference: every public item, module by module.