Merge branch 'main' into feat/stream-insurance-governance

elizabetheonoja-art · web-flow · commit 1efb2162a1d4 · 2026-03-30T12:55:58.000+01:00
diff --git a/ORACLE_INTEGRATION.md b/ORACLE_INTEGRATION.md
@@ -31,11 +31,18 @@ The solution consists of two main components:
 - **Provider Withdrawals**: Allows providers to withdraw earnings in XLM
 - **Conversion Events**: Emits events for transparency
 - **Backward Compatibility**: Works with existing custom tokens
+- **Emergency Trust Mode**: Enables manual recovery when oracle heartbeat is stale for 72 hours
+- **Unanimous Governance Guard**: Emergency actions require 100% approval from all active members
 
 #### New Functions:
 - `top_up()` - Enhanced to handle XLM→USD conversion
 - `withdraw_earnings()` - New function for USD→XLM conversion
 - `get_current_rate()` - Get current exchange rate
+- `is_trust_mode()` - Returns true when oracle heartbeat is stale for more than 72 hours
+- `propose_emergency_flow_rate()` - Create emergency proposal to set manual flow rate
+- `propose_emergency_pause()` - Create emergency proposal to pause a meter cycle
+- `approve_emergency_action()` - Approve an emergency proposal (one vote per member)
+- `execute_emergency_action()` - Execute only after unanimous member approval
 
 ## Usage Flow
 
@@ -76,6 +83,48 @@ New error types added:
 2. **Staleness Checks**: Rejects old price data
 3. **Access Control**: Admin controls updater role
 4. **Event Logging**: All conversions emit events for transparency
+5. **Trust Mode Gate**: Emergency manual controls are blocked while oracle heartbeat is healthy
+6. **Strict Unanimity**: Every registered active member must approve emergency actions
+7. **Duplicate Vote Prevention**: A member can approve a proposal only once
+
+## Trust Mode and Manual Fallback
+
+### Activation Rule
+
+Trust Mode is derived from on-chain oracle heartbeat state:
+
+- Utility contract fetches oracle `PriceData.last_updated`
+- If `now - last_updated > 72 hours`, Trust Mode is active
+- If no oracle address is configured, Trust Mode is treated as active for recovery operations
+
+Boundary behavior is strict:
+
+- exactly 72 hours stale: not yet in Trust Mode
+- greater than 72 hours stale: Trust Mode active
+
+### Allowed Actions in Trust Mode
+
+Only in Trust Mode, active members can unanimously approve:
+
+1. manual `max_flow_rate_per_hour` update for a meter
+2. manual cycle pause (`is_paused = true`) for a meter
+
+Outside Trust Mode these manual emergency actions revert.
+
+### Member Eligibility and Unanimity
+
+- Members are addresses registered through `register_active_user()`
+- Membership is tracked uniquely per address
+- Proposal creator auto-approves their proposal
+- Additional approvals are counted once per member
+- Execution requires `approval_count == active_member_count`
+
+### Oracle Recovery Assumption
+
+- When oracle heartbeat becomes healthy again, new emergency proposals and approvals are blocked
+- Already executed emergency actions remain in state (no automatic rollback)
+
+This keeps fallback narrowly scoped to catastrophic oracle inactivity without weakening normal oracle-driven behavior.
 
 ## Testing
 
diff --git a/contracts/utility_contracts/src/lib.rs b/contracts/utility_contracts/src/lib.rs
@@ -237,6 +237,24 @@ pub struct AdminTransferProposal {
     pub is_active: bool,
 }
 
+#[contracttype]
+#[derive(Clone)]
+pub enum EmergencyAction {
+    SetFlowRate(i128),
+    PauseCycle,
+}
+
+#[contracttype]
+#[derive(Clone)]
+pub struct EmergencyProposal {
+    pub proposal_id: u64,
+    pub meter_id: u64,
+    pub action: EmergencyAction,
+    pub proposed_by: Address,
+    pub proposed_at: u64,
+    pub executed: bool,
+}
+
 pub fn set_sorosusu_contract(env: Env, addr: Address) {
     env.storage()
         .instance()
@@ -502,6 +520,7 @@ const LEDGER_LIFETIME_EXTENSION: u32 = 1_000_000; // Extend by 1M ledgers
 
 // Task #4: Wasm Hash Rotation Constants
 const UPGRADE_VETO_PERIOD_SECONDS: u64 = 7 * DAY_IN_SECONDS; // 7 days veto period
+const ORACLE_HEARTBEAT_TIMEOUT_SECONDS: u64 = 72 * HOUR_IN_SECONDS;
 
 /// Round XLM amount to nearest minimum increment (0.0000001 XLM)
 /// This prevents value loss over time due to truncation
@@ -614,6 +633,67 @@ fn get_oracle_or_panic(env: &Env) -> Address {
     }
 }
 
