Feat/escrow

[memplethee-lab]

Closes #259

Description

Adds a Soroban escrow-dispute contract for time-locked asset escrow and multisignature dispute resolution.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Performance improvement

Related Issue

Fixes #259
Not applicable.

Changes Made

Contract Changes

• Added the escrow-dispute Soroban contract and registered it in the Cargo workspace.
• Added escrow creation, buyer funding, cancellation, dispute, evidence, voting, resolution, and automatic refund workflows.
• Added persistent storage for escrows, disputes, evidence, votes, signers, thresholds, and idempotency nonces.
• Added trustline validation, token transfers, authorization checks, lifecycle validation, and structured Soroban events.

Tests

• Added 35 integration tests covering lifecycle flows, authorization, state transitions, voting, timelocks, evidence, and funds safety.

Documentation Changes

• Added contract API, error-code, event, deployment, security, and evidence-storage documentation.

Testing

Manual Testing

• Tested on localnet
• Tested on testnet
• Demo app tested
• SDK functionality verified

Automated Testing

• Rust tests pass (cargo test -p escrow-dispute)
• E2E tests pass (npm run test:e2e) — not applicable to this contract-only change
• Frontend build succeeds (npm run build) — not applicable to this contract-only change

Screenshots (if applicable)

Checklist

• Code follows project style guidelines
• Self-reviewed the code
• Updated documentation (README, API docs, etc.)
• No new warnings generated
• Added tests for new features
• All relevant tests passing
• Updated CHANGELOG if applicable

Deployment Notes

Build the WASM artifact with:

stellar contract build --path swaptrade-contracts/escrow-dispute

Deploy using the generated escrow_dispute.wasm and initialize the contract with the admin, signer set, threshold, and dispute window.

Additional Notes

This change does not modify the SDK or Demo App. Evidence documents remain off-chain; only their hashes and metadata are stored on-chain.