Stellar contract upgrade governance & migration plan

[truthixify]

Labels: Stellar Wave, stellar, design, governance, drips, help-wanted
Tier: M (2–4 days)
Type: design / writing

Context

Soroban contracts can be upgraded via the update_current_contract_wasm host function, but only if the contract opts in by storing an upgrade authority. We haven't decided what Wraith's upgrade story is for Stellar, and we need to before mainnet.

This issue is a design document, not code.

Scope

Produce a written proposal at contracts/stellar/GOVERNANCE.md answering:

1. Per-contract upgradability — for each of the four Stellar contracts (announcer, registry, sender, wraith-names), should it be:
   • Frozen (no upgrade path; redeploy means new address) — recommended for announcer/registry?
   • Upgradable by a fixed multisig?
   • Upgradable by a timelock + multisig?
   • Eventually renounceable?
2. Multisig composition — if we choose any upgrade path, what's the signer set? Recommend a starting composition and a 12-month transition plan.
3. Migration UX — if announcer ever needs replacement, what's the experience for active users with un-scanned announcements? Propose an event-bridge strategy.
4. Pause / circuit breaker — should stealth-sender have a pause function for emergencies? Argue both sides.
5. Versioning — how do we communicate breaking changes via scheme_id increments (per ERC-5564) vs. contract redeploys?
6. Comparison table vs. EVM equivalents — what would the same decision look like on Horizen?

Acceptance criteria

• GOVERNANCE.md committed with all six sections.
• Recommendation block at the top: "If we have to ship mainnet next week, what does the governance config look like?"
• Companion follow-up issues filed for any concrete code changes needed to implement the chosen design.

Why this matters

Mainnet launch decisions become irreversible. We need an opinionated proposal we can debate, not a blank slate when we get there.

Resources

• Soroban upgrade pattern: https://developers.stellar.org/docs/build/guides/conventions/upgrading-contracts
• OpenZeppelin Stellar contracts (governance reference): https://github.com/OpenZeppelin/openzeppelin-soroban-contracts

[thebabalola]

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

Hi maintainer, I'm a Stellar developer with experience in governance and technical writing. I can produce a comprehensive written proposal for the Wraith Stellar upgrade governance and migration plan, ensuring that the project has a clear and secure path for future upgrades. Ready to dive in once assigned!

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

[Codekill33]

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

Hello, I'd like to work on this issue.
I will draft the GOVERNANCE.md proposal covering upgrade strategy, governance, migration, and versioning recommendations. I have smart contract design experience.
Kindly assign me to this task. Thanks!

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

[AGWAM001]

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

Please assign this issue to me

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

[zeemscript]

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

Hi Maintainer, I’d like to work on this issue. I have experience handling similar tasks and can start immediately.

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

[drips-wave]

Congratulations, @thebabalola! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

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