Merge pull request #20 from Marvy247/feat/escrow-dispute-4

feat: add escrow dispute mechanism with optional arbitrator

Author: MarcusDavidG

contracts/sharpy/src/events.rs

@@ -54,3 +54,26 @@ pub fn invoice_refunded(env: &Env, id: u64) {
 pub fn payer_refunded(env: &Env, invoice_id: u64, payer: &Address, amount: i128) {
     env.events().publish((symbol_short!("pyr"),), PayerRefundedEvent { invoice_id, payer: payer.clone(), amount });
 }
+
+#[contracttype]
+#[derive(Clone)]
+pub struct DisputeRaisedEvent {
+    pub invoice_id: u64,
+    pub creator: Address,
+}
+
+#[contracttype]
+#[derive(Clone)]
+pub struct DisputeResolvedEvent {
+    pub invoice_id: u64,
+    pub resolver: Address,
+    pub release: bool,
+}
+
+pub fn dispute_raised(env: &Env, invoice_id: u64, creator: &Address) {
+    env.events().publish((symbol_short!("dispute"),), DisputeRaisedEvent { invoice_id, creator: creator.clone() });
+}
+
+pub fn dispute_resolved(env: &Env, invoice_id: u64, resolver: &Address, release: bool) {
+    env.events().publish((symbol_short!("dsprslv"),), DisputeResolvedEvent { invoice_id, resolver: resolver.clone(), release });
+}

contracts/sharpy/src/lib.rs

@@ -10,7 +10,7 @@ mod test;
 
 use soroban_sdk::{contract, contractimpl, symbol_short, token, Address, Env, Map, Symbol, Vec};
 use types::{
-    AuditEntry, CreateInvoiceParams, Invoice, InvoiceOptions, InvoicePayment,
+    AuditEntry, CreateInvoiceParams, DisputeState, Invoice, InvoiceOptions, InvoicePayment,
     InvoiceStatus, Payment, SplitRule, SubscriptionParams,
 };
 
@@ -70,6 +70,7 @@ fn build_invoice(
     escrow_enabled: bool,
     escrow_release_delay: u64,
     split_rules: Vec<SplitRule>,
+    arbitrator: Option<Address>,
 ) -> Invoice {
     let mut claimed: Vec<i128> = Vec::new(env);
     for _ in recipients.iter() {
@@ -92,6 +93,7 @@ fn build_invoice(
         escrow_release_delay,
         split_rules,
         auto_resolve_rules: Vec::new(env),
+        arbitrator,
     }
 }
 
@@ -140,6 +142,7 @@ impl SharpyContract {
         let invoice = build_invoice(
             &env, creator.clone(), recipients, amounts, tokens, deadline,
             options.escrow_enabled, options.escrow_release_delay.unwrap_or(0), options.split_rules,
+            options.arbitrator,
         );
         save_invoice(&env, id, &invoice);
         events::invoice_created(&env, id, &creator);
@@ -157,7 +160,7 @@ impl SharpyContract {
             let id = bump_counter(&env);
             let invoice = build_invoice(
                 &env, creator.clone(), params.recipients.clone(), params.amounts.clone(),
-                params.tokens.clone(), params.deadline, false, 0, Vec::new(&env),
+                params.tokens.clone(), params.deadline, false, 0, Vec::new(&env), None,
             );
             save_invoice(&env, id, &invoice);
             events::invoice_created(&env, id, &creator);
@@ -185,7 +188,7 @@ impl SharpyContract {
         let id = bump_counter(&env);
         let invoice = build_invoice(
             &env, creator.clone(), recipients.clone(), amounts.clone(),
-            tokens.clone(), deadline, false, 0, Vec::new(&env),
+            tokens.clone(), deadline, false, 0, Vec::new(&env), None,
         );
         save_invoice(&env, id, &invoice);
 
@@ -226,7 +229,8 @@ impl SharpyContract {
         if invoice.funded >= total {
             if invoice.escrow_enabled {
                 let release_at = env.ledger().timestamp() + invoice.escrow_release_delay;
-                env.storage().persistent().set(&escrow_state_key(invoice_id), &release_at);
+                let state = DisputeState { release_at, disputed: false, disputed_at: 0 };
+                env.storage().persistent().set(&escrow_state_key(invoice_id), &state);
                 save_invoice(&env, invoice_id, &invoice);
             } else {
                 Self::_release(&env, invoice_id, &mut invoice, &payer);
@@ -262,8 +266,15 @@ impl SharpyContract {
             append_audit(&env, p.invoice_id, symbol_short!("pool_pay"), &payer);
             events::payment_received(&env, p.invoice_id, &payer, p.amount);
             let inv_total: i128 = inv.amounts.iter().sum();
-            if inv.funded >= inv_total && !inv.escrow_enabled {
-                Self::_release(&env, p.invoice_id, &mut inv, &payer);
+            if inv.funded >= inv_total {
+                if inv.escrow_enabled {
+                    let release_at = env.ledger().timestamp() + inv.escrow_release_delay;
+                    let state = DisputeState { release_at, disputed: false, disputed_at: 0 };
+                    env.storage().persistent().set(&escrow_state_key(p.invoice_id), &state);
+                    save_invoice(&env, p.invoice_id, &inv);
+                } else {
+                    Self::_release(&env, p.invoice_id, &mut inv, &payer);
+                }
             } else {
                 save_invoice(&env, p.invoice_id, &inv);
             }
@@ -274,14 +285,71 @@ impl SharpyContract {
         require_not_paused(&env);
         let mut invoice = load_invoice(&env, invoice_id);
         assert!(invoice.escrow_enabled, "escrow not enabled on this invoice");
-        let release_at: u64 = env.storage().persistent()
+        let state: DisputeState = env.storage().persistent()
             .get(&escrow_state_key(invoice_id)).expect("escrow not found");
-        assert!(env.ledger().timestamp() >= release_at, "escrow delay not yet met");
+        assert!(!state.disputed, "release is disputed, use resolve_dispute");
+        assert!(env.ledger().timestamp() >= state.release_at, "escrow delay not yet met");
         let caller = env.current_contract_address();
         Self::_release(&env, invoice_id, &mut invoice, &caller);
         env.storage().persistent().remove(&escrow_state_key(invoice_id));
     }
 
+    pub fn dispute_release(env: Env, invoice_id: u64) {
+        require_not_paused(&env);
+        let invoice = load_invoice(&env, invoice_id);
+        assert!(invoice.status == InvoiceStatus::Pending, "invoice is not pending");
+        assert!(invoice.escrow_enabled, "escrow not enabled on this invoice");
+        invoice.creator.require_auth();
+
+        let state: DisputeState = env.storage().persistent()
+            .get(&escrow_state_key(invoice_id)).expect("escrow not found");
+        assert!(!state.disputed, "dispute already raised");
+        assert!(env.ledger().timestamp() < state.release_at, "escrow delay has passed, cannot dispute");
+
+        let new_state = DisputeState { disputed: true, disputed_at: env.ledger().timestamp(), ..state };
+        env.storage().persistent().set(&escrow_state_key(invoice_id), &new_state);
+        append_audit(&env, invoice_id, symbol_short!("dispute"), &invoice.creator);
+        events::dispute_raised(&env, invoice_id, &invoice.creator);
+    }
+
+    pub fn resolve_dispute(env: Env, invoice_id: u64, release: bool) {
+        require_not_paused(&env);
+        let mut invoice = load_invoice(&env, invoice_id);
+        assert!(invoice.status == InvoiceStatus::Pending, "invoice is not pending");
+
+        let state: DisputeState = env.storage().persistent()
+            .get(&escrow_state_key(invoice_id)).expect("escrow not found");
+        assert!(state.disputed, "no active dispute");
+
+        let resolver = invoice.arbitrator.clone().unwrap_or_else(|| invoice.creator.clone());
+        resolver.require_auth();
+
+        env.storage().persistent().remove(&escrow_state_key(invoice_id));
+
+        if release {
+            Self::_release(&env, invoice_id, &mut invoice, &resolver);
+        } else {
+            let token_client = token::Client::new(&env, &invoice.tokens.get(0).expect("no token"));
+            let mut totals: Map<Address, i128> = Map::new(&env);
+            for payment in invoice.payments.iter() {
+                let prev = totals.get(payment.payer.clone()).unwrap_or(0);
+                totals.set(payment.payer.clone(), prev + payment.amount);
+            }
+            for (payer, amount) in totals.iter() {
+                token_client.transfer(&env.current_contract_address(), &payer, &amount);
+                events::payer_refunded(&env, invoice_id, &payer, amount);
+            }
+
+            invoice.status = InvoiceStatus::Refunded;
+            invoice.completion_time = Some(env.ledger().timestamp());
+            save_invoice(&env, invoice_id, &invoice);
+            append_audit(&env, invoice_id, symbol_short!("resolve"), &resolver);
+            events::invoice_refunded(&env, invoice_id);
+        }
+
+        events::dispute_resolved(&env, invoice_id, &resolver, release);
+    }
+
     fn _release(env: &Env, invoice_id: u64, invoice: &mut Invoice, actor: &Address) {
         assert!(invoice.status == InvoiceStatus::Pending, "invoice is not pending");
 
@@ -336,7 +404,7 @@ impl SharpyContract {
 
                 let next_invoice = build_invoice(
                     env, params.creator.clone(), params.recipients.clone(),
-                    params.amounts.clone(), params.tokens.clone(), next_deadline, false, 0, Vec::new(env),
+                    params.amounts.clone(), params.tokens.clone(), next_deadline, false, 0, Vec::new(env), None,
                 );
                 save_invoice(env, next_id, &next_invoice);
 
@@ -422,4 +490,8 @@ impl SharpyContract {
     pub fn get_next_recurring(env: Env, invoice_id: u64) -> Option<u64> {
         env.storage().persistent().get(&next_invoice_key(invoice_id))
     }
+
+    pub fn get_escrow_state(env: Env, invoice_id: u64) -> Option<DisputeState> {
+        env.storage().persistent().get(&escrow_state_key(invoice_id))
+    }
 }

contracts/sharpy/src/test.rs

@@ -1,6 +1,6 @@
 #[cfg(test)]
 mod tests {
-    use soroban_sdk::{testutils::Address as _, Address, Env, Vec};
+    use soroban_sdk::{testutils::Address as _, token, Address, Env, Vec};
     use soroban_sdk::testutils::Ledger as _;
     use crate::{
         types::{CreateInvoiceParams, InvoiceOptions, InvoicePayment, InvoiceStatus, SplitRule},
@@ -24,6 +24,7 @@ mod tests {
             escrow_release_delay: None,
             split_rules: Vec::new(env),
             auto_resolve_rules: Vec::new(env),
+            arbitrator: None,
         }
     }
 
@@ -268,6 +269,7 @@ mod tests {
             escrow_release_delay: Some(3600u64),
             split_rules: Vec::new(&env),
             auto_resolve_rules: Vec::new(&env),
+            arbitrator: None,
         };
 
         let id = client.create_invoice(&creator, &Vec::from_array(&env, [recipient]),
@@ -390,4 +392,115 @@ mod tests {
             &default_options(&env),
         );
     }
+
+    // -----------------------------------------------------------------------
+    // Escrow dispute tests
+    // -----------------------------------------------------------------------
+
+    fn create_escrow_invoice(
+        env: &Env,
+        client: &SharpyContractClient<'static>,
+        creator: &Address,
+        payer: &Address,
+        recipient: &Address,
+        arbitrator: Option<Address>,
+    ) -> (u64, Address) {
+        let admin = Address::generate(env);
+        let token = env.register_stellar_asset_contract(admin.clone());
+        let sac = soroban_sdk::token::StellarAssetClient::new(env, &token);
+        sac.mint(payer, &1000i128);
+
+        let deadline = env.ledger().timestamp() + 86400;
+        let options = InvoiceOptions {
+            escrow_enabled: true,
+            escrow_release_delay: Some(3600u64),
+            split_rules: Vec::new(env),
+            auto_resolve_rules: Vec::new(env),
+            arbitrator,
+        };
+
+        let id = client.create_invoice(creator, &Vec::from_array(env, [recipient.clone()]),
+            &Vec::from_array(env, [500i128]), &Vec::from_array(env, [token.clone()]),
+            &deadline, &options);
+        (id, token)
+    }
+
+    #[test]
+    fn test_dispute_release_and_resolve_release() {
+        let (env, client) = setup();
+        let creator = Address::generate(&env);
+        let payer = Address::generate(&env);
+        let recipient = Address::generate(&env);
+
+        let (id, _) = create_escrow_invoice(&env, &client, &creator, &payer, &recipient, None);
+
+        client.pay(&payer, &id, &500i128);
+
+        let state = client.get_escrow_state(&id).unwrap();
+        assert!(!state.disputed);
+
+        client.dispute_release(&id);
+        let state = client.get_escrow_state(&id).unwrap();
+        assert!(state.disputed);
+
+        client.resolve_dispute(&id, &true);
+        let invoice = client.get_invoice(&id);
+        assert_eq!(invoice.status, InvoiceStatus::Released);
+    }
+
+    #[test]
+    fn test_dispute_release_and_resolve_refund() {
+        let (env, client) = setup();
+        let creator = Address::generate(&env);
+        let payer = Address::generate(&env);
+        let recipient = Address::generate(&env);
+
+        let (id, _) = create_escrow_invoice(&env, &client, &creator, &payer, &recipient, None);
+
+        client.pay(&payer, &id, &500i128);
+        client.dispute_release(&id);
+
+        client.resolve_dispute(&id, &false);
+        let invoice = client.get_invoice(&id);
+        assert_eq!(invoice.status, InvoiceStatus::Refunded);
+    }
+
+    #[test]
+    fn test_arbitrator_resolves_dispute() {
+        let (env, client) = setup();
+        let creator = Address::generate(&env);
+        let arbitrator = Address::generate(&env);
+        let payer = Address::generate(&env);
+        let recipient = Address::generate(&env);
+
+        let (id, _) = create_escrow_invoice(&env, &client, &creator, &payer, &recipient, Some(arbitrator.clone()));
+
+        let invoice = client.get_invoice(&id);
+        assert_eq!(invoice.arbitrator, Some(arbitrator.clone()));
+
+        client.pay(&payer, &id, &500i128);
+        client.dispute_release(&id);
+
+        client.resolve_dispute(&id, &true);
+        let invoice = client.get_invoice(&id);
+        assert_eq!(invoice.status, InvoiceStatus::Released);
+    }
+
+    #[test]
+    #[should_panic]
+    fn test_release_escrow_rejects_disputed() {
+        let (env, client) = setup();
+        let creator = Address::generate(&env);
+        let payer = Address::generate(&env);
+        let recipient = Address::generate(&env);
+
+        let (id, _) = create_escrow_invoice(&env, &client, &creator, &payer, &recipient, None);
+
+        client.pay(&payer, &id, &500i128);
+        client.dispute_release(&id);
+
+        env.ledger().set_timestamp(env.ledger().timestamp() + 7200);
+
+        client.release_escrow(&id);
+    }
 }

contracts/sharpy/src/types.rs

@@ -73,13 +73,22 @@ pub struct InvoicePayment {
     pub amount: i128,
 }
 
+#[contracttype]
+#[derive(Clone, Debug)]
+pub struct DisputeState {
+    pub release_at: u64,
+    pub disputed: bool,
+    pub disputed_at: u64,
+}
+
 #[contracttype]
 #[derive(Clone, Debug)]
 pub struct InvoiceOptions {
     pub escrow_enabled: bool,
     pub escrow_release_delay: Option<u64>,
     pub split_rules: Vec<SplitRule>,
     pub auto_resolve_rules: Vec<ResolveRule>,
+    pub arbitrator: Option<Address>,
 }
 
 #[contracttype]
@@ -110,4 +119,5 @@ pub struct Invoice {
     pub escrow_release_delay: u64,
     pub split_rules: Vec<SplitRule>,
     pub auto_resolve_rules: Vec<ResolveRule>,
+    pub arbitrator: Option<Address>,
 }