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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions