feat(referral): on-chain payout mode, batched into a single send-many tx

[v0l]

Fixes #184.

Summary

Adds an on-chain referral payout mode. The automated payout worker pays every eligible on-chain referrer in a single send-many transaction (one network fee for the whole batch, absorbed by us — each referrer receives their exact owed amount), so we never spend one fee per referrer. All payout rows produced by a batch share the broadcast txid.

Built on the new payments-rs 0.6.0 OnChainProvider::send_coins send-many API (published from v0l/payments-rs#2).

Changes

• DB: append-only ReferralPayoutMode::OnChain (3); new referral.onchain_address + referral_payout.txid columns (migration 20260723220303_referral_onchain_payout.sql).
• Settings: [referral].min-onchain-payout-sats — a separate, higher threshold (mempool-fee aware). None disables on-chain payouts (commission still accrues for manual admin payout).
• Worker / handler: threads the on-chain provider into ReferralPayoutHandler. Lightning/NWC payouts are unchanged and now skip on-chain referrers, which go through the new batched pass: reserve all → single send_coins → record the shared txid on every row; reservations are released if the send fails, so balances retry next run.
• API: user POST/PATCH /api/v1/referral accept onchain_address + mode: "on_chain"; the address is validated as mainnet (regtest also accepted in debug builds for the e2e/regtest stack). Referral returns onchain_address; ReferralPayout returns txid. Admin referral info exposes onchain_address; payout info exposes txid and it is settable on the payout PATCH.
• Docs: API_DOCUMENTATION.md, ADMIN_API_ENDPOINTS.md, API_CHANGELOG.md, config.yaml.

Fee handling

The network fee is absorbed by LNVPS (paid on top of the outputs), so each referrer receives their exact owed amount.

Tests

• payout_batch_request — one output per referrer, totals sum correctly.
• send_batch — single transaction, shared txid on every row, all rows paid; reservations released on send failure.
• validate_onchain_address — mainnet accepted, regtest only in debug builds, garbage/empty rejected.
• ReferralPayoutMode round-trip incl. on_chain.

Notes

• Touches payments — leaving for review rather than self-merging.
• payments-rs bumped 0.5.0 → 0.6.0.
• No automated e2e for the payout worker (needs a funded regtest on-chain wallet + interval trigger); batching logic is covered by unit tests against the mock provider.

[v0l]

Pushed a big round of revisions from review:

1. Single address field — merged lightning_address + onchain_address into one address (the mode already implies the type). Migration renames referral.lightning_address → address; API/admin expose one address; validation dispatches on the effective mode.

2. Precise outpoint — each payout now records its exact "{txid}:{vout}" (renamed txid → outpoint). A batch is one send-many tx; we decode the returned raw_tx (needs payments-rs 0.7.0, published — send_coins now returns the raw tx) and match each referrer's output script to its vout. Rows from one batch share the txid but carry distinct vouts.

3. Referrer bears the fee (LN + on-chain) — new referral_payout.fee, debited from their balance alongside amount, so a fee-induced deficit is recovered from future referrals (balance saturates at 0). LN fee from the pay_invoice result; on-chain fee = chosen sat/vByte × tx vsize, split proportionally across the batch.

4. mempool.space fee cap — before each on-chain batch we fetch the next-block rate from mempool.space and defer if it exceeds max-onchain-fee-per-vbyte (default 50), so we wait for cheap fees. min-onchain-payout-sats now defaults to 1000 (buffer for the fee); new mempool-url setting.

No further payments-rs changes needed (fee amount is computed locally from the decoded tx). Tests cover the proportional fee split and that each batched payout records a non-zero fee with the larger payout bearing more. Docs/config/changelog updated.

[v0l]

Addressed the fee-estimator + e2e feedback:

FeeEstimator trait — the on-chain fee-rate source is now behind a mockable FeeEstimator trait (fee_estimate.rs) instead of a hard-coded mempool.space call:

• MempoolFeeEstimator (prod) + FixedFeeEstimator (regtest/tests).
• Config [referral].fee-estimator = mempool{url} (default) or fixed{sat-per-vbyte}, replacing the raw mempool-url.
• The fee-rate cap check moved into send_batch, so the defer decision is now unit-tested (a >cap estimate reserves + broadcasts nothing), plus a wiremock test for the mempool parsing.

E2E payout coverage (in the lifecycle test) — a real referral payout run:

• switches the referrer (which already earned BTC commission from the referred VM) to on-chain, and seeds a 2nd on-chain + 1 Lightning referrer;
• triggers ProcessReferralPayouts and asserts both on-chain referrers are paid in one batched tx (shared txid, distinct vouts), each bearing a fee; the unresolvable Lightning referrer leaves no payout row (mixed isolation); and a re-run pays nothing new (idempotency).
• e2e config enables payouts with a fixed fee estimator (regtest has no mempool.space); new db/onchain helpers seed commission, read payouts, and derive regtest payout addresses.

Covers the requested paths: real payout with fee, re-run no-op, batch, and batch mixed with LN. No further payments-rs changes.