Description
Priority
P1
Type / Area
feature, soroban, contracts
Suggested Complexity
High
Summary
Build a complete multi-party escrow contract supporting a buyer, seller, and optional arbitrator, with a full dispute-resolution flow that allows either party to raise a dispute and the arbitrator to split the escrowed funds at any ratio.
Problem
The existing escrow contract (contracts/escrow/) handles basic lock/release but has no dispute mechanism — if buyer and seller disagree, funds are permanently stuck. There is no arbitrator role, no dispute-raised state, no partial-release logic, and no time-based auto-release if no dispute is raised within a window. This is a real product gap that any payments application needs to handle.
Scope
In Scope
New crate: contracts/escrow-v2/ (separate from existing escrow to avoid breaking changes)
Roles: buyer (depositor), seller (recipient), arbitrator (optional third party set at creation)
States: Funded → Released / Disputed → Resolved
Function: fund_escrow — buyer deposits funds, sets seller, arbitrator, auto-release window
Function: release — buyer confirms delivery; releases full amount to seller
Function: raise_dispute — either party raises a dispute before the auto-release window closes; transitions to Disputed state
Function: resolve_dispute — arbitrator only; splits funds between buyer and seller at any ratio (0-100% to either)
Function: auto_release — callable by anyone after the window expires with no dispute; releases to seller
Full test coverage of all state transitions including invalid ones (e.g. releasing after dispute raised must fail)
Out of Scope
On-chain arbitrator selection / reputation system
Multi-asset escrow (single asset per escrow instance)
Files
contracts/escrow-v2/src/lib.rs (new) contracts/escrow-v2/src/types.rs (new) contracts/escrow-v2/src/storage.rs (new) contracts/escrow-v2/src/validation.rs (new) contracts/escrow-v2/src/test.rs (new) contracts/escrow-v2/Cargo.toml (new)
Acceptance Criteria
All four state transitions implemented and tested (Funded → Released, Funded → Disputed, Disputed → Resolved, auto-release)
Invalid transitions explicitly rejected (e.g. resolve before dispute raised, release after dispute raised)
Arbitrator split ratio validated (buyer_bps + seller_bps must equal 10000)
Unauthorized callers cannot trigger any state transition
Auto-release cannot be called before the window expires
cargo test -p escrow-v2 passes
How to Test
cargo test -p escrow-v2
Test each state machine path independently. Verify arbitrator cannot claim funds for themselves (ratio must sum to 10000 between buyer and seller only).
PR Requirements
CI checks must pass
cargo test passes
Include screenshots of test results
Link issue using Closes #ISSUE_NUMBER
Project Links
Repository: https://github.com/stellarspend/stellarspend-contracts Community: https://t.me/+7RpAgpVggOphNzJk
Description
Priority
P1
Type / Area
feature, soroban, contracts
Suggested Complexity
High
Summary
Build a complete multi-party escrow contract supporting a buyer, seller, and optional arbitrator, with a full dispute-resolution flow that allows either party to raise a dispute and the arbitrator to split the escrowed funds at any ratio.
Problem
The existing escrow contract (contracts/escrow/) handles basic lock/release but has no dispute mechanism — if buyer and seller disagree, funds are permanently stuck. There is no arbitrator role, no dispute-raised state, no partial-release logic, and no time-based auto-release if no dispute is raised within a window. This is a real product gap that any payments application needs to handle.
Scope
In Scope
New crate: contracts/escrow-v2/ (separate from existing escrow to avoid breaking changes)
Roles: buyer (depositor), seller (recipient), arbitrator (optional third party set at creation)
States: Funded → Released / Disputed → Resolved
Function: fund_escrow — buyer deposits funds, sets seller, arbitrator, auto-release window
Function: release — buyer confirms delivery; releases full amount to seller
Function: raise_dispute — either party raises a dispute before the auto-release window closes; transitions to Disputed state
Function: resolve_dispute — arbitrator only; splits funds between buyer and seller at any ratio (0-100% to either)
Function: auto_release — callable by anyone after the window expires with no dispute; releases to seller
Full test coverage of all state transitions including invalid ones (e.g. releasing after dispute raised must fail)
Out of Scope
On-chain arbitrator selection / reputation system
Multi-asset escrow (single asset per escrow instance)
Files
contracts/escrow-v2/src/lib.rs (new) contracts/escrow-v2/src/types.rs (new) contracts/escrow-v2/src/storage.rs (new) contracts/escrow-v2/src/validation.rs (new) contracts/escrow-v2/src/test.rs (new) contracts/escrow-v2/Cargo.toml (new)
Acceptance Criteria
All four state transitions implemented and tested (Funded → Released, Funded → Disputed, Disputed → Resolved, auto-release)
Invalid transitions explicitly rejected (e.g. resolve before dispute raised, release after dispute raised)
Arbitrator split ratio validated (buyer_bps + seller_bps must equal 10000)
Unauthorized callers cannot trigger any state transition
Auto-release cannot be called before the window expires
cargo test -p escrow-v2 passes
How to Test
cargo test -p escrow-v2
Test each state machine path independently. Verify arbitrator cannot claim funds for themselves (ratio must sum to 10000 between buyer and seller only).
PR Requirements
CI checks must pass
cargo test passes
Include screenshots of test results
Link issue using Closes #ISSUE_NUMBER
Project Links
Repository: https://github.com/stellarspend/stellarspend-contracts Community: https://t.me/+7RpAgpVggOphNzJk