Archives/lnbook
2
0
Fork 0
mirror of https://github.com/lnbook/lnbook synced 2024-11-18 21:28:03 +00:00
Code Issues Projects Releases Wiki Activity

Edits to invoices, payment hash, preimage

Browse Source
This commit is contained in:
Andreas M. Antonopoulos 2020-07-15 10:22:28 -04:00
parent 5394587703
commit 7a83a23806
1 changed files with 46 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
03_how_ln_works.asciidoc
View File

@ -350,40 +350,57 @@ As long as you run your Lightning node once before the timeout period is reached
=== Invoices === Invoices
Every payment on the Lightning Network starts with a person who wants to receive bitcoins issuing an invoice. Most payments on the Lightning Network start with an invoice, generated by the recipient of the payment. In our previous example, Bob creates an invoice to "request" a payment from Alice.
An invoice is nothing more than a simple payment instruction containing various pieces of information such as a unique payment identifier, called a payment hash, a recipient, an amount, etc.
The main reason for this process is that it helps to make the payment process over a path of payment channels atomic.
Atomic means that no node on the path can decide to take the money that is being routed or stop the routing process.
The payment will either be transferred successfully through the complete path of nodes or will not be delivered at all.
There are no such things as a partial payment or a half successful payment.
While Lightning Nodes usually use the encrypted communication channels over the Lightning peer-to-peer network to exchange information, invoices are being transferred via a second communication channel. [NOTE]
The payee has to pass the invoice to the payer via any arbitrary means. ====
This could be done via a Webservice, an instant message on a chat app, an SMS or an Email. There is a way to send an "unsolicited" payment without an invoice, using a work-around in the protocol called _keysend_. We will examine this in <<keysend>>.
Invoices are usually encoded either as long bech32-encoded strings or as QR codes which enables them to be easily scanned by smartphones. ====
The invoices contains the amount of bitcoin that is requested and a signature of the payee.
The later is used to extract the address of the payee so that the payer knows whom to send the money.
Besides some other meta data the most important but not quite obvious data in the invoice is a Payment Hash.
Did you notice how this contrasts with Bitcoin and how different language terms are used? In Bitcoin, the recipient passes an address to the sender. In Lightning, the payee creates an invoice and sends an invoice to the payer. In Bitcoin, the payer sends funds to an address. In Lightning, the payer pays an invoice and it gets routed to the payee. Bitcoin is based on the concept of an "address", and Lightning is a payment network and based on the concept of an "invoice". An invoice is a simple payment instruction containing information such as a unique payment identifier, called a payment hash, a recipient, an amount, and an optional text description.
The same way, the analog term to Bitcoin's "transaction" is the term "payment" in Lightning.
==== Payment Hash The most important part of the invoice is the payment hash, that allows the payment to travel across multiple channel in an _atomic_ way. Atomic, in computer science, means any action or state change that is either completed successfully or not at all - there is no possibility of an intermediate state or partial action. In the Lightning Network that means that the payment either travels the whole path or fails completely. It cannot be partially completed such that an intermediate node on the path can receive the payment and keep it.
The payee will choose a truly random number `r` and produces the `sha256` of that number which we call the Payment Hash `H(r)`. There is no such thing as a "partial payment" or "partly successful payment".
Note that an adversary should have no means of guessing or predicting `r`.
Using a customer id or the hash of entries of the shopping cart together with a timestamp is not truly random and yields a security risk. Invoices are not communicated over the Lightning Network. Instead, they are communicated "out of band", using any other communication mechanism. This is similar to how Bitcoin addresses are communicated to senders outside the Bitcoin network, as a QR code, over email, or a text message. For example, Bob can present a Lightning invoice to Alice as a QR code, or send it via email, or any other message channel.
The payment process of the Lightning Network is only secure if `r` is chosen completely randomly and is not predictable and as long as the Hash function cannot be inverted.
We note that this is not an additional security assumption for Bitcoin as the security of the Hash function is currently the underlying basis of Bitcoin mining. Invoices are usually encoded either as a long bech32-encoded string or as a QR code, to be scanned by a smartphone Lightning wallet. The invoice contains the amount of bitcoin that is requested and a signature of the recipient. The sender uses the signature to extract the public key (also known as the node ID) of the recipient so that the sender knows where to send the payment.
Did you notice how this contrasts with Bitcoin and how different terms are used? In Bitcoin, the recipient passes an address to the sender. In Lightning, the recipient creates an invoice and sends an invoice to the sender. In Bitcoin, the sender sends funds to an address. In Lightning, the sender pays an invoice and the payment gets routed to the recipient. Bitcoin is based on the concept of an "address", and Lightning is a payment network and based on the concept of an "invoice". In Bitcoin we create a "transaction" whereas in Lightning we send a "payment".
==== Payment Hash and Preimage
The most important part of the invoice is the _payment hash_. When constructing the invoice, Bob will make a payment hash as follows:
1. Bob chooses a random number +r+. This random number is called the _preimage_ or _payment secret_.
2. Bob uses +SHA256+ to calculate the hash +H+ of +r+ called the _payment hash_
latexmath:[H = SHA256(r)].
[NOTE]
====
The term _preimage_ comes from mathematics. In any function _y = f(x)_, the set of inputs that produce a certain value _y_ are called the preimage of _y_. In this case, the function is the SHA256 hash algorithm and any value _r_ that produces the hash _H_ is called a preimage.
====
Since the value +r+ is secret, only Bob knows it's value. No one can guess the value +r+, but once Bob reveals +r+, anyone who has the hash +H+ can check that +r+ is the correct secret, by calculating +SHA256(r)+ and seeing that it matches +H+.
The payment process of the Lightning Network is only secure if +r+ is chosen completely randomly and is not predictable. This security relies on the fact that hash functions cannot be inverted or feasibly brute-forced and therefore no one can find +r+ from +H+.
==== Additional Meta Data ==== Additional Meta Data
Invoices can encode some other useful meta data.
For example a short description. Invoices can optionally include other useful meta data such as a short text description. If a user has several invoices to pay, the user can read the description and be reminded what the invoice is about.
In case a user has several invoices to pay, the user can read the description and be reminded what the invoice is about.
As payment channels do not need to be publicly announced, the payee can also provide some private channels as routing hints to the invoice. The invoice can also include some _routing hints_, which are private channels that have not been publicly announced, but can be used by the sender to construct a route to the recipient. Routing hints can also be used to suggest public channels, for example channels known by the recipient to have enough inbound capacity to route the payment.
These hints can furthermore be used to suggest public channels, e.g. those channels on which the payee has enough inbound liquidity to actually receive the amount.
In case the payer's Lightning node is not able to send the payment over the Lightning Network, invoices can optionally include an on-chain Bitcoin fallback address. In case the sender's Lightning node is unable to send the payment over the Lightning Network, invoices can optionally include an on-chain Bitcoin address as a fallback.
We would however always recommend to open a new Lightning payment channel instead of doing an on-chain Bitcoin payment.
Invoices also have an expiry time so that the payee can delete the preimage after some time to free up space. [NOTE]
====
While it is always possible to "fall back" to an on-chain Bitcoin transaction, it is actually better to open a new channel to the recipient instead. If you have to incur on-chain fees to make a payment, you might as well incur those fees to open a channel and make the payment over Lightning. After the payment is made, you are left with an open channel that has liquidity on the recipient's end and can be used to route payments back to your Lightning node in the future. One on-chain transaction gives you a payment and a channel for future use.
====
Lightning invoices contain an expiry date. Since the recipient must keep the preimage +r+ for every invoice issued, it is useful to have invoices expire so that these preimages do not need to be kept forever. Once an invoice expires or is paid, the recipient can discard the preimage.
=== Delivering the payment === Delivering the payment