Skip to content

feat: Add /onchain command to settle buyer payment on-chain (swap Lightning → on-chain) #797

@Matobi98

Description

@Matobi98

Summary

Allow the buyer to optionally request their payout in on-chain Bitcoin instead of Lightning, by issuing a /onchain command before the seller releases funds. The bot would perform a submarine swap (Lightning → on-chain) and charge an additional fee to cover swap costs.

Proposed UX Flow

  1. A buy or sell order reaches the WAITING_BUYER_INVOICE state (bot is waiting for the buyer to supply a Lightning invoice).
  2. Instead of sending a Lightning invoice, the buyer sends /onchain <bitcoin_address>.
  3. The bot validates the address (mainnet bech32 / p2pkh / p2sh).
  4. The bot replies with a fee breakdown and asks for confirmation:
⛓️ On-chain settlement requested

Amount:           100,000 sats
Swap fee:           1,500 sats (1.5%)
Network fee:          500 sats (estimated)
────────────────────────────
You will receive:  ~98,000 sats

Address: bc1q...xyz

Confirm? [Yes] [No]
  1. On confirmation, the order is flagged with onchain_payout: true and the address is stored.
  2. The rest of the flow is unchanged: seller pays the hold invoice → both parties confirm fiat → seller releases.
  3. At release, instead of paying a Lightning invoice, the bot performs a submarine swap (e.g. via Loop Out, Boltz, or a configured swap provider) and sends on-chain.
  4. The swap fee is recorded on the order and shown in the final receipt.

Data Model Changes

New fields added to the Order schema:

  • onchain_payout — boolean, flags the order for on-chain settlement
  • onchain_address — the destination Bitcoin address provided by the buyer
  • onchain_tx_id — the txid after the swap is broadcast
  • onchain_fee_sats — the actual swap fee charged, in satoshis

Fee Structure

Two new configurable environment variables:

Variable Description Default
ONCHAIN_SWAP_FEE_PERCENT Percentage of the order amount charged for the swap 0.015 (1.5%)
ONCHAIN_MIN_AMOUNT_SATS Minimum order size to allow on-chain settlement 10000

The existing MAX_FEE and community FEE_PERCENT are applied first. The swap fee is additive and shown separately in the breakdown.

New Command

/onchain <bitcoin_address>

  • Only available to the buyer of the order
  • Only valid while the order is in WAITING_BUYER_INVOICE status
  • Replaces the need to provide a Lightning invoice for that order
  • Disabled if the order amount is below ONCHAIN_MIN_AMOUNT_SATS

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions