Merge pull request #281 from abore9769/feature/multisig-arbitration

feat: multi-signature arbitration for high-value trades

Author: Mystery-CLI

contract/src/errors.rs

@@ -93,6 +93,17 @@ pub enum ContractError {
     NoUpgradeInProgress = 63,
     /// Rollback window has passed; state cannot be reverted automatically.
     RollbackWindowExpired = 64,
+    // Multi-sig arbitration errors (70–74)
+    /// threshold == 0 or threshold > arbitrators count.
+    InvalidMultiSigConfig = 70,
+    /// Arbitrator has already cast a vote for this trade.
+    AlreadyVoted = 71,
+    /// Voting window has expired; no more votes accepted.
+    VotingExpired = 72,
+    /// Voting window has not yet expired; cannot force-resolve.
+    VotingNotExpired = 73,
+    /// No consensus reached among arbitrators.
+    NoConsensus = 74,
     // Social feature errors (70-74)
     CannotFollowSelf = 70,
     NotFollowing = 71,

contract/src/events.rs

@@ -350,3 +350,26 @@ pub fn emit_upgrade_cancelled(env: &Env, cancelled_by: Address) {
 pub fn emit_upgrade_rolled_back(env: &Env, rolled_back_by: Address, restored_version: u32) {
     env.events().publish((cat_sys(), symbol_short!("up_rb")), EvUpgradeRolledBack { v: EVENT_VERSION, rolled_back_by, restored_version });
 }
+
+// ---------------------------------------------------------------------------
+// Multi-sig arbitration events
+// ---------------------------------------------------------------------------
+
+fn cat_multisig() -> Symbol { symbol_short!("multisig") }
+
+#[contracttype] #[derive(Clone, Debug)]
+pub struct EvArbVoteCast { pub v: u32, pub trade_id: u64, pub arbitrator: Address, pub resolution: crate::types::DisputeResolution }
+#[contracttype] #[derive(Clone, Debug)]
+pub struct EvMultiSigConsensus { pub v: u32, pub trade_id: u64 }
+#[contracttype] #[derive(Clone, Debug)]
+pub struct EvMultiSigExpired { pub v: u32, pub trade_id: u64 }
+
+pub fn emit_arbitrator_vote_cast(env: &Env, trade_id: u64, arbitrator: Address, resolution: crate::types::DisputeResolution) {
+    env.events().publish((cat_multisig(), symbol_short!("ms_vote")), EvArbVoteCast { v: EVENT_VERSION, trade_id, arbitrator, resolution });
+}
+pub fn emit_multisig_consensus(env: &Env, trade_id: u64) {
+    env.events().publish((cat_multisig(), symbol_short!("ms_cons")), EvMultiSigConsensus { v: EVENT_VERSION, trade_id });
+}
+pub fn emit_multisig_expired(env: &Env, trade_id: u64) {
+    env.events().publish((cat_multisig(), symbol_short!("ms_exp")), EvMultiSigExpired { v: EVENT_VERSION, trade_id });
+}

contract/src/lib.rs

@@ -5,6 +5,7 @@ mod amm;
 mod errors;
 mod events;
 mod governance;
+mod multisig;
 mod oracle;
 mod privacy;
 mod queries;
@@ -22,6 +23,10 @@ use soroban_sdk::{contract, contractimpl, token::TokenClient, Address, BytesN, E
 
 pub use errors::ContractError;
 pub use types::{
+    ArbitrationConfig, ArbitratorVote, DisclosureGrant, DisputeResolution, MultiSigConfig,
+    Proposal, ProposalAction, ProposalStatus, Subscription, SubscriptionTier, TierConfig,
+    TemplateTerms, TemplateVersion, Trade, TradePrivacy, TradeStatus, TradeTemplate,
+    UserTier, UserTierInfo, VotingSummary,
     ArbitratorReputation, DisclosureGrant, DisputeResolution, Proposal, ProposalAction,
     ProposalStatus, Subscription, SubscriptionTier, TierConfig, TemplateTerms, TemplateVersion,
     Trade, TradePrivacy, TradeStatus, TradeTemplate, UserTier, UserTierInfo,
@@ -206,6 +211,91 @@ impl StellarEscrowContract {
     }
 
     // -------------------------------------------------------------------------
+    // Multi-Signature Arbitration
+    // -------------------------------------------------------------------------
+
+    /// Create a trade with multi-signature arbitration.
+    /// All arbitrators in `config` must be registered; threshold must be > 0
+    /// and ≤ arbitrators count.
+    pub fn create_multisig_trade(
+        env: Env,
+        seller: Address,
+        buyer: Address,
+        amount: u64,
+        config: MultiSigConfig,
+        expiry_time: Option<u64>,
+        currency: Option<Address>,
+    ) -> Result<u64, ContractError> {
+        require_initialized(&env)?;
+        require_not_paused(&env)?;
+        if amount == 0 {
+            return Err(ContractError::InvalidAmount);
+        }
+        if config.threshold == 0 || config.threshold > config.arbitrators.len() {
+            return Err(ContractError::InvalidMultiSigConfig);
+        }
+        for i in 0..config.arbitrators.len() {
+            if !has_arbitrator(&env, &config.arbitrators.get(i).unwrap()) {
+                return Err(ContractError::ArbitratorNotRegistered);
+            }
+        }
+        if let Some(expiry) = expiry_time {
+            if expiry <= env.ledger().timestamp() {
+                return Err(ContractError::InvalidExpiry);
+            }
+        }
+        seller.require_auth();
+        let token = currency.unwrap_or(get_usdc_token(&env)?);
+        let trade_id = increment_trade_counter(&env)?;
+        let fee = calc_fee(&env, &seller, amount)?;
+        let trade = Trade {
+            id: trade_id,
+            seller: seller.clone(),
+            buyer: buyer.clone(),
+            amount,
+            fee,
+            arbitrator: Some(ArbitrationConfig::MultiSig(config)),
+            status: TradeStatus::Created,
+            expiry_time,
+            currency: token,
+            metadata: None,
+        };
+        save_trade(&env, trade_id, &trade);
+        events::emit_trade_created(&env, trade_id, seller, buyer, amount, trade.currency);
+        Ok(trade_id)
+    }
+
+    /// Cast a vote on a disputed multi-sig trade.
+    pub fn cast_vote(
+        env: Env,
+        trade_id: u64,
+        arbitrator: Address,
+        resolution: DisputeResolution,
+    ) -> Result<(), ContractError> {
+        require_initialized(&env)?;
+        require_not_paused(&env)?;
+        multisig::cast_vote(&env, trade_id, &arbitrator, resolution)
+    }
+
+    /// Return the current voting state for a multi-sig trade.
+    pub fn get_voting_summary(env: Env, trade_id: u64) -> Result<VotingSummary, ContractError> {
+        require_initialized(&env)?;
+        multisig::voting_summary(&env, trade_id)
+    }
+
+    /// Force-resolve a multi-sig dispute after the voting window expires without
+    /// consensus. Defaults to refunding the buyer. Admin only.
+    pub fn resolve_expired_dispute(
+        env: Env,
+        admin: Address,
+        trade_id: u64,
+    ) -> Result<(), ContractError> {
+        require_initialized(&env)?;
+        require_not_paused(&env)?;
+        require_admin(&env, &admin)?;
+        let resolution = multisig::resolve_expired_dispute(&env, trade_id, &admin)?;
+        let trade = get_trade(&env, trade_id)?;
+        StellarEscrowContract::execute_dispute_resolution(env, trade_id, resolution, trade)
     // Arbitrator Reputation
     // -------------------------------------------------------------------------
 

contract/src/multisig.rs

@@ -0,0 +1,194 @@
+/// Multi-signature arbitration for high-value trades.
+///
+/// Flow:
+///   1. Seller calls `create_multisig_trade` with a `MultiSigConfig`
+///      (arbitrators list, threshold, voting_timeout_seconds).
+///   2. Buyer or seller raises a dispute — voting window opens automatically.
+///   3. Each panel arbitrator calls `cast_vote` with their preferred resolution.
+///   4. Once `threshold` arbitrators agree on the same outcome, consensus is
+///      reached and `resolve_dispute` executes it.
+///   5. If the window expires without consensus, admin calls
+///      `resolve_expired_dispute` — defaults to refunding the buyer.
+
+use soroban_sdk::{Address, Env, Vec};
+
+use crate::errors::ContractError;
+use crate::events;
+use crate::storage::{
+    get_all_votes_for_trade, get_trade, has_arbitrator, has_arbitrator_voted,
+    save_arbitrator_vote,
+};
+use crate::types::{
+    ArbitrationConfig, ArbitratorVote, DisputeResolution, MultiSigConfig, Trade,
+    TradeStatus, VotingSummary,
+};
+
+// ---------------------------------------------------------------------------
+// Cast vote
+// ---------------------------------------------------------------------------
+
+pub fn cast_vote(
+    env: &Env,
+    trade_id: u64,
+    arbitrator: &Address,
+    resolution: DisputeResolution,
+) -> Result<(), ContractError> {
+    let trade = get_trade(env, trade_id)?;
+    if trade.status != TradeStatus::Disputed {
+        return Err(ContractError::InvalidStatus);
+    }
+    let config = extract_multisig_config(&trade)?;
+
+    if !is_panel_member(arbitrator, &config.arbitrators) {
+        return Err(ContractError::Unauthorized);
+    }
+    if !has_arbitrator(env, arbitrator) {
+        return Err(ContractError::ArbitratorNotRegistered);
+    }
+    if has_arbitrator_voted(env, trade_id, arbitrator) {
+        return Err(ContractError::AlreadyVoted);
+    }
+    if is_voting_expired(env, &config) {
+        return Err(ContractError::VotingExpired);
+    }
+
+    arbitrator.require_auth();
+
+    save_arbitrator_vote(
+        env,
+        trade_id,
+        arbitrator,
+        &ArbitratorVote {
+            arbitrator: arbitrator.clone(),
+            resolution: resolution.clone(),
+            timestamp: env.ledger().timestamp(),
+        },
+    );
+
+    events::emit_arbitrator_vote_cast(env, trade_id, arbitrator.clone(), resolution);
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Voting summary / consensus
+// ---------------------------------------------------------------------------
+
+pub fn voting_summary(env: &Env, trade_id: u64) -> Result<VotingSummary, ContractError> {
+    let trade = get_trade(env, trade_id)?;
+    let config = extract_multisig_config(&trade)?;
+
+    let votes = get_all_votes_for_trade(env, trade_id, &config.arbitrators);
+    let votes_cast = votes.len() as u32;
+    let total_arbitrators = config.arbitrators.len() as u32;
+    let expired = is_voting_expired(env, &config);
+    let threshold = config.threshold;
+
+    // Tally votes per resolution variant
+    let mut release_to_buyer: u32 = 0;
+    let mut release_to_seller: u32 = 0;
+    // Partial votes: Vec of (buyer_bps, count)
+    let mut partial: Vec<(u32, u32)> = Vec::new(env);
+
+    for i in 0..votes.len() {
+        match votes.get(i).unwrap().resolution {
+            DisputeResolution::ReleaseToBuyer => release_to_buyer += 1,
+            DisputeResolution::ReleaseToSeller => release_to_seller += 1,
+            DisputeResolution::Partial { buyer_bps } => {
+                let mut found = false;
+                for j in 0..partial.len() {
+                    let (bps, cnt) = partial.get(j).unwrap();
+                    if bps == buyer_bps {
+                        partial.set(j, (bps, cnt + 1));
+                        found = true;
+                        break;
+                    }
+                }
+                if !found {
+                    partial.push_back((buyer_bps, 1));
+                }
+            }
+        }
+    }
+
+    let consensus: Option<DisputeResolution> = if release_to_buyer >= threshold {
+        Some(DisputeResolution::ReleaseToBuyer)
+    } else if release_to_seller >= threshold {
+        Some(DisputeResolution::ReleaseToSeller)
+    } else {
+        let mut found: Option<DisputeResolution> = None;
+        for i in 0..partial.len() {
+            let (bps, cnt) = partial.get(i).unwrap();
+            if cnt >= threshold {
+                found = Some(DisputeResolution::Partial { buyer_bps: bps });
+                break;
+            }
+        }
+        found
+    };
+
+    if consensus.is_some() {
+        events::emit_multisig_consensus(env, trade_id);
+    }
+
+    Ok(VotingSummary {
+        total_arbitrators,
+        votes_cast,
+        threshold,
+        has_consensus: consensus.is_some(),
+        consensus_resolution: consensus,
+        voting_expired: expired,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Expired-dispute resolution
+// ---------------------------------------------------------------------------
+
+/// Force-resolve after the voting window expires without consensus.
+/// Safe default: refund the buyer. Admin-only.
+pub fn resolve_expired_dispute(
+    env: &Env,
+    trade_id: u64,
+    admin: &Address,
+) -> Result<DisputeResolution, ContractError> {
+    let trade = get_trade(env, trade_id)?;
+    if trade.status != TradeStatus::Disputed {
+        return Err(ContractError::InvalidStatus);
+    }
+    let config = extract_multisig_config(&trade)?;
+    if !is_voting_expired(env, &config) {
+        return Err(ContractError::VotingNotExpired);
+    }
+    admin.require_auth();
+    events::emit_multisig_expired(env, trade_id);
+    Ok(DisputeResolution::ReleaseToBuyer)
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+fn extract_multisig_config(trade: &Trade) -> Result<MultiSigConfig, ContractError> {
+    match &trade.arbitrator {
+        Some(ArbitrationConfig::MultiSig(cfg)) => Ok(cfg.clone()),
+        _ => Err(ContractError::InvalidStatus),
+    }
+}
+
+fn is_panel_member(arbitrator: &Address, panel: &Vec<Address>) -> bool {
+    for i in 0..panel.len() {
+        if panel.get(i).unwrap() == *arbitrator {
+            return true;
+        }
+    }
+    false
+}
+
+fn is_voting_expired(env: &Env, config: &MultiSigConfig) -> bool {
+    match config.voting_started_at {
+        Some(started) => {
+            env.ledger().timestamp() > started.saturating_add(config.voting_timeout_seconds)
+        }
+        None => false,
+    }
+}