Arkade payout: accept on-chain + LN destinations (auto-route by type)

[Kukks]

Context

Today ArkPayoutHandler.ParseClaimDestination (BTCPayServer.Plugins.ArkPayServer/Payouts/Ark/ArkPayoutHandler.cs:96-117) accepts exactly two destination shapes:

• A bare ArkAddress (tark1...)
• A bitcoin: URI (wrapped as ArkUriClaimDestination)

Anything else — a bare on-chain address (bc1…, bcrt1…, etc.), a BOLT11 invoice (lnbc…), or an LNURL — is rejected with "A valid address was not provided". Operators that want to pay those destinations have to fall back to the BTC-CHAIN or BTC-LN payout methods explicitly, which fragments the "Arkade balance pays things" mental model.

The plugin already has the underlying primitives wired up for the Send wizard:

• VTXO → on-chain: batch-settle to an on-chain output, or chain swap via Boltz
• VTXO → Lightning: submarine swap via Boltz

So the gap is at the payout-handler layer, not the protocol layer.

Proposal

Let the Arkade payout method auto-detect the destination type:

Destination	Route
tark1… (Ark address)	VTXO → VTXO (current behaviour)
bitcoin: URI with ark=	VTXO → VTXO (current behaviour)
bitcoin: URI without ark=	VTXO → on-chain (chain swap or batch on-chain output)
Bare on-chain address	VTXO → on-chain (same as above)
lnbc… (BOLT11)	VTXO → LN (Boltz submarine swap)
LNURL-pay	resolve to BOLT11, then route as LN

Single payout method, dispatch happens inside InitiatePayment based on the parsed claim destination.

Tradeoffs / open questions

1. Failure-mode opacity. Each route has very different latency and failure characteristics:

   • VTXO → VTXO: instant, near-bulletproof
   • VTXO → on-chain: ~10s batch wait, or minutes via Boltz chain swap (depends on Boltz limits + arkd batch session)
   • VTXO → LN: depends on Boltz availability, swap limits, and the LN route

   A payout that "just hangs" because we silently fell back across tiers will be hard to debug. We probably need explicit status messages per route (e.g. "Awaiting batch settle", "Boltz swap pending", "LN settling").

2. Min/max amount constraints differ per route. Boltz swaps have configured min/max; arkd batch settle has its own dust threshold; LN has its own. GetMinimumPayoutAmount currently returns the arkd dust value — would need to be route-aware (or just return the loosest minimum and validate later).

3. Fees differ per route. Today the payout proof is ArkPayoutProof (TransactionId). A chain-swap or LN payout would have a different "proof" — swap id, preimage, or final on-chain txid. The proof model probably needs to be a discriminated union, or a base type with route-specific subclasses.

4. Refund semantics for failed swaps. If a Boltz submarine swap fails after our VTXO is locked into the HTLC, the cooperative-refund path needs to be triggered automatically (or surfaced to the operator). The plugin already has SwapsManagementService.RequestRefundCooperatively — needs to be tied into payout cancellation/reject.

5. Alternative scope: keep payout strict (Ark address only) and instead document that operators should pick BTC-LN / BTC-CHAIN explicitly for non-Ark destinations. Less elegant UX but the dispatch + failure-mapping problem disappears.

Acceptance criteria (sketch)

• ArkPayoutHandler.ParseClaimDestination recognises bare on-chain addresses + BOLT11 invoices (and optionally LNURL).
• InitiatePayment dispatches each destination type to the appropriate Send/Swap flow rather than always redirecting to the offchain Send wizard.
• ArkPayoutProof is extended (or split) so the proof reflects the route actually taken (offchain txid / on-chain txid / swap id + preimage).
• GetMinimumPayoutAmount is route-aware.
• Failed swaps trigger cooperative refund automatically.
• UI surfaces the route + current status per payout (not a generic "Awaiting payment").
• Existing Ark-address-only payouts keep working with the same proof shape (no migration of historical payout rows).

Out of scope

• Cross-asset payouts (Arkade asset balance → BTC destination). Same hatch but different problem.
• Boarding-input-only payouts (paying into a boarding address from an external wallet — that's the inverse of what we're doing here).

[arkanaai]

Codebase Context

The routing infrastructure for VTXO→LN is already partially wired — the gap is at the payout-handler boundary, not the spend layer.

What already exists

ArkadeSpendingService.Spend() (Services/ArkadeSpendingService.cs:25) handles:

• BOLT11 (line 40–68): detects lightning: prefix or bare lnbc... via BOLT11PaymentRequest.TryParse, delegates to ArkLightningClient.Pay().
• bitcoin: URI with Ark address (line 70–106): detects ark= query param or Ark address in the URI host, calls arkadeSpender.Spend() with ArkTxOutType.Vtxo.

ArkPayoutHandler.ParseClaimDestination() (Payouts/Ark/ArkPayoutHandler.cs:96–117) only accepts:

• bitcoin: URIs → ArkUriClaimDestination
• Bare Ark addresses → ArkAddressClaimDestination

Everything else falls through to the catch-all and returns "A valid address was not provided". BOLT11 strings and bare on-chain addresses never reach ArkadeSpendingService.

Implementation gap summary

Destination	ParseClaimDestination	ArkadeSpendingService.Spend	Status
Ark address	✅	✅	Working
bitcoin: URI with ark=	✅	✅	Working
BOLT11 (lnbc...)	❌ rejected	✅ (line 40–68)	Wire up ParseClaimDestination
Bare on-chain address	❌ rejected	❌ (throws MalformedPaymentDestination at line 108)	Both layers need work
bitcoin: URI without ark=	❌ rejected	❌	Both layers need work
LNURL	❌ rejected	❌	Both layers need work

Note on SwapsManagementService.RequestRefundCooperatively

This class/method does not exist in the current plugin codebase — it may need to be built as part of this feature (or it lives in the NArk SDK and needs to be surfaced here). The cooperative-refund path for failed Boltz swaps is the riskiest part of this feature from a fund-safety perspective.

Related open PRs

• PR feat: Greenfield REST API for Arkade wallet operations #42 (feat: Greenfield REST API) — includes POST /send that delegates to ArkadeSpendingService.Spend(). If BOLT11 + on-chain routing is added to Spend(), it will automatically benefit the REST API as well; no parallel plumbing needed.
• PR feat(assets): Arkade asset management + dedicated Arkade Asset payment method #55 (feat(assets): Arkade asset payment method) — extends the settlement proof model. Worth coordinating the ArkPayoutProof discriminated-union change described in tradeoff Add initial db migration #3 here with the work already in progress there.

Suggested implementation order

1. Add a LnClaimDestination (wrapping the decoded BOLT11PaymentRequest) and extend ParseClaimDestination to recognise bare BOLT11 + lightning: URIs — unlocks LN payouts immediately since ArkadeSpendingService already supports the spend side.
2. Add bare on-chain + bitcoin: (no ark=) support to both ParseClaimDestination and ArkadeSpendingService.Spend() (Boltz chain-swap path).
3. Handle cooperative-refund wiring for failed swaps before marking on-chain route complete.
4. Extend ArkPayoutProof to a discriminated union (tradeoff Add initial db migration #3) — this is a proof-model migration, so co-ordinate with PR feat(assets): Arkade asset management + dedicated Arkade Asset payment method #55.