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.

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...

[Invoice Breakdown]
├── lnbc - Network (mainnet Bitcoin)
├── 2500u - Amount (250,000 sats)
├── 1 - Separator
├── pvjluez... - Bech32-encoded data
└── 9qxpqysgq... - Signature

Network Prefixes

Amount Encoding

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

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

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"

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:

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.

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

The 9 field encodes supported features:

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 Offers (BOLT12) for details.

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 Offers (BOLT12) (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.

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)

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

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

• BOLT 11 Specification
• Lightning Invoice Decoder - Online tool