[ARCHITECTURE] Soroban contracts are immutable - no upgrade mechanism

[Menjay7]

Description

This PR formalizes the architectural decision that Soroban contracts are deployed as immutable artifacts and will not implement an on-chain upgrade mechanism. The objective is to maintain simplicity, predictability, and trust by ensuring that deployed contract logic cannot be modified after deployment.

Motivation

Introducing upgradeability adds complexity, increases security risks, and requires additional governance mechanisms. By keeping contracts immutable, we gain:

Predictable behavior: Contract logic remains constant throughout its lifecycle.
Enhanced security: Eliminates risks associated with upgrade keys and malicious or accidental upgrades.
Simpler architecture: Reduces maintenance overhead and operational complexity.
Greater trust: Users and integrators can rely on deployed contracts remaining unchanged.
Architectural Decision
Deployed Soroban contracts are treated as immutable.
No proxy patterns, delegate calls, or upgrade administrators will be implemented.
New functionality or fixes require deploying a new contract version.
State migration, if needed, will be handled through explicit migration strategies and versioned deployments.
Implications
Advantages
Reduced attack surface
Easier auditing and verification
Clear version history and deployment lineage
Improved decentralization and transparency
Trade-offs
Bug fixes require new deployments
Features cannot be added to existing contract instances
Consumers may need to migrate to newer contract versions
Implementation Notes
Document immutability guarantees in architecture and developer guides.
Establish contract versioning conventions.
Define migration procedures for future contract iterations.
Ensure client applications can discover and interact with the latest contract versions.
Testing
Verified architecture documentation reflects immutability constraints
Confirmed no upgrade hooks or proxy mechanisms exist
Reviewed deployment and migration workflows
Obtain architecture review and team approval
Future Considerations

If requirements evolve, new versions should be released as separate contract deployments with explicit migration paths rather than introducing upgradeability into existing contracts...closed #172

[Xuccessor]

Hey @Menjay7 — appreciate the docs write-up! Heads up though: issue #172 actually asks for a proxy/upgrade mechanism scaffolded in apps/contracts/src/lib.rs, not just documentation. Want to take a stab at the contract-side change too? Happy to merge once there is real upgrade-pattern scaffolding.

[Xuccessor]

Hey @Menjay7 — appreciate the docs write-up! Heads up though: issue #172 actually asks for a proxy/upgrade mechanism scaffolded in apps/contracts/src/lib.rs, not just documentation. Want to take a stab at the contract-side change too? Happy to merge once there is real upgrade-pattern scaffolding.

[GBOYEE]

I'd like to work on this issue. I have background in contracts and will submit a PR ASAP.

[GBOYEE]

I'd like to work on this.

Approach:

• I'll add the CI config and test it locally before pushing
• Verify with existing tests + add new ones if needed

Estimated effort: ~1-2 hours. PR incoming shortly.
Closes #302

[Xuccessor]

Thanks for the work here. Unfortunately, this branch has real merge conflicts with main right now and can't be merged as-is. Could you rebase against the current main and push? Happy to merge once it lands cleanly.