Feat/escrow milestone dispute

[Praizfotos]

Description

Adds a new escrow Soroban smart contract supporting milestone-based fund release and arbiter-mediated dispute resolution. Funds are locked on creation and released incrementally as the depositor approves each milestone. Either party can open a dispute, which freezes the escrow until the arbiter splits the remaining balance.

Fixes #(issue)

Type of Change

• New feature (non-breaking change which adds functionality)

Changes Made

• soroban-contract/contracts/escrow/Cargo.toml — new crate, mirrors workspace conventions
• soroban-contract/contracts/escrow/src/lib.rs — contract implementation:
  • initialize — one-time admin setup via upgradeable crate
  • create_escrow — pulls full sum from depositor, stores per-milestone amounts
  • approve_milestone — depositor releases a milestone's funds to recipient; auto-closes when all milestones done
  • open_dispute — depositor or recipient freezes escrow in Disputed state
  • resolve_dispute — arbiter splits remaining balance with configurable recipient_share
  • get_escrow — read-only query
  • Full upgrade/pause delegation to upgradeable crate
  • Events: EscrowCreated, MilestoneApproved, EscrowClosed, DisputeOpened, DisputeResolved
• soroban-contract/contracts/escrow/src/test.rs — 8 unit tests covering full lifecycle
• soroban-contract/Cargo.toml — contracts/escrow registered in workspace

Testing

• 8 unit tests written covering:
  • create_escrow transfers funds from depositor
  • approve_milestone releases correct amount to recipient
  • All milestones approved auto-closes escrow
  • Double-approve rejected
  • Open dispute blocks further milestone approvals
  • resolve_dispute correctly splits remaining balance
  • resolve_dispute fails when no dispute is open
  • Invalid recipient_share (exceeds remaining) rejected
• Integration test against deployed testnet contract (requires stellar contract deploy)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• My changes generate no new warnings
• No new dependencies added (reuses soroban-sdk and upgradeable from workspace)
• Auth checks on all state-mutating functions
• Events emitted for all state transitions

Additional Notes

• The arbiter address is set immutably at escrow creation — there is no arbiter rotation.
• recipient_share in resolve_dispute is an absolute amount (not a percentage), giving the arbiter full flexibility.
• Milestones are identified by zero-based index; off-chain descriptions should be stored by the client and referenced by index.

closes #246

[drips-wave]

@Praizfotos Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits