Problem Statement / Feature Objective
As contracts evolve, their storage schemas change. The current approach of clearing all storage and reinitializing on upgrade is destructive and causes data loss. A storage migration framework must be built that associates each contract's storage with a schema version integer, provides a declarative migration DSL for transforming storage between versions, and executes migrations atomically during the upgrade coordinator's upgrade flow. The framework must support additive migrations (new fields added), field type changes (u32 → i128), and semantic migrations (merge two fields into one with transformation).
Technical Invariants & Bounds
- Schema version: each contract's
StorageVersion data entry is a u32 (version number). Initial contract deploy sets version 1.
- Migration DSL:
Migrate::new(1, 2).add_field("new_field", |ctx| default_val).transform("old_field", |ctx| ctx.read_u32() * 1000).merge("field_a", "field_b", |a, b| a + b).
- Migration execution: called by upgrade-coordinator after WASM upgrade and before new functionality is enabled.
- Atomicity: migration either fully completes or rolls back to previous state; if storage write fails mid-migration, all writes in the current migration step are reverted.
- Dry-run mode:
migrate_dry_run(from_version, to_version) simulates the migration on a copy of storage (forked ledger state) and returns the diff.
- Testing: a test framework that creates a fork of the ledger at a specific version, runs migration, and asserts storage state matches expectations.
Codebase Navigation Guide
contracts/migration-framework/src/lib.rs — migration DSL and executor.contracts/migration-framework/src/dry_run.rs — fork-based dry run simulation.contracts/migration-framework/src/testing.rs — test utilities for migration verification.contracts/*/migrations/ — directory per contract for migration definitions.
Problem Statement / Feature Objective
As contracts evolve, their storage schemas change. The current approach of clearing all storage and reinitializing on upgrade is destructive and causes data loss. A storage migration framework must be built that associates each contract's storage with a schema version integer, provides a declarative migration DSL for transforming storage between versions, and executes migrations atomically during the upgrade coordinator's upgrade flow. The framework must support additive migrations (new fields added), field type changes (u32 → i128), and semantic migrations (merge two fields into one with transformation).
Technical Invariants & Bounds
StorageVersiondata entry is au32(version number). Initial contract deploy sets version 1.Migrate::new(1, 2).add_field("new_field", |ctx| default_val).transform("old_field", |ctx| ctx.read_u32() * 1000).merge("field_a", "field_b", |a, b| a + b).migrate_dry_run(from_version, to_version)simulates the migration on a copy of storage (forked ledger state) and returns the diff.Codebase Navigation Guide
contracts/migration-framework/src/lib.rs— migration DSL and executor.contracts/migration-framework/src/dry_run.rs— fork-based dry run simulation.contracts/migration-framework/src/testing.rs— test utilities for migration verification.contracts/*/migrations/— directory per contract for migration definitions.