[DeepDev69x3]

Summary

This PR defines and documents the complete Soroban payment_escrow contract lifecycle, backend retry semantics, and idempotency guarantees, fulfilling the requirements for issue #2026.

Closes #2026

Details of Changes

1. Lifecycle & Retry Specification (contracts/README.md):

   • Documented the contract state machine transitions (Locked -> Released / Refunded / Completed).
   • Defined terminal state finality and immutability: once Released (2), Refunded (3), or Completed (4), subsequent transitions return explicit error codes (AlreadyResolved BACKEND: Setup NestJS Backend with Essential Dependencies #2, AlreadyReleased folder #6, AlreadyRefunded Implement Clock-In Card Component #7).
   • Documented duplicate create semantics: why create explicitly returns Error::AlreadyExists (setup nestjs auth module using CLI #4) to prevent double-debiting payer tokens, rather than acting as a silent no-op.
   • Specified unconfirmed transaction reconciliation: why indeterminate submission outcomes query get_status for ground truth rather than blindly resubmitting.

2. Integration Test Suite (contracts/payment_escrow/tests/lifecycle_idempotency_test.rs):

   • duplicate_create_returns_already_exists_preventing_double_debit: Verifies duplicate create calls do not double-debit payer balances and return Error::AlreadyExists.
   • unconfirmed_transaction_reconciliation_via_get_status: Tests ground-truth reconciliation for confirmed vs unsubmitted/dropped transactions.
   • terminal_state_released_is_immutable_and_rejects_subsequent_transitions: Asserts that release, refund, release_partial, and refund_remaining on released escrows are rejected.
   • terminal_state_refunded_is_immutable_and_rejects_subsequent_transitions: Asserts immutability and rejection of further operations on refunded escrows.
   • terminal_state_completed_via_partial_releases_rejects_further_settlement: Verifies completion transitions and rejection of post-completion operations.
   • query_idempotency_get_status_is_read_only_and_deterministic: Asserts query repeatability and read-only behavior across ledger advances.

Verification & CI Proof

• cargo fmt --all -- --check: Passed
• cargo clippy --workspace --all-targets -- -D warnings: Passed (0 warnings)
• cargo test --workspace: 35/35 tests passing
• scripts/audit_require_auth.sh: 100% auth coverage passed

[vercel]

@DeepDev69x3 is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.