Lightning Invoices (BOLT11)

Lightning invoices are payment requests encoded in the BOLT11 format. They contain all the information a payer needs to send a payment, including the payment hash, amount, destination, and expiry.

Invoice Structure

A BOLT11 invoice consists of three parts:

1. Human-Readable Part (HRP): Network prefix and amount
2. Data Part: Encoded payment details
3. Signature: Proves invoice authenticity

Example Invoice:
lnbc2500u1pvjluezsp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygspp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpu9qxpqysgq...

Breakdown:
├── lnbc          ← Network (mainnet Bitcoin)
├── 2500u         ← Amount (2500 micro-BTC = 250,000 sats)
├── 1             ← Separator
├── pvjluez...    ← Bech32-encoded data
└── 9qxpqysgq...  ← Signature

Human-Readable Part

Network Prefixes

Amount Encoding

Note: Pico amounts must be multiples of 10 (minimum resolution is 1 millisatoshi).

Data Part Fields

The data section uses tagged fields in TLV (Type-Length-Value) format:

Parsing Invoices

Creating Invoices

Using lncli:

# Create invoice for 10,000 sats with description
lncli addinvoice --amt=10000 --memo="Payment for coffee"

# Create invoice with specific expiry (1 hour)
lncli addinvoice --amt=50000 --memo="Service fee" --expiry=3600

# Create invoice with private route hints
lncli addinvoice --amt=25000 --private

# Create zero-amount invoice (payer chooses amount)
lncli addinvoice --memo="Donation"

Invoice Expiry

Invoices have a default expiry of 1 hour (3600 seconds). After expiry:

• Invoice should not be paid
• Payment hash may be reused by recipient
• Sender's wallet should reject expired invoices

Common expiry values:

Route Hints

Private channels require route hints to be payable:

Route Hint Structure:
├── Node ID (33 bytes)
├── Short Channel ID (8 bytes)
├── Fee Base (4 bytes)
├── Fee Proportional (4 bytes)
└── CLTV Expiry Delta (2 bytes)

Route hints tell the sender how to reach a node through private/unannounced channels.

Payment Secret (s field)

The payment secret (added in BOLT11 amendment):

• 32 bytes of random data
• Prevents payment probing attacks
• Required for Multi-Part Payments (MPP)
• Proves payer has the actual invoice

Feature Bits

The 9 field encodes supported features:

BOLT12 and Offers

BOLT12 extends the Lightning payment model with offers and invoice requests. Unlike BOLT11, where the payee creates an invoice when they want to be paid, BOLT12 offers are static, reusable descriptors that payers use to request an invoice from the payee. Benefits include:

• Reusable offers: One offer can yield many invoices (e.g., subscriptions, donations, any-amount).
• Payee offline at creation: The offer can be published (e.g., on a website); the payee only needs to be online when the payer sends an invoice request and the payee returns an invoice.
• Keysend-style flows: Structured alternative to keysend where the payee still controls the payment hash and amount via the invoice they generate.

Support varies: Core Lightning and LDK have BOLT12 support; LND and others are adding it. See BOLT12 & Offers for details.

Common Patterns

Reusable Invoices

Standard BOLT11 invoices should only be paid once. For reusable or dynamic payments:

• Use Keysend (no invoice needed)
• Use LNURL-pay (dynamic invoice generation)
• Use BOLT12 & Offers (when supported by your node and payees)

Fallback Addresses

Include on-chain fallback for large amounts:

lncli addinvoice --amt=1000000 --fallback_addr=bc1q...

If Lightning payment fails, payer can use on-chain address.

Validation Checklist

When receiving an invoice, verify:

1. Network matches your node (mainnet/testnet)
2. Not expired (current time < timestamp + expiry)
3. Amount is acceptable (if specified)
4. Features are supported by your node
5. Signature is valid (proves invoice authenticity)

Summary

BOLT11 invoices provide:

• Standardized format for payment requests
• Amount encoding from pico-BTC to whole BTC
• Expiry handling to prevent stale payments
• Route hints for private channel payments
• Payment secrets for security and MPP support

Related Topics

• BOLT12 & Offers - Offers, invoice requests, and reusable payment flows
• Multi-Part Payments - Splitting large payments
• Channels - Where payments flow
• HTLCs - Payment mechanism

Resources

• BOLT 11 Specification
• Lightning Invoice Decoder - Online tool