schema-versioned migration/upgrade path for settlement storage

[mikewheeleer]

Summary

There is no safe way to evolve settlement storage — an upgrade risks reading stale layouts. Add a schema-version field and a guarded migration entrypoint.

Why this matters

Storage evolution without versioning corrupts state on upgrade. A version gate + migration makes upgrades safe and idempotent.

Requirements

• Store a schema_version; expose it via a read view.
• Add an admin-guarded migrate() that upgrades in-place, gated on the current version.
• Migration is idempotent — running it twice is a no-op.
• Emit an event recording the version transition.

Technical guidance

• Refuse to migrate from an unexpected version.
• Keep pre/post invariants asserted in tests.

Edge cases — each must have a test

• migrate from old version -> upgrades, version bumped
• migrate again -> no-op
• migrate from wrong version -> rejected
• non-admin migrate -> rejected
• post-migration invariants hold

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Automatic on-read migration
• Downgrade path

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.

[DammyAji]

Hello @mikewheeleer, I’d like to take on this issue.
From my understanding, this is about making settlement storage upgrades safe by introducing schema versioning and a guarded migration path. I’ll go through the codebase to understand the current settlement storage layout and upgrade patterns, then add the schema version, admin-only migrate() entrypoint, version checks, and migration event.
I’ll also cover the migration edge cases with unit and integration tests, including repeated migrations, unexpected versions, non-admin access, and post-migration invariants. I’ll keep the implementation aligned with the existing Rust/Soroban conventions and make sure the required formatting, linting, and test checks pass.
I’d appreciate the opportunity to contribute to making the settlement storage safer to upgrade. Thank you.

[guptakumarranjeet150]

Hi everyone,

I would like to resolve this issue. Here is my proposed execution plan:

• Implementation: Implement schema-versioned migration/upgrade path for settlement storage with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Testing & Verification: Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.
• Delivery: Ready to ship a thoroughly tested PR within 12–24 hours with passing CI.

Happy to pick this up today—please assign to me!

[ranjeet150]

Hello! I'd like to work on this issue.

I would like to resolve this issue. Here is my proposed execution plan:

• Implementation: Implement schema-versioned migration/upgrade path for settlement storage with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Testing & Verification: Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.
• Delivery: Ready to ship a thoroughly tested PR within 12–24 hours with passing CI.

Ready to deliver a clean, tested PR within 12–24 hours. Please assign!