feat: Decentralized Dispute Escrow Splitting with Multi-Sig Arbitration (#76)

[robertocarlous]

Closes #85

Summary

Implements #76 — adds support for splitting escrowed dispute funds among multiple recipients according to negotiated percentage shares, gated by multi-sig arbitrator threshold signatures.

---

What was implemented

1. Fractional Split Parameters in Dispute Resolution

Added a new resolve_dispute_split entry point that accepts:

• task_id — must be in Disputed status
• recipients: Vec<Address> — non-empty list of payment recipients (creator, assignee, mediator, third parties, etc.)
• shares_bps: Vec<u32> — basis-point share per recipient (must sum to exactly 10000 = 100%)

Key invariant: recipients.len() == shares_bps.len() and sum(shares_bps) == 10000.

Fee handling: Platform fee is deducted from the total escrowed reward before proportional distribution. Each recipient receives (total - fee) * share_bps / 10000. The fee is transferred atomically to the fee_recipient. Integer truncation ensures the contract never over-pays.

Example with 1000 tokens, 10% fee, 40/30/30 split:

• Fee = 1000 x 1000 / 10000 = 100 -> fee_recipient
• Distributable = 900
• Recipient 1 (40%): 900 x 4000 / 10000 = 360
• Recipient 2 (30%): 900 x 3000 / 10000 = 270
• Recipient 3 (30%): 900 x 3000 / 10000 = 270

2. Multi-Sig Arbitrator Execution Handler

Extended MultisigAction with a new variant:

ResolveDisputeSplit(task_id: u32, recipients: Vec<Address>, shares_bps: Vec<u32>)

This allows arbitrator committees (configured via configure_multisig) to propose and vote on dispute resolutions. When the threshold number of signer approvals is reached, the split is executed atomically via apply_action.

• Proposals are validated at creation time (shares sum, recipient count, etc.)
• At execution time, approvals are re-checked against the current signer set
• Supports both auto-execute and manual-execute modes

3. Atomic Distribution with Correct Fees

All transfers happen in a single transaction:

1. Each recipient's payout is computed and transferred
2. Platform fee is transferred to fee_recipient
3. Escrow is released
4. Task status updated to Resolved
5. disp_splt event emitted for off-chain indexing

---

Files changed

File	Change
src/lib.rs	Added DisputeSplitRecipient, DisputeSplit types; resolve_dispute_split contract method and module-level function
src/multisig.rs	Added ResolveDisputeSplit variant to MultisigAction; validation and execution in apply_action
src/events.rs	Added emit_dispute_split_resolved event
src/test.rs	Added 6 new tests covering split payouts, validation, and multisig integration

---

Tests

Test	What it covers
test_dispute_split_three_way	3-way 40/30/30 split with 10% fee — verifies exact payout amounts
test_dispute_split_zero_fee	3-way 25/25/50 split with 0% fee — verifies full distribution
test_dispute_split_rejects_non_disputed	Rejects split on a task not in Disputed status
test_dispute_split_rejects_invalid_shares	Rejects when shares don't sum to 10000 bps
test_dispute_split_rejects_mismatched_lengths	Rejects when recipients and shares vectors differ in length
test_dispute_split_via_multisig_proposal	End-to-end: 2-of-3 multisig approval -> auto-execute -> funds distributed

All 84 tests pass. No warnings.

---

Acceptance Criteria

• Fractional split math checked against total balance
• Multi-sig arbitrator execution handler
• Tests covering split payouts