Resources
Versioning
How StateSync-GKR versions its component releases, Cargo packages, documentation and proof encodings, and which interfaces the current release line keeps fixed.
StateSync-GKR uses several independent version numbers. This page explains what each one identifies, which interfaces stay fixed within the current release line and how to pin the source you integrate.
Version numbers at a glance#
| Version | Current value | What it identifies |
|---|---|---|
| Component release | 1.2 line; current version 1.2.1 | A release of the whole component, recorded in the changelog |
| Cargo package version | 0.1.0-dev for every workspace package; 0.1.0 for the separate serving crate | The value in the workspace manifest; the packages are not published to crates.io |
| Docs version line | 1.2 | These pages |
| Proof encoding axes | proof_encoding_version, protocol_version, circuit_version and leaf_encoding_version, each 1 | Fields inside an inner-proof-v1 encoded proof |
| Rust toolchain | Pinned to 1.96.1; declared rust-version 1.85 | The compiler used for documented commands and measurements, and the minimum declared in the manifest |
These numbers move independently. The Cargo package version does not change with a component release, and a version string inside an identifier, such as the transcript domain tag statesync-gkr/v0.1, follows its own axis rather than the component version.
Component releases#
A component release version identifies a published release of the component as a whole. The current version is 1.2.1, a patch release of the 1.2 line: it keeps the code of 1.2.0, the first release of the line, and attaches an external proof of the 1.2 program. Changes made after the latest release are listed under Unreleased in the changelog until the next release is published. Earlier releases are 1.2.0, 1.1.1, the licensing revision of 1.1.0, and 1.1.0; an earlier 1.0.0 candidate is retained as historical evidence, and no tag or release was published for it.
Each release line has its own proof-bound program identity. The 1.2 line identity supersedes the 1.1 identity, and the records of the 1.1 and 1.0 lines stay byte frozen. Changing a protected source byte creates a different candidate identity, and expected hashes are never edited to make a changed build pass. Version 1.2.0 changed protected prover source, so it has a new program identity, recorded from two controlled clean builds. Release 1.2.0 still carried the external proof of the recorded 1.1 program; release 1.2.1 attaches an external proof of the 1.2 program, and the 1.1 proof stays a record of the 1.1 program. Release tags are immutable and are never moved or reused.
Cargo packages and source pins#
The workspace contains the statesync-gkr facade package and eight crates: ssgkr-primitives, ssgkr-sumcheck, ssgkr-protocol, ssgkr-compiler, ssgkr-batching, ssgkr-commitment, ssgkr-verification and ssgkr-wrap. Every package has version 0.1.0-dev and sets publish = false, so none is available from crates.io. The serving crate ssgkr-serving in benches/serving is a separate workspace outside the protected source, with its own version 0.1.0; it also sets publish = false.
The packages are distributed as source. Add StateSync-GKR to your application as a Git dependency pinned to an exact commit of the current official distribution, keep your application's Cargo.lock, and build with --locked. Installation shows the dependency entry and toolchain setup.
The repository pins Rust 1.96.1 in rust-toolchain.toml for reproducible builds, and the documented commands and measurements use that toolchain. The manifest declares edition 2024 and rust-version 1.85.
Docs version lines#
The Docs are organized by version line. Version line 1.2 documents the 1.2 component line. It was added as a separate Docs version line when 1.2.0 was released, and these addresses now serve it; the 1.1 releases stay archived under their own DOIs, listed in Citing StateSync-GKR. The pages of this line describe the 1.2 component line only.
Compatibility#
The repository does not publish a Semantic Versioning (opens in a new tab) policy for the Rust API. Treat any change of source revision as potentially breaking, pin an exact commit and read the changelog before you update. For example, 1.2.0 added the SyncError::KindMismatch variant, so an exhaustive match on SyncError written for 1.1 needs one more arm, as Errors shows. Proof bytes and the encoding did not change between 1.1.0 and 1.2.0, or in 1.2.1.
Frozen interfaces of the current release line#
The proof identity of the current release line freezes six compatibility surfaces. Within the line, they do not change:
- the crate dependency direction, in which the generic sumcheck and protocol crates never depend on the sparse-Merkle compiler;
- the sumcheck interface and its message order;
- the layered-circuit shape and gate semantics;
- the boundary between native sparse-Merkle semantics and circuit acceptance;
- the transcript observation order and domain tag;
- the public-input field set and its order.
A change to any of these surfaces is a change to protected source and therefore a new identity, not an ordinary update. The repository's ARCHITECTURE.md lists the same surfaces.
Proof encoding#
The inner-proof-v1 format is frozen. A byte-level layout change increments proof_encoding_version, and a semantic change increments the matching axis: protocol_version for transcript and proof semantics, circuit_version for compiler and circuit semantics, and leaf_encoding_version for the leaf encoding layout. Decoders reject an unknown version instead of inferring or defaulting it. Because version 1 is the first wire-stable version, compatibility vectors start accumulating at the first version increase. See Wire format.
Host integration seam#
The host integration interface in src/oss_interface.rs, the OssCoreInterface trait and its in-memory MockOssCore, is documented in the source as an open seam that is not frozen. Expect it to evolve with host-side integration needs.
Dependency updates#
Within the current identity cycle, the root Cargo.lock and the zkVM manifests are part of the proof-bound source, so routine Cargo dependency version updates are paused. Security alerts and security updates stay enabled.
Where changes are recorded#
- The changelog in these Docs lists user-visible component changes by release.
- CHANGELOG.md in the source repository (opens in a new tab) is the source of those entries.