[Governance] Formal Upgrade Framework with Version Tracking, Migration Hooks, and Rollback (Issue #16)

[Jokay1997]

Summary

Closes #16.

Implements a Formal Upgrade Framework for EquipChain smart contracts, providing version tracking, sequential migration hooks, two-phase upgrade approval, storage schema versioning, and emergency rollback. This replaces ad-hoc contract upgrades with a governed, auditable process enforced entirely on-chain.

---

Files Changed

File	Type	Description
\contracts/utility_contracts/src/upgrade_framework.rs\	✨ New	Full upgrade framework (version tracking, migrations, two-phase upgrade, rollback, schema versioning)
\contracts/utility_contracts/src/lib.rs\	🔧 Modified	Module declaration, new \DataKey\ variants, new \ContractError\ variants
\contracts/utility_contracts/src/nonce_sync_tests.rs\	🔧 Modified	Fixed missing \Vec/\String\ imports for CI
\contracts/utility_contracts/src/tariff_oracle_tests.rs\	🔧 Modified	Pre-existing CI fix
\contracts/utility_contracts/src/temporary_storage_tests.rs\	🔧 Modified	Pre-existing CI fix

---

Implementation Details

upgrade_framework.rs — New Module

Version Tracking

• \ContractVersion\ stores the current (major, minor, patch)\ tuple in instance storage
• \LastUpgradeLedger\ records the ledger sequence of the most recent upgrade
• \VersionInfo(u32)\ stores per-version metadata (WASM hash, timestamp, executor) for full audit trail
• \VersionCount\ tracks the total number of upgrades applied (append-only)

Migration Registry

• A static \MIGRATIONS\ array maps \rom_version → migration_fn\
• On upgrade, migrations execute sequentially from the current version to the target version
• Each migration function receives the \Env\ and can read/write storage to reshape data
• A failed migration returns \MigrationFailed (error 122)\ and the upgrade is aborted without advancing the version

Two-Phase Upgrade
propose_upgrade → (multi-sig approval) → execute_upgrade

• \propose_upgrade\ stores the target WASM hash and opens an approval window
• Multi-sig signers approve via the existing approval mechanism
• \execute_upgrade\ can only be called after the quorum is reached and the timelock has elapsed
• \cancel_upgrade_proposal\ allows the proposer to retract before execution

Upgrade Delay Enforcement

• \MIN_UPGRADE_INTERVAL\ (72 hours) enforced between consecutive non-emergency upgrades
• \UpgradeDelayNotElapsed (error 119)\ returned if the interval has not passed
• Emergency upgrades bypass the interval but require multi-sig authorization

Emergency Rollback

• 
  ollback_to_version(n)\ restores a previous WASM hash from \PreviousWasmHash(u32)\ storage
• Each rollback point is single-use; a consumed rollback returns \RollbackAlreadyConsumed (error 121)\
• A missing rollback point returns \RollbackPointNotFound (error 120)\
• Emergency rollback still requires multi-sig authorization

Storage Schema Versioning

• \StorageSchemaVersion(BytesN<32>)\ tracks the schema version for each \DataKey\ variant
• Allows migrations to detect and upgrade stale data structures independently per key
• Guards against version skew when reading storage written by an older contract version

lib.rs — Registry Updates

New \DataKey\ variants:

• \ContractVersion\
• \LastUpgradeLedger\
• \VersionInfo(u32)\
• \VersionCount\
• \StorageSchemaVersion(BytesN<32>)\
• \RollbackPoint(u32)\
• \RollbackCount\
• \PreviousWasmHash(u32)\

New \ContractError\ variants:

• \UpgradeDelayNotElapsed = 119\
• \RollbackPointNotFound = 120\
• \RollbackAlreadyConsumed = 121\
• \MigrationFailed = 122\

---

Testing

• All pre-existing CI compilation errors on this branch resolved (missing imports, collapsible \if\ clippy warnings)
• \cargo check --workspace\ and \cargo test --workspace\ pass