Implement Soroban Contract Upgrade Orchestration with State Migration Safety Verification

[temma02]

Description

packages/stellar/src/soroban-migration.ts handles contract migrations but has no orchestration layer that verifies state schema compatibility before upgrading. Implement an upgrade orchestration service that validates migration safety before submitting the upgrade transaction.

Requirements and Context

• Compare old and new contract ABI schemas before upgrade
• Block upgrades that remove or rename existing storage keys without a migration path
• Support dry-run mode: simulate the upgrade and validate state without committing
• Emit a detailed diff report of schema changes for developer review

Suggested Execution

Branch: feat/soroban-contract-upgrade-orchestration

Implement Changes

• Add upgrade-orchestrator.ts in packages/stellar/src/
• Implement ABI schema comparison using a structural diff algorithm
• Add dry-run mode that calls simulateTransaction without broadcasting
• Add tests for safe upgrade, breaking change detection, and dry-run validation

Test and Commit

Run pnpm test --filter=stellar -- upgrade-orchestrator and confirm breaking change detection tests pass.

Example Commit Message

feat(soroban): add contract upgrade orchestration with state migration safety verification

Co-authored-by: <your-name>

Guidelines

• Branch off main, keep PRs focused on one issue
• All new code must include unit or integration tests
• Ensure pnpm lint and pnpm typecheck pass before review
• Link this issue in your PR description
• Request review from at least one maintainer before merging

[UzyKhs]

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

Hey Maintainer! I’m a SWE and I'm ready to tackle issue #770. Could you assign it to me? Thank you.

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

[roobie001]

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

hello maintainer, can i work on this please

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

[Kappa16]

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

Please maintainer..I can handle this professionally and make sure this issue is closed ASAP WITHOUT ERRORS.

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

[Silver36-ship-it]

@Silver36-ship-it has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would love to work on this professionally, please assign it to me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Silver36-ship-it to this issue.

[ayomidearegbeshola29-dev]

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

I would like to work on this pls

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

[drips-wave]

Congratulations, @ayomidearegbeshola29-dev! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

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

[drips-wave]

This issue has been completed by @ayomidearegbeshola29-dev as part of the Stellar Wave Program's 6th Wave 🥳

😎 @ayomidearegbeshola29-dev: You earned 150 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.