[SC-49] Document and test the contract upgrade path

[yusuftomilola]

Overview

There is no documented upgrade story for the workspace. Once contracts hold real asset registry data, changing a storage layout without a tested migration means data loss — and asset ownership records are precisely the data you cannot afford to lose.

Tasks

• Document the upgrade model per contract: upgradeable via update_current_contract_wasm, or immutable-and-redeploy?
• For upgradeable contracts, restrict the upgrade entrypoint to admin (ideally the two-step admin from [SC-48]) and emit an event.
• Add a storage-version key and an idempotent migration function that runs once.
• Test: deploy v1, write state, upgrade to v2, assert state survives and reads correctly under the new layout.
• Write an upgrade runbook in contract documentation.

Acceptance Criteria

• Every contract's upgrade posture is documented.
• Upgrade entrypoints are admin-gated and emit events.
• An upgrade test proves state is preserved across a version bump.

Dependencies

Builds on [SC-48].

Notes for Contributors

Requires Rust + Soroban. Workspace: contracts/ (soroban-sdk 22, members: assetsup, contrib, multisig-wallet, multisig_transfer, asset-maintenance). Run cargo test --all, cargo fmt --all -- --check, and cargo clippy --all-targets --all-features -- -D warnings before opening a PR — CI enforces all three. Comment below to be assigned.

[fathiaoyinloye]

Hi, I'd like to work on this issue. I have relevant experience with the technologies and concepts involved, and I'm confident I can make the necessary implementation to ensure the it meets the acceptance criteria. I'd be happy to contribute to this task.

[georgeonweb3]

Hello, I'd appreciate it if this issue was assigned to me, I'm confident I should be able to finish and submit a PR within a day

[temitope-007]

@temitope-007 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi maintainer

I'd like to take up this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @temitope-007 to this issue.

[Fash004]

@Fash004 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Please assign this issue to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Fash004 to this issue.

[ekwe7]

@ekwe7 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would love to work on this issue. I have experience building production ready applications and collaborating through GitHub workflows. I'll carefully analyze the current implementation, propose a reliable solution, and submit a well-tested PR. My focus is on clean code, maintainability, and timely delivery

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ekwe7 to this issue.

[TomikeDS]

@TomikeDS has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

can i work on this issue?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @TomikeDS to this issue.

[Songu3020]

@Songu3020 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Songu3020 to this issue.

[Caneryy]

@Caneryy has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hi, I'd like to work on this issue please.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Caneryy to this issue.

[drips-wave]

Congratulations, @TomikeDS! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @TomikeDS: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