feat(escrow): implement raise_dispute with event emission and timelin…

[BernardOnuh]

Closes #16 — Escrow Contract: Dispute Initiation Flow

Summary

Implements the raise_dispute function in the Soroban escrow contract, fulfilling all requirements outlined in Issue #5 / #16. This function provides a formal, secure, and auditable way for either party to initiate the arbitration phase.

---

Changes

contracts/escrow/src/lib.rs

• Added DisputeRaisedEvent struct (annotated with #[contracttype]) carrying Job ID, initiator address, milestone progress, and timestamp
• Implemented raise_dispute(env, job_id, caller) function with the following behaviour:
  • Authenticates caller strictly via env.require_auth()
  • Restricts invocation to the Payer (client) or Payee (freelancer) only — third parties are rejected
  • Asserts job is in Active state before allowing dispute
  • Guards against disputes when all funds are already released
  • Enforces a 7-day grace period past expires_at to prevent abuse on drastically expired jobs
  • Transitions escrow state to Disputed, immediately locking release_funds and release_milestone
  • Emits a DisputeRaised on-chain event under the ("escrow", "DisputeRaised") topic for the backend/AI Judge to consume

---

Tests Added

Test	Covers
test_raise_dispute_by_client_locks_funds	Client can raise dispute, status → Disputed
test_raise_dispute_by_freelancer_locks_funds	Freelancer can raise dispute, status → Disputed
test_raise_dispute_by_third_party_panics	Unauthorized address is rejected
test_raise_dispute_on_completed_job_panics	Dispute blocked after job completion
test_raise_dispute_blocks_release_funds	Standard fund release is blocked post-dispute
test_raise_dispute_then_resolve	Full dispute → admin resolution flow

All existing tests continue to pass.

---

Notes

• open_dispute is retained for backward compatibility. raise_dispute is the new canonical function satisfying the issue requirements (auth, event emission, deadline enforcement).
• The 7-day grace period after expires_at is configurable if the team prefers a different window.
• The DisputeRaised event is structured for easy consumption by the backend event listener that spins up the AI Agent Judge.

[drips-wave]

@BernardOnuh 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