@ -222,7 +222,7 @@ Chan is a Chinese entrepreneur who sells information services related to the Lig
Gamer::
Dina is a teenage gamer from Russia. She plays many different computer games, but her favorite ones are those that have an "in-game economy" based on real money. As she plays games, she also earns money by acquiring and selling virtual in-game items. The Lightning Network allows her to transact in small amounts for in-game items as well as earn small amounts for completing quests.
=== Chapter Summary
=== Conclusion
In this chapter, we talked about the fundamental concept that underlies both Bitcoin and the Lightning Network: the fairness protocol.
@ -186,7 +186,7 @@ image::images/mtln_0201.png["Eclair wallet in the Google Play Store"]
It is possible to experiment and test all Bitcoin-type software with zero risk (except for your own time) by using testnet bitcoins. You can also download the Eclair testnet wallet to try Lightning (on testnet) by going to the Google Play Store.
====
Alice notices a few different elements on this page that help her ascertain that this is, most likely, the correct "Eclair Mobile" wallet she is looking for. Firstly, the organization ACINQfootnote:[ACINQ: Developers of the Eclair Mobile Lightning wallet (https://acinq.co[]).] is listed as the developer of this mobile wallet, which Alice knows from her research is the correct developer. Secondly, the wallet has been installed "10,000+" times and has more than 320 positive reviews. It is unlikely that this is a rogue app that has snuck into the Google Play Store. As a third step, she goes to the https://acinq.co[ACINQ website]. She verifies that the web page is secure by checking that the address begins with https, or prefixed by a padlock in some browsers. On the website, she goes to the Download section or looks for the link to the Google App Store. She finds the link and clicks it. She compares that this link brings her to the very same app in the Google App Store. Satisfied by these findings, Alice installs the Eclair app on her mobile device.
Alice notices a few different elements on this page that help her ascertain that this is, most likely, the correct "Eclair Mobile" wallet she is looking for. Firstly, the organization ACINQfootnote:[ACINQ: Developers of the Eclair Mobile Lightning wallet.] is listed as the developer of this mobile wallet, which Alice knows from her research is the correct developer. Secondly, the wallet has been installed "10,000+" times and has more than 320 positive reviews. It is unlikely that this is a rogue app that has snuck into the Google Play Store. As a third step, she goes to the https://acinq.co[ACINQ website]. She verifies that the web page is secure by checking that the address begins with https, or prefixed by a padlock in some browsers. On the website, she goes to the Download section or looks for the link to the Google App Store. She finds the link and clicks it. She compares that this link brings her to the very same app in the Google App Store. Satisfied by these findings, Alice installs the Eclair app on her mobile device.
[WARNING]
====
@ -289,7 +289,7 @@ Both Bitcoin addresses and QR codes contain error detection information that pre
Alice can take her mobile device to the ATM and show it to the built-in camera, as shown in <<bitcoin-atm-receive>>. After inserting some cash into the slot, she will receive bitcoin in Eclair!
[[bitcoin-atm-receive]]
.Bitcoin ATM scans the QR code.
.Bitcoin ATM scans the QR code
image::images/mtln_0205.png["Bitcoin ATM scans the QR code"]
Alice will see the transaction from the ATM in the TRANSACTION HISTORY tab of the Eclair wallet. Although Eclair will detect the bitcoin transaction in just a few seconds, it will take approximately one hour for the bitcoin transaction to be "confirmed" on the Bitcoin blockchain. As you can see in <<eclair-tx1>>, Alice's Eclair wallet shows "6+ conf" below the transaction, indicating that the transaction has received the required minimum of six confirmations, and her funds are now ready to use.
@ -227,7 +227,7 @@ We will examine the revocation mechanism in more detail in <<revocation>>, where
In simple terms, Alice signs Bob's new commitment transaction only if Bob offers his half of the revocation secret for the previous commitment. Bob only signs Alice's new commitment transaction if she gives him her half of the revocation secret from the previous commitment.
With each new commitment, they exchange the necessary "punishment" secret that allows them to effectively _revoke_ the prior commitment transaction by making it unprofitable to transmit. Essentially, they destroy the ability to use old commitments as they sign the new ones. What we mean is that while it is still technically possible to use old commitments, the penalty mechanism makes it economically irrational to do so.
With each new commitment, they exchange the necessary "punishment" secret that allows them to effectively _revoke_ the prior commitment transaction by making it unprofitable to transmit. Essentially, they destroy the ability to use old commitments as they sign the new ones. What we mean is that while it is still technically possible to use old commitments, the penalty mechanism makes it economically irrational to pass:[<span class="keep-together">do so</span>].
The timelock is set to a number of blocks up to 2,016 (approximately two weeks). If either channel partner publishes a commitment transaction without cooperating with the other partner, they will have to wait for that number of blocks (e.g., two weeks) to claim their balance. The other channel partner can claim their own balance at any time. Furthermore, if the commitment they published was previously revoked, the channel partner can _also_ immediately claim the cheating party's balance, bypassing the timelock and punishing the cheater.
@ -419,7 +419,7 @@ Invoices are usually encoded either as a long __bech32__-encoded string or as a
[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 SHA-256 hash algorithm, and any value _r_ that produces the hash _H_ is called a preimage.
The term _preimage_ comes from mathematics. In any function pass:[<span class="keep-together"><em>y</em> = <em>f</em>(<em>x</em>)</span>], the set of inputs that produce a certain value _y_ are called the preimage of _y_. In this case, the function is the SHA-256 hash algorithm, and any value _r_ that produces the hash _H_ is called a preimage.
====
There is no known way to find the inverse of SHA-256 (i.e., compute a preimage from a hash). Only Bob knows the value _r_, so it is Bob's secret. But once Bob reveals _r_, anyone who has the hash _H_ can check that _r_ is the correct secret, by calculating SHA-256(_r_) and seeing that it matches _H_.
@ -522,7 +522,7 @@ The user might only realize that probing is taking place if the payment does not
[NOTE]
====
On the internet, we use the Internet Protocol and an IP forwarding algorithm to forward internet packages from the sender to the destination. While these protocols have the nice property of allowing internet hosts to collaboratively find a path for information flow through the internet, we cannot reuse and adopt this protocol for forwarding payments on the Lightning Network. Unlike the internet, Lightning payments have to be _atomic_, and channel balances have to remain _private_. Furthermore, the channel capacity in Lightning changes frequently, unlike the internet where connection capacity is relatively static. These constraints require novel strategies.
On the internet, we use the Internet Protocol and an IP forwarding algorithm to forward internet packages from the sender to the destination. While these protocols have the nice property of allowing internet hosts to collaboratively find a path for information flow through the internet, we cannot reuse and adopt this protocol for forwarding payments on the Lightning Network. Unlike the internet, Lightning payments have to be _atomic_, and channel balances have to remain _private_. Furthermore, the channel capacity in Lightning changes frequently, unlike the internet where connection capacity is relatively static. These constraints require novel pass:[<span class="keep-together">strategies</span>].
====
Of course, pathfinding is trivial if we want to pay our direct channel partner and we have enough balance on our side of the channel to do so. In all other cases, our node uses information from the gossip protocol to do pathfinding. This includes currently known public payment channels, known nodes, known topology (how known nodes are connected), known channel capacities, and known fee policies set by the node owners.
@ -622,7 +622,7 @@ In contrast, Alice will not open a channel to someone unknown who just uninvited
Some of these differences are differences in terminology. There are also architectural differences and differences in the user experience. In the next few sections, we will examine the differences and similarities, explain the terminology, and adjust our expectations.
==== Addresses versus Invoices, Transactions versus Payments
==== Addresses Versus Invoices, Transactions Versus Payments
((("Bitcoin–Lightning Network comparisons","addresses versus invoices")))((("Bitcoin–Lightning Network comparisons","transactions versus payments")))In a typical payment using Bitcoin, a user receives a Bitcoin address (e.g., scanning a QR code on a web page, or receiving it in an instant message or email from a friend). They then use their Bitcoin wallet to create a transaction to send funds to this address.
@ -634,7 +634,7 @@ There are some differences in the user experience, however. A Bitcoin address is
In Lightning, however, each invoice can only be used once for a specific payment amount. You cannot pay more or less, you cannot use an invoice again, and the invoice has an expiry time built in. In Lightning, a recipient has to generate a new invoice for each payment, specifying the payment amount in advance. There is an exception to this, a mechanism called _keysend_, which we will examine in <<keysend>>.
==== Selecting Outputs versus Finding a Path
==== Selecting Outputs Versus Finding a Path
((("Bitcoin–Lightning Network comparisons","selecting outputs versus finding a path")))((("unspent transaction outputs (UTXOs)")))((("UTXOs (unspent transaction outputs)")))To make a payment on the Bitcoin network, a sender needs to consume one or more unspent transaction outputs (UTXOs).
If a user has multiple UTXOs, they (or rather their wallet) will need to select which UTXO(s) to send.
@ -646,14 +646,14 @@ Because many possible channels and paths can be used to make a payment, the Ligh
With technologies such as atomic multipath payments (AMP) and multipart payments (MPP), which we will review in subsequent chapters, several Lightning paths can be aggregated into a single atomic payment, just like several Bitcoin UTXOs can be aggregated into a single atomic Bitcoin transaction.
==== Change Outputs on Bitcoin versus No Change on Lightning
==== Change Outputs on Bitcoin Versus No Change on Lightning
((("Bitcoin–Lightning Network comparisons","change outputs")))To make a payment on the Bitcoin network, the sender needs to consume one or more unspent transaction outputs (UTXOs). UTXOs can only be spent in full; they cannot be divided and partially spent. So if a user wishes to spend 0.8 BTC, but only has a 1 BTC UTXO, they need to spend the entire 1 BTC UTXO by sending 0.8 BTC to the recipient and 0.2 BTC back to themselves as change. The 0.2 BTC change payment creates a new UTXO called a "change output."
On Lightning, the funding transaction spends some Bitcoin UTXO, creating a multisignature UTXO to open the channel. Once the bitcoin is locked within that channel, portions of it can be sent back and forth within the channel, without the need to create any change.
This is because the channel partners simply update the channel balance and only create a new UTXO when the channel is eventually closed using the channel closing transaction.
==== Mining Fees versus Routing Fees
==== Mining Fees Versus Routing Fees
((("Bitcoin–Lightning Network comparisons","mining fees versus routing fees")))On the Bitcoin network, users pay fees to miners to have their transactions included in a block.
These fees are paid to the miner who mines that particular block.
@ -663,7 +663,7 @@ Because miners will typically mine the most profitable transactions first, a use
On the Lightning Network, users pay fees to other (intermediary node) users to route payments through their channels.
To route a payment, an intermediary node will have to move funds in two or more channels they own, as well as transmit the data for the sender's payment. Typically, the routing user will charge the sender based on the _value_ of the payment, having established a minimum ((("base fee")))_base fee_ (a flat fee for each payment) and a ((("fee rate")))_fee rate_ (a prorated fee proportional to the value of the payment). Higher value payments will thus cost more to route, and a market for liquidity is formed, where different users charge different fees for routing through their channels.
==== Varying Fees Depending on Traffic versus Announced Fees
==== Varying Fees Depending on Traffic Versus Announced Fees
((("Bitcoin–Lightning Network comparisons","varying fees versus announced fees")))On the Bitcoin network, miners are profit seeking and will typically include as many transactions in a block as possible, while staying within the block capacity called the ((("block weight")))_block weight_.
@ -671,11 +671,11 @@ To route a payment, an intermediary node will have to move funds in two or more
Thus, when there are many transactions in the queue, users have to pay a higher fee to be included in the next block, or they have to wait until there are fewer transactions in the queue.
This naturally leads to the emergence of a fee market where users pay based on how urgently they need their transaction included in the next block.
The scarce resource on the Bitcoin network is the space in the blocks. Bitcoin users compete for block space, and the Bitcoin fee market is based on available block space. The scarce resources in the Lightning Network are the ((("channel connectivity")))((("channel liquidity")))_channel liquidity_ (capacity of funds available for routing in channels) and _channel connectivity_ (how many well-connected nodes channels can reach). Lightning users compete for capacity and connectivity; therefore, the Lightning fee market is driven by capacity and connectivity.
The scarce resource on the Bitcoin network is the space in the blocks. Bitcoin users compete for block space, and the Bitcoin fee market is based on available block space. The scarce resources in the Lightning Network are the ((("channel connectivity")))((("channel liquidity")))_channel liquidity_ (capacity of funds available for routing in channels) and _channel connectivity_ (how many well-connected nodes channels can reach). Lightning users compete for capacity pass:[<span class="keep-together">and connectivity</span>]; therefore, the Lightning fee market is driven by capacity and pass:[<span class="keep-together">connectivity</span>].
On the Lightning Network, users are paying fees to the users routing their payments. Routing a payment, in economic terms, is nothing more than providing and assigning capacity to the sender. Naturally, routers who charge lower fees for the same capacity will be more attractive to route through. Thus a fee market exists where routers are in competition with each other over the fees they charge to route payments through their channels.
==== Public Bitcoin Transactions versus Private Lightning Payments
==== Public Bitcoin Transactions Versus Private Lightning Payments
((("Bitcoin–Lightning Network comparisons","public Bitcoin transactions versus private Lightning payments")))On the Bitcoin network, every transaction is publicly visible on the Bitcoin blockchain. While the addresses involved are pseudonymous and are not typically tied to an identity, they are still seen and validated by every other user on the network.
In addition, blockchain surveillance companies collect and analyze this data en masse and sell it to interested parties such as private firms, governments, and intelligence agencies.
@ -684,7 +684,7 @@ LN payments, on the other hand, are almost completely private. Typically, only t
In summary, Bitcoin transactions are broadcast publicly and stored forever. Lightning payments are executed between a few selected peers, and information about them is privately stored only until the channel is closed. Creating mass surveillance and analysis tools equivalent to those used on Bitcoin will be much harder on Lightning.
==== Waiting for Confirmations versus Instant Settlement
==== Waiting for Confirmations Versus Instant Settlement
((("Bitcoin–Lightning Network comparisons","waiting for confirmations versus instant settlement")))On the Bitcoin network, transactions are only settled once they have been included in a block, in which case they are said to be "confirmed" in that block. As more blocks are mined, the transaction acquires more "confirmations" and is considered more secure.
@ -693,7 +693,7 @@ In practical terms, instant settlement means that payments take only a few secon
Finally, when the channel is closed, a transaction is made on the Bitcoin network; once that transaction is confirmed, the channel is considered closed.
==== Sending Arbitrary Amounts versus Capacity Restrictions
==== Sending Arbitrary Amounts Versus Capacity Restrictions
((("Bitcoin–Lightning Network comparisons","sending arbitrary amounts versus capacity restrictions")))On the Bitcoin network, a user can send any amount of bitcoin that they own to another user, without capacity restrictions. A single transaction can theoretically send up to 21 million bitcoin as a payment.
@ -705,7 +705,7 @@ If the payment is routed, every routing node along the routing path must have ch
Hence, capacity and connectivity are critical and scarce resources in the Lightning Network.
==== Incentives for Large Value Payment versus Small Value Payments
==== Incentives for Large Value Payment Versus Small Value Payments
((("Bitcoin–Lightning Network comparisons","fee structures")))((("fees","Bitcoin–Lightning Network comparisons")))The fee structure in Bitcoin is independent of the transaction value.
A $1 million transaction has the same fee as a $1 transaction on Bitcoin, assuming a similar transaction size, in bytes (more specifically "virtual" bytes after SegWit [Segregated Witness protocol]).
@ -714,7 +714,7 @@ Therefore, in Lightning the payment fee increases with payment value.
These opposing fee structures create different incentives and lead to different usage in regards to transaction value.
A transaction of greater value will be cheaper on Bitcoin; hence, users will prefer Bitcoin for large value transactions. Similarly, on the other end of the scale, users will prefer Lightning for small value transactions.
==== Using the Blockchain as a Ledger versus as a Court System
==== Using the Blockchain as a Ledger Versus as a Court System
((("Bitcoin–Lightning Network comparisons","blockchain: ledger versus court system")))On the Bitcoin network, every transaction is eventually recorded in a block on the blockchain.
The blockchain thus forms a complete history of every transaction since Bitcoin's creation, and a way to fully audit every bitcoin in existence.
@ -728,7 +728,7 @@ If Alice tries to cheat by submitting the opening state of the channel to the Bi
For the Lightning Network, the Bitcoin blockchain acts as a court system.
Like a robotic judge, Bitcoin records the initial and final balances of each channel and approves penalties if one of the parties tries to cheat.
==== Offline versus Online, Asynchronous versus Synchronous
==== Offline Versus Online, Asynchronous Versus Synchronous
((("Bitcoin–Lightning Network comparisons","minimum payment size: satoshi versus millisatoshi")))((("Bitcoin–Lightning Network comparisons","payment activity: asynchronous versus synchronous")))((("millisatoshi")))((("satoshi")))When a Bitcoin user sends funds to a destination address, they do not need to know anything about the recipient. The recipient might be offline or online, and no interaction between sender and recipient is needed. The interaction is between sender and the Bitcoin blockchain. Receiving bitcoin on the Bitcoin blockchain is a _passive_ and _asynchronous_ activity that does not require any interaction by the recipient or for the recipient to be online at any time. Bitcoin addresses can even be generated offline and are never "registered" with the Bitcoin network. Only spending bitcoin requires interaction.
@ -737,7 +737,7 @@ The recipient must run a node or have someone that runs a node on their behalf (
The synchronous and always-online nature of the Lightning Network is probably the biggest difference in the user experience, and this often confounds users who are accustomed to Bitcoin.
==== Satoshis versus Millisatoshis
==== Satoshis Versus Millisatoshis
On the Bitcoin network, the smallest amount is a _satoshi_, which cannot be divided any further. Lightning is a bit more flexible, and Lightning nodes work with _millisatoshis_ (thousandths of a satoshi). This allows tiny payments to be sent via Lightning. A single millisatoshi payment can be sent across a payment channel, an amount so small it should properly be characterized as a _nanopayment_.
@ -464,7 +464,7 @@ We now have a copy of `c-lightning` cloned into the _lightning_ subfolder, and w
==== Compiling the c-lightning Source Code
((("c-lightning Lightning Node project","compiling the c-lightning source code")))Next, we use a set of _build scripts_ that are commonly available in many open source projects. These build scripts use the +configure+ and +make+ commands which allow us to:
((("c-lightning Lightning Node project","compiling the c-lightning source code")))Next, we use a set of _build scripts_ that are commonly available in many open source projects. These build scripts use the +configure+ and +make+ commands, which allow pass:[<span class="keep-together">us to</span>]:
* Select the build options and check necessary dependencies (+configure+)
* Build and install the executables and libraries (+make+)
@ -556,15 +556,15 @@ v0.10.1-34-gfe86c11
The version consists of the latest release version (v0.10.1), followed by the number of changes since the release (34), and finally a hash identifying exactly which revision (fe86c11). You may see a different version from that shown previously as the software continues to evolve long after this book is published. However, no matter what version you see, the fact that the commands execute and respond with version information means that you have succeeded in building the `c-lightning` software.
=== The Lightning Network Daemon (LND) Node Project
=== The Lightning Network Daemon Node Project
((("Lightning Network Daemon (LND) node project", id="ix_04_node_client-asciidoc9", range="startofrange")))((("Lightning node software","Lightning Network Daemon node project", id="ix_04_node_client-asciidoc10", range="startofrange")))The Lightning Network Daemon (LND) is a complete implementation of an LN node by Lightning Labs. The LND project provides a number of executable applications, including +lnd+ (the daemon itself) and +lncli+ (the command-line utility). LND has several pluggable backend chain services, including btcd (a full node), +bitcoind+ (Bitcoin Core), and Neutrino (a new, experimental light client). LND is written in the Go programming language. The project is open source and developed collaboratively on https://github.com/LightningNetwork/lnd[GitHub].(((range="endofrange", startref="ix_04_node_client-asciidoc10")))(((range="endofrange", startref="ix_04_node_client-asciidoc9")))
((("Lightning Network Daemon (LND) node project")))((("Lightning node software","Lightning Network Daemon node project")))The Lightning Network Daemon (LND) is a complete implementation of an LN node by Lightning Labs. The LND project provides a number of executable applications, including +lnd+ (the daemon itself) and +lncli+ (the command-line utility). LND has several pluggable backend chain services, including btcd (a full node), +bitcoind+ (Bitcoin Core), and Neutrino (a new, experimental light client). LND is written in the Go programming language. The project is open source and developed collaboratively on https://github.com/LightningNetwork/lnd[GitHub].
In the next few sections we will build a Docker container to run LND, build LND from source code, and learn how to configure and run LND.
==== The LND Docker Container
((("Lightning Network Daemon (LND) node project","LND Docker container")))We can pull the LND example Docker container from the book's Docker Hub repository:
((("Lightning Network Daemon (LND) node project","LND Docker container")))We can pull the LND example Docker container from the book's Docker Hub pass:[<span class="keep-together">repository</span>]:
[source,bash]
----
@ -993,7 +993,7 @@ services:
The preceding fragment defines a network called +lnnet+ and a container called +bitcoind+ which will attach to the +lnnet+ network. The container is the same one we built at the beginning of this chapter. We expose three of the container's ports, allowing us to send commands to it and monitor blocks and transactions. Next, the configuration specifies an LND container called "Alice." Further down you will also see specifications for containers called "Bob" (`c-lightning`), "Chan" (Eclair), and "Dina" (LND again).
Since all these diverse implementations follow the Basis of Lightning Technology (BOLT) specification and have been extensively tested for interoperability, they have no difficulty working together to build a Lightning network.
Since all these diverse implementations follow the BOLT specification and have been extensively tested for interoperability, they have no difficulty working together to build a Lightning network.
@ -179,7 +179,7 @@ In addition to a Bitcoin and Lightning node, myNode can optionally install a var
==== Umbrel
((("helpers (installation/configuration software)","Umbrel", id="ix_05_node_operations-asciidoc4", range="startofrange")))((("Umbrel", id="ix_05_node_operations-asciidoc5", range="startofrange")))Famous for their UX/UI (shown in <<umbrel>>), _Umbrel_ provides a very easy and accessible way to get your Bitcoin and Lightning node up and running in no time, especially for beginners. A very distinctive feature is that Umbrel utilizes Neutrino/SPV during the initial block download (IBD) so you can instantly start using your node. Once Bitcoin Core is fully synced in the background, it automatically switches over and disables SPV mode. Umbrel OS supports the Raspberry Pi 4 and can also be installed on any Linux-based OS or on a virtual machine on macOS or Windows. You can also connect any wallet that supports Bitcoin Core P2P, Bitcoin Core RPC, the Electrum protocol, or lndconnect.
((("helpers (installation/configuration software)","Umbrel", id="ix_05_node_operations-asciidoc4", range="startofrange")))((("Umbrel", id="ix_05_node_operations-asciidoc5", range="startofrange")))Famous for their UX/UI (shown in <<umbrel>>), _Umbrel_ provides a very easy and accessible way to get your Bitcoin and Lightning node up and running in no time, especially for beginners. A very distinctive feature is that Umbrel utilizes Neutrino/SPV during the IBD so you can instantly start using your node. Once Bitcoin Core is fully synced in the background, it automatically switches over and disables SPV mode. Umbrel OS supports the Raspberry Pi 4 and can also be installed on any Linux-based OS or on a virtual machine on macOS or Windows. You can also connect any wallet that supports Bitcoin Core P2P, Bitcoin Core RPC, the Electrum protocol, or lndconnect.
There's no need to wait for a rainy day—you can go right to https://getumbrel.com[Umbrel] to learn more.
@ -443,8 +443,8 @@ For this test to work, you have to have either a Bitcoin or Lightning node (or b
You can use some very popular and useful websites to find out what is your external IP address and whether it allows and forwards incoming connections to a known port. Here are two that are reliable:
* https://canyouseeme.org/
* https://www.whatismyip.com/port-scanner/
* https://canyouseeme.org[]
* https://www.whatismyip.com/port-scanner[]
By default, these services only allow you to check incoming connections to the IP address from which you are connecting. This is done to prevent you from using the service to scan other people's networks and computers. You will see your router's external IP address and a field for entering a port number. If you haven't changed the default ports in your node configuration, try port 8333 (Bitcoin) and/or 9735 (Lightning).
@ -545,7 +545,7 @@ This is a list of the most basic security measures. It is by no means exhaustive
==== Node Access
((("Lightning node operation","node access")))((("remote procedure call (RPC) API")))((("RPC (remote procedure call) API")))Your Lightning node will expose a remote procedure call (RPC) API. This means that your node can be controlled remotely by commands sent to a specific TCP port. Access control to that RPC API is achieved by some form of user authentication. Depending on the type of Lightning node you set up, this will either be done by username/password authentication or by a mechanism called an authentication _macaroon_. As the name implies, a macaroon is a more sophisticated type of cookie. Unlike a cookie, it is cryptographically signed and can express a set of access capabilities.
((("Lightning node operation","node access")))((("remote procedure call (RPC) API")))((("RPC (remote procedure call) API")))Your Lightning node will expose a remote procedure call (RPC) API. This means that your node can be controlled remotely by commands sent to a specific TCP port. Access control to that RPC API is achieved by some form of user authentication. Depending on the type of Lightning node you set up, this will either be done by pass:[<span class="keep-together">username/password</span>] authentication or by a mechanism called an authentication _macaroon_. As the name implies, a macaroon is a more sophisticated type of cookie. Unlike a cookie, it is cryptographically signed and can express a set of access pass:[<span class="keep-together">capabilities</span>].
For example, LND uses macaroons to grant access to the RPC API. By default, the LND software creates three macaroons with different levels of access, called +admin+, +invoice+, and +readonly+. Depending on which macaroon you copy and use in your RPC client, you either have _read-only_ access, _invoice_ access (which includes the read-only capabilities), or _admin_ access, which gives you full control. There is also a macaroon +bakery+ function in LND that can construct macaroons with any combination of capabilities with very fine-grained control.
@ -572,11 +572,11 @@ You can see that SCBs are not a foolproof safeguard. They are a weak compromise
Channel backup mechanisms are still a work in progress and a weakness in most Lightning implementations.
((("Lightning Network Daemon (LND) node project","SCBs and")))At the time of writing this book, only LND offers a built-in mechanism for SCBs. Eclair has a similar mechanism deployed for server-side deployments, although Eclair Mobile does offer optional backup to a Google Drive. `c-lightning` recently merged the necessary interfaces for a plug-in to implement channel backups. Unfortunately, there is no consistent, agreed upon backup mechanism across different node implementations.
((("Lightning Network Daemon (LND) node project","SCBs and")))At the time of writing this book, only LND offers a built-in mechanism for SCBs. Eclair has a similar mechanism deployed for server-side deployments, although Eclair Mobile does offer optional backup to a Google Drive. `c-lightning` recently merged the necessary interfaces for a plug-in to implement channel backups. Unfortunately, there is no consistent, agreed upon backup mechanism across different node pass:[<span class="keep-together">implementations</span>].
File-based backups of the Lightning node databases are at best a partial solution because you run the risk of backing up an inconsistent database state. In addition, you may not reliably catch the latest state commitments. It is much better to have a backup mechanism that is triggered every time there is a state change in a channel, thereby ensuring data consistency.
To set up SCBs in LND, set the +backupfilepath+ parameter either on the command line or in the configuration file. LND will then save an SCB file in that directory path. Of course, that's only the first step of the solution. Now, you have to set up a mechanism that monitors this file for changes. Each time the file changes, the backup mechanism must copy this file to another, preferably off-site disk. Such backup mechanisms are beyond the scope of this book. Nonetheless, any sophisticated backup solution should be able to handle this scenario. Recall, the backup files should be encrypted too.
To set up SCBs in LND, set the +backupfilepath+ parameter either on the command line or in the configuration file. LND will then save an SCB file in that directory path. Of course, that's only the first step of the solution. Now, you have to set up a mechanism that monitors this file for changes. Each time the file changes, pass:[<span class="keep-together">the backup</span>] mechanism must copy this file to another, preferably off-site disk. Such backup mechanisms are beyond the scope of this book. Nonetheless, any sophisticated backup solution should be able to handle this scenario. Recall, the backup files should be encrypted too.
==== Hot Wallet Risk
@ -626,7 +626,7 @@ You could do this by trusting an intermediary to act as a gateway, but this risk
[NOTE]
====
To use the Loop service you must be running an LND Lightning node.
To use the Loop service, you must be running an LND Lightning node.
====
For the purpose of reducing the balance of your Lightning hot wallet, you would use the Loop Out service. To use the Loop service, you need to install some additional software on your node. The Loop software runs alongside your LND node and provides some command-line tools to execute submarine swaps. You can find the Loop software and installation instructions on https://github.com/lightninglabs/loop[GitHub].
@ -954,7 +954,7 @@ There are a number of competing projects that offer web-based Lightning node man
<<rtl-web-interface>> shows an example screenshot of RTL's web interface, as provided on the project repository.
((("architecture, Lightning Network","layers")))The five layers of the Lightning Network, from the bottom up, are:
Network connection layer:: This contains the protocols that interact directly with the internet core protocols (TCP/IP), overlay protocols (Tor v2/v3), and internet services (DNS). This layer also contains the cryptographic transport protocols that protect Lightning messages.
Network connection layer:: This contains the protocols that interact directly with the internet core protocols (TCP/IP), overlay protocols (Tor v2/v3), and internet services (DNS). This layer also contains the cryptographic transport protocols that protect Lightning pass:[<span class="keep-together">messages</span>].
Messaging layer:: This layer contains the protocols that nodes use to negotiate features, format messages, and encode message fields.
@ -34,22 +34,22 @@ We spent quite some time trying to decide the best order of presenting this deta
Here's what we will cover:
<<payment_channels>>:: In this chapter we will look at how payment channels work, in significantly more depth than we saw in the earlier parts of the book. We will look at the structure and Bitcoin Script of the funding and commitment transactions, and the process used by nodes to negotiate each step in the protocol.
pass:[<a data-type="xref" href="payment_channels" data-xrefstyle="chap-num-title">#payment_channels</a>]:: In this chapter we will look at how payment channels work, in significantly more depth than we saw in the earlier parts of the book. We will look at the structure and Bitcoin Script of the funding and commitment transactions, and the process used by nodes to negotiate each step in the protocol.
<<routing>>:: Next, we will put together several payment channels in a network and route a payment from one end to the other. In that process we will dive into the hash time-locked contract (HTLC) smart contract and the Bitcoin Script that we use to construct it.
pass:[<a data-type="xref" href="#routing" data-xrefstyle="chap-num-title">#routing</a>]:: Next, we will put together several payment channels in a network and route a payment from one end to the other. In that process we will dive into the hash time-locked contract (HTLC) smart contract and the Bitcoin Script that we use to construct it.
<<channel_operation>>:: Putting together the concepts of a simple payment channel and a routed payment using HTLCs, we will now look at how HTLCs are part of each channel's commitment transaction. We will also look at the protocol for adding, settling, failing, and removing HTLCs from the commitments.
pass:[<a data-type="xref" href="#channel_operation" data-xrefstyle="chap-num-title">#channel_operation</a>]:: Putting together the concepts of a simple payment channel and a routed payment using HTLCs, we will now look at how HTLCs are part of each channel's commitment transaction. We will also look at the protocol for adding, settling, failing, and removing HTLCs from the commitments.
<<onion_routing>>:: Next, we will look at how the HTLC information is propagated across the network inside the onion routing protocol. We will look at the mechanism for layered encryption and decryption that gives the Lightning Network some of its privacy characteristics.
pass:[<a data-type="xref" href="#onion_routing" data-xrefstyle="chap-num-title">#onion_routing</a>]:: Next, we will look at how the HTLC information is propagated across the network inside the onion routing protocol. We will look at the mechanism for layered encryption and decryption that gives the Lightning Network some of its privacy characteristics.
<<gossip>>:: In this chapter we will look at how Lightning nodes find each other and learn about published channels to construct a channel graph that they can use to find paths across the network.
pass:[<a data-type="xref" href="#gossip" data-xrefstyle="chap-num-title">#gossip</a>]:: In this chapter we will look at how Lightning nodes find each other and learn about published channels to construct a channel graph that they can use to find paths across the network.
<<path_finding>>:: Next, we will see how the information from the gossip protocol is used by each node to build a "map" of the entire network, which it can use to find paths from one point to another to route payments. We'll also look at the exiting innovations in pathfinding, such as multipart payments.
pass:[<a data-type="xref" href="#path_finding" data-xrefstyle="chap-num-title">>#path_finding</a>]:: Next, we will see how the information from the gossip protocol is used by each node to build a "map" of the entire network, which it can use to find paths from one point to another to route payments. We'll also look at the exiting innovations in pathfinding, such as multipart payments.
<<invoices>>:: A key part of the Lightning Network is payment requests, also known as Lightning invoices. In this chapter we dissect the structure and encoding of an invoice.
pass:[<a data-type="xref" href="#wire_protocol" data-xrefstyle="chap-num-title">#wire_protocol</a>]:: Underpinning the Lightning Network is the peer-to-peer protocol that nodes use to exchange messages about the network and about their channels. In this chapter we look at how those messages are constructed and the extension capabilities built into messages with feature bits and Type-Length-Value (TLV) encoding.
<<wire_protocol>>:: Underpinning the Lightning Network is the peer-to-peer protocol that nodes use to exchange messages about the network and about their channels. In this chapter we look at how those messages are constructed and the extension capabilities built into messages with feature bits and Type-Length-Value (TLV) encoding.
pass:[<a data-type="xref" href="#encrypted_message_transport" data-xrefstyle="chap-num-title">#encrypted_message_transport</a>]:: Moving down to the lower-level part of the network, we will look at the underlying encrypted transport system that ensures the secrecy and integrity of all communications between nodes.(((range="endofrange", startref="ix_06_lightning_architecture-asciidoc0")))
<<encrypted_message_transport>>:: Moving down to the lower-level part of the network, we will look at the underlying encrypted transport system that ensures the secrecy and integrity of all communications between nodes.(((range="endofrange", startref="ix_06_lightning_architecture-asciidoc0")))
pass:[<a data-type="xref" href="#invoices" data-xrefstyle="chap-num-title">#invoices</a>]:: A key part of the Lightning Network is payment requests, also known as Lightning invoices. In this chapter we dissect the structure and encoding of an invoice.
@ -131,7 +132,7 @@ To open a payment channel, two nodes must first be connected as direct peers by
[TIP]
====
We describe two different protocols in this scenario. First, there is a _message protocol_, which establishes how the Lightning nodes communicate over the internet and what messages they exchange with each other. Second, there is the _cryptographic protocol_, which establishes how the two nodes construct and sign Bitcoin transactions.
We describe two different protocols in this scenario. First, there is a _message protocol_, which establishes how the Lightning nodes communicate over the internet and what messages they exchange with each other. Second, there is the _cryptographic protocol_, which establishes how the two nodes construct and sign Bitcoin pass:[<span class="keep-together">transactions</span>].
====
[[peer_protocol_channel_management]]
@ -260,12 +261,10 @@ The two most important fields in +accept_channel+ that Alice will use to constru
Alice's node constructs a multisignature script as shown here:
[[A_B_multisig]]
.A 2-of-2 multisig script with Alice and Bob's funding_pubkey values
Note that, in practice, the funding keys are deterministically _sorted_ (using lexicographical order of the serialized compressed form of the public keys) before being placed in the witness script. By agreeing to this sorted order ahead of time, we ensure that both parties will construct an identical funding transaction output, which is signed by the exchanged commitment transaction signature.
((("payment channel","constructing the funding transaction")))Alice's node can now construct a funding transaction, sending the amount agreed on with Bob (`funding_satoshis`) to the 2-of-2 multisig address. Let's assume that funding_satoshis was 140,000 and Alice is spending a 200,000 satoshi output and creating 60,000 satoshi change. The transaction will look something like Figure 7-4.
((("payment channel","constructing the funding transaction")))Alice's node can now construct a funding transaction, sending the amount agreed on with Bob (`funding_satoshis`) to the 2-of-2 multisig address. Let's assume that funding_satoshis was 140,000 and Alice is spending a 200,000 satoshi output and creating 60,000 satoshi change. The transaction will look something like <<A_B_funding_Tx>>.
[[A_B_funding_Tx]]
.Alice constructs the funding transaction
@ -305,9 +304,9 @@ We can create a similar agreement in Bitcoin. For example, we can create a refun
==== Constructing the Presigned Refund Transaction
((("payment channel","constructing the presigned refund transaction")))((("refund transactions")))Alice will construct the refund transaction immediately after constructing (but not broadcasting) the funding transaction. The refund transaction spends the 2-of-2 multisig back to Alice's wallet. ((("commitment transactions","refund transactions and")))We call this refund transaction a _commitment transaction_ because it commits both channel partners to distributing the channel balance fairly. Since Alice funded the channel on her own, she gets the entire balance, and both Alice and Bob commit to refunding Alice with this transaction.
((("payment channel","constructing the presigned refund transaction")))((("refund transactions")))Alice will construct the refund transaction immediately after constructing (but not broadcasting) the funding transaction. The refund transaction spends the 2-of-2 pass:[<span class="keep-together">multisig</span>] back to Alice's wallet. ((("commitment transactions","refund transactions and")))We call this refund transaction a _commitment transaction_ because it commits both channel partners to distributing the channel balance fairly. Since Alice funded the channel on her own, she gets the entire balance, and both Alice and Bob commit to refunding Alice with this transaction.
In practice, it is a bit more complicated as we will see in subsequent chapters, but for now let's keep things simple and assume it looks like Figure 7-5.
In practice, it is a bit more complicated as we will see in subsequent chapters, but for now let's keep things simple and assume it looks like <<A_B_fund_refund_Tx>>.
[[A_B_fund_refund_Tx]]
.Alice also constructs the refund transaction
@ -321,7 +320,7 @@ Later in this chapter we will see how more commitment transactions can be made t
The refund transaction is not yet a valid transaction. For it to become a valid transaction two things must happen:
* The funding transaction must be broadcast to the Bitcoin network. (To ensure the security of the Lightning Network, we will also require it to be confirmed by the Bitcoin blockchain, though this is not strictly necessary to chain transactions.)
* The funding transaction must be broadcast to the Bitcoin network. (To ensure the security of the Lightning Network, we will also require it to be confirmed by the Bitcoin blockchain, though this is not strictly necessary to chain pass:[<span class="keep-together">transactions</span>].)
* The refund transaction's input needs Alice's and Bob's signatures.
[role="pagebreak-before"]
@ -419,7 +418,7 @@ Let's assume that Alice wants to send 70,000 satoshis to Bob to pay her bill at
==== Splitting the Balance
((("payment channel","splitting the payment balance")))In principle, sending a payment from Alice to Bob is simply a matter of redistributing the balance of the channel. Before the payment is sent, Alice has 140,000 satoshis and Bob has none. After the 70,000 satoshi payment is sent, Alice has 70,000 satoshis and Bob has 70,000 satoshis.
((("payment channel","splitting the payment balance")))In principle, sending a payment from Alice to Bob is simply a matter of redistributing the balance of the channel. Before the payment is sent, Alice has 140,000 satoshis and Bob has none. After the 70,000 satoshi payment is sent, Alice has 70,000 satoshis pass:[<span class="keep-together">and Bob</span>] has 70,000 satoshis.
((("commitment transactions","splitting balances with")))Therefore, all Alice and Bob have to do is create and sign a transaction that spends the 2-of-2 multisig to two outputs paying Alice and Bob their corresponding balances. We call this updated transaction a _commitment transaction_.
@ -475,13 +474,13 @@ Let's look at these three elements in turn.
==== Asymmetric Commitment Transactions
((("commitment transactions","asymmetric")))((("payment channel","asymmetric commitment transactions")))Alice and Bob hold slightly different commitment transactions. Let's look specifically at Commitment #2 from <<competing_commitments_1>>, in more detail in Figure 7-7.
((("commitment transactions","asymmetric")))((("payment channel","asymmetric commitment transactions")))Alice and Bob hold slightly different commitment transactions. Let's look specifically at Commitment #2 from <<competing_commitments_1>>, in more detail in <<commitment_2>>.
Alice and Bob hold two different variations of this transaction, as shown in <<asymmetric_1>>.
Alice and Bob hold two different variations of this transaction, as illustrated in <<asymmetric_1>>.
[[asymmetric_1]]
.Asymmetric commitment transactions
@ -497,7 +496,7 @@ Bob holds the mirror image of that transaction, where the first output is 80,000
((("payment channel","delayed spending to_self")))Using asymmetric transactions allows the protocol to easily ascribe _blame_ to the cheating party. An invariant that the _broadcasting_ party must always wait ensures that the "honest" party has time to refute the claim and revoke their funds. This asymmetry is manifested in the form of differing outputs for each side: the `to_local` output is always timelocked and can't be spent immediately, whereas the `to_remote` output is not timelocked and can be spent immediately.
In the commitment transaction held by Alice, for example, the `to_local` output that pays her is timelocked for 432 blocks, whereas the `to_remote` output that pays Bob can be spent immediately (see Figure 7-9). Bob's commitment transaction for Commitment #2 is the mirror image: his own (`to_local`) output is timelocked and Alice's `to_remote` output can be spent immediately.
In the commitment transaction held by Alice, for example, the `to_local` output that pays her is timelocked for 432 blocks, whereas the `to_remote` output that pays Bob can be spent immediately (see <<asymmetric_delayed_1>>). Bob's commitment transaction for Commitment #2 is the mirror image: his own (`to_local`) output is timelocked and Alice's `to_remote` output can be spent immediately.
[[asymmetric_delayed_1]]
.Asymmetric and delayed commitment transactions
@ -577,7 +576,7 @@ In other words, the `revocationbase_priv` can only be derived (and used to sign
[TIP]
====
((("relative timelock")))The timelock used in the commitment transaction with +CHECKSEQUENCEVERIFY+ is a _relative timelock_. It counts elapsed blocks from the confirmation of this output. That means it will not be spendable until the +to_self_delay+ block _after_ this commitment transaction is broadcast and confirmed.
((("relative timelock")))The timelock used in the commitment transaction with +CHECK​SE⁠QUENCEVERIFY+ is a _relative timelock_. It counts elapsed blocks from the confirmation of this output. That means it will not be spendable until the +to_self_delay+ block _after_ this commitment transaction is broadcast and confirmed.
====
The second output (to_remote) output of the commitment transaction is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md#to_remote-output[BOLT #3: Commitment Transaction, `to_remote` Output], and in the simplest form is a Pay-to-Witness-Public-Key-Hash (P2WPKH) for +<remote_pubkey>+, meaning that it simply pays the owner who can sign for +<remote_pubkey>+.
@ -34,7 +34,7 @@ This process of connecting a series of payment channels with end-to-end security
In this chapter, we'll dive into the mechanism of routing in the Lightning Network, detailing the precise manner in which payments flow through the network. First, we will clarify the concept of routing and compare it to that of pathfinding, because these are often confused and used interchangeably. Next, we will construct the fairness protocol: an atomic, trustless, multihop protocol used to route payments. To demonstrate how this fairness protocol works, we will be using a physical equivalent of transferring gold coins between four people. Finally, we will look at the atomic, trustless, multihop protocol implementation currently used in the Lightning Network, which is called a hash time-locked contract (HTLC).
=== Routing versus Pathfinding
=== Routing Versus Pathfinding
((("pathfinding","routing versus")))((("routing","pathfinding versus")))It's important to note that we separate the concept of _routing_ from the concept of _pathfinding_. These two concepts are often confused, and the term _routing_ is often used to describe both concepts. Let's remove the ambiguity before we proceed any further.
@ -64,7 +64,7 @@ Essentially, Alice will pay Bob, who will pay Chan, who will pay Dina. No direct
The main challenge is to do this in a way that prevents Bob and Chan from stealing the money that Alice wants delivered to Dina.
==== A Physical Example of "Routing"
=== A Physical Example of "Routing"
((("routing","real-world physical example", id="ix_08_routing_htlcs-asciidoc1", range="startofrange")))To understand how the Lightning Network protects the payment while being routed, we can compare it to an example of routing physical payments with gold coins in the real world.
@ -138,7 +138,11 @@ The secret that "unlocks" the payment is called the _payment secret_.
For now, we keep things simple and assume that Dina's secret is simply the text line: `Dinas secret`. This secret message is called the _payment secret_ or _payment preimage_.
To "commit" to this secret, Dina computes the SHA-256 hash, which when encoded in hexadecimal, can be displayed as follows: `0575965b3b44be51e8057d551c4016d83cb1fba9ea8d6e986447ba33fe69f6b3`.
To "commit" to this secret, Dina computes the SHA-256 hash, which when encoded in hexadecimal, can be displayed as follows:
To facilitate Alice's payment, Dina will create the payment secret and the payment hash, and send the payment hash to Alice. In <<alice_dina_routing_3>> we see that Dina sends the payment hash to Alice via some external channel (dashed line), such as an email or text message.
@ -149,7 +153,7 @@ image::images/mtln_0806.png["Dina sends the hashed secret to Alice"]
Alice doesn't know the secret, but she can rewrite her contract to use the hash of the secret as a proof of payment:
____
_I, Alice, will reimburse you, Bob, with 12 gold coins if you can show me a valid message that hashes to:`057596...`.
_I, Alice, will reimburse you, Bob, with 12 gold coins if you can show me a valid message that hashes to:`057596`....
You can acquire this message by setting up a similar contract with Chan who has to set up a similar contract with Dina.
To assure you that you will be reimbursed, I will provide the 12 gold coins to a trusted escrow before you set up your next contract._
____
@ -164,7 +168,7 @@ Similarly, Chan will also demand a fee and will expect to receive 11 gold coins
Bob's contract with Chan will read:
____
_I, Bob, will reimburse you, Chan, with 11 gold coins if you can show me a valid message that hashes to:`057596...`.
_I, Bob, will reimburse you, Chan, with 11 gold coins if you can show me a valid message that hashes to:`057596`....
You can acquire this message by setting up a similar contract with Dina.
To assure you that you will be reimbursed, I will provide the 11 gold coins to a trusted escrow before you set up your next contract._
____
@ -172,7 +176,7 @@ ____
Once Chan gets the message from the escrow that Bob has deposited the 11 gold coins, Chan sets up a similar contract with Dina:
____
_I, Chan, will reimburse you, Dina, with 10 gold coins if you can show me a valid message that hashes to:`057596...`.
_I, Chan, will reimburse you, Dina, with 10 gold coins if you can show me a valid message that hashes to:`057596`....
To assure you that you will be reimbursed after revealing the secret, I will provide the 10 gold coins to a trusted escrow._
____
@ -184,7 +188,7 @@ It is now up to Dina to reveal the secret, which is the preimage to the hash she
Dina now sends +Dinas secret+ to Chan.
Chan checks that +Dinas secret+ hashes to +057596...+. Chan now has proof of payment and so instructs the escrow service to release the 10 gold coins to Dina.
Chan checks that +Dinas secret+ hashes to +057596+.... Chan now has proof of payment and so instructs the escrow service to release the 10 gold coins to Dina.
Chan now provides the secret to Bob. Bob checks it and instructs the escrow service to release the 11 gold coins to Chan.
@ -296,10 +300,10 @@ As we saw in previous examples, we assume that Alice does not have a direct paym
Remember how Bob and Chan might expect a small compensation for routing the payment through their nodes? Alice wants to pay Dina 50,000 satoshis, but as you will see in the following sections she will send Bob 50,200 satoshis. The extra 200 satoshis will pay Bob and Chan 100 satoshis each, as a routing fee.
====
Now, Alice's node can construct a Lightning payment. In the next few sections, we will see how Alice's node constructs a hash time-locked contract(HTLC) to pay Dina and how that HTLC is forwarded along the path from Alice to Dina.
Now, Alice's node can construct a Lightning payment. In the next few sections, we will see how Alice's node constructs an HTLC to pay Dina and how that HTLC is forwarded along the path from Alice to Dina.
==== On-Chain versus Off-Chain Settlement of HTLCs
==== On-Chain Versus Off-Chain Settlement of HTLCs
((("hash time-locked contracts (HTLCs)","on-chain versus off-chain settlement of")))((("off-chain settlement, on-chain payment versus")))((("on-chain payment","off-chain settlement versus")))((("routing","on-chain versus off-chain settlement of HTLCs")))The purpose of the Lightning Network is to enable _off-chain_ transactions that are trusted just the same as on-chain transactions because no one can cheat. The reason no one can cheat is because at any time, any of the participants can take their off-chain transactions on-chain. Each off-chain transaction is ready to be submitted to the Bitcoin blockchain at any time. Thus, the Bitcoin blockchain acts as a dispute-resolution and final settlement mechanism if necessary.
== Channel Operation and pass:[<span class="keep-together">Payment Forwarding</span>]
((("payment channel","operation", id="ix_09_channel_operation-asciidoc0", range="startofrange")))In this chapter we will bring together payment channels and hash time-locked contracts (HTLCs). In <<payment_channels>> we explained the way Alice and Bob construct a payment channel between their two nodes. We also looked at the commitment and penalty mechanisms that secure the payment channel. In <<routing>> we looked at hash time-locked contracts (HTLCs) and how these can be used to route a payment across a path made of multiple payment channels. In this chapter we bring the two concepts together by looking at how HTLCs are managed on each payment channel, how the HTLCs are committed to the channel state, and how they are settled to update the channel balances.
((("payment channel","operation", id="ix_09_channel_operation-asciidoc0", range="startofrange")))In this chapter we will bring together payment channels and hash time-locked contracts (HTLCs). In <<payment_channels>>, we explained the way Alice and Bob construct a payment channel between their two nodes. We also looked at the commitment and penalty mechanisms that secure the payment channel. In <<routing>>, we looked at HTLCs and how these can be used to route a payment across a path made of multiple payment channels. In this chapter we bring the two concepts together by looking at how HTLCs are managed on each payment channel, how the HTLCs are committed to the channel state, and how they are settled to update the channel balances.
Specifically, we will be discussing "Adding, settling, failing HTLCs" and the "Channel state machine" that form the overlap between the peer-to-peer layer and the routing layer, as highlighted by an outline in <<LN_protocol_channelops_highlight>>.
@ -10,13 +10,13 @@ Specifically, we will be discussing "Adding, settling, failing HTLCs" and the "C
image::images/mtln_0901.png["Channel operation and payment forwarding in the Lightning protocol suite"]
=== Local (Single Channel) versus Routed (Multiple Channels)
=== Local (Single Channel) Versus Routed (Multiple Channels)
((("payment channel","local channel versus routed channels")))Even though it is possible to send payments across a payment channel simply by updating the channel balances and creating new commitment transactions, the Lightning protocol uses HTLCs even for "local" payments across a payment channel. The reason for this is to maintain the same protocol design regardless of whether a payment is only one hop (across a single payment channel) or several hops (routed across multiple payment channels).
By maintaining the same abstraction for both local and remote, we not only simplify the protocol design but also improve privacy. For the recipient of a payment there is no discernible difference between a payment made directly by their channel partner and a payment forwarded by their channel partner on behalf of someone else.
=== Forwarding Payments and Updating Commitments with HTLCs
=== Forwarding Payments and Updating Commitments pass:[<span class="keep-together">with HTLCs</span>]
((("commitment transactions","updating commitments with HTLCs", id="ix_09_channel_operation-asciidoc1", range="startofrange")))((("hash time-locked contracts (HTLCs)","updating commitments with", id="ix_09_channel_operation-asciidoc2", range="startofrange")))((("payment channel","updating commitments with HTLCs", id="ix_09_channel_operation-asciidoc3", range="startofrange")))We will revisit our example from <<routing>> to demonstrate how the HTLCs from Alice to Dina get committed to each payment channel. As you recall in our example, Alice is paying Dina 50,000 satoshis by routing an HTLC via Bob and Chan. The network is shown in <<alice_dina_htlc_2>>.
@ -137,7 +137,7 @@ image::images/mtln_0905.png["Bob's new commitment with an HTLC output"]
Shortly after sending the +update_add_htlc+ message, she will commit to the new state of the channel, so that the HTLC can be safely added by Bob. Bob has the HTLC information and has constructed a new commitment but does not yet have this new commitment signed by Alice.
Alice sends +commitment_signed+ to Bob, with the signature for the new commitment and for the HTLC within. We saw the +commitment_signed+ message in <<payment_channels>>, but now we can understand the rest of the fields. As a reminder, it is shown in Example 9-3.
Alice sends +commitment_signed+ to Bob, with the signature for the new commitment and for the HTLC within. We saw the +commitment_signed+ message in <<payment_channels>>, but now we can understand the rest of the fields. As a reminder, it is shown in <<ops_commitment_signed_message>>.
[[ops_commitment_signed_message]]
.The `commitment_signed` message
@ -212,7 +212,7 @@ Bob now sends a +commitment_signed+ back to Alice, with his signatures for Alice
Now Alice has the signature for the new commitment transaction. The state of the channel is shown in <<signed_commitment_3a>>.
[[signed_commitment_3a]]
.Alice has a new *signed* commitment
.Alice has a new signed commitment
image::images/mtln_0909.png[Alice has a new signed commitment]
Alice can now acknowledge the new commitment by revoking the old one. Alice sends the +revoke_and_ack+ message containing the necessary +per_commitment_point+ that will allow Bob to construct a revocation key and penalty transaction. Thus, Alice revokes her old commitment.
@ -235,7 +235,7 @@ As we will see in the next section, the maximum is only for _pending_ HTLCs beca
=== HTLC Fulfillment
((("hash time-locked contracts (HTLCs)","fulfillment", id="ix_09_channel_operation-asciidoc9", range="startofrange")))((("payment forwarding","HTLC fulfillment", id="ix_09_channel_operation-asciidoc10", range="startofrange")))Now Bob and Alice both have a new commitment transaction with an additional HTLC output, and we have achieved a major step toward updating a payment channel.
((("hash time-locked contracts (HTLCs)","fulfillment", id="ix_09_channel_operation-asciidoc9", range="startofrange")))((("payment forwarding","HTLC fulfillment", id="ix_09_channel_operation-asciidoc10", range="startofrange")))Now Bob and Alice both have a new commitment transaction with an additional HTLC output, and we have achieved a major step toward updating a payment pass:[<span class="keep-together">channel</span>].
The new balance of Alice and Bob does not reflect yet that Alice has successfully sent 50,200 satoshis to Bob.
@ -249,7 +249,7 @@ Next, Chan will do the same with Dina: offer a 50,000 satoshi HTLC, commit, and
==== Dina Fulfills the HTLC with Chan
Dina can settle the HTLC by sending an +update_fulfill_htlc+ message to Chan. The +update_fulfill_htlc+ message is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#removing-an-htlc-update_fulfill_htlc-update_fail_htlc-and-update_fail_malformed_htlc[BOLT #2: Peer Protocol, `update_fulfill_htlc`] and is shown here:
Dina can settle the HTLC by sending an +update_ful⁠fill_​htlc+ message to Chan. The +update_fulfill_htlc+ message is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#removing-an-htlc-update_fulfill_htlc-update_fail_htlc-and-update_fail_malformed_htlc[BOLT #2: Peer Protocol, `update_fulfill_htlc`] and is shown here:
[[update_fulfill_htlc_message]]
.The +update_fulfill_htlc+ message
@ -306,6 +306,7 @@ Next, they complete two rounds of commitment and revocation. First, Alice sends
.Alice signs Bob's new commitment and Bob revoked the old one
image::images/mtln_0913.png[Alice signs Bob's new commitment and Bob revoked the old one]
[role="pagebreak-before"]
Finally, Bob signs Alice's commitment by sending Alice a +commitment_signed+ message. Then Alice acknowledges and revokes her old commitment by sending +revoke_and_ack+ to Bob. The end result is that both Alice and Bob have moved their channel state to Commitment #4, have removed the HTLC, and have updated their balances. Their current channel state is represented by the commitment transactions that are shown in <<alice_bob_htlc_fulfilled>>(((range="endofrange", startref="ix_09_channel_operation-asciidoc12")))(((range="endofrange", startref="ix_09_channel_operation-asciidoc11"))). (((range="endofrange", startref="ix_09_channel_operation-asciidoc10")))(((range="endofrange", startref="ix_09_channel_operation-asciidoc9")))
[[alice_bob_htlc_fulfilled]]
@ -330,7 +331,7 @@ The +update_fail_htlc+ message is shown in the following:
[len*byte:reason]
----
It's pretty self-explanatory. The multibyte +reason+ field is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages[BOLT #4: Onion Routing], which we will describe in more detail in <<onion_routing>>.
It's pretty self-explanatory. The multibyte +reason+ field is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#failure-messages[BOLT #4: Onion Routing], which we will describe in <<onion_routing>>.
If Alice received an +update_fail_htlc+ from Bob, the process would unfold in much the same way: the two channel partners would remove the HTLC, create updated commitment transactions, and go through two rounds of commitment/revocation to move the channel state forward to the next commitment. The only difference: the end balances would revert back to what they were without the HTLC, essentially refunding Alice for the HTLC value.
@ -287,7 +287,7 @@ For simplicity and to avoid getting too technical, we have not included these de
[[ecdh]]
[[ecdh_explained]]
.Elliptic Curve Diffie–Hellman (ECDH) Explained
.Elliptic Curve Diffie–Hellman Explained
****
((("ECDH (Elliptic Curve Diffie–Hellman)")))((("Elliptic Curve Diffie–Hellman (ECDH)")))Assume Alice's private key is _a_ and Bob's private key is _b_. Using the elliptic curve, Alice and Bob each multiply their private key by the generator point _G_ to produce their public keys _A_ and _B_, respectively:
@ -416,12 +416,12 @@ At each hop, the hop payload appears at the beginning of the onion payload, foll
[TIP]
====
The onion payload is 1,300 bytes. Each hop payload is 65 bytes or less (padded to 65 bytes if less). So the total onion payload can fit 20 hop payloads (1300 = 20 x 65). The maximum onion routed path is therefore 20 hops.
The onion payload is 1,300 bytes. Each hop payload is 65 bytes or less (padded to 65 bytes if less). So the total onion payload can fit 20 hop payloads (1300 = 20 × 65). The maximum onion routed path is therefore 20 hops.
====
As each layer is "peeled off," more filler data (essentially junk) is added at the end of the onion payload so the next hop gets an onion of the same size and is once again the "first hop" in the onion.
The onion size is 1,366 bytes, structured as shown in <<onion_packet>>.
The onion size is 1,366 bytes, structured as shown in <<onion_packet>>:
1 byte:: A version byte
33 bytes:: A compressed public session key (<<session_key>>) from which the per-hop shared secret (<<shared_secret>>) can be generated without revealing Alice's identity
@ -480,7 +480,7 @@ The inner HMAC is then revealed during the inverse of the "shift and encrypt" ro
((("onion routing","wrapping hop payloads", id="ix_10_onion_routing-asciidoc12", range="startofrange")))As a reminder, the onion is wrapped by starting at the end of the path from Dina, the final node or recipient. Then the path is built in reverse all the way back to the sender, Alice.
Alice starts with an empty 1,300-byte field, the fixed-length _onion payload_. Then, Alice fills the onion payload with a pseudorandom byte stream "filler" that is generated from the ++pad++ key.
Alice starts with an empty 1,300-byte field, the fixed-length _onion payload_. Then, she fills the onion payload with a pseudorandom byte stream "filler" that is generated from the ++pad++ key.
This is shown in <<onion_payload_filler>>.
@ -586,10 +586,6 @@ In <<bob_onion_wrapping>> we see the steps used to wrap Bob's hop payload in the
All right, by now this is easy!
[[bob_onion_wrapping]]
.Wrapping the onion for Bob
image::images/mtln_1021.png[]
Start with the onion payload (obfuscated) containing Chan's and Dina's hop payloads.
Obtain the session key for this hop dervied from the blinding factor generated by the prior hop.
@ -600,6 +596,10 @@ Obfuscate the whole thing XOR with the ++rho++ key from the Alice-Bob shared sec
Calculate the outer HMAC and stick it on the end of Bob's hop payload.(((range="endofrange", startref="ix_10_onion_routing-asciidoc12")))
[[bob_onion_wrapping]]
.Wrapping the onion for Bob
image::images/mtln_1021.png[]
==== The Final Onion Packet
@ -646,7 +646,9 @@ Alice will send the +update_add_htlc+ message to Bob. Let's look at what this me
+amount_msat+:: The amount of the HTLC: 50,200,000 millisatoshis.
+payment_hash+:: The RIPEMD160(SHA-256) payment hash, +9e017f6767971ed7cea17f98528d5f5c0ccb2c71+.
+payment_hash+:: The RIPEMD160(SHA-256) payment hash:
+
+9e017f6767971ed7cea17f98528d5f5c0ccb2c71+.
+cltv_expiry+:: The expiry timelock for the HTLC will be 700,058. Alice adds 20 blocks to the expiry set in Bob's payload according to Bob's negotiated +cltv_expiry_delta+.
@ -715,6 +717,7 @@ Bob now has a 1,300-byte onion packet to send to the next hop. It is almost iden
.Bob removes the hop payload and left-shifts the rest, filling the gap with new filler
image::images/mtln_1025.png["Bob removes the hop payload and left-shifts the rest, filling the gap with new filler"]
[role="pagebreak-before"]
No one can tell the difference between filler put there by Alice and filler put there by Bob. Filler is filler! It's all random bytes anyway. Note that if Bob (or one of Bob's other aliases) is present in the route in two distinct locations, then they can tell the difference because the base protocol always uses the same payment hash across the entire route. Atomic multipath payments (AMPs) and Point Time-Locked Contracts (PTLCs) eliminate the correlation vector by randomizing the payment identifier across each route/hop.
==== Bob Constructs the New Onion Packet
@ -755,7 +758,11 @@ Bob now constructs and HTLC to send to Chan, as follows:
+amount_msat+:: The amount of the HTLC: 50,100,000 millisatoshis.
+payment_hash+:: The RIPEMD160(SHA-256) payment hash, +9e017f6767971ed7cea17f98528d5f5c0ccb2c71+. This is the same as the payment hash from Alice's HTLC.
+payment_hash+:: The RIPEMD160(SHA-256) payment hash:
@ -61,7 +61,7 @@ Because the Lightning Network is a peer-to-peer network, some initial bootstrapp
As an initial step, our new node needs to somehow _discover_ at least _one_ peer that is already connected to the network and has a full channel graph (as we'll see later, there's no canonical version of the channel graph). Using one of many initial bootstrapping protocols to find that first peer, after a connection is established, our new
peer now needs to _download_ and _validate_ the channel graph. Once the channel graph has been fully validated, our new peer is ready to start opening channels and sending payments on the network.
After initial bootstrap, a node on the network needs to continue to maintain its view of the channel graph by processing new channel routing policy updates, discovering and validating new channels, removing channels that have been closed on-chain, and finally pruning channels that fail to send out a proper "heartbeat" every two weeks or so.
After initial bootstrap, a node on the network needs to continue to maintain its view of the channel graph by processing new channel routing policy updates, discovering and validating new channels, removing channels that have been closed on-chain, and finally pruning channels that fail to send out a proper "heartbeat" every two weeks pass:[<span class="keep-together">or so</span>].
Upon completion of this chapter, you will understand a key component of
the peer-to-peer Lightning Network: namely, how peers discover each other and maintain a local copy (perspective) of the channel graph. We'll begin by exploring the story of a new node that has just booted up and needs to find other peers to connect to on the network.(((range="endofrange", startref="ix_11_gossip_channel_graph-asciidoc1")))(((range="endofrange", startref="ix_11_gossip_channel_graph-asciidoc0")))
In the preceding command, we've queried the server so we can obtain an IPv4 (+A+ record) address for our target node (replaced by ++__X.X.X.X__++ in the preceding example). Now that we have the raw public key, IP address, and TCP port, we can connect to the node transport protocol at:
In the preceding command, we've queried the server so we can obtain an IPv4 pass:[<span class="keep-together">(<code>A</code> record)</span>] address for our target node (replaced by ++__X.X.X.X__++ in the preceding example). Now that we have the raw public key, IP address, and TCP port, we can connect to the node transport protocol at:
Breaking down the query one key-value pair at a time, we gain the following
insights:
* +r0+: The query targets the Bitcoin realm
* +a2+: The query only wants IPv4 addresses to be returned
* +n10+: The query requests
+r0+:: The query targets the Bitcoin realm
+a2+:: The query only wants IPv4 addresses to be returned
+n10+:: The query requests
Try some combinations of the various flags using the +dig+ DNS command-line tool yourself(((range="endofrange", startref="ix_11_gossip_channel_graph-asciidoc3")))(((range="endofrange", startref="ix_11_gossip_channel_graph-asciidoc2"))):
@ -360,7 +360,7 @@ Due to the existence of unadvertised channels, the _true_ size of the channel gr
((("blockchain","locating a channel on the Bitcoin blockchain")))((("channel_announcement message","locating a channel on the Bitcoin blockchain")))As mentioned earlier, the channel graph is authenticated due to its usage of public key cryptography, as well as the Bitcoin blockchain as a spam prevention system. To have a node accept a new +channel_announcement+, the advertisement must _prove_ that the channel actually exists in the Bitcoin blockchain. This proof system adds an up-front cost to adding a new entry to the channel graph (the on-chain fees one must pay to create the UTXO of the channel). As a result, we mitigate spam and ensure that a dishonest node on the network can't fill up the memory of an honest node at no cost with bogus channels.
Given that we need to construct a proof of the existence of a channel, a
natural question that arises is: how do we "point to" or reference a given channel for the verifier? Given that a payment channel is anchored in an unspent transaction output (see <<utxo>>), an initial thought might be to first attempt to advertise the full outpoint (+txid:index+) of the channel. Given the outpoint is globally unique and confirmed in the chain, this sounds like a good idea; however, it has a drawback: the verifier must maintain a full copy of the UTXO set to verify channels. This works fine for Bitcoin full nodes, but clients that rely on lightweight verification don't typically maintain a full UTXO set. Because we want to ensure we can support mobile nodes in the Lightning Network, we're forced to find another solution.
natural question that arises is: how do we "point to" or reference a given channel for the verifier? Given that a payment channel is anchored in an unspent transaction output (see <<utxo>>), an initial thought might be to first attempt to advertise the full outpoint (+txid:index+) of the channel. Given that the outpoint is globally unique and confirmed in the chain, this sounds like a good idea; however, it has a drawback: the verifier must maintain a full copy of the UTXO set to verify channels. This works fine for Bitcoin full nodes, but clients that rely on lightweight verification don't typically maintain a full UTXO set. Because we want to ensure we can support mobile nodes in the Lightning Network, we're forced to find another solution.
What if rather than referencing a channel by its UTXO, we reference it based on its "location" in the chain? To do this, we'll need a scheme that allows us to reference a given block, then a transaction within that block, and finally a specific output created by that transaction. Such an identifier is described in https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md[BOLT #7] and is referred to as a _short channel ID_, or +scid+.
The +scid+ is used in +channel_announcement+ (and +channel_update+) as well as within the onion-encrypted routing packet included within HTLCs, as we learned in <<onion_routing>>.
@ -142,11 +142,11 @@ Most Lightning node and wallet implementations improve on this approach by order
. Find paths connecting the sender to the recipient.
. Order the paths by some weight (this may be part of the previous step's algorithm).
. Order the paths by some weight (this may be part of the previous step's pass:[<span class="keep-together">algorithm</span>]).
. Try each path in order until payment succeeds (the trial-and-error loop).
. Optionally use the HTLC failure returns to update our graph, reducing uncertainty.
. Optionally use the HTLC failure returns to update our graph, reducing pass:[<span class="keep-together">uncertainty</span>].
We can group these steps into three primary activities:
@ -174,7 +174,7 @@ Depending on the algorithm we will use for pathfinding, we may establish a numbe
For now, let's ignore the cost function and simply establish a channel graph showing nodes and channels, using the +node_announcement+ and +channel_announcement+ messages.
In this chapter we will see how Selena attempts to find a path to pay Rashid 1,000,000 (1M) satoshis. To start, Selena is constructing a channel graph using the information from Lightning Network gossip to discover nodes and channels. Selena will then explore her channel graph to find a path to send a payment to Rashid.
In this chapter we will see how Selena attempts to find a path to pay Rashid one million satoshis. To start, Selena is constructing a channel graph using the information from Lightning Network gossip to discover nodes and channels. Selena will then explore her channel graph to find a path to send a payment to Rashid.
This is _Selena's_ channel graph. There is no such thing as _the_ channel graph, there is only ever _a channel graph_, and it is always from the perspective of the node that has constructed it (see <<map_territory_relation>>).
@ -276,7 +276,7 @@ In other words, "The more channels (hops) you use, the lower the chance of succe
[NOTE]
====
There is a lot of mathematical theory and modeling behind the uncertainty of the liquidity in the channels. Fundamental work about modeling the uncertainty intervals of the channel liquidity can be found in the paper https://arxiv.org/abs/2103.08576["Security and Privacy of Lightning Network Payments with Uncertain Channel Balances"] by (coauthor of this book) Pickhardt et al.
There is a lot of mathematical theory and modeling behind the uncertainty of the liquidity in the channels. Fundamental work about modeling the uncertainty intervals of the channel liquidity can be found in the paper https://arxiv.org/abs/2103.08576["Security and Privacy of Lightning Network Payments with Uncertain Channel Balances"] by (coauthor of this book) Pickhardt pass:[<span class="keep-together">et al</span>].
====
==== Fees and Other Channel Metrics
@ -353,7 +353,7 @@ image::images/mtln_1208.png[]
===== Learning from success
Selena has also learnt a lot from this successful payment. She now knows that all the channels on the path S->A->B->X->Y->R had enough liquidity to deliver the payment. Furthermore, she now knows that each of these channels has moved the HTLC amount (1M + fees) to the other end of the channel. This allows Selena to recalculate the range of liquidity on the receiving side of all the channels in that path, replacing the minimum liquidity with 1M + fees.
Selena has also learned a lot from this successful payment. She now knows that all the channels on the path S->A->B->X->Y->R had enough liquidity to deliver the payment. Furthermore, she now knows that each of these channels has moved the HTLC amount (1M + fees) to the other end of the channel. This allows Selena to recalculate the range of liquidity on the receiving side of all the channels in that path, replacing the minimum liquidity with 1M + fees.
===== Stale knowledge?
@ -364,7 +364,7 @@ However, this knowledge becomes somewhat "stale" as the other nodes send or rout
Therefore, Selena's node must consider how long to keep this knowledge before assuming that it is stale and no longer useful(((range="endofrange", startref="ix_12_path_finding-asciidoc9")))(((range="endofrange", startref="ix_12_path_finding-asciidoc8"))).
[[mpp]]
=== Multipart Payments (MPP)
=== Multipart Payments
((("multipart payments (MPP)", id="ix_12_path_finding-asciidoc10", range="startofrange")))((("payment delivery","multipart payments", id="ix_12_path_finding-asciidoc11", range="startofrange")))_Multipart payments (MPP)_ are a feature that was introduced in the Lightning Network in 2020 and are already very widely available. Multipart payments allow a payment to be split into multiple _parts_ which are sent as HTLCs over several different paths to the intended recipient, preserving the _atomicity_ of the overall payment. In this context, atomicity means that either all the HTLC parts of a payment are eventually fulfilled or the entire payment fails and all the HTLC parts fail. There is no possibility of a partially successful payment.
@ -11,7 +11,7 @@ that have been built into the protocol.
=== Messaging Layer in the Lightning Protocol Suite
((("Lightning Network Protocol","messaging layer")))((("wire protocol","messaging layer in the Lightning Protocol Suite")))The messaging layer, which is detailed in this chapter, consists of "Framing and message format," "Type-Length-Value (TLV)" encoding, and "Feature bits." These components are highlighted by an outline in the protocol suite, shown in <<LN_protocol_wire_message_highlight>>.
((("Lightning Network Protocol","messaging layer")))((("wire protocol","messaging layer in the Lightning Protocol Suite")))The messaging layer, which is detailed in this chapter, consists of "Framing and message format," "Type-Length-Value" encoding, and "Feature bits." These components are highlighted by an outline in the protocol suite, shown in <<LN_protocol_wire_message_highlight>>.
[[LN_protocol_wire_message_highlight]]
.Messaging layer in the Lightning protocol suite
@ -102,7 +102,7 @@ including the prefix type of the message along with the contents of its message
((("Type-Length-Value (TLV) message extensions","message extensions in wire protocol")))((("wire protocol","TLV message extensions")))Earlier in this chapter we mentioned that messages can be up to 65 KB in size,
and if while parsing a message, extra bytes are left over, then those bytes
@ -151,7 +151,7 @@ transactions they don't understand, then they simply ignore them as their funds
aren't using those new features.
[[tlv]]
=== Type-Length-Value (TLV) Format
=== Type-Length-Value Format
((("Type-Length-Value (TLV) format", id="ix_13_wire_protocol-asciidoc3", range="startofrange")))((("Type-Length-Value (TLV) format","wire protocol and", id="ix_13_wire_protocol-asciidoc4", range="startofrange")))((("wire protocol","TLV format", id="ix_13_wire_protocol-asciidoc5", range="startofrange")))To be able to upgrade messages in a manner that is both forward and backward
compatible, in addition to feature bits (more on that later), the Lightning Network utilizes a custom message serialization format plainly called Type-Length-Value, or TLV for short. The format was inspired by the widely used Protobuf
@ -167,7 +167,7 @@ implementation of the TLV message format weighs in at only 2.3k lines of code
With the necessary background presented, we're now ready to describe the TLV
format in detail. A TLV message extension is said to be a stream of
individual TLV records. A single TLV record has three components: the type of
individual pass:[<span class="keep-together">TLV records</span>]. A single TLV record has three components: the type of
the record, the length of the record, and finally the opaque value of the
@ -132,9 +132,9 @@ hear during a thunderstorm when very far away.
((("Lightning encrypted transport protocol","elements of", id="ix_14_encrypted_transport-asciidoc1", range="startofrange")))In this section we will break down the Lightning encrypted transport protocol and delve into the details of the cryptographic algorithms and protocol used to establish encrypted, authenticated, and integrity-assured communications between peers. Feel free to skip this section if you find this level of detail daunting.
((("Lightning encrypted transport protocol","Noise XK")))((("Noise Protocol Framework","Noise XK")))((("Noise_XK")))The Noise Protocol is extremely flexible in that it advertises several
((("Lightning encrypted transport protocol","Noise_XK")))((("Noise Protocol Framework","Noise_XK")))((("Noise_XK")))The Noise Protocol is extremely flexible in that it advertises several
handshakes, each with different security and privacy properties for a would-be
protocol implementer to select from. A deep exploration of each of the
handshakes and their various trade-offs is out of the scope of this chapter.
@ -168,7 +168,7 @@ between two ephemeral keys.
==== High-Level Overview
((("Lightning encrypted transport protocol","high-level overview")))((("Noise_XK","high-level overview")))Using the notation laid out earlier, we can succinctly describe the `Noise_XK`
as follows:
as pass:[<span class="keep-together">follows</span>]:
```
Noise_XK(s, rs):
<- rs
@ -599,7 +599,7 @@ Where `len` obtains the length in bytes of the Lightning message.
* The nonce `sn` must be incremented after this step.
* A zero-length byte slice is to be passed as the AD (associated data).
4. Finally, encrypt the message itself (`m`) using the same procedure used to
encrypt the length prefix. Let this encrypted ciphertext be known as `c`.
encrypt the length prefix. Let this encrypted ciphertext be known pass:[<span class="keep-together">as <code>c</code></span>].
+
The nonce `sn` must be incremented after this step.
5. Send `lc || c` over the network buffer.
@ -616,7 +616,7 @@ steps are completed:
* A zero-length byte slice is to be passed as the AD (associated data).
* The nonce `rn` must be incremented after this step.
4. Read _exactly_ `l + 16` bytes from the network buffer, and let the bytes be
known as `c`.
known pass:[<span class="keep-together">as <code>c</code></span>].
5. Decrypt `c` (using `ChaCha20-Poly1305`, `rn`, and `rk`) to obtain decrypted
@ -24,7 +24,7 @@ to complete a payment from receiver to sender is described in https://github.com
payment hash and destination are communicated in a payment request to
make the encoding more fully featured.
=== Lightning Payment Requests versus Bitcoin Addresses
=== 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?
@ -57,7 +57,7 @@ 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 and Interpretation
((("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
@ -71,9 +71,12 @@ possibly an on-chain fallback address are also communicated. The full specificat
((("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:
@ -16,7 +16,7 @@ Unlike trivial scaling solutions like custodial Bitcoin banks, the Lightning Net
First, a privacy researcher would define a _security model_ that specifies what an adversary is capable of and aims to achieve.
Then, they would describe the relevant properties of the system and check whether it conforms to the requirements.
==== Process to Evaluate Privacy
=== Process to Evaluate Privacy
((("security and privacy","evaluation process for privacy")))((("security assumptions")))A security model is based on a set of underlying _security assumptions_.
In cryptographic systems, these assumptions are often centered around the mathematical properties of the cryptographic primitives, such as ciphers, signatures, and hash functions.
@ -80,7 +80,7 @@ Imagine you meet a person on a city street.
What is their anonymity set from your point of view?
If you don't know them personally, and without any additional information, their anonymity set roughly equals the city's population, including travelers.
If you additionally consider their appearance, you may be able to roughly estimate their age and exclude the city residents who are obviously older or younger than the person in question from the anonymity set.
Furthermore, if you notice that the person walks into the office of Company X using an electronic badge, the anonymity set shrinks to the number of Company X's employees and visitors.
Furthermore, if you notice that the person walks into the office of Company X using an electronic badge, the anonymity set shrinks to the number pass:[<span class="keep-together">of Company</span>] X's employees and visitors.
Finally, you may notice the license number of the car they used to arrive at the place.
If you are a casual observer, this doesn't give you much.
However, if you are a city official and have access to the database that matches license plate numbers with names, you can narrow down the anonymity set to just a few people: the car owner and any close friends and relatives that may have borrowed the car.
@ -523,7 +523,7 @@ Let's look at some of the relevant incentives:
In the early stages of the Lightning Network, many node operators have claimed that the earned routing fees do not compensate for the opportunity costs stemming from liquidity lock-up. This would indicate that operating a node may be driven mostly by altruistic incentives "for the good of the network."
This might change in the future if the Lightning Network has significantly larger traffic or if a market for routing fees emerges.
On the other hand, if a node wishes to optimize its routing fees, it would minimize the average shortest path lengths to every other node.
Put differently, a profit-seeker node will try to locate itself in the _center_ of the channel graph or close to it.
Put differently, a profit-seeker node will try to locate itself in the _center_ of the channel graph or close pass:[<span class="keep-together">to it</span>].
=== Practical Advice for Users to Protect Their Privacy
@ -53,7 +53,7 @@ eltoo:: A proposed channel mechanism that uses input-rebinding to significantly
==== Opt-In End-to-End Features
((("innovations in Lightning","opt-in end-to-end features")))Point Time-Locked Contracts (PTLCs):: A different approach to HTLCs, PTLCs can increase privacy, reduce information leaked to intermediary nodes, and operate more efficiently than HTLC-based channels.
((("innovations in Lightning","opt-in end-to-end features")))Point Time-Locked Contracts:: A different approach to HTLCs, PTLCs can increase privacy, reduce information leaked to intermediary nodes, and operate more efficiently than HTLC-based channels.
Large channels:: Large or _Wumbo_ channels were introduced in a dynamic way to the network without requiring coordination. Channels that support large payments are advertized as part of the channel announcement messages and can be used in an opt-in manner.
For example, if we use a command-line terminal to feed the text "Mastering the Lightning Network" into the SHA-256 function, it will produce a fingerprint as follows:
----
@ -97,7 +97,7 @@ Uncorrelated:: A small change in the input produces such a big change in the out
Uniform/random:: A cryptographic hash function produces hashes that are uniformly distributed across the entire 256-bit space of possible outputs. The output of a hash appears to be random, though it is not truly random.
Using these features of cryptographic hashes, we can build some interesting applications:
Using these features of cryptographic hashes, we can build some interesting pass:[<span class="keep-together">applications</span>]:
Fingerprints:: A hash can be used to fingerprint a file or message so that it can be uniquely identified. Hashes can be used as universal identifiers of any data set.
@ -192,16 +192,17 @@ While the transactions created by the Lightning Network have multiple outputs, t
((("Bitcoin transactions","transaction chains")))((("transaction chains")))Every output can be spent as an input in a subsequent transaction. So, for example, if Bob decided to spend 10,000 satoshi in a transaction paying Chan, and Chan spent 4,000 satoshi to pay Dina, it would play out as shown in <<tx_chain>>.
[[tx_chain]]
.Alice pays Bob who pays Chan who pays Dina
image::images/mtln_aa06.png["Alice pays Bob who pays Chan who pays Dina"]
An output is considered _spent_ if it is referenced as an input in another transaction that is recorded on the blockchain. An output is considered _unspent_ (and available for spending) if no recorded transaction references it.
The only type of transaction that doesn't have inputs is a special transaction created by Bitcoin miners called the _coinbase transaction_. The coinbase transaction has only outputs and no inputs because it creates new bitcoin from mining. Every other transaction spends one or more previously recorded outputs as its inputs.
Since transactions are chained, if you pick a transaction at random, you can follow any one of its inputs backward to the previous transaction that created it. If you keep doing that, you will eventually reach a coinbase transaction where the bitcoin was first mined.
[[tx_chain]]
.Alice pays Bob who pays Chan who pays Dina
image::images/mtln_aa06.png["Alice pays Bob who pays Chan who pays Dina"]
==== TxID: Transaction Identifiers
((("Bitcoin transactions","transaction identifiers")))((("TxID (transaction identifiers)")))Every transaction in the Bitcoin system is identified by a unique identifier (assuming the existence of BIP-0030), called the _transaction ID_ or _TxID_ for short. To produce a unique identifier, we use the SHA-256 cryptographic hash function to produce a hash of the transaction's data. This "fingerprint" serves as a universal identifier. A transaction can be referenced by its transaction ID, and once a transaction is recorded on the Bitcoin blockchain, every node in the Bitcoin network knows that this transaction is valid.
@ -213,9 +214,7 @@ For example, a transaction ID might look like this:
This is a real transaction (created as an example for the _Mastering Bitcoin_ book) that can be found on the Bitcoin blockchain.
Try to find it by entering this TxID into a block explorer:
This is a real transaction (created as an example for the _Mastering Bitcoin_ book) that can be found on the Bitcoin blockchain. Try to find it by entering this TxID into a block explorer:
@ -77,7 +77,7 @@ To resume an already existing container, use the `start` command like so:
==== Deleting a Container by Name
((("Docker containers","deleting a container by name")))If you name a container instead of letting Docker name it randomly, you cannot reuse that name until the container is deleted. Docker will return an error like this:
[source,bash]
----
docker: Error response from daemon: Conflict. The container name "/bitcoind" is already in use...
* https://commons.wikimedia.org/wiki/File:Introduction_to_the_Lightning_Network_Protocol_and_the_Basics_of_Lightning_Technology_(BOLT_aka_Lightning-rfc).pdf[Wikimedia Commons, "Introduction to the Lightning Network Protocol and the Basics of Lightning Technology"]
* https://w.wiki/4QCf[Wikimedia Commons, "Introduction to the Lightning Network Protocol and the Basics of Lightning Technology"]
[role="pagebreak-before less_space"]
=== BTCPay Server
BTCPay Server https://github.com/btcpayserver/btcpayserver-media[logo, screenshots, and other images] used with permission under the https://github.com/btcpayserver/btcpayserver-media/blob/master/LICENSE[MIT License]:
@ -179,6 +179,8 @@ and `pong` messages are defined.
[[apdx_ping_message]]
===== The ping message
The `ping` message is used to check whether the other party in a connection is "live." It contains the following fields:
* Type: 18
* Fields:
** `uint16` : `num_pong_bytes`
@ -190,6 +192,8 @@ Next its companion, the `pong` message.
[[apdx_pong_message]]
===== The pong message
The +pong+ message is sent in response to the +ping+ message and contains the following fields:
* Type: 19
* Fields:
** `uint16` : `pong_body_len`
@ -231,6 +235,8 @@ The detailed protocol flow using these messages is described in <<payment_channe
[[apdx_open_channel_message]]
===== The open_channel message
The +open_channel+ message starts the channel funding process and contains the following fields:
* Type: 32
* Fields:
** `chain_hash` : `chain_hash`
@ -281,6 +287,7 @@ commonly referred to as a private channel.
((("accept_channel message")))((("wire protocol messages","accept_channel message")))The `accept_channel` message is the response to the `open_channel` message.
[role="pagebreak-before"]
* Type: 33
* Fields:
** `32*byte` : `temp_chan_id`
@ -364,11 +371,13 @@ message has been received and sent can the channel begin to be used.(((range="en
==== Channel Closing
((("wire protocol messages","channel closing")))Channel closing is a multistep process. ((("wire protocol messages","shutdown message")))One node initiates by sending the `shutdown` message. The two channel partners then exchange a series of `channel_closing` messages to negotiate mutually acceptable fees for the closing transaction. ((("closing_signed message")))((("wire protocol messages","closing_signed message")))The channel funder sends the first `closing_signed` message, and the other side can accept by sending a `closing_signed` message with the same fee values.
((("wire protocol messages","channel closing")))Channel closing is a multistep process. ((("wire protocol messages","shutdown message")))One node initiates by sending the `shutdown` message. The two channel partners then exchange a series of `closing_signed` messages to negotiate mutually acceptable fees for the closing transaction. ((("closing_signed message")))((("wire protocol messages","closing_signed message")))The channel funder sends the first `closing_signed` message, and the other side can accept by sending a `closing_signed` message with the same fee values.
[[apdx_shutdown_message]]
===== The shutdown message
The +shutdown+ message initiates the process of closing a channel and contains the following fields:
* Type: 38
* Fields:
** `channel_id` : `channel_id`
@ -378,6 +387,8 @@ message has been received and sent can the channel begin to be used.(((range="en
[[apdx_closing_signed_message]]
===== The closing_signed message
The +closing_signed+ message is sent by each channel partner until they agree on fees. It contains the following fields:
* Type: 39
* Fields:
** `channel_id` : `channel_id`
@ -393,6 +404,7 @@ and forward payments for a given channel.
To send, receive, or forward a payment over a channel, an HTLC must
first be added to both commitment transactions that comprise a channel link.
[role="pagebreak-before less_space"]
[[apdx_update_add_htlc_message]]
===== The update_add_htlc message
@ -471,6 +483,7 @@ In addition to sending a signature for the next commitment transaction, the
sender of this message also needs to send a signature for each HTLC that's
present on the commitment transaction.
[role="pagebreak-before less_space"]
[[apdx_revoke_and_ack_message]]
===== The revoke_and_ack message
@ -489,7 +502,6 @@ While revoking a commitment transaction, the revoker then also provides the
next commitment point that's required to allow the other party to send them a
new commitment state.
[role="pagebreak-before less_space"]
[[apdx_update_fee_message]]
===== The update_fee message
@ -633,12 +645,14 @@ signatures required to generate an `announce_signatures` message.(((range="endof
==== Channel Graph Syncing
((("channel graph syncing messages", id="ix_appendix_protocol_messages-asciidoc7", range="startofrange")))((("wire protocol messages","channel graph syncing", id="ix_appendix_protocol_messages-asciidoc8", range="startofrange")))The ((("channel graph syncing messages","query_short_chan_ids message")))((("query_short_chan_ids message")))`query_short_chan_ids` message allows a peer to obtain the channel information
related to a series of short channel IDs.
Nodes create a local perspective of the channel graph using five messages: +query_short_chan_ids+, +reply_short_chan_ids_end+, +query_channel_range+, +reply_channel_range+, and +gossip_timestamp_range+.
[[apdx_query_short_chan_ids_message]]
===== The query_short_chan_ids message
((("channel graph syncing messages", id="ix_appendix_protocol_messages-asciidoc7", range="startofrange")))((("wire protocol messages","channel graph syncing", id="ix_appendix_protocol_messages-asciidoc8", range="startofrange")))The ((("channel graph syncing messages","query_short_chan_ids message")))((("query_short_chan_ids message")))`query_short_chan_ids` message allows a peer to obtain the channel information
<p><strong>Andreas M. Antonopoulos</strong> is a best-selling author, speaker, educator, and highly sought after expert in Bitcoin and open blockchain technologies. He is known for making complex subjects easy to understand and highlighting both the positive and negative impacts these technologies can have on our global societies.</p>
<p>Andreas has written two more best-selling technical books for programmers with O’Reilly Media, <em>Mastering Bitcoin</em> and <em>Mastering Ethereum</em>. He has also published <em>The Internet of Money</em> series of books, which focus on the social, political, and economic importance and implications of these technologies. Andreas produces free educational content on his YouTube channel weekly and teaches virtual workshops on his website. Learn more at <ahref='http://aantonop.com'>aantonop.com</a>.</p>
<p>Andreas has written two more best-selling technical books for programmers with O’Reilly Media, <em>Mastering Bitcoin</em> and <em>Mastering Ethereum</em>. He has also published <em>The Internet of Money</em> series of books, which focus on the social, political, and economic importance and implications of these technologies. Andreas produces free educational content on his YouTube channel weekly and teaches virtual workshops on his website. Learn more at <ahref='http://aantonop.com'><em>aantonop.com</em></a>.</p>
<p><strong>Olaoluwa Osuntokun</strong> is the cofounder and CTO of Lightning Labs, and also the lead developer of lnd, one of the main implementations of Lightning. He received his BS and MS in Computer Science from UCSB and was a member of the Forbes 30 Under 30 class of 2019. During his graduate studies he focused on the field of applied cryptography, specifically encrypted search. He has been an active Bitcoin developer for over five years, and is an author of several Bitcoin Improvement Proposals (BIP-157 and 158). These days, his primary focus lies in building, designing, and evolving private, scalable off-chain blockchain protocols, such as Lightning.</p>
<p><strong>Olaoluwa Osuntokun</strong> is the cofounder and CTO of Lightning Labs, and also the lead developer of lnd, one of the main implementations of Lightning. He received his BS and MS in computer science from UCSB and was a member of the Forbes 30 Under 30 class of 2019. During his graduate studies he focused on the field of applied cryptography, specifically encrypted search. He has been an active Bitcoin developer for over five years, and is an author of several Bitcoin Improvement Proposals (BIP-157 and 158). These days, his primary focus lies in building, designing, and evolving private, scalable off-chain blockchain protocols, such as Lightning.</p>
<p><strong>René Pickhardt</strong> is a trained mathematician and data science consultant who uses his statistical knowledge to do research with NTNU about pathfinding, privacy, reliability of payments, and service-level agreements of the Lightning Network. René maintains a technical and developer-oriented <ahref='https://www.youtube.com/renepickhardt'>YouTube channel</a> about the Lightning Network and has answered roughly half of the questions about the Lightning Network on the Bitcoin Stack Exchange, making him the go-to point for almost all new developers who want to join the space. René has held numerous workshops about the Lightning Network in public and private, including teaching students of the 2019 Chaincode Labs residency together with other core Lightning developers.</p>
<p>Also known as the southern wood ant, this subspecies of wood ants are aggressive, active, and large. The wood ant queens are typically 12–15 mm in size and can live up to 15 years. Worker ants, on the other hand, are slightly smaller at 8–10 mm and have a lifespan of anywhere between a few weeks to seven years depending on whether they’re male or female (males die soon after mating).</p>
<p>Capable of producing formic acid in their abdomens, red wood ants can eject it up to a few feet away when threatened by predators. Their nests are often conspicuous mounds of grass, twigs, or conifer needles, often built against a rotting tree stump in an area that the sunlight can easily reach. Wood ants live in large colonies that may have 100,000 to 400,000 workers and 100 queens. Red wood ants are very territorial, and often attack and remove other ant species from the area.</p>
<p>Capable of producing formic acid in their abdomens, red wood ants can eject it up to a few feet away when threatened by predators. Their nests are usually conspicuous mounds of grass, twigs, or conifer needles, often built against a rotting tree stump in an area that the sunlight can easily reach. Wood ants live in large colonies that may have 100,000 to 400,000 workers and 100 queens. Red wood ants are very territorial, and known to attack and remove other ant species from the area.</p>
<p>Red wood worker ants forage up to 50 meters from their nest to collect a natural resin found dripping from pine trees. In a behavior unique to wood ants, individual ants walk over the resin to disinfect themselves from bacteria and fungi. Additionally, they also eat aphid honeydew, small insects, and arachnids. Red wood ants are commonly used in forestry and often introduced into an area as a form of pest management.</p>
<p>The red wood ants are currently a protected species and are categorized as “near threatened” by the IUCN. Many of the animals on O'Reilly covers are endangered; all of them are important to the world. To learn more about how you can help, go to <ahref="http://animals.oreilly.com/">animals.oreilly.com</a>.</p>
<p>The red wood ants are currently a protected species and are categorized as “near threatened” by the IUCN. Many of the animals on O'Reilly covers are endangered; all of them are important to the world.</p>
<p>The cover illustration is by Karen Montgomery, based on a black-and-white engraving from a loose plate, origin unknown. The cover fonts are Gilroy Semibold and Guardian Sans. The text font is Adobe Minion Pro; the heading font is Adobe Myriad Condensed; and the code font is Dalton Maag's Ubuntu Mono.</p>
| PERM\|1 | +invalid_realm+ | The `realm` byte was not understood by the processing node
| NODE\|2 | +temporary_node_failure+ | General temporary failure of the processing node
| PERM\|NODE\|2 | +permanent_node_failure+ | General permanent failure of the processing node
| PERM\|NODE\|3 | +required_node_fea⁠ture_​missing+ | The processing node has a required feature which was not in this onion
| BADONION\|PERM\|4 | +invalid_onion_version+ | The `version` byte was not understood by the processing node
| BADONION\|PERM\|5 | +invalid_onion_hmac+ | The HMAC of the onion was incorrect when it reached the processing node
| BADONION\|PERM\|6 | +invalid_onion_key+ | The ephemeral key was unparsable by the processing node
| UPDATE\|7 | +temporary_channel_​fail⁠ure+ | The channel from the processing node was unable to handle this HTLC,
| `PERM\|1` | +invalid_realm+ | The `realm` byte was not understood by the processing node
| `NODE\|2` | +temporary_node_failure+ | General temporary failure of the processing node
| `PERM\|NODE\|2` | +permanent_node_failure+ | General permanent failure of the processing node
| `PERM\|NODE\|3` | +required_node_fea⁠ture_​missing+ | The processing node has a required feature which was not in this onion
| `BADONION\|PERM\|4` | +invalid_onion_version+ | The `version` byte was not understood by the processing node
| `BADONION\|PERM\|5` | +invalid_onion_hmac+ | The HMAC of the onion was incorrect when it reached the processing node
| `BADONION\|PERM\|6` | +invalid_onion_key+ | The ephemeral key was unparsable by the processing node
| `UPDATE\|7` | +temporary_channel_​fail⁠ure+ | The channel from the processing node was unable to handle this HTLC,
but may be able to handle it, or others, later
| PERM\|8 | +permanent_channel_​fail⁠ure+ | The channel from the processing node is unable to handle any HTLCs
| PERM\|9 | +required_channel_​fea⁠ture_missing+ | The channel from the processing node requires features not present in
| `PERM\|8` | +permanent_channel_​fail⁠ure+ | The channel from the processing node is unable to handle any HTLCs
| `PERM\|9` | +required_channel_​fea⁠ture_missing+ | The channel from the processing node requires features not present in
the onion
| PERM\|10 | +unknown_next_peer+ | The onion specified a `short_channel_id` which doesn't match any
| `PERM\|10` | +unknown_next_peer+ | The onion specified a `short_channel_id` which doesn't match any
leading from the processing node
| UPDATE\|11 | +amount_below_minimum+ | The HTLC amount was below the `htlc_minimum_msat` of the channel from
| `UPDATE\|11` | +amount_below_minimum+ | The HTLC amount was below the `htlc_minimum_msat` of the channel from
the processing node
| UPDATE\|12 | +fee_insufficient+ | The fee amount was below that required by the channel from the
| `UPDATE\|12` | +fee_insufficient+ | The fee amount was below that required by the channel from the
processing node
| UPDATE\|13 | +incorrect_cltv_expiry+ | The `cltv_expiry` does not comply with the `cltv_expiry_delta` required by
| `UPDATE\|13` | +incorrect_cltv_expiry+ | The `cltv_expiry` does not comply with the `cltv_expiry_delta` required by
the channel from the processing node
| UPDATE\|14 | +expiry_too_soon+ | The CLTV expiry is too close to the current block height for safe
| `UPDATE\|14` | +expiry_too_soon+ | The CLTV expiry is too close to the current block height for safe
handling by the processing node
| PERM\|15 | +incor⁠rect_or_unknown_​pay⁠ment_details+ | The `payment_hash` is unknown to the final node, the `payment_secret` doesn't
| `PERM\|15` | +incor⁠rect_or_unknown_​pay⁠ment_details+ | The `payment_hash` is unknown to the final node, the `payment_secret` doesn't
match the `payment_hash`, the amount for that `payment_hash` is incorrect, or
the CLTV expiry of the HTLC is too close to the current block height for safe
handling
| 18 | +final_incor⁠rect_​cltv_expiry+ | The CLTV expiry in the HTLC doesn't match the value in the onion
| 19 | +final_incor⁠rect_​htlc_amount+ | The amount in the HTLC doesn't match the value in the onion
| UPDATE\|20 | +channel_disabled+ | The channel from the processing node has been disabled
| 21 | +expiry_too_far+ | The CLTV expiry in the HTLC is too far in the future
| PERM\|22 | +invalid_onion_payload+ | The decrypted onion per-hop payload was not understood by the processing node
| `18` | +final_incor⁠rect_​cltv_expiry+ | The CLTV expiry in the HTLC doesn't match the value in the onion
| `19` | +final_incor⁠rect_​htlc_amount+ | The amount in the HTLC doesn't match the value in the onion
| `UPDATE\|20` | +channel_disabled+ | The channel from the processing node has been disabled
| `21` | +expiry_too_far+ | The CLTV expiry in the HTLC is too far in the future
| `PERM\|22` | +invalid_onion_payload+ | The decrypted onion per-hop payload was not understood by the processing node
or is incomplete
| 23 | +mpp_timeout+ | The complete amount of the multipart payment was not received within a
| `23` | +mpp_timeout+ | The complete amount of the multipart payment was not received within a
The capacity of a payment channel is equivalent to the amount of bitcoin provided by the funding transaction.
Because the funding transaction is publicly visible on the blockchain, and the channel is announced via the gossip protocol, the capacity is public information.
It does not reveal any information about how much bitcoin each of the channel partners owns in the channel, i.e., the balance.
A high capacity does not guarantee that the channel can be used for routing in both directions.
A high capacity does not guarantee that the channel can be used for routing in both pass:[<span class="keep-together">directions</span>].
c-lightning::
Implementation of the LN Protocol by the Victoria-based company https://blockstream.com[Blockstream]. It is written in C. Source code is at https://github.com/ElementsProject/lightning[GitHub].
@ -97,7 +97,7 @@ commitment transaction::
A commitment transaction is a Bitcoin transaction, signed by both channel partners, that encodes the latest balance of a channel.
Every time a new payment is made or forwarded using the channel, the channel balance will update, and a new commitment transaction will be signed by both parties.
Importantly, in a channel between Alice and Bob, both Alice and Bob keep their own version of the commitment transaction, which is also signed by the other party.
At any point, the channel can be closed by either Alice or Bob if they submit their commitment transaction to the Bitcoin blockchain.
At any point, the pass:[<span class="keep-together">channel</span>] can be closed by either Alice or Bob if they submit their commitment transaction to the Bitcoin blockchain.
Submitting an older (outdated) commitment transaction is considered _cheating_ (i.e., a protocol breach) in the Lightning Network and can be penalized by the other party, claiming all the funds in the channel for themselves, via a penalty transaction.
confirmations::
@ -195,14 +195,14 @@ invoice::
Invoices can also include a fallback Bitcoin address to which the payment can be made in case no route can be found, as well as hints for routing a payment through a private channel.
just-in-time (JIT) routing::
Just-in-time (JIT) routing is an alternative to source-based routing that was first proposed by coauthor René Pickhardt.
Just-in-time (JIT) routing is an alternative to source-based routing that was first pass:[<span class="keep-together">proposed</span>] by coauthor René Pickhardt.
With JIT routing, intermediary nodes along a path can pause an in-flight payment to rebalance their channels before proceeding with the payment.
This might allow them to successfully forward payments that might otherwise have failed due to a lack of outgoing capacity.
Lightning message::
A Lightning message is an encrypted data string that can be sent between two peers on the Lightning Network. Similar to other communication protocols, Lightning messages consist of a header and a body. The header and the body have their own HMAC. Lightning messages are the main building block of the messaging layer.
The Lightning Network is a protocol on top of Bitcoin (or other cryptocurrencies).
It creates a network of payment channels which enables the trustless forwarding of payments through the network with the help of HTLCs and onion routing.
Other components of the Lightning Network are the gossip protocol, the transport layer, and payment requests.
@ -12,8 +12,6 @@ The initial idea of the Lightning Network was proposed in 2015 in the groundbrea
In 2019, Andreas M. Antonopoulos, Olaoluwa Osuntokun, and René Pickhardt agreed to collaborate to write this book. It appears we have been successful!
=== How to Use This Book
[[intended_audience_sec]]
=== Intended Audience
@ -74,7 +72,7 @@ If you feel your use of code examples falls outside fair use or the permission g
=== References to Companies and Products
All references to companies and products are intended for educational, demonstration, and reference purposes. The authors do not endorse any of the companies or products mentioned. We have not tested the operation or security of any of the products, projects, or code segments shown in this book. Use them at your own risk!
All references to companies and products are intended for educational, demonstration, and reference purposes. The authors do not endorse any of the companies pass:[<span class="keep-together">or products</span>] mentioned. We have not tested the operation or security of any of the products, projects, or code segments shown in this book. Use them at your own risk!
[[addresses_and_transactions_sec]]
=== Addresses and Transactions in This Book
@ -101,7 +99,7 @@ Our unique network of experts and innovators share their knowledge and expertise
[[how_to_contact_us_sec]]
=== How to Contact Us
Information about _Mastering the Lightning Network_ as well as the Open Edition and translations are available at link:$$https://lnbook.info/$$[].
Information about _Mastering the Lightning Network_ as well as the Open Edition and translations are available at link:$$https://lnbook.info$$[].
Please address comments and questions concerning this book to the publisher:
@ -129,7 +127,7 @@ Watch us on YouTube: link:$$http://www.youtube.com/oreillymedia$$[]
==== Contacting Andreas
You can contact Andreas M. Antonopoulos on his personal site:
Andreas would also like to thank all of the patrons who support his work through monthly donations. You can support Andreas on Patreon at link:$$https://patreon.com/aantonop$$[].
Andreas would also like to thank the patrons who support his work through monthly donations. You can support Andreas on Patreon at link:$$https://patreon.com/aantonop$$[].
==== Contacting René
You can contact René Pickhardt on his personal site:
René would also like to thank all of the patrons who support his work through monthly donations. You can support René on Patreon at link:$$https://patreon.com/renepickhardt$$[].
@ -172,13 +170,13 @@ Follow Olaoluwa on Twitter:
link:$$https://twitter.com/roasbeef$$[]
[[acknowledgments_sec]]
=== Acknowledgments By Andreas
=== Acknowledgments by Andreas
I owe my love of words and books to my mother, Theresa, who raised me in a house with books lining every wall. My mother also bought me my first computer in 1982, despite being a self-described technophobe. My father, Menelaos, a civil engineer who published his first book at 80 years old, was the one who taught me logical and analytical thinking and a love of science and engineering.
Thank you all for supporting me throughout this journey.
=== Acknowledgments By René
=== Acknowledgments by René
I want to thank the German education system through which I acquired the knowledge upon which my work builds. It is one of the greatest gifts I was given.
Similarly I want to thank the German public healthcare system and every person devoting their time into working within that industry. Your effort and endurance make you my personal heroes and I will never forget the help, patience, and support I received when I was in need.
<metaname="author"content="Andreas M. Antonopolous, Olaoluwa Osuntokun, and Rene Pickhardt"/>
<metaname="date"content="2021-02-16"/>
<metaname="description"content="Launched in early 2018, the Lightning Network (LN) is rapidly growing in users and capacity. This second-layer payment protocol works on top of Bitcoin and other cryptocurrencies to provide near-instantaneous transactions between two parties. With this practical guide, authors Andreas M. Antonopoulos, Olaoluwa Osuntokun, and Rene Pickhardt explain how this advancement will enable the next level of scale for Bitcoin, increasing speed and privacy while reducing fees."/>
<metaname="date"content="2021-11-22"/>
<metaname="description"content="The Lightning Network (LN) is a rapidly growing second-layer payment protocol that works on top of Bitcoin to provide near-instantaneous transactions between two parties. With this practical guide, authors Andreas M. Antonopoulos, Olaoluwa Osuntokun, and Rene Pickhardt explain how this advancement will enable the next level of scale for Bitcoin, increasing speed and privacy while reducing fees. Ideal for developers, systems architects, investors, and entrepreneurs."/>
Andreas M. Antonopoulos
2 years ago
