feat: implement client migration functionality with proposal and acce…

[Oluwasuyi-Timilehin]

#closes #319

Summary

This PR adds secure client migration support to the contracts/escrow package.
The feature enables the current escrow client to propose a new client address and allows the proposed client to accept the migration later.
The pending migration proposal is stored in Soroban temporary storage with a TTL, so stale proposals automatically expire.

What changed

• Added PendingClientMigration and migration flow in contracts/escrow/src/migration.rs
  • propose_client_migration
  • accept_client_migration
  • has_pending_client_migration
  • get_pending_client_migration
• Integrated migration module in contracts/escrow/src/lib.rs
• Added tests covering the full migration lifecycle and edge cases in contracts/escrow/src/test/client_migration.rs
• Documented migration behavior in docs/escrow/migration.md

Behavior details

• propose_client_migration:

  • requires authorization from the current client
  • rejects if the proposed client is the current client or freelancer
  • rejects if the contract is completed, cancelled, refunded, or disputed
  • stores a pending migration request in temporary storage with TTL
  • emits client_migration_proposed

• accept_client_migration:

  • requires authorization from the proposed client
  • loads and validates a live pending migration record
  • rejects if the pending migration has expired or is missing
  • updates only EscrowContractData.client
  • removes the pending request from transient storage
  • emits client_migration_accepted

• TTL behavior ensures proposals cannot be accepted after expiry.

Tests

The following cases were added and validated:

• successful proposal and acceptance of client migration
• unauthorized accept attempt fails
• proposing the freelancer address is rejected
• accepting an expired pending migration is rejected
• proposing migration after contract completion is rejected

Validation

• cargo test in contracts/escrow passes with 36 passed; 0 failed

Files changed

• contracts/escrow/src/migration.rs
• contracts/escrow/src/lib.rs
• contracts/escrow/src/test/client_migration.rs
• docs/escrow/migration.md

Notes for reviewers

• Verify the authorization and status guard logic around migration proposal and acceptance.
• Confirm TTL-backed temporary storage semantics are used correctly for pending migration state.
• Review the new test setup for expired migration handling and Soroban ledger TTL compatibility.

#closes

[drips-wave]

@Oluwasuyi-Timilehin 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