Skip to content

feat(verification): rebuild payment verification as a typed multi-step pipeline - #575

Open
woahwhattheheck wants to merge 5 commits into
Quittance-Labs:mainfrom
woahwhattheheck:latch/quittance-441-verify-pipeline
Open

woahwhattheheck wants to merge 5 commits into
Quittance-Labs:mainfrom
woahwhattheheck:latch/quittance-441-verify-pipeline

Conversation

@woahwhattheheck

@woahwhattheheck woahwhattheheck commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes #441. Rebuilds payment verification into an ordered multi-step pipeline with typed stage results shared by the API, payment monitor, and pay-page error mapping.

Pipeline

  1. fetch_transaction — hash/network/Horizon fetch, payment-op selection (incl. ambiguous / none)
  2. match_destination — seller match, including muxed M... destinations
  3. match_asset — code + issuer
  4. match_amount — zero-stroop window (AMOUNT_TOO_LOW / AMOUNT_TOO_HIGH / AMOUNT_MISMATCH)
  5. match_memo — text memo (+ MEMO_TYPE_MISMATCH)
  6. attribute — payer fields + required ledger close time
  7. persist_paid — atomic PAID transition (TX_HASH_ALREADY_USED, status races)

Hard failures short-circuit. Stage failures map onto the existing shared rejection codes (extended mapping only; no unnecessary new codes).

Done when

  • Manual verify and monitor call the same pipeline (executePaymentVerificationPipeline)
  • Stage failures covered by unit tests (fixtures per stage + full success)
  • Pay page still shows correct labels for amount, memo, and destination rejects (code → verify-rejection-label / VERIFICATION_MESSAGES; stage/code attached to VERIFY_FAILED)
  • No duplicate happy-path verify+persist implementations remain in handlers vs monitor

Test plan

  • npm --prefix backend run typecheck
  • npm --prefix frontend run typecheck
  • node --import tsx --test tests/payment-verification-pipeline.test.ts
  • node --import tsx --test tests/shared-verification-contract.test.ts tests/payment-verification.test.ts
  • node --import tsx --test tests/payment-monitor-runtime.test.ts tests/server-mvp-payment-monitor.test.ts tests/verify-cache.test.ts
  • npm --prefix frontend test (verification + rejection-label + payment-page-state)

Original contributor reward review

/claim #441

This is @woahwhattheheck's original contribution for issue #441. I affirmatively request review for any eligible GrantFox OSS contribution reward and confirmation of acceptance, reward allocation, payout method, and expected payment timing. The issue's “Maybe Rewarded” label does not establish any fixed amount or an awarded or received payment.

…line

Route manual verify and the payment monitor through one ordered pipeline
(fetch → destination → asset → amount → memo → attribute → persist PAID)
with shared stage results, rejection-code mapping, and stage-aware pay-page
errors. Closes Quittance-Labs#441.
@CemAyyildiz

Copy link
Copy Markdown
Collaborator

This branch now has merge conflicts with main (storage changes from #577 landed). Please rebase so CI can run against the current code.

Preserve the mandatory audit methods and adapter parity changes from Quittance-Labs#577 while keeping manual verification and the monitor on the shared pipeline.

Reject malformed hash and payer inputs before Horizon reads, with the shared stage-aware error envelope. Extend the existing payment-loop regression to verify the attribution stage.
Integrate main 282c75a while preserving the accepted c0c0f4c repair.

Retain incoming lifecycle and operational logging, map typed persistence conflicts in the shared pipeline, and carry stage/code metadata through the moved pay-page controller. Preserve the incoming hook, API wrappers, and both branches' existing regression source.

Source-only integration during the executor pause; runtime verification remains pending.

Operation: Q575-LATER-MAIN-INTEGRATION-20261004-A3DEA
Preserve the accepted stage/code production contract and update the existing VERIFY_FAILED assertion to include its optional-stage fallback and rejection code. This resolves the single controller expectation mismatch reported by current-head CI run 37180881850.

Source-only repair; no workflow dispatch or rerun and no local runtime execution.

Operation: Q575-CI-CONTROLLER-CONTRACT-20261004-A3DEA
Supply HTTP 404 at the SDK call boundary while retaining the real service and Horizon wrapper. Assert the requested hash and single attempt, and restore the server factory after the case.

Operation: Q575-HORIZON-404-BOUNDARY-20261004-A3DEA
@woahwhattheheck

Copy link
Copy Markdown
Contributor Author

Resolved the October 1 integration request. I updated the existing branch onto current main without force-pushing, retained the storage-contract changes from #577, and resolved the verification-pipeline conflicts in place. The PR is now mergeable at 71284d1968d64dd06a3aad12bc6c9e57ccbc26fc against current main@282c75ad933651a93b89a8412ab649b48714c739. Exact-head CI run 37183648276 completed successfully. The later follow-ups are limited to aligning the stage/code controller expectation and making the Horizon 404 regression deterministic at the SDK boundary. Ready for another review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Rebuild payment verification as a multi-step pipeline with typed stages

2 participants