feat: Add /onchain command to settle buyer payment on-chain (swap Lightning → on-chain)
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 292
- Forks
- 136
- Avg merge
- 19m
- Merged PRs (30d)
- 1
Description
## 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 `.
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]
```
5. On confirmation, the order is flagged with `onchain_payout: true` and the address is stored.
6. The rest of the flow is unchanged: seller pays the hold invoice → both parties confirm fiat → seller releases.
7. 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.
8. 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 `
- 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`
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the order flow around WAITING_BUYER_INVOICE and locating the Order schema and command entry points. Review how configurable fees are handled, then determine how the chosen swap provider would fit the release path. Done means the /onchain flow, validation, confirmation, persistence, fee handling, and final transaction receipt work end to end.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design, blockchain, payments
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100