[Smart Contracts] Add Contract Upgradeability & Migration Harness via Soroban WASM Hash Update

[blurbeast]

Overview & Background

Soroban smart contracts support in-place contract code upgrades via the native system call:

env.deployer().update_current_contract_wasm(new_wasm_hash)

Currently, FlowFi's stream_contract contains no upgrade entrypoint or storage migration mechanism. If a critical protocol vulnerability, security patch, or state schema update is needed, the current contract cannot be upgraded in place. Without an upgrade path, migrating active streams would require manual contract deprecation, fund extraction, and redeployment—disrupting ongoing vesting schedules.

---

Detailed Problem Statement

1. Inability to Patch Bugs:
   • Discovered edge cases, arithmetic quirks, or Soroban SDK protocol bumps cannot be applied to the existing contract address.
2. Permanent Address Invariance:
   • Deploying a new contract changes the contract address, breaking all existing integrations, indexers, frontends, and external smart contract integrations.
3. Lack of Migration Framework:
   • No standardized schema versioning exists in instance storage to handle data schema changes between contract revisions.

---

Technical Specification & Architecture

1. Upgrade Entrypoint & Access Control

Implement in contracts/stream_contract/src/lib.rs:

pub fn upgrade(env: Env, new_wasm_hash: BytesN<32>) -> Result<(), StreamError> {
    let config = storage::load_config(&env).ok_or(StreamError::NotInitialized)?;
    config.admin.require_auth();
    env.deployer().update_current_contract_wasm(new_wasm_hash.clone());
    events::emit_contract_upgraded(&env, &new_wasm_hash);
    Ok(())
}

2. State Schema Versioning

Add contract version tracking to instance storage:

#[contracttype]
pub enum DataKey {
    // ...
    ContractVersion,
}

pub fn get_contract_version(env: Env) -> u32;
pub fn migrate(env: Env, target_version: u32) -> Result<(), StreamError>;

3. Events

Emit ContractUpgraded event containing old_wasm_hash, new_wasm_hash, and ledger timestamp.

---

Target Files

• contracts/stream_contract/src/lib.rs
• contracts/stream_contract/src/storage.rs
• contracts/stream_contract/src/events.rs
• contracts/stream_contract/src/test.rs

---

Acceptance Criteria

• upgrade entrypoint updates the contract WASM hash on the ledger.
• Non-admin callers attempting to invoke upgrade or migrate strictly fail with authorization errors.
• Contract state (active streams, balances, protocol config) remains fully intact and functional post-upgrade.
• Unit tests verify upgrading to a mock WASM binary with backward-compatible state reads.

[graceful-tech12]

@graceful-tech12 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Good Day Dev, i have read and understood the requirements of this issue. I will deliver a graceful implementation of solution. Please assign!

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

[harmondconsultant-png]

@harmondconsultant-png has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

hy, i can work on it pleas assign

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

[pimaster900]

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

i would like to work on this

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

[geofferydavido-spec]

@geofferydavido-spec has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi Maintainer, I’m ready to take on this issue.

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

[unknown-variableycdm]

@unknown-variableycdm has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

After reviewing the issue requirements, I’m confident I can address the problem effectively and deliver an implementation that meets all the outlined criteria.

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

[Abub57]

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

I am a detail-oriented and reliable individual with strong skills in research, data entry, online tasks, and following instructions. I am committed to delivering accurate and high-quality work within deadlines and am available to start tasks immediately.

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

[galliogy]

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

I would like to work on this issue

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

[Darkvader-ship-it]

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

can i work on this

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

[drips-wave]

Congratulations, @Darkvader-ship-it! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on September 30, 2026.

🧑‍💻 @Darkvader-ship-it: 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 🌊