Skip to content

feat: add Stellar contract upgrade governance and migration plan #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
thebabalola wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

feat: add Stellar contract upgrade governance and migration plan #37

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions stellar/UPGRADE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Stellar Contract Upgrade Governance & Migration Plan

This document outlines the strategy for upgrading Wraith Protocol smart contracts on the Stellar network, ensuring security, transparency, and minimal disruption to users.

## 1. Governance Model

### 1.1 Administrative Authority
All upgradeable contracts (currently `stealth-sender`) will have an `admin` address. In the initial phase, this will be a multi-sig account managed by the core team.

### 1.2 Upgrade Mechanism
Soroban contracts can be upgraded by replacing the contract's WASM hash.
- **Action**: `env.deployer().update_current_contract_wasm(new_wasm_hash)`
- **Restriction**: This action MUST be restricted to the `admin` account via `admin.require_auth()`.

### 1.3 Governance Transition
As the protocol matures, the `admin` role will transition from a team multi-sig to a Decentralized Autonomous Organization (DAO) or a time-locked governance contract.

## 2. Upgrade Procedure

### 2.1 Preparation
1. **Security Audit**: Any new WASM code must undergo a security audit.
2. **Testnet Validation**: Deploy and test the new WASM on `testnet` and `futurenet`.
3. **WASM Upload**: Upload the new WASM to the network to obtain the new WASM hash.

### 2.2 Execution
1. **Announcement**: Notify the community via official channels at least 72 hours before execution (on mainnet).
2. **Invoke Upgrade**: The `admin` invokes the `upgrade` function on the contract with the new WASM hash.
3. **Verification**: Verify the upgrade by checking the contract's WASM hash on-chain.

## 3. Migration Plan (v1 to v2)

### 3.1 Registry Data
The `stealth-registry` uses `persistent` storage. Upgrading the contract logic will NOT affect existing registrations as long as the `DataKey` structure remains compatible.

### 3.2 Sender State
The `stealth-sender` stores the `announcer` contract ID. An upgrade function should allow the `admin` to update this ID if the announcer is ever replaced.

### 3.3 Emergency Pause
A circuit breaker (pause) mechanism should be implemented in the `stealth-sender` to allow the `admin` to stop new transactions in case of a critical vulnerability discovery.

## 4. Implementation Checklist for v2
- [ ] Add `upgrade(new_wasm_hash)` function to all core contracts.
- [ ] Implement `pause()` and `unpause()` in `stealth-sender`.
- [ ] Add `set_admin(new_admin)` for governance handovers.
- [ ] Ensure all state-changing administrative functions emit `GovernanceEvent`.