wownerogue/docs/PAYMENTS.md

Payments (P3)

The game no longer implements per-chain wallet/daemon code inline. It talks to pluggable payment providers behind one contract, so an operator routes each chain to whichever backend they run.

The contract

src/payments/providers/paymentProvider.js:

createInvoice({chain, amountAtomic, description, userId, orderId})
    → {invoiceId, address, uri, amountAtomic, expiresAt, raw}
getInvoiceStatus(ref)   → {status, complete, paidAtomic, confirmations, raw}
startWatch(ref, onUpdate, intervalMs)   /  stopWatch(ref)
sendPayout({chain, address, amountAtomic})  → {txids, raw}
validateAddress(chain, address)  → {valid}
supportsChain(chain)  → bool

PaymentProviderRegistry routes chain → providerId (operator-configurable) with a support-based fallback: if the routed provider can't serve a chain, any registered provider that can is used.

The providers

Provider	id	Serves	Notes
BTCPay Greenfield	btcpay	BTC, LTC	src/payments/providers/btcpayProvider.js — real BTCPay Server. Invoice priced in the chain's own crypto; address read from the invoice payment-methods; token auth.
xmrcheckout	xmrcheckout	XMR	Same class, different endpoint — the checkout app exposes a BTCPay-Greenfield-compatible shim.
wowcheckout	wowcheckout	WOW	Ditto (matched pair to xmrcheckout).
Native Monero	native-monero	XMR, WOW	src/payments/providers/nativeMoneroProvider.js — wraps the existing walletRPCService (subaddress invoicing + transfer_split payouts).

The key discovery: BTCPay, xmrcheckout, and wowcheckout all speak one Greenfield contract, so a single BTCPayProvider class (constructor-configurable id) serves all three — just registered at different endpoints. See the btcpay-infra-topology note for the operator's LAN endpoints.

Bootstrap & routing

buildProviderRegistry({env, walletService}) (src/payments/providers/index.js) is the single wiring seam:

• Native Monero/Wownero provider registers whenever a walletService exists.
• Each Greenfield gateway activates from its own env trio: BTCPAY_URL/_STORE_ID/_API_KEY (chains from BTCPAY_CHAINS, default BTC,LTC), XMRCHECKOUT_URL/_STORE_ID/_API_KEY (XMR), WOWCHECKOUT_URL/_STORE_ID/_API_KEY (WOW).
• Default routing: BTC/LTC → btcpay, XMR/WOW → their checkout gateway (else native). PAYMENT_ROUTING (CHAIN:provider,… or JSON) overrides any mapping.

Behavior-preserving: with no gateway env set (prod today), only the native provider registers and every chain routes to it — byte-for-byte the legacy flow.

The hot path

• Invoice creation — gameModeManager.createPaymentRequest calls getProvider(cryptoType).createInvoice(...). The native provider delegates to the same walletService.createPaymentRequest, so the subaddress and monitoring maps are identical to before.
• Monitoring — network/paymentHandlers._monitorAddress calls provider.startWatch. Native passes the raw wallet status straight through (legacy path unchanged); BTCPayProvider.getWalletStatus maps a Greenfield invoice to the same raw shape (Settled → confirmed+complete, Processing → in_mempool, paid/required amounts from payment-methods via ChainProfile decimals). The confirmation logic is extracted to _handlePaymentStatus, shared by native + gateway.
• Payouts stay native (the checkout apps are receive-only; XMR/WOW payouts remain on wallet-RPC).

Turning a gateway on

1. Mint a store API key in the gateway's admin (money infra — a human step).
2. Set the *_URL/_STORE_ID/_API_KEY env on the deploy host, using an address the host can actually reach (verify LAN reachability; a nebula/overlay IP may not route).
3. Restart. Invoices for that chain now create + confirm through the gateway; no code redeploy.

Money math

All amounts are atomic BigInt, decimals-parameterized via src/money/atomic.js (format, add, mulByDecimal, …) and src/chain/chainProfile.js (decimalsFor, atomicDivisor). Never floats. WOW = 11 decimals, XMR/BTC/LTC per their chain, GRIN = 9.

Files

src/payments/providers/paymentProvider.js      contract + registry
src/payments/providers/btcpayProvider.js        Greenfield client (btcpay / xmrcheckout / wowcheckout)
src/payments/providers/nativeMoneroProvider.js  wraps walletRPCService
src/payments/providers/index.js                 buildProviderRegistry (env → registry)
src/payments/walletRPCService.js                Monero/Wownero wallet-RPC
src/game/gameModeManager.js                     createPaymentRequest (invoice seam)
src/network/paymentHandlers.js                  _monitorAddress / _handlePaymentStatus (monitoring seam)