feat: Implement merchant escrow receipt functionality with tests

[steph-crown]

Summary by CodeRabbit

• New Features

  • Added a merchant-facing escrow receipt view showing escrow ID, buyer, seller, current status, and whether release is currently allowed.
  • The receipt can now be retrieved directly for an escrow record, with a clear not-found response for missing records.

• Tests

  • Added broad test coverage for receipt output across funded, disputed, released, and refunded escrow states, plus missing-record handling.

Resolves #171

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new MerchantEscrowReceipt struct and get_merchant_escrow_receipt contract method that returns escrow order details and a computed release_eligible flag for a given escrow id. Integration tests cover all escrow states (Funded, Disputed, Released, Refunded) and the NotFound error path, with deterministic JSON snapshots for each scenario.

Changes

MerchantEscrowReceipt getter and test coverage

Layer / File(s)	Summary
MerchantEscrowReceipt struct and getter method contracts/escrow/src/lib.rs	Defines MerchantEscrowReceipt as a #[contracttype] struct with order_id, merchant, buyer, status, and release_eligible. Adds get_merchant_escrow_receipt which loads the escrow record, computes release_eligible via release_block_reason(...).is_none(), and returns EscrowError::NotFound when absent.
Integration tests for all receipt states contracts/escrow/src/integration_tests.rs	Adds tests validating get_merchant_escrow_receipt output fields for Funded, Disputed, Released, and Refunded states, plus a try_get_merchant_escrow_receipt test for the NotFound path.
Test snapshots for MerchantEscrowReceipt scenarios contracts/escrow/test_snapshots/integration_tests/test_merchant_escrow_receipt_*.1.json	Adds five deterministic JSON snapshots recording auth/invocation traces and expected ledger state for each merchant receipt test scenario.
Test snapshots for refund eligibility scenarios contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_*.1.json	Adds deterministic JSON snapshots for all refund eligibility scenarios: admin, seller, buyer before/after timeout, disputed, unauthorized stranger, already released, already refunded, and not-found.
Unit test snapshots contracts/escrow/test_snapshots/test/test/test_get_token_not_found.1.json, ...test_set_create_paused_success.1.json, ...test_set_create_paused_unauthorized.1.json	Adds snapshots for the get_token_not_found, set_create_paused_success, and set_create_paused_unauthorized unit test scenarios.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• [Soroban/Escrow] Add Merchant-Facing Escrow Receipt Getter #171: This PR implements the merchant-facing escrow receipt getter and its integration tests/snapshots described in that issue.

Possibly related PRs

• DelegoLabs/Delego#144: The new MerchantEscrowReceipt getter depends on EscrowStatus variants and escrow record fields introduced/shaped in this PR.
• DelegoLabs/Delego#267: The get_merchant_escrow_receipt method reuses the same release_block_reason eligibility logic introduced in this PR for get_release_eligibility.

Poem

🐇 Hop hop, a receipt appears,
The merchant checks their escrow with cheer!
Funded, released, disputed, refunded too,
Each snapshot pinned with fields held true.
release_eligible blooms, no reason to block—
This bunny approves the new getter clock! 🕐

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the new merchant escrow receipt feature and its accompanying tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

contracts/escrow/src/integration_tests.rs (1)

564-576: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a timed-out funded case for release_eligible.

This suite only proves release_eligible = false after status transitions. The new getter also returns false for escrows that are still Funded once timeout_ledger is reached, so the timeout branch behind release_block_reason(...) is still untested.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@contracts/escrow/src/integration_tests.rs` around lines 564 - 576, The funded
receipt test does not cover the timeout-driven false case for release
eligibility. Update test_merchant_escrow_receipt_funded in integration_tests.rs
to advance the ledger/time past timeout_ledger before calling
EscrowContractClient::get_merchant_escrow_receipt, then assert that
receipt.status remains EscrowStatus::Funded while receipt.release_eligible
becomes false. This should exercise the release_block_reason timeout branch
without changing the existing status-transition coverage.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@contracts/escrow/src/integration_tests.rs`:
- Around line 564-576: The funded receipt test does not cover the timeout-driven
false case for release eligibility. Update test_merchant_escrow_receipt_funded
in integration_tests.rs to advance the ledger/time past timeout_ledger before
calling EscrowContractClient::get_merchant_escrow_receipt, then assert that
receipt.status remains EscrowStatus::Funded while receipt.release_eligible
becomes false. This should exercise the release_block_reason timeout branch
without changing the existing status-transition coverage.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5aa2a3d2-7fb0-4163-8f64-af41a0848776

📥 Commits

Reviewing files that changed from the base of the PR and between 6d6168c and 31220fe.

📒 Files selected for processing (19)

• contracts/escrow/src/integration_tests.rs
• contracts/escrow/src/lib.rs
• contracts/escrow/test_snapshots/integration_tests/test_merchant_escrow_receipt_disputed.1.json
• contracts/escrow/test_snapshots/integration_tests/test_merchant_escrow_receipt_funded.1.json
• contracts/escrow/test_snapshots/integration_tests/test_merchant_escrow_receipt_not_found.1.json
• contracts/escrow/test_snapshots/integration_tests/test_merchant_escrow_receipt_refunded.1.json
• contracts/escrow/test_snapshots/integration_tests/test_merchant_escrow_receipt_released.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_admin_always_eligible.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_already_refunded.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_already_released.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_buyer_after_timeout.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_buyer_before_timeout.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_disputed.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_not_found.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_seller_always_eligible.1.json
• contracts/escrow/test_snapshots/integration_tests/test_refund_eligibility_unauthorized_stranger.1.json
• contracts/escrow/test_snapshots/test/test/test_get_token_not_found.1.json
• contracts/escrow/test_snapshots/test/test/test_set_create_paused_success.1.json
• contracts/escrow/test_snapshots/test/test/test_set_create_paused_unauthorized.1.json

[drips-wave]

@steph-crown 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

[ScriptedBro]

Please resolve conflicts