Data & Queries] Soroban: Read APIs for invoice payment status (Medium, 150 points)

[Cedarich]

Description

Add view methods to the Soroban contract so clients can query payment information for a given invoice ID or list recent payments, complementing event-based indexing.

Requirements and Context

• Events are great for streaming, but some clients need direct queries.
• The current contract may only emit events without stored state.
• Done means:
  • View functions exist to:
    • Get payment info by invoice_id.
    • Optionally list payments for a given payer or recent history.

Suggested Execution

• Extend the Soroban contract:
  • Add storage mapping from invoice_id to a payment record.
  • Implement a view method like get_payment(invoice_id) returning a struct.
• Ensure:
  • Reads are cheap and don’t mutate state.
  • The data model aligns with the backend’s expectations.

Test and Commit

• After recording a payment:
  • Call get_payment(invoice_id) via the Soroban CLI.
  • Confirm the data returned matches what was recorded.
• Include in your PR:
  • Command examples to query payment status.
  • Sample outputs for successful lookups and not-found cases.

Example Commit Message

• feat(contracts): add soroban view apis for invoice payment status

Guidelines

• Complexity: Medium (150 points) — adds state and read methods, but limited surface area.
• Handle non-existent invoices gracefully (e.g. return null/empty or a descriptive error).
• Keep the storage layout simple and well-documented.
• Reference this issue in your PR description (Closes #<issue_id>).

---

[caxtonacollins]

Hi 👋 am a full-stack developer
I will love to work on this issue please assign

[JuliobaCR]

Hi ZyntariHQ team,

I'm Julio, a Full Stack Developer with hands-on experience building smart contracts on Stellar/Soroban, and I’d like to take ownership of this issue.

The distinction between event-based and query-based access patterns is key here. While events are excellent for indexing and off-chain processing, direct view functions are essential for clients that need to fetch current state deterministically without replaying historical data.

My approach would be to extend the contract’s storage model to support efficient lookups by invoice_id, ensuring the view function remains read only, side effect free, and cost efficient. The implementation would also handle the not-found case gracefully, returning a clear optional response rather than failing, so clients can reliably distinguish between paid and unpaid invoices.

Regarding the optional listing by payer, I would evaluate the trade offs in storage cost versus query efficiency based on the current contract model and document the architectural decision clearly in the PR.

The delivery would include tests, CLI usage examples, and sample outputs for both success and not-found scenarios as requested.

Estimated time of completion: 1 day, including validation and full PR documentation.

I’m comfortable working independently and delivering a clean, production ready implementation aligned with the contract’s design principles.
Looking forward to contributing to ZyntariHQ. Thank you for your consideration.

[diegoTech14]

Hey, I'd like to take this one.
I have 3 years of software engineering experience, including a year working on API integrations. I'm comfortable with Rust/Soroban contract development and familiar with the storage patterns needed here — mapping invoice IDs to payment records and exposing read-only view methods.
My plan:
Add a PaymentRecord struct and a Map<invoice_id, PaymentRecord> in contract storage
Implement get_payment(invoice_id) returning Option for graceful not-found handling
Optionally add list_payments_by_payer(payer_address) using an index map
Include CLI query examples and sample outputs in the PR
Should be straightforward to keep reads cheap with env.storage().persistent().get(). Let me know if there are any constraints on the storage tier (instance vs persistent) or the existing data model I should align with.