Payment Hold: authorize & capture demo (merchant + customer web views)

[tiero]

What

An end-to-end, serverless "authorize and capture" payment demo at covenants/payment-hold/regtest/typescript/ — gas-pump style: the customer taps to lock a hold in a covenant VTXO, the merchant captures the metered amount (change auto-returns), can void, and the customer can unilaterally reclaim after a CLTV timelock. The permissionless analog of Coinbase/Shopify's Commerce Payments AuthCaptureEscrow (path-by-path comparison table in the README).

Pieces

• SDK program artifact — contract/payment-hold.program.json: five paths (capture with the amount as a witness value, captureAll for full/sub-dust-change captures, void, customer-signed CLTV reclaim, CSV exit). Per-hold address uniqueness via an orderSalt in the capture covenant. The compiler's .ark sources + ContractJson artifact ship under contract/reference/ (reference only until Emit SDK Program JSON from compiled artifacts (bindgen sdk-program target) compiler#64 lands; contracts from Add payment hold contracts with authorize-and-capture flow compiler#66).
• JS lib — src/lib/: terms TLV codec (packet type 0x50 on the funding tx → restore from chain), hold lifecycle ops, and a watcher that classifies spends by matching the revealed tapleaf against the compiled program (SSE indexer subscription replaces processor webhooks).
• Web views — merchant terminal (merchant.html) and customer wallet (customer.html), vanilla TS + Vite, multi-page so the two roles are genuinely separate browser contexts. Handoff: BroadcastChannel → payment link/receipt → on-chain packet. Dev proxy handles CORS for arkd/emulator/esplora.
• Contract playground — playground/: compiles the reference .ark contracts to their artifact in-browser via the compiler's wasm-pack build (local pkg/ via playground/build.sh, hosted fallback).
• Smoke CI — .github/workflows/payment-hold-smoke.yml boots arkade-regtest and runs the full e2e on every PR touching this demo.
• Offline unit tests — 23 tests: program validation, JSON ↔ TS literal equality, address derivation cross-checked against a hand-built taproot tree + stability golden, spend-tx build shapes (witness encoding, reclaim nLockTime), spend classification.

Verification status

• ✅ pnpm test (23/23), tsc clean, pnpm build green, all three pages render.
• ✅ End-to-end on arkade-regtest, in CI — first run passed all 11 checks in 3m45s: address-derivation parity between the two parties (G1); covenant enforcement including both tamper rejections — a capture paying the merchant one sat more than the witnessed amount, and one routing the change back to the merchant, both refused by the co-signer (G2); partial capture 30k/20k with correct watcher classification and merchant balance; sub-dust change routed via captureAll; void; reclaim refused before the timelock and settled after it via the CLTV covenant path (G3); terms packet restored from the funding tx (G4).

🤖 Generated with Claude Code

https://claude.ai/code/session_01G9JEqcarRxL54WPaSyoFaR

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d84b3030-20c9-49a2-8913-c4982a6fff5f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch payment-hold-demo

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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