Companion tool

BTCPay integration

This project is a BTCPay companion, not a checkout replacement. It owns compose-time preflight; BTCPay Zcash plugin + backend own invoice creation, settlement, and payment detection.

Ownership boundary

Concern	Owner
Memo + transparent, amount, network, URI round-trip	This preflight tool
Create BTCPay invoice, detect payment, confirm settlement	BTCPay Zcash plugin + zkool / lightwalletd

Handoff export

Handoff v1 exports JSON with schema id btcpay-zec-helper.handoff/v1 (legacy stable id; npm package is zcash-invoice-preflight).

preflight.checks[] — same codes as CLI doctor
invoice.paymentRequestUri — validated ZIP-321 string
invoice.btcpayInvoiceId — null until plugin creates a real invoice
disclaimer + ownership — no fake settlement claims

Full schema: handoff-v1.json on GitHub

Detection adapter seam

The status lane on the desk uses MockDetectionAdapter by default. A ZkoolDetectionAdapter stub documents where real chain watching would plug in — out of scope for this demo, explicitly labeled in the UI.

Importable modules

Plugin authors can reuse checks without the POS UI:

import { preflightInvoice } from "zcash-invoice-preflight/preflight"
import { toBtcpayHandoff } from "zcash-invoice-preflight/handoff"
import { ensureAddressEngine } from "zcash-invoice-preflight/address"

await ensureAddressEngine()
const report = preflightInvoice({ address, amount, memo, network: "mainnet" })
const handoff = toBtcpayHandoff({
  id: "inv_demo",
  network: "mainnet",
  address,
  amount: report.payment?.amount,
  uri: report.uri,
  status: "unpaid",
  preflight: { ok: report.ok, checks: report.checks },
  meta: { chainWatch: false },
})

For maintainers

For BTCPay Zcash maintainers: versioned handoff JSON lets the plugin reuse the same preflight fail codes as the merchant desk. Compare these codes with what your stack enforces at invoice creation.

Export handoff on desk Reviewer guide