SIP-3: Lightning-Atomic NFT Trades

Abstract

This specification defines the protocol for atomic NFT trades where Lightning payment settlement is cryptographically bound to PSBT finalization. It establishes the handshake flow, timeout rules, and failure handling to ensure buyer and seller atomicity.

Motivation

Standard Bitcoin transactions take ~10 minutes to confirm. Lightning enables sub-second payment, but linking it atomically to NFT ownership transfer requires careful protocol design to prevent:

• Buyer pays but seller doesn't transfer NFT
• Seller transfers NFT but buyer doesn't pay
• Coordinator theft or censorship

Specification

Trade Flow

1. Seller → Coordinator: List NFT
   - Provide inscription ID, price (sats), PSBT transferring NFT

2. Buyer → Coordinator: Accept offer
   - Request Lightning invoice

3. Coordinator → Buyer: HTLC invoice
   - Payment hash H = hash(preimage)
   - Timeout: 60 blocks (~10 hours)

4. Buyer → Lightning: Pay invoice
   - Payment routed via Lightning Network

5. Seller receives preimage P
   - Seller verifies hash(P) = H
   - Seller broadcasts signed PSBT

6. Coordinator monitors blockchain
   - After 1 confirmation: Release preimage to buyer
   - Trade complete

HTLC Timeout Rules

Timeout	Value	Rationale
Lightning invoice	60 blocks	Enough time for PSBT broadcast + confirmations
PSBT broadcast	Within 30 blocks	After buyer pays, seller must broadcast quickly
Confirmation wait	6 blocks	Standard finality threshold

Atomicity Guarantee

The protocol ensures atomicity through HTLC construction:

IF buyer pays Lightning invoice
    Seller learns preimage P
    Seller must broadcast PSBT to claim payment
    Coordinator cannot steal (doesn't know seller's keys)
ELSE
    Invoice expires, no payment captured
    Both parties refunded automatically

Failure Modes

1. Buyer Pays But PSBT Fails

Scenario: Buyer pays Lightning invoice, but seller's PSBT is invalid or double-spent.

Resolution:

• Coordinator monitors PSBT broadcast for 30 blocks
• If PSBT not confirmed by block 30: Coordinator refunds buyer via on-chain fallback
• Fallback PSBT: Coordinator pre-signs refund transaction using same HTLC preimage

2. Seller Broadcasts PSBT But Mempool Pinning

Scenario: Attacker broadcasts low-fee conflicting tx to block PSBT.

Mitigation:

• PSBT must use RBF (BIP 125) to allow fee bumping
• Coordinator monitors mempool and alerts seller to fee-bump
• CPFP allowed: Buyer can child-pays-for-parent if needed

3. Blockchain Reorg After Payment

Scenario: PSBT confirmed, then chain reorgs and tx disappears.

Resolution:

• Coordinator waits 6 confirmations before releasing preimage
• If reorg deeper than 6 blocks: Manual dispute resolution
• Lightning payment already settled (cannot reorg Lightning state)

Coordinator API (Proposed)

POST /v1/trade/create
{
  "inscription_id": "abc123...i0",
  "price_sats": 100000,
  "seller_address": "bc1p...",
  "psbt": "cHNidP8BAH..."
}

Response:
{
  "trade_id": "uuid",
  "status": "pending"
}

---

GET /v1/trade/{trade_id}/invoice

Response:
{
  "payment_request": "lnbc1...",
  "payment_hash": "abc123...",
  "expires_at": 1234567890
}

---

POST /v1/trade/{trade_id}/finalize
{
  "payment_preimage": "def456..."
}

Response:
{
  "txid": "xyz789...",
  "confirmations": 0
}

Implementation Requirements

Coordinator Service Must:

1. Validate PSBT transfers correct inscription to buyer
2. Generate HTLC invoices via Spark SDK or LND
3. Monitor Lightning payments and blockchain confirmations
4. Enforce timeout rules and trigger refunds
5. Provide WebSocket updates for trade status

Wallet Support Requires:

1. PSBT creation for inscription transfers
2. Lightning invoice payment via Spark SDK
3. API integration with coordinator
4. User confirmation flow (payment + PSBT signing)

Security Considerations

Coordinator Trust Assumptions

The coordinator can:

• ❌ Cannot steal funds (doesn't control keys)
• ❌ Cannot forge payments (Lightning cryptography prevents this)
• VALID: Can censor trades (DoS risk)
• VALID: Can see trade metadata (privacy risk)

Mitigations

• Censorship: Run your own coordinator (open source)
• Privacy: Use Tor or VPN when connecting to coordinator
• Coordinator downtime: Buyers can still claim refund via on-chain fallback

Current Status

NOT IMPLEMENTED. This specification describes the intended design. To use this protocol, someone must build:

1. Coordinator service (~200 hours development)
2. Wallet integration (Sparrow plugin, UniSat PR, etc.)
3. Spark SDK integration for HTLC generation
4. Testnet deployment and testing