[[invoices]] [[lightning_payment_requests]] [[payment_requests]] == Lightning Payment Requests 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 _Payment Requests_, aka _Invoices_ are part of the Payment Layer and are show in the upper left of <>: [[LN_payment_request_highlight]] .The Lightning Network Protocol Suite image::images/LN_payment_request_highlight.png["The Lightning Network 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 in order 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 in order to make the encoding more fully feature. === Lightning Payment Requests vs Bitcoin Addresses A commonly asked question when people first encounter a Lightning Payment request is: why can't a normal static address format be used instead? In order 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 re-using 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, in order 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, as the payment pre-image 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, as the payment may not actually be delivered to the destination. It's safe to assume that after a pre-image has been reveled, all nodes in the path will keep it around forever, then rather than forward the HTLC in order 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 pre-image 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 in order to allow a degree of payment request re-use. === BOLT 11: Lightning 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 time-lock 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 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 time it was created: ``` lnbc2500u1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpuaztrnwngzn3kdzw5hydlzf03qdgm2hdq27cqv3agm2awhz5se903vruatfhq77w3ls4evs3ch9zw97j25emudupq63nyw24cg27h2rspfj9srp ``` ==== The 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 parse able 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 2500 uBTC (micro-bitcoin), or `25,0000,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. This allows client software and also humans to quickly determine if a payment request can be satisfied by their node or not. .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" amt. 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 1000 to instead use `2500m` or (2500 `mBTC`). As a rule of thumb in order 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 a follows: .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 & the Data Segment If the "unreadable" portion of 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 3 sections: * The timestamp. * Zero or more tagged key-value pairs. * The signature of the entire invoice. The timestamp is expressed in seconds since the 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 <>, the BOLT 11 invoice format uses a series of extensible key-value pairs to encode information needed to satisfy a payment. As key-value pairs are used, it's easy for 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 request's 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 verifies extracts the public key, then verifies that against the public key included in the invoice. ===== 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. As 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 3 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 as follows: .BOLT 11 Tagged Invoice Fields [options="header"] |=== |Field Tag|Data Length|Usage |`p`|`52`|The `SHA-256` payment hash. |`s`|`52`|A `256-bit` secret that increase 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 (3600) 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 fall back on-chain address to be used to complete the payment if the payment cannot be completed over LN. |`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 hints 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 eh sender the functionality needed in order to complete a payment. As an example, if a new payment type is added in the future that isn't backwards compatible with the original payment type, then the receiver can set a _required_ feature bit in order to communicate that the payer needs to underhand that feature in order 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.