lnbook/15_payment_requests.asciidoc

[[invoices]]
== Lightning Payment Requests

((("Lightning invoices", id="ix_15_payment_requests-asciidoc0", range="startofrange")))In this chapter we will look at _Lightning payment requests_, or as they are more commonly known, _Lightning invoices_.

=== Invoices in the Lightning Protocol Suite

((("Lightning invoices","Lightning Protocol suite and")))((("Lightning Network Protocol","Lightning invoices in")))_Payment requests_, aka _invoices_, are part of the payment layer and are shown in the upper left of <<LN_payment_request_highlight>>.

[[LN_payment_request_highlight]]
.Payment requests in the Lightning protocol suite
image::images/mtln_1501.png["Payment requests in the Lightning protocol suite"]

=== Introduction

As we've learned throughout the book, minimally two pieces of data are required
to complete a Lightning payment: a payment hash and a destination. As
SHA-256 is used in the Lightning Network to implement HTLCs, this information
requires 32 bytes to communicate. Destinations, on the other hand, are
simply the `secp256k1` public key of the node that wishes to receive a payment.
The purpose of a payment request in the context of the Lightning Network is to
communicate these two pieces of information from sender to receiver. The QR-code-friendly format for communicating the information required
to complete a payment from receiver to sender is described in https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md[BOLT #11: Invoice Protocol for Lightning Payments]. In practice, more than just the
payment hash and destination are communicated in a payment request to
make the encoding more fully featured.

=== Lightning Payment Requests Versus Bitcoin Addresses

((("Bitcoin addresses, Lightning invoices versus")))((("Lightning invoices","Bitcoin addresses versus")))A commonly asked question when people first encounter a Lightning Payment
request is: why can't a normal static address format be used instead?

To answer this question, you must first internalize how Lightning
differs from base layer Bitcoin as a payment method. Compared to a Bitcoin
address which may be used to make a potentially unbounded number of payments
(though reusing a Bitcoin address may degrade one's privacy), a Lightning
payment request should only ever be used _once_.  This is due to the fact that
sending a payment to a Bitcoin address essentially uses a public key
cryptosystem to "encode" the payment in a manner that only the true "owner" of
that Bitcoin address can redeem it.

In contrast, to complete a Lightning payment, the recipient must
reveal a "secret" to the entire payment route, including the sender. This can be
interpreted as usage of a kind of domain-specific symmetric cryptography because
the payment preimage is for practical purposes a nonce (number only used
once). If the sender attempts to make another payment using that identical
payment hash, then they risk losing funds because the payment may not actually be
delivered to the destination. It's safe to assume that after a preimage has
been revealed, all nodes in the path will keep it around forever, then rather
than forward the HTLC to collect a routing fee if the payment is
completed, they can simply settle the payment at that instance and gain the
entire payment amount in return. As a result, it's unsafe to ever use a payment
request more than once.

New variants of the original Lightning payment request exist that allow the sender to reuse them as many times as they want. These variants flip the normal payment flow as the sender transmits a preimage within the encrypted onion payload to the receiver, who is the only
one that is able to decrypt it and settle the payment. Alternatively, assuming
a mechanism that allows a sender to typically request a new payment request
from the receiver, then an interactive protocol can be used to allow a
degree of payment request reuse.

=== BOLT #11: Lightning Payment Request Serialization pass:[<span class="keep-together">and Interpretation</span>]

((("BOLT (Basis of Lightning Technology) standards documents","Lightning payment request serialization/interpretation")))((("Lightning invoices","payment request serialization/interpretation")))In this section, we'll describe the mechanism used to encode the set of
information required to complete a payment on the Lightning Network. As
mentioned earlier, the payment hash and destination is the minimum amount of
information required to complete a payment. However, in practice, more
information such as timelock information, payment request expiration, and
possibly an on-chain fallback address are also communicated. The full specification document is https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md[BOLT #11: Invoice Protocol for Lightning Payments].

==== Payment Request Encoding in Practice

((("Lightning invoices","payment request encoding in practice")))First, let's examine what a real payment request looks like in practice. The
following is a valid payment request that could have been used to complete a
payment on the mainnet Lightning Network at the time it was created:

----
lnbc2500u1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysx
xatsyp3k7enxv4jsxqzpuaztrnwngzn3kdzw5hydlzf03qdgm2hdq27cqv3agm2awhz5se903vruatf
hq77w3ls4evs3ch9zw97j25emudupq63nyw24cg27h2rspfj9srp
----

==== The Human-Readable Prefix

((("human-readable prefixes")))((("Lightning invoices","human-readable prefix")))Looking at the string, we can tease out a portion that we can parse with our
eyes, while the rest of it just looks like a random set of strings. The part
that is somewhat parsable by a human is referred to as the _human-readable prefix_. It allows a human to quickly extract some relevant information from a
payment request at a glance. In this case, we can see that this payment is for
the mainnet instance of the Lightning Network (`lnbc`), and is requesting 2,500
uBTC (microbitcoin), or 25,000,000 satoshis. The latter potion is referred
to as the data portion and uses an extensible format to encode the
information required to complete a payment.

Each version of instance of the Lightning Network (mainnet, testnet, etc.) has
its own human-readable prefix (see <<table1501>>). This allows client software and also humans to
quickly determine if a payment request can be satisfied by their node or not.

[role="pagebreak-before less_space"]
[[table1501]]
.BOLT #11 network prefixes
[options="header"]
|=============================
|Network       |BOLT #11 prefix
|mainnet       |`lnbc`
|testnet       |`lntb`
|simnet/regtest|`lnbcrt`
|=============================


The first portion of the human-readable prefix is a _compact_ expression of the
amount of the payment request. The compact amount is encoded in two parts. First, an integer is used as the _base_ amount. This is then followed by a
multiplier that allows us to specify distinct order of magnitude increases
offset by the base amount. If we return to our initial example, then we can
take the `2500u` portion and decrease it by a factor of 1,000 to instead use
`2500m` or (2,500 mBTC).  As a rule of thumb, to ascertain the amount
of an invoice at a glance, take the base factor and multiply it by the
multiplier.

A full list of the currently defined multipliers is given in <<table1502>>.

[[table1502]]
.BOLT #11 amount multipliers
[options="header"]
|==============================================
|Multiplier|Bitcoin unit|Multiplication factor
|`m`|milli|0.001
|`u`|micro|0.000001
|`n`|nano|0.000000001
|`p`|pico|0.000000000001
|==============================================


==== bech32 and the Data Segment

((("bech32, Lightning invoices and")))((("Lightning invoices","bech32 and data segment")))If the "unreadable" portion looks familiar, then that's because it uses the
very same encoding scheme as SegWit compatible Bitcoin addresses use today,
namely bech32. Describing the bech32 encoding scheme is outside the scope
of this chapter. In brief, it's a sophisticated way to encode short strings
that has very good error correction as well as detection properties.

The data portion can be separated into three sections:

  * The timestamp
  * Zero or more tagged key-value pairs
  * The signature of the entire invoice

The timestamp is expressed in seconds since the year 1970, or the Unix Epoch. This
timestamp allows the sender to gauge how old the invoice is, and as we'll see
later, allows the receiver to force an invoice to only be valid for a period of
time if they wish.

Similar to the TLV format we learned about in <<tlv>>, the BOLT #11 invoice
format uses a series of extensible key-value pairs to encode information
needed to satisfy a payment. Because key-value pairs are used, it's easy to add
new values in the future if a new payment type or additional
requirement/functionality is introduced.

Finally, a signature is included that covers the entire invoice signed by the
destination of the payment. This signature allows the sender to verify that the
payment request was indeed created by the destination of the payment. Unlike
Bitcoin payment requests which aren't signed, this allows us to ensure that a
particular entity signed the payment request. The signature itself is encoded
using a recovery ID, which allows a more compact signature to be used that
allows public key extraction. When verifying the signature, the recovery ID
extracts the public key, then verifies that against the public key included in
the invoice.

===== Tagged invoice fields

((("Lightning invoices","tagged invoice fields")))The tagged invoice fields are encoded in the main body of the invoice. These
fields represent different key-value pairs that express either additional
information that may help complete the payment or information which is
_required_ to complete the payment. Because a slight variant of bech32 is
utilized, each of these fields are actually in the "base 5" domain.

A given tag field is comprised of three components:

  * The `type` of the field (5 bits)
  * The `length` of the data of the field (10 bits)
  * The `data` itself, which is `length * 5 bytes` in size

A full list of all the currently defined tagged fields is given in <<table1503>>.

[[table1503]]
.BOLT #11 tagged invoice fields
[options="header"]
|===
|pass:[<span class="keep-together">Field tag</span>]|pass:[<span class="keep-together">Data length</span>]|Usage
|`p`|`52`|The SHA-256 payment hash.
|`s`|`52`|A 256-bit secret that increases the end-to-end privacy of a payment by mitigating probing by intermediate nodes.
|`d`|Variable|The description, a short UTF-8 string of the purpose of the payment.
|`n`|`53`|The public key of the destination node.
|`h`|`52`|A hash that represents a description of the payment itself. This can be used to commit to a description that's over 639 bytes in length.
|`x`|Variable|The expiry time, in seconds, of the payment. The default is 1 hour (3,600) if not specified.
|`c`|Variable|The `min_cltv_expiry` to use for the final hop in the route. The default is 9 if not specified.
|`f`|Variable|A fallback on-chain address to be used to complete the payment if the payment cannot be completed over the Lightning Network.
|`r`|Variable|One or more entries that allow a receiver to give the sender additional ephemeral edges to complete the payment.
|`9`|Variable|A set of 5-bit values that contain the feature bits that are required in order to complete the payment.
|===

The elements contained in the field `r` are commonly referred to as _routing hints_. They allow the receiver to communicate an extra set of edges that may
help the sender complete their payment. The hints are usually used when the
receiver has some/all private channels, and they wish to guide the sender into
this "unmapped" portion of the channel graph. A routing hint encodes
effectively the same information that a normal `channel_update` message does.
The update is itself packed into a single value with the following fields:

 * The `pubkey` of the outgoing node in the edge (264 bits)
 * The `short_channel_id` of the "virtual" edge (64 bits)
 * The base fee (`fee_base_msat`) of the edge (32 bits)
 * The proportional fee (`fee_proportional_millionths`) (32 bits)
 * The CLTV expiry delta (`cltv_expiry_delta`) (16 bits)

The final portion of the data segment is the set of feature bits that
communicate to the sender the functionality needed to complete a
payment. As an example, if a new payment type is added in the future that isn't
backward compatible with the original payment type, then the receiver can set
a _required_ feature bit to communicate that the payer needs to
understand that feature to complete the payment.

=== Conclusion

As we have seen, invoices are a lot more than just a request for an amount. They contain critical information about _how_ to make the payment, such as routing hints, the destination node's public key, ephemeral keys to increase security, and much more.(((range="endofrange", startref="ix_15_payment_requests-asciidoc0")))