Skip to content

VERSIONING.md

Latest commit

 

History

History
57 lines (37 loc) · 2.62 KB

VERSIONING.md

File metadata and controls

57 lines (37 loc) · 2.62 KB

OpenVM Versioning

OpenVM follows the naming convention of semantic versioning (semver) but with different principles:

  • major: Only changes upon significant proof system or ISA updates
  • minor: Breaking changes where the vkey (MultiStarkVerifyingKey) changes
  • patch: Backward-compatible changes that preserve vkey compatibility

Due to the security critical nature of the OpenVM codebase, we do not follow semver precisely in the sense that breaking code-level API changes will not always result in a major version upgrade. However we follow the principles of semver where we treat the true API of the codebase to be the verification of the proofs generated by the OpenVM framework.

Versioning Principles

The core principle of OpenVM versioning is: "Patch upgrade should be backward compatible".

This means if we upgrade from v1.0.0 to v1.0.1, the old verifier of v1.0.0 should be able to verify the new proof generated by v1.0.1. Crucially, this means the vkey (MultiStarkVerifyingKey) does not change across patch versions.

Backward Compatibility Guarantees

The following properties must remain fixed across patch versions (changing these requires a minor version upgrade):

  1. vkey (MultiStarkVerifyingKey struct)

    • This ensures that a patch-upgraded prover (v1.x.y) can generate proofs that the original verifier (v1.x.0) can verify

  2. Commit structures

    • app_vm_commit, leaf_vm_commit, internal_vm_commit
    • This includes both the VM itself and the serialization (how the commit is computed)

  3. VmConfig format

  4. Build toolchain

    • RISC-V custom instructions
    • Transpiler
    • ISA
    • And thus the resulting VmExe

  5. Output of the prove command (CLI+SDK)

    • The proof format (struct itself and the content)

Exceptions

Changes that are purely additive without modifying existing objects are exceptions to the above rules and can be included in patch versions. Examples include:

  • Adding a new instruction
  • Adding a new prove type (STARK)
  • Adding a new extension (new StarkVerifyingKey for a new circuit)

While rare and ideally avoided, we reserve the option to change formatting of certain outputs or structs (e.g., VmConfig or VmExe) in a patch version if the change is purely cosmetic and a migration tool is provided to easily convert from the old format to the new format.

Patch-level Changes

Other changes that aren't security critical and don't modify any of the above components can be included in patch upgrades:

  • Prover improvements
  • VirtualMachine optimizations
  • Executor enhancements
  • SDK and CLI updates
  • Guest library changes