[v2][contracts] Versioned storage schema and migration path for persistent structs

[Calebux]

Context

SubscriptionData, EscrowAgreement, Card and PaymentChannel are stored directly as contracttype structs in persistent storage. Adding a field to any of them silently breaks deserialization of existing entries after an upgrade, and contract-upgrade has no story for migrating state — only for swapping WASM.

Scope

• Add a schema_version: u32 field to every persisted struct and a StorageVersion instance key per contract.
• Implement a migrate(from_version) entrypoint gated to admin/guardian, callable only once per version step.
• Write read paths that accept the previous schema version and upgrade lazily on write where feasible.
• Add tests that write v1 data, upgrade the contract, and read it back through v2 code.

Acceptance criteria

• Every persisted struct carries a schema version.
• Each contract exposes an admin-gated migrate() that is idempotent and rejects out-of-order versions.
• A test creates v1 state, performs an upgrade, and asserts values survive intact.
• contracts/DEPLOYMENT.md documents the migration procedure and the rollback constraint.

Files / areas

contracts/contracts/*/src/lib.rs, contracts/contracts/contract-upgrade/src/lib.rs, contracts/DEPLOYMENT.md

---

Part of the SYNCRO v2 rewrite. Epic: A — Contract foundation.

[stevengrams]

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

Assign me this task i will solve it, you can check the previous works i was given how i solved them perfectly

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

[bigceejay19]

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

Hi maintainer, I’m available to work on this issue and can provide a clean solution with proper testing.

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

[IjayAbby]

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

Hello, I would love to work on this issue.
Max ETA to complete the task is 4 hours.

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

[ayomidearegbeshola29-dev]

@ayomidearegbeshola29-dev has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi maintainer, I’d like to work on #1227. I have experience with Rust/Soroban, persistent storage, migrations, and testing. I’ll implement versioned structs, admin-gated idempotent migrations, safe v1→v2 state preservation, and comprehensive upgrade tests. I’ll also document migration and rollback procedures and run all required checks. I can open the first PR within 2–3 days after assignment.

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

[drips-wave]

Congratulations, @IjayAbby! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @IjayAbby: 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 🌊