Lighting Invoices

This page shows the basis of lighting invoices

Invoice Structure

A Lightning invoice contains several key pieces of information encoded in a string that starts with "lnbc" (for mainnet) or "lntb" (for testnet).

Key Numbers About Lightning Invoices:

• Maximum Invoice Amount: 0.04294967295 BTC (~$1,500 USD)

• Default Expiry Time: 3600 seconds (1 hour)

• Minimum Amount: 1 satoshi (0.00000001 BTC)

• Invoice String Length: Typically 200-300 characters

• Processing Time: < 1 second to generate/validate

Invoice Components:

1. Amount (in millisatoshis)

2. Timestamp (Unix timestamp)

3. Expiry time (default 1 hour)

4. Payment hash (32 bytes)

5. Description (optional memo)

6. Routing hints (optional)

Important Metrics:

• Success Rate: ~98% for properly formatted invoices

• Average Processing Time: 50-200 milliseconds

• Invoice Size: ~250 bytes average

• Supported Character Set: Bech32 encoding

• Maximum Description Length: 639 bytes

Best Practices:

• Set reasonable expiry times (1-24 hours)

• Include clear descriptions

• Use unique payment hashes

• Implement proper error handling

• Consider fallback addresses

---

The below examples are taken from Lighting lab doc

Example of a Lightning Invoice

lnbc20m1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqhp58yjmdan79s6qqdhdzgynm4zwqd5d7xmw5fk98klysy043l2ahrqsfpp3qjmp7lwpagxun9pygexvgpjdc4jdj85fr9yq20q82gphp2nflc7jtzrcazrra7wwgzxqc8u7754cdlpfrmccae92qgzqvzq2ps8pqqqqqqpqqqqq9qqqvpeuqafqxu92d8lr6fvg0r5gv0heeeqgcrqlnm6jhphu9y00rrhy4grqszsvpcgpy9qqqqqqgqqqqq7qqzqj9n4evl6mr5aj9f58zp6fyjzup6ywn3x6sk8akg5v4tgn2q8g4fhx05wf6juaxu9760yp46454gpg5mtzgerlzezqcqvjnhjh8z3g2qqdhhwkj

Amount

The prefix is followed by the amount. While a typical Lightning invoice will include an amount, it is possible to issue invoices without amounts. Lightning Invoices reference bitcoin, not satoshi. To save space for round invoices, an amount may be followed by a multiplier. A single satoshi Lightning invoice for example would appear as 10n, a hundred satoshi as 1u, and a milli-satoshi as 10p.

unit	multiplier	satoshi
m (milli)	0.001	100,000
u (micro)	0.000001	100
n (nano)	0.000000001	0.1
p (pico)	0.000000000001	0.0001

Prefix and amount together are human-readable, allowing a savvy user to immediately identify it as a Lightning invoice and deduce its amount.

Timestamp

The first part of the data part is a unix timestamp.

Tagged

There are a number of tags that may be used to indicate additional data. Some of that data is required, while others can be optionally supplied by the payee.

Currently defined are the following fields:

• p (1): The 256-bit SHA256 payment_hash. This preimage is later revealed as part of the payment process and can act as proof of payment.

• s (16): A 256-bit secret prevents forwarding nodes from probing the payment recipient.

• d (13): A short description of purpose of payment may be added here, encoded with UTF-8, e.g. '1 cup of coffee' or '一杯咖啡'. If this field is not set, tag h has to be used instead.

• n (19): The 33-byte public key of the payee node may be included here.

• h (23): If field d does not provide space, a hash of the longer description may be included here. How the full description then gets communicated is not defined here.

• x (6): The expiry time in seconds.

• c (24): The min_final_cltv_expiry for the last HTLC in the route. Typically defaults to 18.

• f (9): A fallback on-chain address can be included here in case the Lightning payment fails for whatever reason.

• r (3): One or more entries containing extra routing information for a private route. These routing hints include a

  • pubkey (264 bits)

  • short_channel_id (64 bits)

  • fee_base_msat (32 bits, big-endian)

  • fee_proportional_millionths (32 bits, big-endian)

  • cltv_expiry_delta (16 bits, big-endian)

• 9 (5): One or more 5-bit values containing features supported or required for receiving this payment.

Signature

Finally, the invoice will include a signature. This signature is verified using the public key provided in the invoice.

LNURL

A Lightning Network URL, or LNURL, is a proposed standard for interactions between a Lightning payer and payee.

In short, a LNURL is a bech32 encoded url pre-fixed with lnurl. The Lightning wallet is expected to decode the url, contact the url and await a json object with further instructions, most notably a tag defining the behavior of the lnurl.

LNURLs are most commonly used to initiate withdrawals or create static payment links.

Decode a Lightning invoice

You can decode any Lightning invoice to inspect its contents with the command lncli decodepayreq.

For the above example, the result is the following:

{ "destination": "03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad", "payment_hash": "0001020304050607080900010203040506070809000102030405060708090102", "num_satoshis": "2000000", "timestamp": "1496314658", "expiry": "3600", "description": "", "description_hash": "3925b6f67e2c340036ed12093dd44e0368df1b6ea26c53dbe4811f58fd5db8c1", "fallback_addr": "1RustyRX2oai4EYYDpQGWvEL62BBGqN9T", "cltv_expiry": "9", "route_hints": [ { "hop_hints": [ { "node_id": "029e03a901b85534ff1e92c43c74431f7ce72046060fcf7a95c37e148f78c77255", "chan_id": "72623859790382856", "fee_base_msat": 1, "fee_proportional_millionths": 20, "cltv_expiry_delta": 3 }, { "node_id": "039e03a901b85534ff1e92c43c74431f7ce72046060fcf7a95c37e148f78c77255", "chan_id": "217304205466536202", "fee_base_msat": 2, "fee_proportional_millionths": 30, "cltv_expiry_delta": 4 } ] } ], "payment_addr": null, "num_msat": "2000000000", "features": { } }