Project
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.1 line; current version 1.1.1, the licensing revision of 1.1.0 | A release of the whole component, recorded in the changelog |
| Cargo package version | 0.1.0-dev for every workspace package | The value in the workspace manifest; the packages are not published to crates.io |
| Docs version line | 1.1 | 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.1.1, the licensing revision of 1.1.0. Changes made after the latest release are listed under Unreleased in the changelog until the next release is published. An earlier 1.0.0 candidate is retained as historical evidence; no tag or release was published for it.
Each release line has its own proof-bound program identity. The 1.1 line identity supersedes the 1.0 identity, whose record stays 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.1.1 changed one protected metadata field, the root Cargo license field; it is recorded as the one checked difference, and the historical proof identity applies to the recorded program only. 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 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.1 documents the 1.1 component line. When a later component line is documented, it is added as a separate Docs version line. The pages of this line describe the 1.1 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.
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.