feat(receipts): add ledger-anchored online verification alongside offline checks

[karagozemin]

Difficulty

Hard — production engineering across multiple components; a small cleanup or test-only patch does not complete this issue.

Context

docs/LIMITATIONS.md explicitly states that receipt verification is offline-only and does not establish that a receipt matches chain state. Keep offline verification intact and add an explicit online evidence mode.

Starting points

• docs/LIMITATIONS.md
• packages/sdk/src/verify.ts
• packages/sdk/src/receipt.ts
• services/receipt-cli/src/index.ts

Scope

• Introduce an online verifier binding a receipt to network, contract, ledger and transaction/event evidence.
• Cross-check commitments, bidder ordering, clearing outcome and settlement/refund evidence using paginated reads.
• Distinguish internally valid, chain-confirmed, unverifiable and contradictory results.
• Expose evidence metadata and deterministic CLI JSON/exit-code contracts.

Acceptance criteria

• A fabricated but internally consistent receipt cannot be labeled chain-confirmed.
• Network/contract mismatch, changed winner and omitted payout evidence fail with field-level reasons.
• Pruned ledger history and provider outage return unverifiable, not valid or fabricated evidence.
• Provider disagreement is visible; RPC agreement is not described as a cryptographic proof of consensus.
• Existing offline fixtures remain valid without requiring network access.

Verification

Exercise an injected ledger adapter with canonical, tampered, missing-history and contradictory-provider fixtures; add an opt-in read-only testnet integration test with recorded ledger references.

Out of scope

Changing settlement, storing private identities, or making paid/mainnet transactions during verification.

[Iker2522]

I am applying to take ownership of this issue.

I will implement ledger-anchored online receipt verification in Sub-Rosa-Issue / sub-rosa-issue.

I will enhance packages/sdk/src/verify.ts and services/receipt-cli to introduce online evidence verification while preserving existing offline verification workflows. The online verifier will cross-check receipt commitments, bidder ordering, clearing prices, and payout events against live chain state using paginated Soroban RPC queries. Verification outcomes will be categorized into chain-confirmed, internally-valid-only, unverifiable (e.g., pruned ledger/RPC outages), and contradictory (tampered or fabricated receipts), outputting field-level diagnostics and deterministic CLI exit codes.

I will also update docs/LIMITATIONS.md to document the new online verification guarantees and limitations.

I will verify the delivery using injected mock ledger adapters covering canonical, tampered, missing history, and split-RPC provider fixtures, alongside opt-in read-only testnet tests. PR ready in 48 hours. Closes #358.

[ZacLou]

I am a senior full-stack developer with 15+ years of experience. I have deep expertise in ledger systems, receipt verification, and building secure financial applications. I have implemented ledger-anchored verification, offline checks, and complex reconciliation systems in production. Ready to start immediately.

[Joyful12-tech]

Hello Maintainer! I'd like to work on this issue. I can deliver it following the requirements and submit a quality PR within 2 days. Thank you!

[ranjeet150]

Hello! I'd like to work on this issue.

I would love to take this on. My planned approach:

• Implement feat(receipts): add ledger-anchored online verification alongside offline checks with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.

Looking forward to contributing—please feel free to assign!

[guptakumarranjeet150]

Hi everyone,

I would love to take this on. My planned approach:

• Implement feat(receipts): add ledger-anchored online verification alongside offline checks with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.

Excited to work on this—please assign to me and I'll submit a clean PR shortly!