feat(contracts): dispute arbitration / resolver registry (#1040)

Escrow dispute resolution was admin-only (a single arbiter). Add a
standalone resolver-registry contract that decentralizes it into a set
of arbiters who vote on dispute outcomes.

- admin-managed arbiter set (add/remove) and configurable quorum
- per-escrow dispute cases with release/refund vote tallies and
  one-vote-per-arbiter enforcement
- on reaching quorum, a binding resolve_dispute cross-contract call is
  issued into the escrow (registry acts as the escrow's arbiter)
- 17 unit tests (incl. real escrow integration proving funds move) plus
  3 property/fuzz tests; builds for wasm32v1-none

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: vibenedict

contracts/Cargo.lock

@@ -10,6 +10,7 @@ members = [
   "contracts/zk-payment-verifier",
   "contracts/payment-channel",
   "contracts/contract-upgrade",
+  "contracts/resolver-registry",
 ]
 
 [workspace.dependencies]

contracts/Cargo.toml

@@ -27,6 +27,7 @@ contracts/
 │   ├── src/                     # SubscriptionRegistry contract source
 │   ├── agent-registry/          # Authorized agents registry contract
 │   ├── escrow/                  # Payment holding escrow contract
+│   ├── resolver-registry/       # Dispute arbitration / resolver registry
 │   ├── subscription_logging/    # On-chain audit trail logging contract
 │   ├── subscription_renewal/    # Main subscription renewal logic contract
 │   └── virtual-card/            # Non-custodial virtual card contract
@@ -132,12 +133,22 @@ cargo test
 - `record_log` - Appends a log entry (Reminder, Approval, Renewal, Failure, Retry, Cancellation).
 - `get_logs` - Query logs for a specific subscription.
 
+### 7. Resolver Registry Contract (`contracts/contracts/resolver-registry/`)
+**Purpose**: Decentralize escrow dispute resolution from a single admin arbiter to a voting set of arbiters. When a configurable quorum agrees on an outcome, the registry issues a binding `resolve_dispute` cross-contract call into the escrow. (Wire it up by setting the escrow's `arbiter` to the registry's contract address.)
+- `init` - Initialize with an admin and an initial quorum.
+- `add_arbiter` / `remove_arbiter` - Admin manages the arbiter voting set.
+- `set_quorum` - Admin adjusts the number of matching votes required to bind an outcome.
+- `open_case` - An arbiter or admin opens a dispute case bound to an escrow agreement.
+- `vote` - An arbiter votes to release (1) or refund (2); reaching quorum fires the binding escrow callback.
+- `get_case` / `get_case_count` / `get_quorum` / `get_arbiters` / `is_arbiter` / `get_vote` - Queries.
+
 ## Contract Development Roadmap
 
 ### Completed (MVP Stage)
 - [x] On-chain subscription registry and tracking
 - [x] Multi-agent renewal registry with scope controls
 - [x] Secure escrow agreements with arbiter-mediated dispute resolution
+- [x] Decentralized dispute arbitration via a quorum-voting resolver registry
 - [x] Non-custodial virtual cards with disposable/auto-close behavior
 - [x] On-chain audit logging system
 

contracts/README.md

@@ -0,0 +1,16 @@
+[package]
+name = "resolver-registry"
+version = "0.0.1"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib", "lib"]
+
+[dependencies]
+soroban-sdk = { workspace = true }
+
+[dev-dependencies]
+soroban-sdk = { workspace = true, features = ["testutils"] }
+proptest = { workspace = true }
+escrow = { path = "../escrow" }

contracts/contracts/resolver-registry/Cargo.toml

@@ -0,0 +1,130 @@
+#![cfg(test)]
+extern crate std;
+
+use escrow::{EscrowContract, EscrowContractClient, EscrowState};
+use proptest::prelude::*;
+use soroban_sdk::{
+    testutils::{Address as _, EnvTestConfig},
+    token::StellarAssetClient,
+    Address, Env, String,
+};
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::vec::Vec as StdVec;
+
+use super::{CaseStatus, ResolverRegistry, ResolverRegistryClient};
+
+const AMOUNT: i128 = 1_000_000_000;
+
+fn fuzz_env() -> Env {
+    Env::new_with_config(EnvTestConfig {
+        capture_snapshot_at_drop: false,
+        ..EnvTestConfig::default()
+    })
+}
+
+struct Ctx {
+    registry: ResolverRegistryClient<'static>,
+    escrow: EscrowContractClient<'static>,
+    arbiters: StdVec<Address>,
+}
+
+fn setup(quorum: u32, num_arbiters: usize) -> Ctx {
+    let env = fuzz_env();
+    env.mock_all_auths();
+
+    let admin = Address::generate(&env);
+    let payer = Address::generate(&env);
+    let payee = Address::generate(&env);
+
+    let registry_id = env.register(ResolverRegistry, ());
+    let registry = ResolverRegistryClient::new(&env, &registry_id);
+    registry.init(&admin, &quorum);
+
+    let mut arbiters = StdVec::new();
+    for _ in 0..num_arbiters {
+        let a = Address::generate(&env);
+        registry.add_arbiter(&a);
+        arbiters.push(a);
+    }
+
+    let escrow_id_addr = env.register(EscrowContract, ());
+    let escrow = EscrowContractClient::new(&env, &escrow_id_addr);
+    escrow.init(&admin);
+
+    let sac = env.register_stellar_asset_contract_v2(admin.clone());
+    let token = sac.address();
+    StellarAssetClient::new(&env, &token).mint(&payer, &(AMOUNT * 2));
+
+    let expiry = env.ledger().timestamp() + 86_400;
+    let desc = String::from_str(&env, "fuzz");
+    let id = escrow.create_escrow(&payer, &payee, &registry_id, &token, &AMOUNT, &expiry, &desc);
+    escrow.deposit(&id);
+    escrow.raise_dispute(&id, &payer);
+
+    Ctx {
+        registry,
+        escrow,
+        arbiters,
+    }
+}
+
+proptest! {
+    #![proptest_config(ProptestConfig::with_cases(12))]
+
+    /// Casting exactly `quorum` identical votes resolves the case to that
+    /// outcome and drives the real escrow into the matching terminal state.
+    #[test]
+    fn fuzz_quorum_resolves_escrow(
+        quorum in 1u32..=4u32,
+        outcome in 1u32..=2u32,
+    ) {
+        let n = quorum as usize + 1; // always enough arbiters to reach quorum
+        let ctx = setup(quorum, n);
+        // escrow_id is always 1 (single escrow per env).
+        let case = ctx.registry.open_case(&ctx.arbiters[0], &ctx.escrow.address, &1);
+
+        for i in 0..(quorum as usize) {
+            ctx.registry.vote(&ctx.arbiters[i], &case, &outcome);
+        }
+
+        let resolved = ctx.registry.get_case(&case);
+        prop_assert_eq!(resolved.status, CaseStatus::Resolved);
+        prop_assert_eq!(resolved.outcome, outcome);
+
+        let expected = if outcome == 1 { EscrowState::Released } else { EscrowState::Refunded };
+        prop_assert_eq!(ctx.escrow.get_escrow(&1).state, expected);
+    }
+
+    /// Fewer than `quorum` votes never resolves the case and never touches the
+    /// escrow, which stays disputed.
+    #[test]
+    fn fuzz_sub_quorum_never_resolves(
+        quorum in 2u32..=4u32,
+        outcome in 1u32..=2u32,
+    ) {
+        let n = quorum as usize + 1;
+        let ctx = setup(quorum, n);
+        let case = ctx.registry.open_case(&ctx.arbiters[0], &ctx.escrow.address, &1);
+
+        for i in 0..(quorum as usize - 1) {
+            ctx.registry.vote(&ctx.arbiters[i], &case, &outcome);
+        }
+
+        prop_assert_eq!(ctx.registry.get_case(&case).status, CaseStatus::Open);
+        prop_assert_eq!(ctx.escrow.get_escrow(&1).state, EscrowState::Disputed);
+    }
+
+    /// An arbiter can never double-vote regardless of ordering.
+    #[test]
+    fn fuzz_no_double_vote(outcome in 1u32..=2u32) {
+        let ctx = setup(3, 3);
+        let case = ctx.registry.open_case(&ctx.arbiters[0], &ctx.escrow.address, &1);
+        ctx.registry.vote(&ctx.arbiters[0], &case, &outcome);
+
+        let result = catch_unwind(AssertUnwindSafe(|| {
+            ctx.registry.vote(&ctx.arbiters[0], &case, &outcome);
+        }));
+        prop_assert!(result.is_err(), "double vote must panic");
+        prop_assert_eq!(ctx.registry.get_case(&case).votes_release + ctx.registry.get_case(&case).votes_refund, 1);
+    }
+}