Skip to content

VERSIONS.md

Latest commit

 

History

History
118 lines (80 loc) · 4.54 KB

VERSIONS.md

File metadata and controls

118 lines (80 loc) · 4.54 KB
Raw

Contract Versions and Compatibility Matrix

This document defines semantic versioning (MAJOR.MINOR.PATCH) for all Grainlify contracts, tracks breaking changes, and documents migration and compatibility expectations across versions.

Contracts covered:

  • grainlify-core
  • program-escrow
  • bounty-escrow (placeholder until stabilized)

Versioning Policy

  • MAJOR: Incompatible API/storage changes and/or required migration
  • MINOR: Backward-compatible features or optional fields
  • PATCH: Backward-compatible bug fixes or docs/tests only

All contracts expose both a numeric version for on-chain checks and a semantic string for off-chain tooling. Numeric encoding policy: major10_000 + minor100 + patch. Example: 1.2.3 => 10203.

grainlify-core

Current: 1.0.0 (numeric 10000) Planned next: 2.0.0 (numeric 20000)

SemVer Numeric Date Description Breaking
1.0.0 10000 TBA Initial release with admin + multisig upgrade hooks and version tracking No
1.1.0 10100 TBA Add migration state/events and PreviousVersion, no storage schema changes No
2.0.0 20000 TBA Introduce explicit migration API and compatibility checks, require migrate() call Yes

Compatibility Matrix (grainlify-core)

From To Migration Function Notes
1.0.x 1.1.x No N/A Fully compatible; features optional
1.x 2.0.0 Yes migrate_v1_to_v2 State journal introduced; emits events
2.0.x 2.1.x No N/A Backward compatible feature additions

Migration Guide

  • 1.x -> 2.0.0
    • Deploy new WASM, then call migrate(target=2, hash)
    • Verify via get_migration_state(); ensure to_version == 2
    • Update off-chain indexers to listen to (migration) events
    • Note: migrate() accepts raw sequential version targets (e.g. 2), while require_min_version() and get_version_numeric_encoded() use numeric-encoded values (e.g. 20000).

Breaking changes: require explicit migrate() before using new features that rely on migrated state.

program-escrow

Current: 1.0.0 (numeric 10000)

SemVer Numeric Date Description Breaking
1.0.0 10000 TBA Initial public release of program escrow No
1.0.1 10001 TBA Documentation/events clarifications; no storage changes No

Compatibility Matrix (program-escrow)

From To Migration Function Notes
1.0.x 1.0.y No N/A Patch only

Migration Guide

  • 1.0.0 -> 1.0.1
    • No on-chain migration required; upgrade WASM only

Global Migration Process

  1. Upload the new WASM and record new_wasm_hash.
  2. For grainlify-core single-admin upgrades, call schedule_upgrade(new_wasm_hash) and wait until the returned executable_at timestamp. The default delay is 86,400 seconds; admins may configure a delay no lower than 300 seconds with set_upgrade_delay(delay_seconds).
  3. Execute upgrade(new_wasm_hash) only after the timelock is ready. The scheduled hash must match the execution hash.
  4. If migration is required, call migrate(target_sequential_version, migration_hash)
  5. Verify with get_version(), get_migration_state()
  6. Update clients to enforce minimal compatible version

Example (grainlify-core)

// Schedule upgrade, execute after the timelock, then migrate
auth_admin.require_auth();
let scheduled = contract.schedule_upgrade(&env, &new_wasm_hash);
assert!(scheduled.executable_at >= scheduled.scheduled_at);

// Wait until ledger timestamp >= scheduled.executable_at.
contract.upgrade(&env, &new_wasm_hash);

let hash = BytesN::from_array(&env, &[0u8;32]);
contract.migrate(&env, &2, &hash);
assert_eq!(contract.get_version(&env), 2);

Events and Tracking

  • upgrade scheduled event: (wasm_hash, scheduled_at, executable_at, delay_seconds)
  • upgrade executed event: (wasm_hash, executed_at, previous_version)
  • migration event: (from_version, to_version, timestamp, migration_hash, success)
  • monitoring metrics emitted for upgrade/migrate

Version Checks (client guidance)

  • Off-chain SDKs should enforce minimal version using numeric encoding
  • On-chain functions may guard behavior with require_min_version(min_semver_numeric)

Breaking Changes Log

  • 2.0.0 (core): Require explicit migration; introduce MigrationState recording as hard requirement for post-2.x features.

Notes

  • WASM hashes should be recorded post-deploy in this document under the appropriate version row when known.