feat: Implement merchant escrow receipt functionality with tests

contracts/escrow/src/integration_tests.rs

@@ -558,3 +558,75 @@ fn test_release_eligibility_terminal_refund_blocks_release() {
     assert!(!re.eligible);
     assert_eq!(re.reason, soroban_sdk::symbol_short!("refunded"));
 }
+
+// ── MerchantEscrowReceipt getter tests ─────────────────────────────────────
+
+#[test]
+fn test_merchant_escrow_receipt_funded() {
+    let t = TestEnv::setup();
+    let client = EscrowContractClient::new(&t.env, &t.escrow_contract_id);
+    let eid = deposit_escrow(&t, 1000, 100);
+
+    let receipt = client.get_merchant_escrow_receipt(&eid);
+    assert_eq!(receipt.escrow_id, t.order_id());
+    assert_eq!(receipt.merchant, t.seller);
+    assert_eq!(receipt.buyer, t.buyer);
+    assert_eq!(receipt.status, EscrowStatus::Funded);
+    assert!(receipt.release_eligible);
+}
+
+#[test]
+fn test_merchant_escrow_receipt_disputed() {
+    let t = TestEnv::setup();
+    let client = EscrowContractClient::new(&t.env, &t.escrow_contract_id);
+    let eid = deposit_escrow(&t, 1000, 100);
+    client.dispute(&eid, &t.buyer);
+
+    let receipt = client.get_merchant_escrow_receipt(&eid);
+    assert_eq!(receipt.escrow_id, t.order_id());
+    assert_eq!(receipt.merchant, t.seller);
+    assert_eq!(receipt.buyer, t.buyer);
+    assert_eq!(receipt.status, EscrowStatus::Disputed);
+    assert!(!receipt.release_eligible);
+}
+
+#[test]
+fn test_merchant_escrow_receipt_released() {
+    let t = TestEnv::setup();
+    let client = EscrowContractClient::new(&t.env, &t.escrow_contract_id);
+    let eid = deposit_escrow(&t, 1000, 100);
+    client.release(&eid, &t.buyer);
+
+    let receipt = client.get_merchant_escrow_receipt(&eid);
+    assert_eq!(receipt.escrow_id, t.order_id());
+    assert_eq!(receipt.merchant, t.seller);
+    assert_eq!(receipt.buyer, t.buyer);
+    assert_eq!(receipt.status, EscrowStatus::Released);
+    assert!(!receipt.release_eligible);
+}
+
+#[test]
+fn test_merchant_escrow_receipt_refunded() {
+    let t = TestEnv::setup();
+    let client = EscrowContractClient::new(&t.env, &t.escrow_contract_id);
+    let eid = deposit_escrow(&t, 1000, 100);
+    client.refund(&eid, &t.seller);
+
+    let receipt = client.get_merchant_escrow_receipt(&eid);
+    assert_eq!(receipt.escrow_id, t.order_id());
+    assert_eq!(receipt.merchant, t.seller);
+    assert_eq!(receipt.buyer, t.buyer);
+    assert_eq!(receipt.status, EscrowStatus::Refunded);
+    assert!(!receipt.release_eligible);
+}
+
+#[test]
+fn test_merchant_escrow_receipt_not_found() {
+    let t = TestEnv::setup();
+    let client = EscrowContractClient::new(&t.env, &t.escrow_contract_id);
+
+    assert_eq!(
+        client.try_get_merchant_escrow_receipt(&999u64),
+        Err(Ok(EscrowError::NotFound))
+    );
+}

contracts/escrow/src/lib.rs

@@ -238,6 +238,20 @@ pub struct ReleaseEligibility {
     pub reason: Symbol,
 }
 
+/// Merchant-facing escrow receipt returned by `get_merchant_escrow_receipt`.
+///
+/// `escrow_id` mirrors the escrow record's 32-byte order id so merchant
+/// dashboards can correlate the read-only response with their backend order.
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct MerchantEscrowReceipt {
+    pub escrow_id: BytesN<32>,
+    pub merchant: Address,
+    pub buyer: Address,
+    pub status: EscrowStatus,
+    pub release_eligible: bool,
+}
+
 #[contract]
 pub struct EscrowContract;
 
@@ -911,6 +925,32 @@ impl EscrowContract {
         }
     }
 
+    /// Read-only merchant receipt for dashboards and settlement checks.
+    ///
+    /// `release_eligible` is derived from escrow status and timeout without
+    /// mutating contract state. Returns `NotFound` when the escrow does not exist.
+    pub fn get_merchant_escrow_receipt(
+        env: Env,
+        escrow_id: u64,
+    ) -> Result<MerchantEscrowReceipt, EscrowError> {
+        let key = DataKey::Escrow(escrow_id);
+        let record: EscrowRecord = env
+            .storage()
+            .persistent()
+            .get(&key)
+            .ok_or(EscrowError::NotFound)?;
+
+        let release_eligible = Self::release_block_reason(env, &record).is_none();
+
+        Ok(MerchantEscrowReceipt {
+            escrow_id: record.order_id,
+            merchant: record.seller,
+            buyer: record.buyer,
+            status: record.status,
+            release_eligible,
+        })
+    }
+
     /// Read-only getter for escrow state.
     pub fn get_escrow(env: Env, escrow_id: u64) -> EscrowRecord {
         let key = DataKey::Escrow(escrow_id);