+fn is_trust_mode_active(env: &Env) -> bool {
+    let now = env.ledger().timestamp();
+    match env
+        .storage()
+        .instance()
+        .get::<DataKey, Address>(&DataKey::Oracle)
+    {
+        Some(oracle_address) => {
+            let oracle_client = PriceOracleClient::new(env, &oracle_address);
+            let price_data = oracle_client.get_price();
+            now.saturating_sub(price_data.last_updated) > ORACLE_HEARTBEAT_TIMEOUT_SECONDS
+        }
+        None => true,
+    }
+}
+
+fn require_trust_mode(env: &Env) {
+    if !is_trust_mode_active(env) {
+        panic_with_error!(env, ContractError::OracleHeartbeatHealthy);
+    }
+}
+
+fn active_member_count(env: &Env) -> u32 {
+    env.storage()
+        .instance()
+        .get::<DataKey, u32>(&DataKey::ActiveUsers)
+        .unwrap_or(0)
+}
+
+fn require_emergency_member(env: &Env, member: &Address) {
+    member.require_auth();
+    let is_member = env
+        .storage()
+        .instance()
+        .get::<DataKey, bool>(&DataKey::ActiveUserMember(member.clone()))
+        .unwrap_or(false);
+    if !is_member {
+        panic_with_error!(env, ContractError::NotEmergencyMember);
+    }
+}
+
+fn next_emergency_proposal_id(env: &Env) -> u64 {
+    let current = env
+        .storage()
+        .instance()
+        .get::<DataKey, u64>(&DataKey::EmergencyProposalSeq)
+        .unwrap_or(0);
+    let next = current.saturating_add(1);
+    env.storage()
+        .instance()
+        .set(&DataKey::EmergencyProposalSeq, &next);
+    next
+}
+
+fn get_emergency_proposal_or_panic(env: &Env, proposal_id: u64) -> EmergencyProposal {
+    env.storage()
+        .instance()
+        .get::<DataKey, EmergencyProposal>(&DataKey::EmergencyProposal(proposal_id))
+        .unwrap_or_else(|| panic_with_error!(env, ContractError::EmergencyProposalNotFound))
+}
+
 fn convert_xlm_to_usd_if_needed(
     env: &Env,
     amount: i128,
@@ -2066,6 +2146,193 @@ impl UtilityContract {
             .publish((symbol_short!("Paused"), meter_id), paused);
     }
 
+    pub fn is_trust_mode(env: Env) -> bool {
+        is_trust_mode_active(&env)
+    }
+
+    pub fn propose_emergency_flow_rate(
+        env: Env,
+        member: Address,
+        meter_id: u64,
+        max_rate_per_hour: i128,
+    ) -> u64 {
+        require_trust_mode(&env);
+        require_emergency_member(&env, &member);
+        if active_member_count(&env) == 0 {
+            panic_with_error!(&env, ContractError::EmergencyNoMembers);
+        }
+        if max_rate_per_hour <= 0 {
+            panic_with_error!(&env, ContractError::InvalidTokenAmount);
+        }
+
+        // Ensure the target meter exists before proposal creation.
+        let _meter = get_meter_or_panic(&env, meter_id);
+        let proposal_id = next_emergency_proposal_id(&env);
+        let proposal = EmergencyProposal {
+            proposal_id,
+            meter_id,
+            action: EmergencyAction::SetFlowRate(max_rate_per_hour),
+            proposed_by: member.clone(),
+            proposed_at: env.ledger().timestamp(),
+            executed: false,
+        };
+
+        env.storage()
+            .instance()
+            .set(&DataKey::EmergencyProposal(proposal_id), &proposal);
+        env.storage().instance().set(
+            &DataKey::EmergencyProposalApproval(proposal_id, member),
+            &true,
+        );
+        env.storage()
+            .instance()
+            .set(&DataKey::EmergencyProposalApprovalCount(proposal_id), &1u32);
+
+        env.events().publish(
+            (symbol_short!("EmgProp"), proposal_id),
+            (meter_id, env.ledger().timestamp()),
+        );
+
+        proposal_id
+    }
+
+    pub fn propose_emergency_pause(env: Env, member: Address, meter_id: u64) -> u64 {
+        require_trust_mode(&env);
+        require_emergency_member(&env, &member);
+        if active_member_count(&env) == 0 {
+            panic_with_error!(&env, ContractError::EmergencyNoMembers);
+        }
+
+        // Ensure the target meter exists before proposal creation.
+        let _meter = get_meter_or_panic(&env, meter_id);
+        let proposal_id = next_emergency_proposal_id(&env);
+        let proposal = EmergencyProposal {
+            proposal_id,
+            meter_id,
+            action: EmergencyAction::PauseCycle,
+            proposed_by: member.clone(),
+            proposed_at: env.ledger().timestamp(),
+            executed: false,
+        };
+
+        env.storage()
+            .instance()
+            .set(&DataKey::EmergencyProposal(proposal_id), &proposal);
+        env.storage().instance().set(
+            &DataKey::EmergencyProposalApproval(proposal_id, member),
+            &true,
+        );
+        env.storage()
+            .instance()
+            .set(&DataKey::EmergencyProposalApprovalCount(proposal_id), &1u32);
+
+        env.events().publish(
+            (symbol_short!("EmgProp"), proposal_id),
+            (meter_id, env.ledger().timestamp()),
+        );
+
+        proposal_id
+    }
+
+    pub fn approve_emergency_action(env: Env, member: Address, proposal_id: u64) {
+        require_trust_mode(&env);
+        require_emergency_member(&env, &member);
+        if active_member_count(&env) == 0 {
+            panic_with_error!(&env, ContractError::EmergencyNoMembers);
+        }
+
+        let proposal = get_emergency_proposal_or_panic(&env, proposal_id);
+        if proposal.executed {
+            panic_with_error!(&env, ContractError::EmergencyProposalExecuted);
+        }
+
+        if env.storage().instance().has(&DataKey::EmergencyProposalApproval(
+            proposal_id,
+            member.clone(),
+        )) {
+            panic_with_error!(&env, ContractError::AlreadyVoted);
+        }
+
+        env.storage().instance().set(
+            &DataKey::EmergencyProposalApproval(proposal_id, member),
+            &true,
+        );
+
+        let approvals = env
+            .storage()
+            .instance()
+            .get::<DataKey, u32>(&DataKey::EmergencyProposalApprovalCount(proposal_id))
+            .unwrap_or(0)
+            .saturating_add(1);
+        env.storage()
+            .instance()
+            .set(&DataKey::EmergencyProposalApprovalCount(proposal_id), &approvals);
+
+        env.events().publish(
+            (symbol_short!("EmgAppr"), proposal_id),
+            approvals,
+        );
+    }
+
+    pub fn execute_emergency_action(env: Env, member: Address, proposal_id: u64) {
+        require_trust_mode(&env);
+        require_emergency_member(&env, &member);
+
+        let total_members = active_member_count(&env);
+        if total_members == 0 {
+            panic_with_error!(&env, ContractError::EmergencyNoMembers);
+        }
+
+        let mut proposal = get_emergency_proposal_or_panic(&env, proposal_id);
+        if proposal.executed {
+            panic_with_error!(&env, ContractError::EmergencyProposalExecuted);
+        }
+
+        let approvals = env
+            .storage()
+            .instance()
+            .get::<DataKey, u32>(&DataKey::EmergencyProposalApprovalCount(proposal_id))
+            .unwrap_or(0);
+        if approvals != total_members {
+            panic_with_error!(&env, ContractError::EmergencyApprovalIncomplete);
+        }
+
+        let mut meter = get_meter_or_panic(&env, proposal.meter_id);
+        match proposal.action {
+            EmergencyAction::SetFlowRate(rate) => {
+                if rate <= 0 {
+                    panic_with_error!(&env, ContractError::InvalidTokenAmount);
+                }
+                meter.max_flow_rate_per_hour = rate;
+            }
+            EmergencyAction::PauseCycle => {
+                meter.is_paused = true;
+                let now = env.ledger().timestamp();
+                refresh_activity(&mut meter, now);
+            }
+        }
+
+        env.storage()
+            .instance()
+            .set(&DataKey::Meter(proposal.meter_id), &meter);
+
+        proposal.executed = true;
+        env.storage()
+            .instance()
+            .set(&DataKey::EmergencyProposal(proposal_id), &proposal);
+
+        env.events().publish(
+            (symbol_short!("EmgExec"), proposal_id),
+            proposal.meter_id,
+        );
+    }
+
+    pub fn get_emergency_proposal(env: Env, proposal_id: u64) -> Option<EmergencyProposal> {
+        env.storage()
+            .instance()
+            .get(&DataKey::EmergencyProposal(proposal_id))
+    }
+
     pub fn set_tiered_pricing(env: Env, meter_id: u64, threshold: i128, rate: i128) {
         let mut meter = get_meter_or_panic(&env, meter_id);
         meter.provider.require_auth();
@@ -3508,15 +3775,26 @@ impl UtilityContract {
     pub fn register_active_user(env: Env, user: Address) {
         user.require_auth();
 
-        // Simplified: just increment counter
-        let count: u32 = env
+        // Track members uniquely so unanimous emergency approvals are exact.
+        let already_member = env
             .storage()
             .instance()
-            .get(&DataKey::ActiveUsers)
-            .unwrap_or(0);
-        env.storage()
-            .instance()
-            .set(&DataKey::ActiveUsers, &(count + 1));
+            .get::<DataKey, bool>(&DataKey::ActiveUserMember(user.clone()))
+            .unwrap_or(false);
+
+        if !already_member {
+            let count: u32 = env
+                .storage()
+                .instance()
+                .get(&DataKey::ActiveUsers)
+                .unwrap_or(0);
+            env.storage()
+                .instance()
+                .set(&DataKey::ActiveUsers, &(count + 1));
+            env.storage()
+                .instance()
+                .set(&DataKey::ActiveUserMember(user.clone()), &true);
+        }
 
         env.events()
             .publish((soroban_sdk::symbol_short!("ActvUser"),), user);
diff --git a/contracts/utility_contracts/src/test.rs b/contracts/utility_contracts/src/test.rs
