ran script to title case headers

pull/899/head
Kristen Borg 3 years ago
parent ac270b5c4b
commit 57c815ba3a

@ -47,7 +47,7 @@ Throughout this book, you will see "Bitcoin" with the first letter capitalized,
Now that you're familiar with these basic terms, let's move to a concept you are already comfortable with: trust.
=== Trust in decentralized networks
=== Trust in Decentralized Networks
You will often hear people calling Bitcoin and the Lightning Network "trustless". At first glance this is confusing. After all, isn't trust a good thing? Banks even use it in their names! Isn't a "trustless" system, a system devoid of trust, a bad thing?
@ -60,7 +60,7 @@ Trustless does not mean devoid of trust. It means that trust is not a necessary
Before we get into how the Lightning Network works, it's important to understand one basic concept that underlies Bitcoin, the Lightning Network and many other such systems: something we call a _fairness protocol_. A fairness protocol is a way to _achieve fair outcomes between participants, who do not need to trust each other, without the need for a central authority_ and it is the backbone of decentralized systems like Bitcoin.
=== Fairness without central authority
=== Fairness Without Central Authority
When people have competing interests, how can they establish enough trust to engage in some cooperative or transactional behavior? The answer to this question lies at the core of several scientific and humanistic disciplines, such as economics, sociology, behavioral psychology, and mathematics. Some of those disciplines give us "soft" answers that depend on concepts such as reputation, fairness, morality, and even religion. Other disciplines give us concrete answers that depend only on the assumption that the participants in these interactions will act rationally, with their self-interest as the main objective.
@ -74,7 +74,7 @@ In broad terms, there are a handful of ways to ensure fair outcomes in interacti
* Game theoretical fairness protocols - this last category emerges from the combination of the internet and cryptography and is the subject of this section. Let's see how it works and what its advantages and disadvantages are.
==== Trusted protocols without intermediaries
==== Trusted Protocols Without Intermediaries
Cryptographic systems like Bitcoin and the Lightning Network are systems that allow you to transact with people (and computers) that you don't trust. This is often referred to as "trustless" operation, even though it is not actually trustless. You have to trust in the software that you run, and you have to trust that the protocol implemented by that software will result in fair outcomes.
@ -88,7 +88,7 @@ While game theory and its use in cryptographic systems may appear confounding an
In this book, we call this pattern a _Fairness Protocol_ defined as a process that uses a system of incentives and/or disincentives to ensure fair outcomes for participants who don't trust each other. Enforcement of a fairness protocol is only necessary to ensure that the participants can't escape the incentives or disincentives.
==== A fairness protocol in action
==== A Fairness Protocol in Action
Let's look at an example of a fairness protocol, which you may already be familiar with.
@ -105,7 +105,7 @@ A much better solution exists: the siblings are taught to play a game called "sp
While the infamous chip battles of the 1980's neatly illustrate the point, any similarity between the scenario above and any of the authors' actual childhood experiences with their cousins is entirely coincidental... Or is it?
====
==== Security primitives as building blocks
==== Security Primitives As Building Blocks
In order for a fairness protocol like this to work, there need to be certain guarantees, or _security primitives_, that can be combined to ensure enforcement. The first security primitive is _strict time ordering/sequencing_: the "splitting" action must happen before the "choosing" action. It's not immediately obvious, but unless you can guarantee that action A happens before action B, then the protocol falls apart. The second security primitive is _commitment with non-repudiation_. Each sibling must commit to their choice of role: either splitter or chooser. Also, once the splitting has been completed, the splitter is committed to the split they created - they cannot repudiate that choice and go try again.
@ -121,7 +121,7 @@ In our real-life example, we saw one form of fairness protocol called "split and
Now that you understand this basic pattern, you will start seeing it everywhere in Bitcoin, the Lightning Network and many other systems. Let's look at some specific examples next.
==== Example of the fairness protocol
==== Example of the Fairness Protocol
The most prominent example of a "fairness protocol" is Bitcoin's consensus algorithm, _Proof of Work_ (PoW). In Bitcoin, miners compete to verify transactions and aggregate them in blocks. To ensure that the miners do not cheat, without entrusting them with authority, Bitcoin uses a system of incentives and disincentives. Miners have to use electricity and dedicate hardware doing "work" that is embedded as a "proof" inside every block. This is achieved because of a property of hash functions where the output value is randomly distributed across the entire range of possible outputs. If miners succeed in producing a valid block fast enough, they are rewarded by earning the block reward for that block. Forcing miners to use a lot of electricity before the network considers their block means that they have an incentive to correctly validate the transactions in the block. If they cheat or make any kind of mistake, their block is rejected and the electricity they used to "prove" it is wasted. No one needs to force miners to produce valid blocks; the reward and punishment incentivize them to do so. All the protocol needs to do is ensure that only valid blocks with proof of work are accepted.
@ -191,7 +191,7 @@ Aside from reducing the burden on nodes, payments on the Lightning Network are c
While the Lightning Network was initially conceived for Bitcoin, it can be implemented on any blockchain that meets some basic technical requirements. Other blockchains, such as Litecoin, already support the Lightning Network. Additionally, several other blockchains are developing similar "second layer" or "layer 2" solutions to help them scale.
=== The Lightning Network's defining features
=== The Lightning Network's Defining Features
The Lightning Network is a network that operates as a "second layer" protocol on top of Bitcoin and other blockchains. The Lightning Network enables fast, secure, private, trustless, and permissionless payments. Here are some of the features of the Lightning Network:

@ -1,10 +1,10 @@
[[getting-started]]
== Getting started
== Getting Started
In this chapter, we will begin where most people start when encountering the Lightning Network for the first time - choosing software to participate in the Lightning Network economy. We will examine the choices of two users who represent a common use-case for the Lightning Network and learn by example. Alice, a coffee shop customer, will be using a Lightning wallet on her mobile device to buy coffee from Bob's Cafe. Bob, a merchant, will be using a Lightning node and wallet to run a point-of-sale system at his cafe, so he can accept payments over the Lightning Network.
=== Alice's first Lightning wallet
=== Alice's First Lightning Wallet
Alice is a long time Bitcoin user. We first met Alice in Chapter 1 of _"Mastering Bitcoin"_ footnote:["Mastering Bitcoin 2nd Edition, Chapter 1" Andreas M. Antonopoulos (https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch01.asciidoc).], when she bought a cup of coffee from Bob's cafe using a Bitcoin transaction. If you are not yet familiar with how Bitcoin transactions work or need a refresher, please read Mastering Bitcoin or the summary in <<bitcoin_fundamentals_review>>.
@ -12,14 +12,14 @@ Alice recently learned that Bob's Cafe just started accepting Lightning Network
Alice does not want to entrust custody of her bitcoin to third parties. She has learned enough about cryptocurrency to know how to use a wallet. She also wants a mobile wallet so that she can use it for small payments on-the-go, so she chooses the _Eclair_ wallet, a popular non-custodial mobile Lightning wallet. Let's learn more about how and why she's made these choices.
=== Lightning nodes
=== Lightning Nodes
The Lightning Network is accessed via software applications that can speak the Lightning Network protocol. A _Lightning Network node_ (or simply "node") is a software application that has three important characteristics. First, Lightning nodes are "wallets", so they send and receive payments over the Lightning Network as well as on the Bitcoin network. Second, nodes must communicate on a peer-to-peer basis with other Lightning nodes creating the network. Finally, Lightning nodes also need access to the Bitcoin blockchain (or other blockchains for other cryptocurrencies) to secure the funds used for payments.
Users have the highest degree of control by running their own Bitcoin node and Lightning node. However, Lightning nodes can also use a lightweight Bitcoin client, commonly referred to as Simplified Payment Verification (SPV), to interact with the Bitcoin blockchain.
[[ln_explorer]]
=== Lightning explorers
=== Lightning Explorers
Lightning network explorers are useful tools to show the statistics of nodes, channels and network capacity.
@ -42,7 +42,7 @@ Use Lightning explorers to visualize the network or gather information, but not
To have an authoritative view of the Lightning Network, run your own Lightning node that will build a channel graph and collect various statistics, which you can view with a web-based interface.
====
=== Lightning wallets
=== Lightning Wallets
The term "Lightning wallet" is somewhat ambiguous, as it can describe a broad variety of components combined with some user interface. The most common components of Lightning wallet software include:
@ -152,7 +152,7 @@ https://testnet.help/en/btcfaucet/testnet
All of the examples in this book can be replicated exactly on testnet with TBTC, so you can follow along if you want without risking real money.
=== Balancing complexity and control
=== Balancing Complexity and Control
Lightning wallets have to strike a careful balance between complexity and user control. Those that give the user the most control over their funds, the highest degree of privacy, and the greatest independence from third party services are necessarily more complex and difficult to operate. As the technology advances, some of these trade-offs will become less stark, and users may be able to get more control without more complexity. However, for now, different companies and projects are exploring different positions along this control-complexity spectrum and hoping to find the "sweet spot" for the users they are targeting.
@ -160,7 +160,7 @@ When selecting a wallet, keep in mind that even if you don't see these trade-off
In the next section, we will return to our first user and walk through her first Lightning wallet setup. She has chosen a wallet that is more sophisticated than the easier custodial wallets. This allows us to show some of the underlying complexity and introduce some of the inner workings of an advanced wallet. You may find that your first ideal wallet is further towards "ease of use", accepting some of the control and privacy trade-offs. Or perhaps you are more of a "power user" and want to run your own Lightning and Bitcoin nodes as part of your wallet solution.
=== Downloading and installing a Lightning wallet
=== Downloading and Installing a Lightning Wallet
When looking for a new cryptocurrency wallet, you must be very careful to select a secure source for the software.
@ -185,11 +185,11 @@ Alice notices a few different elements on this page, that help her ascertain tha
Always exercise great care when installing software on any device. There are many fake cryptocurrency wallets that will not only steal your money but might also compromise all other applications on your device.
====
=== Creating a new wallet
=== Creating a New Wallet
When Alice opens the Eclair Mobile app for the first time, she is presented with a choice to "Create a New Wallet" or to "Import an Existing Wallet". Alice will create a new wallet, but let's first discuss why these options are presented here and what it means to "import an existing wallet".
==== Responsibility with key custody
==== Responsibility with Key Custody
As we mentioned at the beginning of this section, Eclair is a _non-custodial_ wallet, meaning that Alice has sole custody of the keys used to control her bitcoin. This also means that Alice is responsible for protecting and backing up those keys. If Alice loses the keys, no one can help her recover the bitcoin, and they will be lost forever.
@ -198,7 +198,7 @@ As we mentioned at the beginning of this section, Eclair is a _non-custodial_ wa
With the Eclair Mobile wallet, Alice has custody and control of the keys and, therefore, full responsibility to keep the keys safe and backed up. If she loses the keys, she loses the bitcoin, and no one can help her recover from that loss!
====
==== Mnemonic words
==== Mnemonic Words
Similar to most Bitcoin wallets, Eclair Mobile provides a _mnemonic phrase_ (also sometimes called a "seed" or "seed phrase") for Alice to back up. The mnemonic phrase consists of 24 English words, selected randomly by the software, and used as the basis for the keys that are generated by the wallet. The mnemonic phrase can be used by Alice to restore all the transactions and funds in the Eclair Mobile wallet in the case of an event such as a lost mobile device, a software bug, or memory corruption.
@ -216,7 +216,7 @@ image::images/mtln_0202.png["New Wallet Mnemonic Phrase"]
In <<eclair-mnemonic>>, we have purposely obscured part of the mnemonic phrase to prevent readers of this book from reusing the mnemonic.
[[mnemonic-storage]]
==== Storing the mnemonic safely
==== Storing the Mnemonic Safely
Alice needs to be careful to store the mnemonic phrase in a way that prevents theft but also avoids accidental loss. The recommended way to properly balance these risks is to write two copies of the mnemonic phrase on paper, with each of the words numbered - the order matters.
@ -231,7 +231,7 @@ Never attempt a "DIY" security scheme that deviates in any way from the best pra
After Alice initializes her Eclair Mobile wallet, she will see a brief tutorial that highlights the various elements of the user interface. We won't replicate the tutorial here, but we will explore all of those elements as we follow Alice's attempt to buy a cup of coffee!
=== Loading bitcoin onto the wallet
=== Loading Bitcoin Onto the Wallet
Alice now has a Lightning wallet. But, it's empty! She now faces one of the more challenging aspects of this experiment; she has to find a way to acquire some bitcoin and load it onto her Eclair wallet.
@ -241,7 +241,7 @@ If Alice already has bitcoin in another wallet, she could choose to send that bi
====
[[acquiring-bitcoin]]
==== Acquiring bitcoin
==== Acquiring Bitcoin
There are several ways Alice can acquire bitcoin:
@ -253,7 +253,7 @@ There are several ways Alice can acquire bitcoin:
All of these methods have varying degrees of difficulty, and many will involve paying a fee. Some will also require Alice to provide identification documents to comply with local banking regulations. However, with all these methods, Alice will be able to receive bitcoin.
==== Receiving bitcoin
==== Receiving Bitcoin
Let's assume Alice has found a local Bitcoin ATM and has decided to buy some bitcoin in exchange for cash. An example of a Bitcoin ATM, one built by the Lamassu company, is shown in <<bitcoin-atm>>. Such Bitcoin ATMs accept national currency (cash) through a cash slot and send bitcoin to a Bitcoin address scanned from a user's wallet using a built-in camera.
@ -305,7 +305,7 @@ Fortunately, the Lightning Network offers more private solutions to this, discus
Finally, if Alice bought bitcoin from a cryptocurrency exchange, she could (and should) "withdraw" the bitcoin by pasting her Bitcoin address into the exchange website. The exchange will then send the bitcoin to her address directly.
=== From Bitcoin to Lightning network
=== From Bitcoin to Lightning Network
Alice's bitcoin is now controlled by her Eclair wallet and has been recorded on the Bitcoin blockchain. At this point, Alice's bitcoin is "on-chain," meaning that the transaction has been broadcast to the entire Bitcoin network, verified by all Bitcoin nodes, and "mined" (recorded) onto the Bitcoin blockchain.
@ -313,7 +313,7 @@ So far, the Eclair Mobile wallet has behaved only as a Bitcoin wallet, and Alice
Now, Alice is ready to start using the Lightning Network by taking her bitcoin "off-chain" in order to take advantage of the fast, cheap, and private payments that the Lightning Network offers.
==== Lightning Network channels
==== Lightning Network Channels
Swiping right, Alice accesses the "LIGHTNING CHANNELS" section of Eclair. Here she can manage the channels that will connect her wallet to the Lightning Network.
@ -361,7 +361,7 @@ Choosing the ACINQ node will slightly reduce Alice's privacy, as it will give AC
Alice selects "ACINQ Node" and is ready to open her first channel on the Lightning network.
==== Opening a Lightning channel
==== Opening a Lightning Channel
When Alice selects a node to open a new channel, she is asked to select how much bitcoin she wants to allocate to this channel. In subsequent chapters, we will discuss the implications of these choices, but for now, Alice will allocate almost all her funds to the channel. Since she will have to pay transaction fees to open the channel, she will select an amount slightly less than her total balance footnote:[The Eclair wallet doesn't offer an option to automatically calculate the necessary fees and allocate the maximum amount of funds to a channel, so Alice has to calculate this herself.]
@ -390,7 +390,7 @@ image::images/mtln_0211.png["Channel is Open"]
Did you notice that the channel amount seems to have changed? It hasn't: the channel contains 0.018 BTC, but in the time between screenshots the BTC exchange rate changed, so the USD value is different. You can choose to show balances in BTC or USD, but keep in mind that USD values are calculated in real-time and will change!
====
=== Buying a cup of coffee using LN
=== Buying a Cup of Coffee Using Ln
Alice now has everything ready to start using the Lightning Network. As you can see, it took a bit of work and a bit of time waiting for confirmations. However, now subsequent actions are fast and easy. The Lightning Network enables payments without having to wait for confirmations, as funds get settled in seconds.
@ -412,7 +412,7 @@ On the counter at Bob's Cafe, there is a tablet device showing <<bob-cafe-posapp
.Bob's Point-of-Sale Application
image::images/mtln_0212.png["Bob's Point-of-Sale Application"]
==== A Lightning invoice
==== A Lightning Invoice
Alice selects the "Cafe Latte" option from the screen and is presented with a _Lightning Invoice_ (also known as a "payment request") as shown in <<bob-cafe-invoice>>

@ -1,5 +1,5 @@
[[ch03_How_Lightning_Works]]
== How the Lightning Network works
== How the Lightning Network Works
Now that we've followed Alice as she set up a Lightning Wallet and purchased a coffee from Bob, we'll look under the hood and unpack the different components of the Lightning Network involved in that process.
This chapter will give a high-level overview and will not delve into all the technical details.
@ -27,7 +27,7 @@ We'll start with a one sentence definition of what the Lightning Network (LN) is
**The Lightning Network (LN) is a peer-to-peer network of _payment channels_ implemented as smart contracts on the _Bitcoin blockchain_ as well as a communication protocol that defines how participants set up and execute these smart contracts.**
[[what_is_payment_channel]]
=== What is a payment channel?
=== What Is a Payment Channel?
There are several ways to describe a payment channel, depending on the context. Let's start at a high level and then add some more detail.
@ -41,7 +41,7 @@ To summarize:
A payment channel is a financial relationship between nodes, allocating funds from a multi-signature address, through a strictly defined cryptographic protocol.
=== Payment channel basics
=== Payment Channel Basics
Underlying the payment channel is simply a 2-of-2 multisignature address on the Bitcoin blockchain, for which you hold one key and your channel partner holds the other key.
@ -61,7 +61,7 @@ If you have an unpublished transaction from a 2-of-2 multisignature address that
The ability to hold a partially-signed transaction, offline and unpublished, with the option to publish and own that balance at any time, is the basis of the Lightning Network.
====
=== Routing payments across channels
=== Routing Payments Across Channels
Once several participants have channels from one party to another, payments can also be "forwarded" from payment channel to payment channel, by setting up a _path_ across the network connecting several payment channels together.
@ -85,7 +85,7 @@ Alice, for example, needs the network topology information to be aware of the ch
Last but not least, it is important to understand that the Lightning Network is nothing more than an application on top of Bitcoin, using Bitcoin transactions and Bitcoin Script. There is no "Lightning coin" or "Lightning blockchain".
Beyond all the technical primitives, the Lightning Network protocol is a creative way to get more benefits out of Bitcoin by allowing an arbitrary amount of instant payments with instant settlements without the necessity of having to trust anyone else but the Bitcoin network.
=== Payment channels
=== Payment Channels
As we saw in the previous chapter, Alice used her wallet software to create a payment channel between her and another Lightning Network participant.
@ -114,7 +114,7 @@ The other two proposed methods are _Duplex Micropayment_ channels, introduced by
Eltoo channels have some interesting properties and simplify the implementation of payment channels. However, eltoo channels require a change in the Bitcoin scripting language and therefore cannot be implemented on the Bitcoin mainnet as of 2020.
==== Multisignature address
==== Multisignature Address
Payment channels are built on top of 2-of-2 multisignature addresses.
@ -122,7 +122,7 @@ In summary, a multi-signature address is where bitcoin is locked so that it requ
Multisignature scripts and addresses are explained in more detail in <<multisig>>.
==== Funding transaction
==== Funding Transaction
The fundamental building block of a payment channel, is a 2-of-2 multisignature address. One of the two channel partners will fund the payment channel by sending bitcoin to the multisignature address. This transaction is called the _funding transaction_, and is recorded on the Bitcoin blockchain. footnote:[While the original Lightning whitepaper described channels funded by both channel partners, the current specification, as of 2020, assumes that just one partner commits funds to the channel. As of May 2021 dual-funded lightning channels are experimental in the c-lightning LN implementation.]
@ -179,7 +179,7 @@ If Alice wants to send 30k satoshi to Bob, both would create a new version of th
Now that we understand commitment transactions, let's look at some of the more subtle details. You may notice that this protocol leaves a way for either Alice or Bob to cheat.
==== Cheating with prior state
==== Cheating with Prior State
How many commitment transactions does Alice hold after she pays 30k satoshi to Bob? She holds two: the original one paying her 100k satoshi and the more recent one, paying her 70k satoshi and Bob 30k satoshi.
@ -245,7 +245,7 @@ Technologies such as watchtower services or changing the channel construction pr
Alice can close the channel at any time if Bob does not respond, claiming her fair share of the balance.
After publishing the *last* commitment transaction on-chain, Alice has to wait for the timelock to expire before she can spend her funds from the commitment transaction. As we will see later, there is an easier way to close a channel without waiting, as long as Alice and Bob are both online and cooperate to close the channel with the correct balance allocation. But the commitment transactions stored by each channel partner act as a failsafe, ensuring they do not lose funds if there is a problem with their channel partner.
==== Announcing the channel
==== Announcing the Channel
Channel partners can agree to announce their channel to the whole Lightning Network, making it a _public channel_. To announce the channel, they use the Lightning Network's gossip protocol to tell other nodes about the existence, capacity and fees of the channel.
@ -265,7 +265,7 @@ When a channel and its capacity is publicly announced using the gossip protocol,
When new nodes join the Lightning Network they collect the channel announcements propagated via the gossip protocol from their peers, building an internal "map" of the Lightning Network. This map can then be used to find paths for payments, connecting channels together end-to-end.
==== Closing the channel
==== Closing the Channel
The best way to close a channel is... to not close it!
Opening and closing channels require an on-chain transaction, which will incur transaction fees.
@ -410,7 +410,7 @@ Invoices are usually encoded either as a long bech32-encoded string or as a QR c
Did you notice how this contrasts with Bitcoin and how different terms are used? In Bitcoin, the recipient passes an address to the sender. In Lightning, the recipient creates an invoice and sends an invoice to the sender. In Bitcoin, the sender sends funds to an address. In Lightning, the sender pays an invoice and the payment gets routed to the recipient. Bitcoin is based on the concept of an "address", and Lightning is a payment network based on the concept of an "invoice". In Bitcoin, we create a "transaction" whereas in Lightning we send a "payment".
==== Payment hash and preimage
==== Payment Hash and Preimage
The most important part of the invoice is the _payment hash_. When constructing the invoice, Bob will make a payment hash as follows:
@ -428,7 +428,7 @@ There is no known way to find the inverse of SHA256 (i.e. compute a preimage fro
The payment process of the Lightning Network is only secure if +r+ is chosen completely randomly and is not predictable. This security relies on the fact that hash functions cannot be inverted or feasibly brute-forced and therefore no one can find +r+ from +H+.
==== Additional metadata
==== Additional Metadata
Invoices can optionally include other useful metadata such as a short text description. If a user has several invoices to pay, the user can read the description and be reminded of what the invoice is about.
@ -444,7 +444,7 @@ While it is always possible to "fall back" to an on-chain Bitcoin transaction, i
Lightning invoices contain an expiry date. Since the recipient must keep the preimage +r+ for every invoice issued, it is useful to have invoices expire so that these preimages do not need to be kept forever. Once an invoice expires or is paid, the recipient can discard the preimage.
=== Delivering the payment
=== Delivering the Payment
We have seen how the recipient creates an invoice that contains a payment hash. This payment hash will be used to move the payment across a series of payment channels, from sender to recipient, even if they do not have a direct payment channel between them.
@ -452,7 +452,7 @@ In the next few sections, we will dive into the ideas and methods that are being
First, let's look at the Lightning Network's communication protocol.
==== The peer-to-peer gossip protocol
==== The Peer-To-Peer Gossip Protocol
As we mentioned previously, when a payment channel is constructed, the channel partners have the option of making it public, announcing its existence and details to the whole Lightning Network.
@ -491,7 +491,7 @@ For now, it is only important to know that the gossip protocol exists and that i
This topology information is crucial for delivering payments through the network of payment channels.
==== Pathfinding and routing
==== Pathfinding and Routing
Payments on the Lightning Network are forwarded along a _path_ made of channels linking one participant to another, from the payment source to the payment destination. The process of finding a path from source to destination is called _pathfinding_. The process of using that path to make the payment is called _routing_.
@ -502,7 +502,7 @@ A frequent criticism of the Lightning Network is that "routing" is not solved, o
As we will see next, the Lightning Network currently uses a _source-based_ protocol for pathfinding and an _onion routed_ protocol for routing payments. Source-based means that the sender of the payment has to find a path through the network to the intended destination. Onion-routed means that the elements of the path are layered (like an onion), with each layer encrypted so that it can only be seen by one node at a time. We will discuss onion routing in the next section.
=== Source-based pathfinding
=== Source-Based Pathfinding
If we knew the exact channel balances of every channel, we could easily compute a payment path using any of the standard pathfinding algorithms taught in any computer science class. This could even be solved in a way that optimizes the fees paid to nodes for forwarding the payment.
@ -529,7 +529,7 @@ On the Internet, we use the Internet protocol and an IP forwarding algorithm to
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.
==== Onion routing
==== Onion Routing
The Lightning Network uses an _onion routing protocol_ similar to the famous Tor (The Onion Router) network.
The onion routing protocol used in Lightning is called the _SPHINX mixformat_ and will be explained in detail in a later chapter.
@ -570,7 +570,7 @@ The onion routing protocol used in Lightning has the following properties:
Onion routing will be examined in detail in <<onion_routing>>.
==== Payment forwarding algorithm
==== Payment Forwarding Algorithm
Once the sender of a payment finds a possible path across the network and constructs an onion, the payment is forwarded by each node in the path. Each node processes one layer of the onion and forwards it to the next node in the path.
@ -594,7 +594,7 @@ As the error propagates backwards on each channel along the path, the channel pa
While the likelihood for a payment failure is high if it does not settle quickly, a node should never initiate another payment attempt along a different path before the onion returns with an error. The sender would pay twice if both payment attempts eventually succeeded.
=== Peer-to-peer communication encryption
=== Peer-To-Peer Communication Encryption
The Lightning Network protocol is mainly a peer-to-peer protocol between its participants. As we saw in previous sections, there are two overlapping functions in the network, forming two logical networks that together are _The Lightning Network_:
@ -610,7 +610,7 @@ The use of the Noise Protocol Framework in the Lightning Network ensures that ev
https://github.com/nayutaco/lightning-dissector
=== Thoughts about trust
=== Thoughts About Trust
As long as a person follows the protocol and has their node secured, there is no major risk of losing funds when participating in the Lightning Network.
However, there is the cost of paying on-chain fees when opening a channel.
Any cost should come with a corresponding benefit.
@ -628,7 +628,7 @@ While the Lightning Network is built on top of Bitcoin and inherits many of its
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 vs. invoices, transactions vs. payments
==== Addresses Vs. Invoices, Transactions Vs. Payments
In a typical payment using Bitcoin, a user receives a Bitcoin address (e.g. scanning a QR code on a webpage, 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.
@ -640,7 +640,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 vs. finding a path
==== Selecting Outputs Vs. Finding a Path
In order 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.
@ -652,14 +652,14 @@ As many possible channels and paths can be used to make a payment, the Lightning
With technologies such as Atomic Multi-Path (AMP) and Multi-Path Payments (MPP), which we will review in subsequent chapters, several Lightning paths can be aggregated into a single atomic payment, just like several Bitcoin UTXO can be aggregated into a single atomic Bitcoin transaction.
==== Change outputs on Bitcoin vs. no change on Lightning
==== Change Outputs On Bitcoin Vs. No Change On Lightning
In order to make a payment on the Bitcoin network, the sender needs to consume one or more Unspent Transaction Outputs (UTXOs). UTXO 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, then 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 multi-signature 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, with the channel closing transaction.
==== Mining fees vs. routing fees
==== Mining Fees Vs. 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.
@ -669,7 +669,7 @@ As miners will typically mine the most profitable transactions first, a user who
On the Lightning Network, users pay fees to other (intermediary node) users to route payments through their channels.
In order 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_ (a flat fee for each payment) and a _fee rate_ (a pro-rated 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 vs. announced fees
==== Varying Fees Depending On Traffic Vs. 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_.
@ -681,7 +681,7 @@ The scarce resource on the Bitcoin network is the space in the blocks. Bitcoin u
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 vs. private Lightning payments
==== Public Bitcoin Transactions Vs. 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.
@ -690,7 +690,7 @@ Lightning Network payments on the other hand, are almost completely private. Typ
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 and 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 vs. instant settlement
==== Waiting for Confirmations Vs. 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.
@ -699,7 +699,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 vs. capacity restrictions
==== Sending Arbitrary Amounts Vs. 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.
@ -711,7 +711,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 vs. small value payments
==== Incentives for Large Value Payment Vs. Small Value Payments
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).
@ -720,7 +720,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 and 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 vs. as a court system
==== Using the Blockchain As a Ledger Vs. As a 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.
@ -734,7 +734,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 vs. online, asynchronous vs. synchronous
==== Offline Vs. Online, Asynchronous Vs. Synchronous
When a Bitcoin user sends funds to a destination address he does 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.
@ -743,7 +743,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 often confounds users who are accustomed to Bitcoin.
==== Satoshis vs. milli-satoshis
==== Satoshis Vs. Milli-Satoshis
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 _milli-satoshis_ (thousandths of a satoshi). This allows tiny payments to be sent via Lightning. A single milli-satoshi payment can be sent across a payment channel, an amount so small it should properly be characterized as a _nanopayment_.
@ -753,25 +753,25 @@ The milli-satoshi unit cannot, of course, be settled on the Bitcoin blockchain a
While the Lightning Network differs from Bitcoin in a number of ways, including in architecture and user experience, it is built from Bitcoin and retains many of Bitcoins core features.
==== Monetary unit
==== Monetary Unit
Both the Bitcoin network and the Lightning network use the same monetary units: bitcoin. Lightning payments use the very same bitcoin as Bitcoin transactions. As an implication, because the monetary unit is the same, the monetary limit is the same: less than 21 million bitcoin. Of Bitcoin's 21 million total bitcoin, some are already allocated to 2-of-2 multi-signature addresses as part of payment channels on the Lightning Network.
==== Irreversibility and finality of payments
==== Irreversibility and Finality of Payments
Both Bitcoin transactions and Lightning payments are irreversible and immutable. There is no "undo" operation or "chargeback" for either system. As a sender of either one, you have to act responsibly, but also, as a recipient you are guaranteed finality of your transactions.
==== Trust and counterparty risk
==== Trust and Counterparty Risk
As with Bitcoin, Lightning requires the user only to trust mathematics, encryption, and that the software does not have any critical bugs. Neither Bitcoin nor Lightning requires the user to trust a person, a company, an institution, or a government.
Since Lightning sits on top of Bitcoin and relies on Bitcoin as its underlying base layer, it is clear that the security model of Lightning reduces to the security of Bitcoin. This means that Lightning offers broadly the same security as Bitcoin under most circumstances, with only a slight reduction in security under some narrow circumstances.
==== Permissionless operation
==== Permissionless Operation
Both Bitcoin and Lightning can be used by anybody with access to the Internet and to the appropriate software, e.g. node and wallet.
Neither network requires users to get permission, vetting, or authorization from third-parties, companies, institutions or a government. Governments can outlaw Bitcoin or Lightning within their jurisdiction, but cannot prevent their global use.
==== Open source and open system
==== Open Source and Open System
Both, Bitcoin and Lightning are open-source software systems built by a decentralized global community of volunteers, available under open licenses. Both are based on open and interoperable protocols, which operate as open systems and open networks. Global, open and free.

@ -1,5 +1,5 @@
[[set_up_a_lightning_node]]
== Lightning node software
== Lightning Node Software
As we have seen in previous chapters, a Lightning node is a computer system that participates in the Lightning Network. The Lightning Network is not a product or company, it is a set of open standards that define a baseline for interoperability. As such, Lightning node software has been built by a variety of companies and community groups. The vast majority of Lightning software is _open source_, meaning that the source code is open and licensed in such a way as to enable collaboration, sharing and community participation in the development process. Similarly, the Lightning node implementations we will present in this chapter are all open source and are collaboratively developed.
@ -13,11 +13,11 @@ Another major difference between Lightning node software and Bitcoin node softwa
In this chapter, you will learn how to set up each of the software packages for the most popular Lightning node implementations. We've presented them in alphabetical order to emphasize that we generally do not prefer or endorse one over the other. Each has its strengths and weaknesses and choosing one will depend on a variety of factors. Since they are developed in different programming languages (e.g. Go, C, etc.), your choice may also depend on your level of familiarity and expertise with a specific language and development toolset.
=== Lightning development environment
=== Lightning Development Environment
If you're a developer, you will want to set up a development environment with all the tools, libraries, and support software for writing and running Lightning software. In this highly technical chapter, we'll walk through that process step-by-step. If the material becomes too dense or you're not actually setting up a development environment, then feel free to skip to the next chapter, which is less technical.
==== Using the command-line
==== Using the Command-Line
The examples in this chapter, and more broadly in most of this book, use a command-line terminal. That means that you type commands into a terminal and receive text responses. Furthermore, the examples are demonstrated on an operating system based on the Linux kernel and GNU software system, specifically the latest long-term stable release of Ubuntu (Ubuntu 20.04 LTS). The majority of the examples can be replicated on other operating systems such as Windows or Mac OS, with small modifications to the commands. The biggest difference between operating systems is the _package manager_ which installs the various software libraries and their pre-requisites. In the given examples, we will use +apt+, which is the package manager for Ubuntu. On Mac OS, a common package manager used for open source development is Homebrew (command +brew+) found at https://brew.sh.
@ -30,7 +30,7 @@ In many of the examples in this chapter we will be using the operating system's
To keep things consistent, we use the +bash+ shell in all command-line examples. While other shells will behave in a similar way, and you will be able to run all the examples without it, some of the shell scripts are written specifically for the +bash+ shell and may require some changes or customizations to run in another shell. For consistency, you can install the +bash+ shell on Windows and Mac OS, and it comes installed by default on most Linux systems.
==== Downloading the book repository
==== Downloading the Book Repository
All the code examples are available in the book's online repository. Because the repository will be kept up-to-date as much as possible, you should always look for the latest version in the online repository instead of copying it from the printed book or the ebook.
@ -56,7 +56,7 @@ $ cd lnbook
All subsequent examples will assume that you are running commands from inside this folder.
=== Docker containers
=== Docker Containers
Many developers use a _container_, which is a type of virtual machine, to install a pre-configured operating system and applications with all the necessary dependencies. Much of the Lightning software can also be installed using a container system such as _Docker_ found at https://docker.com. Container installations are a lot easier, especially for those who are not used to a command-line environment.
@ -126,7 +126,7 @@ code/docker
As we will see in the next few sections, you can build these containers locally, or you can pull them from the book's repository on _Docker Hub_. The following sections will assume that you have installed Docker and are familiar with the basic use of the +docker+ command.
=== Bitcoin Core and regtest
=== Bitcoin Core and Regtest
Most of the Lightning node implementations need access to a full Bitcoin node in order to work.
@ -136,7 +136,7 @@ A Bitcoin node can be operated in _regtest_ mode, where the node creates a local
The container for Bitcoin Core is +bitcoind+. It is configured to run Bitcoin Core in +regtest+ mode and to mine 6 new blocks every 10 seconds. Its RPC port is exposed on port 18443 and accessible for RPC calls with the username +regtest+ and the password +regtest+. You can also access it with an interactive shell and run +bitcoin-cli+ commands locally.
==== Building the Bitcoin Core container
==== Building the Bitcoin Core Container
Let's prepare the +bitcoind+ container. The easiest way is to pull the latest container from _Docker Hub_:
@ -208,7 +208,7 @@ As you can see, bitcoind starts up and mines 101 simulated blocks to get the cha
For now, there are no transactions. But we have some test bitcoin that has been mined in the wallet and is available to spend. When we connect some Lightning nodes to this chain, we will send some bitcoin to their wallets so that we can open some Lightning channels between the Lightning nodes.
===== Interacting with the Bitcoin Core container
===== Interacting with the bitcoin core container
In the mean time, we can also interact with the +bitcoind+ container by sending it shell commands. The container is sending a log file to the terminal, displaying the mining process of the bitcoind process. To interact with the shell we can issue commands in another terminal, using the +docker exec+ command. Since we previously named the running container with the +name+ argument, we can refer to it by that name when we run the +docker exec+ command. First, let's run an interactive +bash+ shell:
@ -258,7 +258,7 @@ $ docker exec bitcoind bash -c "cli getblockchaininfo | jq .blocks"
As you will see in the following sections, we can run several containers at the same time and then interact with them individually. We can issue commands to extract information such as the Lightning node public key or to take actions such as opening a Lightning channel to another node. The +docker run+ and +docker exec+ commands together with +jq+ for JSON decoding are all we need to build a working Lightning Network that mixes many different node implementations. This enables us to try out diverse experiments on our own computer.
=== The c-lightning Lightning node project
=== The C-Lightning Lightning Node Project
C-lightning is a lightweight, highly customizable, and standard-compliant implementation of the Lightning Network protocol, developed by Blockstream as part of the Elements project. The project is open source and developed collaboratively on Github:
@ -266,7 +266,7 @@ https://github.com/ElementsProject/lightning
In the following sections, we will build a Docker container that runs a c-lightning node connecting to the bitcoind container we build previously. We will also show you how to configure and build the c-lightning software directly from the source code.
==== Building c-lightning as a Docker container
==== Building C-Lightning As a Docker Container
The c-lightning software distribution has a Docker container, but it is designed for running c-lightning in production systems and along side a bitcoind node. We will be using a somewhat simpler container configured to run c-lightning for demonstration purposes.
@ -317,7 +317,7 @@ Our container is now built and ready to run. However, before we run the c-lightn
Docker containers can "talk" to each other over a virtual local area network managed by the Docker system. Each container can have a custom name and other containers can use that name to resolve its IP address and easily connect to it.
====
==== Setting up a Docker network
==== Setting Up a Docker Network
Once a Docker network is set up, Docker will activate the network on our local computer every time Docker starts, e.g. after rebooting. So we only need to set up a network once by using the +docker network create+ command. The network name itself is not important, but it has to be unique on our computer. By default, Docker has three networks named +host+, +bridge+, and +none+. We will name our new network +lnbook+ and create it like this:
@ -335,7 +335,7 @@ ee8824567c95 none null local
As you can see, running +docker network ls+ gives us a listing of the Docker networks. Our +lnbook+ network has been created. We can ignore the network ID, as it is automatically managed.
==== Running the bitcoind and c-lightning containers
==== Running the Bitcoind and C-Lightning Containers
The next step is to start the bitcoind and c-lightning containers and connect them to the +lnbook+ network. To run a container in a specific network, we must pass the +network+ argument to +docker run+. To make it easy for containers to find each other, we will also give each one a name with the +name+ argument. We start bitcoind like this:
@ -397,13 +397,13 @@ In the next section we will also look at how to download, configure and compile
If you are not planning on diving into the source code or programming of a Lightning node, you can skip the next section entirely. The Docker container we just built is sufficient for most of the examples in the book.
====
==== Installing c-lightning from source code
==== Installing C-Lightning from Source Code
The c-lightning developers have provided detailed instructions for building c-lightning from source code. We will be following the instructions here:
https://github.com/ElementsProject/lightning/blob/master/doc/INSTALL.md
==== Installing prerequisite libraries and packages
==== Installing Prerequisite Libraries and Packages
These installation instructions assume you are building c-lightning on a Linux or similar system with GNU build tools. If that is not the case, look for the instructions for your operating system in the ElementsProject repository above.
@ -446,7 +446,7 @@ $
After a few minutes and a lot of on-screen activity, you will have installed all the necessary packages and libraries. Many of these libraries are also used by other Lightning packages and needed for software development in general.
==== Copying the c-lightning source code
==== Copying the C-Lightning Source Code
Next, we will copy the latest version of c-lightning from the source code repository. To do this, we will use the +git clone+ command which clones a version-controlled copy onto your local machine thereby allowing you to keep it synchronized with subsequent changes without having to download the whole repository again:
@ -467,7 +467,7 @@ $ cd lightning
We now have a copy of c-lightning cloned into the +lightning+ subfolder, and we have used the +cd+ (change directory) command to enter that subfolder.
==== Compiling the c-lightning source code
==== 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:
@ -561,7 +561,7 @@ 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 above 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 (Lnd) Node Project
The Lightning Network Daemon (LND) is a complete implementation of a Lightning Network 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 back-end 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 Github:
@ -569,7 +569,7 @@ https://github.com/LightningNetwork/lnd
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
==== The Lnd Docker Container
We can pull the LND example docker container from the book's Docker Hub repository:
@ -618,7 +618,7 @@ Our container is now ready to run. As with the c-lightning container we built pr
Normally, each node operator runs their own Lightning node and their own Bitcoin node on their own server. For us, a single bitcoind container can serve many Lightning nodes. On our simulated network we can run several Lightning nodes, all connecting to a single Bitcoin node in regtest mode.
====
==== Running the bitcoind and LND containers
==== Running the Bitcoind and Lnd Containers
As before, we start the bitcoind container in one terminal and LND in another. If you already have the bitcoind container running, you do not need to restart it. Just leave it running and skip the next step. To start bitcoind in the +lnbook+ network we use +docker run+ like this:
@ -679,7 +679,7 @@ In the next section we will look at how to download and compile LND directly fro
If you are not planning on diving into the source code or programming of a Lightning node, you can skip the next section entirely. The Docker container we just built is sufficient for most of the examples in the book.
====
==== Installing LND from source code
==== Installing Lnd from Source Code
In this section we will build LND from scratch. LND is written in the Go programming language. IF you want to find out more about Go, search for +golang+ instead of +go+ to avoid irrelevant results. Because it is written in Go and not C or C++, it uses a different "build" framework than the GNU autotools/make framework we saw used in c-lightning previously. Don't fret though, it is quite easy to install and use the golang tools and we will show each step here. Go is a fantastic language for collaborative software development as it produces very consistent, precise, and easy to read code regardless of the number of authors. Go is focused and "minimalist" in a way that encourages consistency across versions of the language. As a compiled language, it is also quite efficient. Let's dive in.
@ -712,7 +712,7 @@ $ export PATH=$PATH:$GOPATH/bin
To avoid having to set these environment variables every time you open a shell, you can add those two lines to the end of your bash shell configuration file +.bashrc+ in your home directory, using the editor of your choice.
==== Copying the LND source code
==== Copying the Lnd Source Code
As with many open source projects nowadays, the source code for LND is on Github (www.github.com). The +go get+ command can fetch it directly using the Git protocol:
@ -723,7 +723,7 @@ $ go get -d github.com/lightningnetwork/lnd
Once +go get+ finishes, you will have a sub-directory under +GOPATH+ that contains the LND source code.
==== Compiling the LND source code
==== Compiling the Lnd Source Code
LND uses the +make+ build system. To build the project, we change directory to LND's source code and then use +make+ like this:
@ -745,7 +745,7 @@ lncli version 0.10.99-beta commit=clock/v1.0.0-106-gc1ef5bb908606343d2636c8cd345
You will likely see a different version from that shown above, 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 show you version information means that you have succeeded in building the LND software.
=== The Eclair Lightning node project
=== The Eclair Lightning Node Project
Eclair (French for Lightning) is a Scala implementation of the Lightning Network made by ACINQ. Eclair is also one of the most popular and pioneering mobile Lightning wallets which we used to demonstrate a Lightning payment in the second chapter. In this section we examine the Eclair server project which runs a Lightning node. Eclair is an open source project and can be found on GitHub:
@ -754,7 +754,7 @@ https://github.com/ACINQ/eclair
In the next few sections we will build a Docker container to run Eclair, as we did previously with c-lightning and LND. We will also build Eclair directly from the source code.
==== The Eclair docker container
==== The Eclair Docker Container
Let's pull the book's eclair container from the Docker Hub repository:
@ -802,7 +802,7 @@ Our image is now ready to run. The Eclair container also depends on a running in
One notable difference between Eclair and LND or c-lightning is that Eclair doesn't contain a separate bitcoin wallet but instead relies directly on the bitcoin wallet in Bitcoin Core. Recall that using LND we "funded" its bitcoin wallet by executing a transaction to transfer bitcoin from Bitcoin Core's wallet to LND's bitcoin wallet. This step is not necessary using Eclair. When running Eclair, the Bitcoin Core wallet is used directly as the source of funds to open channels. As a result, unlike the LND or c-lightning containers, the Eclair container does not contain a script to transfer bitcoin into its wallet on startup.
==== Running the bitcoind and Eclair containers
==== Running the Bitcoind and Eclair Containers
As before, we start the bitcoind container in one terminal and the Eclair container in another. If you already have the bitcoind container running, you do not need to restart it. Just leave it running and skip the next step. To start +bitcoind+ in the +lnbook+ network, we use +docker run+ like this:
@ -872,7 +872,7 @@ In the next section we will also look at how to download and compile Eclair dire
If you are not planning on diving into the source code or programming of a Lightning node, you can skip the next section entirely. The Docker container we just built is sufficient for most of the examples in the book.
====
==== Installing Eclair from source code
==== Installing Eclair from Source Code
In this section we will build Eclair from scratch. Eclair is written in the Scala programming language which is compiled using the Java compiler. To run Eclair, we first need to install Java and its build tools. We will be following the instructions found in the BUILD.md document of the Eclair project:
@ -902,7 +902,7 @@ Java version: 11.0.7, vendor: Ubuntu, runtime: /usr/lib/jvm/java-11-openjdk-amd6
We have OpenJDK 11.0.7 and Maven 3.6.1, so we're ready.
==== Copying the Eclair source code
==== Copying the Eclair Source Code
The source code for Eclair is on Github. The +git clone+ command can create a local copy for us. Let's change to our home directory and run it there:
@ -915,7 +915,7 @@ $ git clone https://github.com/ACINQ/eclair.git
Once +git clone+ finishes you will have a sub-directory +eclair+ containing the source code for the Eclair server.
==== Compiling the Eclair source code
==== Compiling the Eclair Source Code
Eclair uses the +Maven+ build system. To build the project we change the working directory to Eclair's source code and then use +mvn package+ like this:
@ -951,7 +951,7 @@ https://github.com/ACINQ/eclair#installing-eclair
Congratulations! You have built Eclair from source and you are ready to code, test, fix bugs, and contribute to this project!
=== Building a complete network of diverse Lightning nodes
=== Building a Complete Network of Diverse Lightning Nodes
Our final example, presented in this section, will bring together all the various containers we've built to form a Lightning network made of diverse (LND, c-lightning, Eclair) node implementations. We'll compose the network by connecting the nodes together and opening channels from one node to another. As the final step, we'll route a payment across these channels!
@ -963,7 +963,7 @@ image::images/mtln_1002.png["A small demonstration network of four nodes"]
Finally, we will have Dina create an invoice and have Alice pay that invoice. Since Alice and Dina are not directly connected, the payment will be routed as an HTLC across all the payment channels.
==== Using docker-compose to orchestrate Docker containers
==== Using Docker-Compose to Orchestrate Docker Containers
To make this example work, we will be using a _container orchestration_ tool that is available as a command called +docker-compose+. This command allows us to specify an application composed of several containers and run the application by launching all the cooperating containers together.
@ -983,7 +983,7 @@ docker-compose version 1.21.0, build unknown
The most common +docker-compose+ commands we will use are +up+ and +down+, e.g. +docker-compose up+.
==== Docker-compose configuration
==== Docker-Compose Configuration
The configuration file for +docker-compose+ is found in the +code/docker+ directory and is named +docker-compose.yml+. It contains a specification for a network and each of the four containers. The top looks like this:
@ -1013,7 +1013,7 @@ The fragment above defines a network called +lnnet+ and a container called +bitc
Since all these diverse implementations follow the Basis of Lightning Technologies (BOLT) specification and have been extensively tested for interoperability, they have no difficulty working together to build a Lightning network.
==== Starting the example Lightning network
==== Starting the Example Lightning Network
Before we get started, we should make sure we're not already running any of the containers. If a new container shares the same name as one that is already running, then it will fail to launch. Use +docker ps+, +docker stop+, and +docker rm+ as necessary to stop and remove any currently running containers!
@ -1064,7 +1064,7 @@ Following the start up, you will see a whole stream of log files as each of the
$ docker-compose logs -f Alice
----
==== Opening channels and routing a payment
==== Opening Channels and Routing a Payment
Our Lightning network should now be running. As we saw in the previous sections of this chapter, we can issue commands to a running Docker container with the +docker exec+ command. Regardless of whether we started the container with +docker run+ or started a bunch of them with +docker-compose up+, we can still access containers individually using the Docker commands.

@ -1,6 +1,6 @@
[[operating_ln_node]]
[[node_operations]]
== Operating a Lightning Network node
== Operating a Lightning Network Node
After having read this far, you have probably set up a Lightning wallet. In this chapter, we will take things one step further and set up a full Lightning node. In addition to setting one up, we will learn how to operate it and maintain it over time.
@ -33,12 +33,12 @@ _after_ you have done this due diligence exercise. Most people will find their m
but somewhere else.
====
=== Choosing your platform
=== Choosing Your Platform
There are many ways you can run a Lightning node ranging from a small mini-PC hosted in your home or a dedicated server to a hosted server in the cloud. The method you choose will depend on the resources you have and how much money you want to spend.
[[continuous_operation]]
==== Why is reliability important for running a Lightning node?
==== Why Is Reliability Important for Running a Lightning Node?
In Bitcoin, hardware is not particularly important unless one is specifically running a mining node.
The Bitcoin Core node software can be run on any machine that meets its minimum requirements and does not need to be online to receive payments; only to send them.
@ -53,7 +53,7 @@ There are also the issues of hardware failure and loss of data. In Bitcoin, a ha
In contrast, in Lightning the information about the user's channels, including the commitment transactions and revocation secrets, are not publicly known and are only stored on the individual user's hardware.
Thus, software and hardware failures in the Lightning Network can easily result in loss of funds.
==== Types of hardware Lightning nodes
==== Types of Hardware Lightning Nodes
There are three main types of hardware Lightning nodes:
@ -61,7 +61,7 @@ There are three main types of hardware Lightning nodes:
* **Dedicated hardware**: A Lightning node can also be run on dedicated hardware like a Raspberry Pi, Rock64, or mini PC. This setup would usually run a software stack including a Bitcoin node and other applications. This setup is popular as the hardware is dedicated to running and maintaining the Lightning node only and is usually set up with an installation "helper".
* **Pre-configured hardware**: A Lightning Network node can also be run on purpose-built hardware specifically selected and configured for it. This would include "out-of-the-box" Lightning node solutions that can be purchased as a kit or a turn-key system.
==== Running in the "cloud"
==== Running in the "Cloud"
_Virtual Private Server_ (VPS) and "cloud computing" services such as Microsoft Azure, Google Cloud, Amazon Web Services (AWS), or DigitalOcean are quite affordable and can be set up very quickly. A Lightning node can be hosted for between $20 and $40 per month on such a service.
@ -71,7 +71,7 @@ On the other hand there are several notable disadvantages. A Lightning node runn
If you have the possibility and capacity of running a node on your own computer at home or in your office, then this might be preferable to running it
in the cloud. Nonetheless, if running your own server is not an option, by all means consider running one on a VPS.
==== Running a node at home
==== Running a Node At Home
If you have a reasonable capacity Internet connection at home or in your office, you can certainly run a Lightning node there. Any "broadband" connection is sufficient for the purpose of running a lightweight node, and a fast connection will allow you to run a Bitcoin full node too.
@ -92,7 +92,7 @@ No one will even know that this little box is actually part of a global banking
Operating a node on a 32-bit operating system and/or 32-bit CPU is not recommended, as the node software may run into resource issues, causing a crash and possibly a loss of funds.
====
==== What hardware is required to run a Lightning node?
==== What Hardware Is Required to Run a Lightning Node?
At a minimum, the following will be required to run a Lightning node:
@ -121,7 +121,7 @@ Ideally, you should connect your Internet router to this UPS as well.
* **Backup**: Backup is crucial as a failure can result in loss of data and hence in loss of funds.
The user will want to consider some kind of data backup solution. This could be a cloud-based automated backup to a server or web service the user controls. Alternatively, it could be an automated local hardware backup, such as a second hard drive. For the best results, both local and remote backup can be combined.
==== Switching server configuration in the cloud
==== Switching Server Configuration in the Cloud
When renting a cloud server, it is often cost effective to change the configuration between two phases of operation. A faster CPU and faster storage will be needed during the Initial Block Download (e.g. the first day). After the blockchain has synced, the CPU and storage speed requirements are much less, so the performance can be downgraded to a more cost-effective level.
@ -141,11 +141,11 @@ For example, the Raspberry Pi 4 cannot benefit from them because of the limited
To choose the size, let's look at the Bitcoin blockchain. As of August 2021, its size is 360GB including the transaction index and grows by roughly 60GB/year. If you want to have some margin available for future growth or to install other data on your node, purchase at least a 512GB drive or better yet a 1TB drive.
[[helpers]]
=== Using an installer or helper
=== Using an Installer or Helper
Installing a Lightning node or a Bitcoin node may be daunting if you are not familiar with a command line environment. Luckily, there are a number of projects that make "helpers", i.e. software that installs and configures the various components for you. You will still need to learn some command line incantations to interact with your node, but most of the initial work is done for you.
==== RaspiBlitz
==== Raspiblitz
One of the most popular and complete "helpers" is _RaspiBlitz_ (<<RaspiBlitz>>), a project built by Christian Rotzoll. It is intended to be installed on a Raspberry Pi 4. RaspiBlitz comes with a recommended hardware "kit" that you can build in a matter of hours or at most a weekend. If you attend a Lightning "hackathon" in your city, you are likely to see many people working on their RaspiBlitz setup, swapping tips, and helping each other. You can find the RaspiBlitz project here:
@ -169,7 +169,7 @@ In addition to a Bitcoin and Lightning node, RaspiBlitz can install a number of
* JoinMarket (CoinJoin service)
==== myNode
==== Mynode
_myNode_ is another popular open source "helper" project including a lot of Bitcoin related software. It is easy to install: you "flash" the installer onto an SD card and boot your mini-PC from the SD card. You do not need any monitor to use myNode as the administrative tools are accessible remotely from a browser. If your mini-PC has no monitor, mouse, or keyboard; you can manage it from another computer or even from your smartphone. Once installed, go to http://mynode.local/ and create a Lightning wallet and node in two clicks.
@ -208,7 +208,7 @@ In addition to a Bitcoin and Lightning node, Umbrel introduced the Umbrel App St
Umbrel is currently still in beta and not considered secure.
==== BTCPay Server
==== Btcpay Server
While not initially designed as an installation "helper", the e-commerce and payment platform _BTCPay Server_ has an incredibly easy installation system that uses Docker containers and +docker-compose+ to install a Bitcoin node, Lightning node, and payment gateway, among many other services. It can be installed on a variety of hardware platforms, from a simple Raspberry Pi 4 (4GB recommended) to a mini PC, old laptop, desktop or server.
@ -232,7 +232,7 @@ In addition to a Bitcoin and Lightning node, BTCPay Server can also install a va
The number of additional services and features is growing rapidly, so the list above is only a small subset of what is available on the BTCPay Server platform.
==== Bitcoin node or lightweight Lightning
==== Bitcoin Node or Lightweight Lightning
One critical choice for your setup will be the choice of the Bitcoin node and its configuration. _Bitcoin Core_, the reference implementation, is the most common choice but not the only choice available. One alternative choice is _btcd_, which is a Go-language implementation of a Bitcoin node. Btcd supports some features that are useful for running an LND Lightning node and are not available in Bitcoin Core.
@ -244,7 +244,7 @@ Keep in mind that operating a Bitcoin node allows you to support other services,
The bottom line for this decision is: If you can afford a disk larger than 500GB, run a full archival Bitcoin node. You will be contributing resources to the Bitcoin system and helping others who cannot afford to do so. If you can't afford such a big disk, run a pruned node. If you can't afford the disk or the bandwidth for even a pruned node, run a lightweight LND node over neutrino.
==== Operating system choice
==== Operating System Choice
The next step is to select an operating system for your node. The vast majority of Internet servers run on some variant of Linux. Linux is the platform of choice for the Internet because it is a powerful, open-source operating system. Linux, however, has a steep learning curve and requires familiarity with a command line environment. It is often intimidating for new users.
@ -252,7 +252,7 @@ Ultimately, most of the services can be run on any modern POSIX operating system
Nowadays, many services are also delivered in the form of containers, usually based on the _Docker_ system. These containers can be deployed on a variety of operating systems, abstracting the underlying OS. You may need to learn some Linux CLI commands nonetheless, as most of the containers run some variant of Linux inside.
=== Choose your Lightning node implementation
=== Choose Your Lightning Node Implementation
As with the choice of operating system, your choice of Lightning node implementation should depend primarily on your familiarity with the programming language and development tools used by the projects. While there are some small differences in features between the various node implementations, those are relatively minor and most implementations converge on the common standards defined by the BOLTs.
@ -281,7 +281,7 @@ On the other hand, if this is your first foray into the command line and server/
As a final consideration, you may want to examine the performance and reliability of different node implementations. This is especially important if you will be using this node in a production environment and expect heavy traffic and high reliability requirements. This might be the case if you plan to run the payment system of a shop on it.
=== Installing a Bitcoin or Lightning node
=== Installing a Bitcoin or Lightning Node
You decided not to use an installation "helper" and instead to dive into the command line of a Linux operating system? That is a brave decision and we'll try to help you make it work. If you'd rather not try to do this manually, consider using an application that helps you install the node software or a container-based solution, as described in <<helpers>>.
@ -292,13 +292,13 @@ This section will delve into the advanced topic of system administration from th
In the next few sections we will briefly describe how to install and configure a Bitcoin and Lightning node on a Linux operating system. You will need to review the installation instructions for the specific Bitcoin and Lightning node applications you decided to use. You can usually find these in a file called +INSTALL+ or in the +docs+ sub-directory of each project. We will only describe some of the common steps that apply to all such services, and the instructions we offer will be necessarily incomplete.
==== Background services
==== Background Services
For those accustomed to running applications on their desktop or smartphone, an application always has a graphical user interface even if it may sometimes run in the background. The Bitcoin and Lightning node applications, however, are very different. These applications do not have a graphical user interface built in. Instead, they run as _headless_ background services, meaning they are always operating in the background and do not interact with the user directly.
This can create some confusion for users who are not used to running background services. How do you know if such a service is currently running? How do you start and stop it? How do you interact with it? The answers to these questions depend on the operating system you are using. For now we will assume you are using some Linux variant and answer them in that context.
==== Process isolation
==== Process Isolation
Background services usually run under a specific user account in order to isolate them from the operating system and each other. For example, Bitcoin Core is configured to run as user +bitcoin+. You will need to use the command line to create a user for each of the services you run.
@ -312,7 +312,7 @@ $ sudo useradd -m -d /external_drive/bitcoin -s /dev/null bitcoin
The +m+ and +d+ flags create the user's home directory as specified by /external_drive/bitcoin in this case. The +s+ flag assigns the user's interactive shell. In this case, we set it to +/dev/null+ to disable interactive shell use. The last argument is the new user's username +bitcoin+.
==== Node startup
==== Node Startup
For both Bitcoin and Lightning node services, "installation" also involves creating a so called _startup script_ to make sure that the node starts when the computer boots. Startup and shutdown of background services is handled by an operating system process, which in Linux is called _init_ or _systemd_. You can usually find a system startup script in the +contrib+ sub-directory of each project. For example, if you are on a modern Linux OS that uses +systemd+, you would find a script called +bitcoind.service+, that can start and stop the Bitcoin Core node service.
@ -386,7 +386,7 @@ $ sudo systemctl start bitcoind
$ sudo systemctl stop bitcoind
----
==== Node configuration
==== Node Configuration
To configure your node, you need to create and reference a configuration file. By convention, this file is usually created in +/etc+, under a directory with the name of the program. For example, Bitcoin Core and LND configurations would usually be stored in:
@ -426,7 +426,7 @@ bitcoin-rpcpassword=PASSWORD
In general, it is a good idea to minimize the amount of customization of these systems. The default configuration is carefully designed to support the most common deployments. If you modify a default value, it may cause problems later on or reduce the performance of your node. In short, modify only when necessary!
==== Network configuration
==== Network Configuration
Network configuration is normally not an issue when configuring a new application. However, peer-to-peer networks like Bitcoin and the Lightning network present some unique challenges for network configuration.
@ -465,7 +465,7 @@ image::images/mtln_0503.png[]
In <<ln_port_check>> you can see the result of checking port 9735 on a server running Lightning, using the +whatismyip.org+ port scanner tool. It shows that the server is accepting incoming connections to the Lightning port. If you see a result like this, you are all set!
===== Automatic port forwarding using UPNP
===== Automatic port forwarding using upnp
Sometimes, even if your Internet router supports UPNP, it may be turned off by default. In that case you need to change your Internet router configuration from its web administration interface:
@ -477,7 +477,7 @@ Sometimes, even if your Internet router supports UPNP, it may be turned off by d
Restart your Bitcoin and/or Lighting node and repeat the open port test with one of the websites we used in the previous section.
===== Using Tor for incoming connections
===== Using tor for incoming connections
_The Onion Router (Tor)_ is a virtual private network with the special property that it encrypts communications between hops, such that any intermediary node cannot determine the origin or destination of a packet. Both Bitcoin and Lightning nodes support operation over Tor, which enables you to operate a node without revealing your IP address or location. Hence, it provides a high level of privacy to your network traffic. An added benefit of running Tor is that because it operates as a VPN, it resolves the problem of port forwarding from your Internet router. Incoming connections are received over the Tor tunnel, and your node can be found through an ad-hoc generated _onion address_ instead of an IP address.
@ -528,7 +528,7 @@ The basic steps are as follows:
Once done re-configuring, repeat the port check using one of the websites from the previous sections.
=== Security of your node
=== Security of Your Node
A Lightning node is, by definition, a hot wallet. That means that the funds (both on-chain and off-chain) controlled by a Lightning node are directly controlled by keys that are loaded in the node's memory or stored on the node's hard disk. If a Lightning node is compromised, it is trivial to create on-chain or off-chain transactions to drain its funds. It is therefore critically important that you protect it from unauthorized access.
@ -537,7 +537,7 @@ Security is a holistic effort, meaning that you have to secure every layer of a
Despite all security measures you will take, remember that the Lightning Network is an early-stage experimental technology and there are likely to be exploitable bugs in the code of any project you use. *Do not put more money than you are willing to risk losing on the Lightning Network.*
==== Operating system security
==== Operating System Security
Securing an operating system is a vast topic that is beyond the scope of this book. However, we can establish some basic principles.
@ -556,7 +556,7 @@ To secure your operating system, here are some of the top items to consider:
This is a list of the most basic security measures. It is by no means exhaustive.
==== Node access
==== Node Access
Your Lightning node will expose a Remote Procedure Call (RPC) Application Programming Interface (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.
@ -566,7 +566,7 @@ If you use a username/password authentication model, make sure you select a long
A plain alphanumeric sequence that is longer than 12 characters and randomly generated is usually sufficient. If you plan to store large amounts of money on your Lightning node and are concerned about remote brute-force attacks, select a password length of more than 20 characters to make such attacks practically infeasible.
=== Node and channel backups
=== Node and Channel Backups
A very important consideration when running a Lightning node is the issue of backups. Unlike a Bitcoin wallet, where a BIP39 mnemonic phrase can recover all the state of the wallet, in Lightning this is _not_ the case.
@ -585,7 +585,7 @@ You can see that SCBs are not a fool-proof safeguard. They are a weak compromise
Channel backup mechanisms are still a work-in-progress and a weakness in most Lightning implementations.
==== Static Channel Backups (SCB)
==== Static Channel Backups (Scb)
At the time of writing this book, only LND offers a built-in mechanism for static channel backups. 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 plugin to implement channel backups. Unfortunately, there is no consistent, agreed upon backup mechanism across different node implementations.
@ -593,7 +593,7 @@ File-based backups of the Lightning node databases are at best a partial solutio
To set up static channel backups 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 setup 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.
==== Hot wallet risk
==== Hot Wallet Risk
As we've discussed previously, the Lightning Network consists of a network of _hot wallets_. The funds you store in a Lightning wallet are *online all the time*. This makes them vulnerable. Hence, you should not store large amounts in a Lightning wallet. Large amounts should be kept in a _cold_ wallet that is _not_ online and which can transact only on-chain.
@ -601,7 +601,7 @@ Even if you start small, as time passes you may still find you have a significan
Let's look at some of the solutions you can use to reduce the funds exposed in a hot wallet.
==== Sweeping funds
==== Sweeping Funds
If your Lightning wallet balance becomes too large for your risk tolerance, you will need to "sweep" funds out of the wallet. You can do so in three ways: on-chain, off-chain, and loop-out. Let's look at each one of these options in the next few sections.
@ -635,7 +635,7 @@ The advantage of a submarine swap for sweeping funds is that no channel needs to
You could do this by trusting an intermediary to act as a gateway, but this risks your coins being stolen. But in the case of a submarine swap, the operation does not require trust. Submarine swaps are non-custodial _atomic_ operations. That means that the counterparty in your submarine swap cannot steal your funds because the on-chain payment depends on the completion of the off-chain payment and vice-versa.
===== Submarine swaps with Loop
===== Submarine swaps with loop
One example of a submarine swap service is _Loop_ by Lightning Labs, the same company that builds LND. Loop comes in two variations: _Loop In_ and _Loop Out_. _Loop In_ accepts a Bitcoin on-chain payment and converts it into a Lightning off-chain payment. _Loop Out_ converts a Lightning payment into a Bitcoin payment.
@ -670,7 +670,7 @@ Run `loop monitor` to monitor progress.
Note that your maximum fee, which represents a worst-case scenario, will depend on the confirmation target that you select.
=== Lightning node uptime and availability
=== Lightning Node Uptime and Availability
Unlike Bitcoin, Lightning nodes need to be online almost continuously. Your node needs to be online to receive payments, open channels, close channels (cooperatively), and monitor protocol violations. Node availability is such an important requirement in the Lightning Network that it is a metric used by various automatic channel management tools (e.g. +autopilot+) to decide which nodes to open channels with. You can also see "availability" as a node metric on popular node explorers (see <<ln_explorer>>) such as +1ml.com+.
@ -678,7 +678,7 @@ Node availability is especially important to mitigate and resolve potential prot
Keeping a node online continuously is not easy, as various bugs and resource limitations can and will occasionally cause downtime. Especially if you run a busy and popular node, you will run into limitations of memory, swap space, number of open files, disk space, and so forth. A whole host of different problems will cause your node or your server to crash.
==== Tolerate faults and automate
==== Tolerate Faults and Automate
If you have the time and skills you should test some basic fault scenarios on the Lightning testnet. On the testnet you will learn valuable lessons without risking any funds. Any step you perform to automate your system will improve your availability.
@ -690,7 +690,7 @@ If you have the time and skills you should test some basic fault scenarios on th
- Configure your log files: All of the above failures should leave textual entries behind in the corresponding log files. Turn up the verbosity of logging if needed. Find these error entries in the log files and use them for monitoring.
==== Monitoring node availability
==== Monitoring Node Availability
Monitoring your node is an important part of keeping it running. You need to monitor not only the availability of the computer itself, but also the availability and correct operation of the Lightning node software.
@ -757,11 +757,11 @@ Finally, a popular standalone watchtower server is _The Eye of Satoshi_ (TEOS).
https://github.com/talaia-labs/python-teos
=== Channel management
=== Channel Management
As a Lightning node operator, one of the recurring tasks you will need to perform is management of your channels. This means opening outbound channels from your node to other nodes, as well as getting other nodes to open inbound channels to your node. In the future, cooperative channel construction may be possible, so you can open symmetric channels that have funds committed on both ends on creation. For now, however, new channels only have funds on one end, on the originator's side. Hence, to make your node _balanced_ with both inbound and outbound capacity, you need to open channels to others and entice others to open channels to your node.
==== Opening outbound channels
==== Opening Outbound Channels
As soon as you get your Lightning node up and running, you can fund its Bitcoin wallet and then start opening channels with those funds.
@ -865,7 +865,7 @@ In the future, such improved autopilots might also use this collected data to ma
Overall, at the time of writing of this book, be cautious not to depend or rely too heavily on autopilots.
==== Getting inbound liquidity
==== Getting Inbound Liquidity
In the current design of the Lightning Network, it is more typical for users to obtain outbound liquidity _before_ obtaining inbound liquidity.
They will do so by opening a channel with another node, and more often they'll be able to spend bitcoin before they can receive it.
@ -898,7 +898,7 @@ In the future these challenges can be partially mitigated by the implementation
Ultimately, Lightning users need to be strategic and proactive about channel management to ensure that sufficient inbound capacity is available to meet their needs.
==== Closing channels
==== Closing Channels
As discussed earlier in the book, a _mutual close_ is the preferred way of closing a channel. However, there are instances where a _force close_ is necessary.
@ -909,7 +909,7 @@ Some examples:
* Your channel partner is online and your nodes are negotiating a mutual close, but they become stuck and cannot reach a resolution.
[[channel_rebalancing]]
==== Re-balancing channels
==== Re-Balancing Channels
In the course of transacting and routing payments on Lightning, the combination of inbound and outbound capacities can become unbalanced.
@ -927,7 +927,7 @@ Circular re-balancing is supported by most Lightning node implementations and ca
Channel rebalancing is a complex issue that is the subject of active research and covered in more detail in <<channel_rebalancing>>.
=== Routing fees
=== Routing Fees
Running a Lightning node allows you to earn fees by routing payments across your channels. Routing fees are generally not a significant source of income and dwarfed by the cost of operating a node. For example, on a relatively busy node that routes a dozen payments a day, the fees amount to no more than 2000 satoshis.
@ -960,14 +960,14 @@ For most nodes, it is usually best to use the default routing fee values. This w
You can also use the routing fee settings to re-balance channels. If most of your channels have the default fees but you want to rebalance a particular channel, just decrease the fees on that specific channel to zero or to very low rates. Then sit back and wait for someone to route a payment over your "cheap" route and re-balance your channels for you as a side-effect.
=== Node management
=== Node Management
Managing your Lightning node on the command line is obviously not easy. It gives you the full flexibility of the node's API and the ability to write your own custom scripts to satisfy your personal requirements. But if you don't want to deal with the complexity of the command line and only need some basic node management capabilities, you should consider installing a web-based user interface that makes node management easier.
There are a number of competing projects that offer web-based Lightning node management. Some of the most popular ones are described below.
[[rtl]]
==== Ride The Lightning (RTL)
==== Ride the Lightning (Rtl)
_RTL_ is a graphical web user interface to help users manage Lightning node operations for the three main Lightning node implementations (LND, c-lightning, and Eclair). RTL is an open source project developed by Suheb, Shahana Farooqui, and many other contributors. You can find the RTL software here:
@ -979,13 +979,13 @@ Here is an example screenshot of RTL's web interface, as provided on the project
.Example RTL web interface
image::images/mtln_0505.png[]
==== LNDMon
==== Lndmon
Lightning Labs, the makers of LND, provide a web-based graphical user interface called +lndmon+ to monitor the various metrics of an LND Lightning node. +lndmon+ only works with LND nodes. It is a read-only interface for monitoring and as such does not allow you to actively manage the node. It cannot open channels or make payments. Find +lndmon+ here:
https://github.com/lightninglabs/lndmon
==== ThunderHub
==== Thunderhub
A very aesthetically pleasing web-based graphical user interface similar to RTL but exclusive to LND. It can be used to make payments, rebalance channels and manage the node through a variety of features. Find +ThunderHub+ here:

@ -9,7 +9,7 @@ The messages exchanged by Alice and Bob's nodes are defined in https://github.co
.The Lightning Network Protocol Suite
image::images/mtln_0701.png["The Lightning Network Protocol Suite"]
=== A different way of using the Bitcoin system
=== A Different Way of Using the Bitcoin System
The Lightning Network is often described as a "Layer 2 Bitcoin Protocol", which makes it sound distinct from Bitcoin. Another way to describe Lightning is as a "smarter way to use Bitcoin" or just as an "Application on top of Bitcoin". Let's explore that.
@ -25,7 +25,7 @@ image::images/mtln_0702.png["Lightning payment channel made of on-chain and off-
Lightning is Bitcoin. It's just a different way of using the Bitcoin system.
=== Bitcoin ownership and control
=== Bitcoin Ownership and Control
Before we understand payment channels, we have to take a small step back and understand how ownership and control work in Bitcoin.
@ -38,17 +38,17 @@ Keep in mind that the term "ownership" as used in Bitcoin is distinct from the t
Bitcoin ownership is only about control of keys and the ability to spend the Bitcoin with those keys. As the popular Bitcoin saying by goes: "Your keys, your coins - not your keys, not your coins"
====
==== Diversity of (independent) ownership and multisig
==== Diversity of (Independent) Ownership and Multisig
Ownership and control of private keys is not always in the hands of one person. That's where things get interesting and complicated. We know that more than one person can come to know the same private key, either through theft or because the original holder of the key makes a copy and gives it to someone else. Are all these people owners? In a practical sense they are, because any one of the people who know the private key can spend the bitcoin without the approval of any other.
Bitcoin also has multisignature addresses where multiple private keys are needed to sign before spending (see <<multisig>>). From a practical perspective, ownership in a multisignature address depends on the quorum (K) and total (N) defined in the K-of-N scheme. A 1-of-10 multisignature scheme would allow any one (K) of 10 (N) signers to spend a bitcoin amount locked in that address. This is similar to the scenario where ten people have a copy of the same private key and any of them can independently spend it.
==== Joint ownership without independent control
==== Joint Ownership Without Independent Control
There is also the scenario where *no one* has quorum. In a 2-of-2 scheme like that used in the Lightning Network, neither signer can spend the bitcoin without obtaining a signature from the other party. Who owns the bitcoin in that case? No one really has ownership because no one has control. They each own the equivalent of a voting share in the decision, but both votes are needed. A key problem (pun intended) with a 2-of-2 scheme, in both Bitcoin and the law, is what happens if one of the parties is unavailable, or if there is a vote deadlock and any one party refuses to cooperate.
==== Preventing "locked" and un-spendable Bitcoin
==== Preventing "Locked" and Un-Spendable Bitcoin
If one of the two signers of a 2-of-2 multisig cannot or will not sign, the funds become un-spendable. Not only can this scenario occur accidentally (loss of keys), but it can be used as a form of blackmail by either party: "I won't sign unless you pay me a part of the funds".
@ -57,13 +57,13 @@ Payment channels in Lightning are based on a 2-of-2 multisig address, with the t
In the next section, as we look at how to open (create) a Lightning channel, we will see how we can prevent loss of funds or any blackmail scenario between the two partners by implementing a fairness protocol for the channel construction with the help of pre-signed transactions that spend the multisig output in a way that gives the peers in the channel exclusive ability to spend one of the outputs which encodes the amount of Bitcoin they own in the channel.
=== Constructing a payment channel
=== Constructing a Payment Channel
In <<what_is_payment_channel>>, we described payment channels as a _financial relationship_ between two Lightning Nodes, which is established by funding a 2-of-2 multisignature address from the two channel partners.
Let's assume that Alice wants to construct a payment channel allowing her to connect to Bob's store directly. First, the two nodes (Alice's and Bob's) have to establish an internet connection to each other, so that they can negotiate a payment channel.
==== Node private and public keys
==== Node Private and Public Keys
Every node on the Lightning Network is identified by a _node public key_. The public key uniquely identifies the specific node and is usually presented as a hexadecimal encoding. For example, Rene Pickhardt currently runs a Lightning Node (+ln.rene-pickhardt.de+) that is identified by the following node public key:
@ -73,7 +73,7 @@ Every node on the Lightning Network is identified by a _node public key_. The pu
Each node generates a root private key when first initialized. The private key is kept private at all times (never shared) and securely stored in the node's wallet. From that private key, the node derives a public key which is the node identifier and shared with the network. Since the key space is enormous, as long as each node generates the private key randomly, it will have a unique public key, which can therefore uniquely identify it on the network.
==== Node network address
==== Node Network Address
Additionally, every node also advertises a network address where it can be reached, in one of several possible formats:
@ -94,7 +94,7 @@ For example, Rene's node with node public key +02a1ceb...45ea7b8+ currently adve
The default TCP port for the Lightning Network is 9735, but a node can choose to listen on any TCP port.
====
==== Node identifiers
==== Node Identifiers
Together the node public key and network address are written in the following format, separated by an +@+ sign, as +NodeID@Address:Port+
@ -113,7 +113,7 @@ The identifier above is often encoded in a QR code, making it easier for users t
Much like Bitcoin Nodes, Lightning Nodes advertise their presence on the Lightning Network by "gossiping" their node public key and network address. That way, other nodes can find them and keep an inventory (database) of all the known nodes that they can connect to and exchange the messages that are defined in the Lightning P2P message protocol.
==== Connecting nodes as direct peers
==== Connecting Nodes As Direct Peers
In order for Alice's node to connect to Bob's node, she will need Bob's node public key, or the full address containing the public key, IP or Tor address and port. Because Bob runs a store, Bob's node address can be retrieved from an invoice or a store payment page on the web. Alice can scan a QR code that contains the address and instruct her node to connect to Bob's node.
@ -124,7 +124,7 @@ Once Alice has connected to Bob's node, their nodes are now directly connected _
To open a payment channel, two nodes must first be _connected_ as direct peers by opening a connection over the internet (or Tor).
====
=== Constructing the channel
=== Constructing the Channel
Now that Alice's and Bob's Lightning nodes are connected, they can begin the process of constructing a payment channel. In this section we will review the communications between their nodes, known as the _Lightning Peer Protocol for Channel Management_, and the cryptographic protocol that they use to build Bitcoin transactions.
@ -138,7 +138,7 @@ We describe two different protocols in this scenario. First, there is a _message
The Lightning Peer Protocol for Channel Management is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md[BOLT #2 - Peer Protocol for Channel Management]. In this chapter we will be reviewing the "Channel Establishment" and "Channel Closing" sections of BOLT#2 in more detail.
==== Channel establishment message flow
==== Channel Establishment Message Flow
Channel establishment is achieved by the exchange of six messages between Alice and Bob's nodes (three from each peer): +open_channel+, +accept_channel+, +funding_created+, +funding_signed+, +funding_locked+ and +funding_locked+. The six messages are shown as a time-sequence diagram in <<funding_message_flow>>:
@ -248,11 +248,11 @@ funding_pubkey:: This is the public key Bob's node contributes for the 2-of-2 mu
minimum_depth:: This is the number of confirmations that Bob's node expects for the funding transaction before it considers the channel "open" and ready to use.
==== The funding transaction
==== The Funding Transaction
Once Alice's node receives Bob's +accept_channel+ message, it has the information necessary to construct the _funding transaction_ that anchors the channel to the Bitcoin blockchain. As we discussed in earlier chapters, a lightning payment channel is anchored by a 2-of-2 multisignature address. First, we need to generate that multisignature address in order to allow us to construct the funding transaction (and the refund transaction as described below).
==== Generating a multisignature address
==== Generating a Multisignature Address
The funding transaction sends some amount of bitcoin (+funding_satoshis+ from the +open_channel+ message) to a 2-of-2 multisignature output that is constructed from Alice and Bob's +funding_pubkey+ public keys.
@ -273,7 +273,7 @@ This script is encoded as a Pay-to-Witness-Script-Hash Bitcoin address, that loo
----
bc1q89ju02heg32yrqdrnqghe6132wek25p6sv6e564znvrvez7tq5zqt4dn02
----
==== Constructing the funding transaction
==== Constructing the Funding Transaction
Alice's node can now construct a funding transaction, sending the amount agreed 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 this:
@ -288,11 +288,11 @@ Alice *does not broadcast* this transaction, because doing so would put her 140,
In the current implementation of Lightning, channels are funded only by the node initiating the channel (Alice in our example). Dual-funded channels have been proposed, but not yet implemented. In a dual-funded channel, both Alice and Bob would contribute inputs to the funding transaction. Dual-funded channels require a slightly more complicated message flow and cryptographic protocol, so they have not been implemented yet but are planned for a future update to the Lightning BOLTs. The C-Lightning implementation includes an experimental version of a variant on dual funded channels.
****
==== Holding signed transactions without broadcasting
==== Holding Signed Transactions Without Broadcasting
An important Bitcoin feature that makes Lightning possible is the ability to construct and sign transactions, but not broadcast them. The transaction is *valid* in every way, but until it is broadcast and confirmed on the Bitcoin blockchain it is not recognized and its outputs are not spendable as they have not been created on the blockchain. We will use this capability many times in the Lightning Network and Alice's node uses the capability when constructing the funding transaction: holding it and not broadcasting it yet.
==== Refund before funding
==== Refund Before Funding
To prevent loss of funds, Alice cannot put her bitcoin into a 2-of-2 until she has a way to get a refund if things go wrong. Essentially, she must plan the "exit" from the channel before she enters into this arrangement.
@ -300,7 +300,7 @@ Consider the legal construct of a prenuptial agreement, also known as a "prenup"
We can create a similar agreement in Bitcoin. For example, we can create a refund transaction, which functions like a prenup, allowing the parties decide how the funds in their channel will be divided before their funds are actually locked into the multisignature funding address.
==== Constructing the pre-signed refund transaction
==== Constructing the Pre-Signed Refund Transaction
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. We call this refund transaction a _commitment transaction_ as 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.
@ -312,7 +312,7 @@ image::images/mtln_0705.png["Alice also constructs the refund transaction"]
Later in this chapter we will see how more commitment transactions can be made to distribute the balance of the channel in different amounts.
==== Chaining transactions without broadcasting
==== Chaining Transactions Without Broadcasting
So now, Alice has constructed the two transactions shown in <<A_B_fund_refund_Tx>>. But you might be wondering how is this possible? Alice hasn't broadcast the funding transaction to the Bitcoin blockchain. As far as everyone on the network is concerned, that transaction doesn't exist. The refund transaction is constructed so as to *spend* one of the outputs of the funding transaction, even though that output doesn't exist yet either. How can you spend an output that hasn't been confirmed on the Bitcoin blockchain?
@ -327,7 +327,7 @@ Notice how Alice has calculated +6da3c2...387710+ as the funding transaction has
This means that Alice can create a chained transaction by referencing an output that doesn't yet exist, knowing that the reference will be valid if the funding transaction is confirmed, making the refund transaction valid too. As we will see in the next section, this "trick" of chaining transactions before they are broadcast requires a very important feature of Bitcoin that was introduced in August of 2017: _Segregated Witness_.
==== Solving malleability (Segregated Witness)
==== Solving Malleability (Segregated Witness)
Alice has to depend on the transaction ID of the funding transaction being known before confirmation. But before the introduction of Segregated Witness (a.k.a SegWit) in August 2017, this was not sufficient to protect Alice. Because of the way transactions were constructed with the signatures (witnesses) included in the transaction ID, it was possible for a third party (e.g. Bob) to broadcast an alternative version of a transaction with a malleated (modified) transaction ID. This is known as _Transaction Malleability_ and made it difficult to implement indefinite lifetime payment channels securely.
@ -390,7 +390,7 @@ Bob constructs a +funding_signed+ message and sends it to Alice. Here we see the
----
==== Broadcasting the funding transaction
==== Broadcasting the Funding Transaction
Upon receiving the +funding_signed+ message from Bob, Alice now has both signatures needed to sign the refund transaction. Her "exit plan" is now secure and therefore she can broadcast the funding transaction without fear of having her funds locked. If anything goes wrong, Alice can simply broadcast the refund transaction and get her money back, without any further help from Bob.
@ -405,7 +405,7 @@ Of course Alice will use the Bitcoin Protocol to verify that the signature that
As soon as the funding transaction has reached the required number of confirmations, both Alice and Bob send the +funding_locked+ message to each other and the channel is ready for use.
=== Sending payments across the channel
=== Sending Payments Across the Channel
The channel has been set up, but in its initial state, all the capacity (140,000 satoshis) is on Alice's side. This means that Alice can send payments to Bob across the channel, but Bob has no funds to send to Alice yet.
@ -413,7 +413,7 @@ In the next few sections we will show how payments are made across the payment c
Let's assume that Alice wants to send 70,000 satoshis to Bob to pay her bill at Bob's coffee shop.
==== Splitting the balance
==== Splitting the 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.
@ -431,7 +431,7 @@ The first commitment transaction shown in <<competing_commitments_1>> is the "re
Each signed and valid commitment transaction can be used by either channel partner at any time to close the channel by broadcasting it to the Bitcoin network. Since they both have the most recent commitment transaction and can use it at any time, they can also just hold it and not broadcast it. It's their guarantee of a fair exit from the channel.
==== Competing commitments
==== Competing Commitments
You may be wondering how it is possible for Alice and Bob to have multiple commitment transactions, all of them attempting to spend the same 2-of-2 output from the funding transaction. Aren't these commitment transactions conflicting? Isn't this a "double-spend" that the Bitcoin system is meant to prevent?
@ -441,13 +441,13 @@ As long as Alice and Bob hold these transactions and don't broadcast them, the f
If more than one commitment transaction are broadcast, there are many factors that will determine which one gets confirmed first: the amount of fees included, the speed of propagation of these competing transactions, network topology, etc. Essentially it becomes a race without a predictable outcome. That doesn't sound very secure. It sounds like someone could cheat.
==== Cheating with old commitment transactions
==== Cheating with Old Commitment Transactions
Let's look more carefully at the commitment transactions in <<competing_commitments_1>>. All four commitment transactions are signed and valid. But only the last one accurately reflects the most recent channel balances. In this particular scenario, Alice has an opportunity to cheat, by broadcasting an older commitment and getting it confirmed on the Bitcoin blockchain. Let's say Alice transmits Commitment #0 and gets it confirmed: she will effectively close the channel and take all 140,000 satoshis herself. In fact, in this particular example any commitment but #3 improves Alice's position and allows her to "cancel" at least part of the payments reflected in the channel.
In the next section we will see how the Lightning Network resolves this problem - preventing older commitment transactions from being used by the channel partners by a mechanism of revocation and penalties. There are other ways to prevent the transmission of older commitment transactions, such as _eltoo channels_ but they require an upgrade to Bitcoin called _input rebinding_.
==== Revoking old commitment transactions
==== Revoking Old Commitment Transactions
Bitcoin transactions do not expire and cannot be "canceled". Neither can they be stopped or censored once they have been broadcast. So how do we "revoke" a transaction that another person holds that has already been signed?
@ -469,7 +469,7 @@ There are three elements that make up the Lightning protocol's revocation and pe
Let's look at these three elements in turn.
==== Asymmetric commitment transactions
==== 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:
@ -489,7 +489,7 @@ In <<asymmetric_1>> we see that Alice holds a transaction that pays 60,000 satos
Bob holds the mirror-image of that transaction, where the first output is 80,000 satoshis _to_self_ (can be spent by Bob's keys), and 60,000 satoshis _to_remote_ (can be spent by Alice's keys).
==== Delayed (timelocked) spending to_self
==== Delayed (Timelocked) 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.
@ -505,7 +505,7 @@ The delay is there for one reason: to allow the *remote* party to exercise a pen
The delay is negotiated by Alice and Bob, during the initial channel construction message flow, as a field called +to_self_delay+. To ensure the security of the channel, the delay is scaled to the capacity of the channel - meaning a channel with more funds has longer delays in the +to_self+ outputs in commitments. Alice's node includes a desired +to_self_delay+ in the +open_channel+ message. If Bob find this acceptable, his node includes the same value for +to_self_delay+ in the +accept_channel+ message. If they do not agree, then the channel is rejected (see +shutdown+ message).
==== Revocation keys
==== Revocation Keys
As we discussed previously, the word "revocation" is a bit misleading because it implies that the "revoked" transaction cannot be used.
@ -520,7 +520,7 @@ So, in our example, each side holds a commitment transaction that includes a rev
image::images/mtln_0710.png["Asymmetric, delayed and revocable commitments"]
[[commitment_transaction]]
=== The commitment transaction
=== The Commitment Transaction
Now that we understand the structure of commitment transactions and why we need asymmetric, delayed, revocable commitments, let's look at the Bitcoin Script that implements this.
@ -569,7 +569,7 @@ The second output (to_remote) output of the commitment transaction, is defined i
Now that we've defined the commitment transactions in detail, let's see how Alice and Bob advance the state of the channel, create and sign new commitment transactions and revoke old commitment transactions.
=== Advancing the channel state
=== Advancing the Channel State
To advance the state of the channel, Alice and Bob exchange two messages: +commitment_signed+ and +revoke_and_ack+. The +commitment_signed+ message can be sent by either channel partner when they have an update to the channel state. The other channel partner then may respond with +revoke_and_ack+ to _revoke_ the old commitment and _acknowledge_ the new commitment.
@ -579,7 +579,7 @@ In <<commitment_message_flow>> we see the Alice and Bob exchanging two pairs of
.Commitment and revocation message flow
image::images/mtln_0711.png[Commitment and revocation message flow]
==== The commitment_signed message
==== The Commitment_Signed Message
The structure of the +commitment_signed+ message is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#committing-updates-so-far-commitment_signed[BOLT #2 - Peer Protocol - commitment_signed] and shown here:
@ -604,7 +604,7 @@ The use of HTLCs to commit updates will be explained in detail in <<htlcs>> and
Alice's +commitment_signed+ message gives Bob the signature needed (Alice's part of the 2-of-2) for a new commitment transaction.
==== The revoke_and_ack message
==== The Revoke_And_Ack Message
Now that Bob has a new commitment transaction, he can revoke the previous commitment by giving Alice a revocation key, and construct the new commitment with Alice's signature.
@ -625,7 +625,7 @@ The +revoke_and_ack+ message is defined in https://github.com/lightningnetwork/l
+next_per_commitment_point+:: Used to build a revocation_pubkey for the new commitment, so that it can later be revoked.
[[revocation]]
==== Revoking and re-committing
==== Revoking and Re-Committing
Let's look at this interaction between Alice and Bob more closely.
@ -638,7 +638,7 @@ As soon as Bob has given this secret to Alice, he *must not* ever broadcast that
Once Alice has received the +revoke_and_ack+ from Bob she can be sure that Bob cannot broadcast the old commitment without being penalized. She now has the keys necessary to create a penalty transaction if Bob broadcasts an old commitment.
[[revocation_secret_derivation]]
==== Cheating and penalty in practice
==== Cheating and Penalty in Practice
In practice, both Alice and Bob have to monitor for "cheating". They are monitoring the Bitcoin blockchain for any commitment transactions related to any of the channels they are operating. If they see a commitment transaction confirmed on-chain they will check to see if it is the most recent commitment. If it is an "old" commitment, they must immediately construct and broadcast a penalty transaction. The penalty transaction spends *both* the +to_local+ and +to_remote+ outputs, closing the channel and sending both balances to the "cheated" channel partner.
@ -678,11 +678,11 @@ image::images/mtln_0714.png[Cheating and penalty]
Bob's penalty transaction pays 140,000 satoshis to his own wallet, taking the entire channel capacity. Alice has not only failed to cheat, she has lost everything in the attempt!
==== The channel reserve: ensuring skin in the game
==== The Channel Reserve: Ensuring Skin in the Game
You may have noticed there is a special situation that needs to be dealt with: if Alice could keep spending her balance until it is zero, she would be in a position to close the channel by broadcasting an old commitment transaction without risking a penalty: either the revoked commitment transaction succeeds after the delay, or the cheater gets caught but there's no consequence because the penalty is zero. From a game theory perspective, it is free money to attempt to cheat in this situation. This is why the channel reserve is in play, so a prospective cheater always faces the risk of a penalty.
=== Closing the channel (cooperative close)
=== Closing the Channel (Cooperative Close)
So far we've looked at the commitment transactions as one possible way to close a channel, unilaterally. This type of channel closure is not ideal, since it forces a timelock on the channel partner that uses it.
@ -694,7 +694,7 @@ The closing message flow is defined in https://github.com/lightningnetwork/light
.The channel close message flow
image::images/mtln_0715.png[The channel close message flow]
==== The shutdown message
==== The Shutdown Message
Channel closing starts with one of the two channel partners sending the +shutdown+ message. The contents of this message are shown here:
@ -718,7 +718,7 @@ Bob will respond with his own +shutdown+ message indicating that he agrees to co
Now both Alice and Bob have each other's preferred wallet address, they can construct identical closing transactions to settle the channel balance.
==== The closing_signed message
==== The Closing_Signed Message
Assuming the channel has no outstanding commitments or updates and the channel partners have exchanged the +shutdown+ messages shown in the previous section, they can now finish this cooperative close.
@ -742,7 +742,7 @@ This negotiation may continue with back-and-forth +closing_signed+ messages unti
Once Alice receives a +closing_signed+ message with the same fee as the one she proposed in her last message, the negotiation is complete. Alice signs and broadcasts the closing transaction and the channel is closed.
==== The cooperative close transaction
==== The Cooperative Close Transaction
The cooperative close transaction looks similar to the last commitment transaction that Alice and Bob had agreed on. However, unlike the last commitment transaction, it does not have timelocks or penalty revocation keys in the outputs. Since both parties cooperate to produce this transaction and they won't be making any further commitments, there is no need for the asymmetric, delayed and revocable elements in this transaction.

@ -1,5 +1,5 @@
[[routing]]
== Routing on a Network of Payment channels
== Routing On a Network of Payment Channels
In this chapter we will finally unpack how payment channels can be connected to form a _network of payment channels_ via a process called _routing_. Specifically, we will look at the first part of the routing layer, the Atomic & Trustless Multihop Payment protocol. This is highlighted by a double outline in the protocol suite, shown in <<LN_protocol_routing_highlight>>:
@ -7,7 +7,7 @@ In this chapter we will finally unpack how payment channels can be connected to
.The Lightning Network Protocol Suite
image::images/mtln_0801.png["The Lightning Network Protocol Suite"]
=== Routing a payment
=== Routing a Payment
In this section we will examine routing from the perspective of Dina, a gamer who receives donations from her fans while she streams her game sessions.
@ -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 "path finding", as 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 4 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 vs. Path Finding
=== Routing Vs. Path Finding
It's important to note that we separate the concept of _routing_ from the concept of _path finding_. 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.
@ -44,7 +44,7 @@ Routing refers to the series of interactions across the network that attempt to
An important rule of thumb is that it's possible for a _path_ to exist between Alice and Bob (perhaps even more than one), yet there may not be an active _route_ on which to send the payment. One example is the scenario where all the nodes connecting Alice and Bob are currently off-line. In this example, one can examine the _channel graph_ and connect a series of payment channels from Alice to Bob, hence a _path_ exists. However, as the intermediary nodes are offline, the payment cannot be sent and so no _route_ exists.
=== Creating a network of payment channels
=== Creating a Network of Payment Channels
Before we dive into the concept of an atomic trustless multihop payment, let's work through an example.
Let's return to Alice who, in previous chapters, purchased a coffee from Bob with whom she has an open channel.
@ -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"
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.
@ -277,7 +277,7 @@ The fairness protocol for routing used in the Lightning Network today is called
Another proposed mechanism for implementing routing is a _Point Time-Locked Contract (PTLC)_. PTLCs also achieve atomicity, trustless operation and multihop security, but do so with increased efficiency and better privacy. Efficient implementation of PTLCs depends on a new digital signature algorithm called _Schnorr signatures_, which is expected to be activated in Bitcoin in 2021.
=== Revisiting our example
=== Revisiting Our Example
Let's revisit our example from the first part of this chapter. Alice wants to "tip" Dina, with a Lightning payment. Let's say Alice wants to send Dina 50,000 satoshis as a tip.
@ -304,7 +304,7 @@ Remember how Bob and Chan might expect a small compensation for routing the paym
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 (HTLCs) to pay Dina and how that HTLC is forwarded along the path from Alice to Dina.
==== On-chain vs Off-chain settlement of HTLCs
==== On-Chain Vs 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.
@ -313,7 +313,7 @@ The mere fact that any transaction can be taken on-chain at any time is precisel
In all the examples that follow, we will assume that any of these transactions can be made on-chain at any time. The participants will choose to keep them off-chain, but there is no difference in the functionality of the system other than the higher fees and delay imposed by on-chain mining of the transactions. The example works the same if all the transactions are on-chain or off-chain.
[[htlcs]]
=== Hash Time Locked Contracts (HTLCs)
=== Hash Time Locked Contracts (Htlcs)
In this section we explain how Hash Time Locked Contracts (HTLCs) work.
@ -339,7 +339,7 @@ In this code, +H+ is the hash, or _payment hash_ and +R+ is the secret or _payme
The use of a cryptographic hash function is one element that guarantees _trustless operation_. The payment intermediaries do not need to trust each other because they know that no one can guess the secret or fake it.
==== HTLCs in Bitcoin Script
==== Htlcs in Bitcoin Script
In our gold coin example, Alice had a contract enforced by escrow like this:
@ -382,7 +382,7 @@ In the following sections, we will focus on the main elements of the script and
The main part of the HTLC is in line 10 of <<received_htlc>>. Let's build it up from scratch!
==== Payment pre-image and hash verification
==== Payment Pre-Image and Hash Verification
The core of an HTLC is the "hash", where payment can be made if the recipient knows the payment pre-image. Alice locks the payment to a specific payment hash and Bob has to present a payment pre-image to claim the funds. The Bitcoin system can verify that Bob's payment pre-image is correct by hashing it and comparing the result to the payment hash that Alice used to lock the funds.
@ -416,7 +416,7 @@ The Bitcoin Script engine would evaluate this script as follows:
3. +H+ is pushed to the stack
4. The OP_EQUAL operator compares +H+ and H~R~. If they are equal, the result is +TRUE+, the script is complete and the payment is verified.
==== Extending HTLCs from Alice to Dina
==== Extending Htlcs from Alice to Dina
Alice will now extend the HTLC across the network so that it reaches Dina.
@ -434,7 +434,7 @@ Bob isn't taking a risk and isn't trusting Alice or Chan. Instead, Bob is trusti
Similarly, Chan can extend a 50,000 HTLC to Dina. He isn't risking anything or trusting Bob or Dina. To redeem the HTLC, Dina would have to broadcast the secret, which Chan could use to redeem Bob's HTLC. Chan would also earn 100 satoshis as a routing fee.
==== Back-propagating the secret
==== Back-Propagating the Secret
Once Dina receives a 50,000 HTLC from Chan, she can now get paid. Dina could simply commit this HTLC on-chain and spend it by revealing the secret in the spending transaction. Or, instead, Dina can update the channel balance with Chan by giving him the secret. There's no reason to incur a transaction fee and go on-chain. So, instead, Dina sends the secret to Chan and they agree to update their channel balances to reflect a 50,000 satoshi Lightning payment to Dina. In <<alice_dina_htlc_redeem_1>> we see Dina giving the secret to Chan, thereby fulfilling the HTLC.
@ -469,7 +469,7 @@ The final channel balances reflect Alice's payment to Dina and the routing fees
image::images/mtln_0813.png["Channel balances after the payment"]
[[preventing_theft]]
==== Signature binding - preventing theft of HTLCs
==== Signature Binding - Preventing Theft of Htlcs
There's a catch. Did you notice it?
@ -570,7 +570,7 @@ With that optimization, you now see how we arrive at the HTLC script shown in li
OP_HASH160 <RIPEMD160(payment_hash)> OP_EQUALVERIFY...
----
==== HTLC cooperative and timeout failure
==== Htlc Cooperative and Timeout Failure
So far we looked at the "Hash" part of HTLC, and how it would work if everyone cooperated and was online at the time of payment.
@ -603,7 +603,7 @@ The +OP_DROP+ operator simply drops the topmost item on the script stack. This i
Finally, once the stack has been cleaned up, there should be a public key and signature left behind, that +OP_CHECKSIG+ can verify. As we saw in <<preventing_theft>>, this is necessary to ensure that only the rightful owner of the funds can claim them, by binding this output to their public key and requiring a signature.
==== Decrementing time-locks
==== Decrementing Time-Locks
As the HTLCs are extended from Alice to Dina, the time-lock refund clause in each HTLC has a _different_ cltv_expiry value. We will see this in more detail as we talk about <<onion_routing>>. But suffice it to say that to ensure an orderly unwinding of a payment that fails, each hop needs to wait a bit less for their refund. The difference between time-locks for each hop is called the cltv_expiry_delta and is set by each node and advertized to the network as we will see in <<gossip>>.

@ -10,13 +10,13 @@ Specifically, we will be discussing "Adding, Settling, Failing HTLCs" and the "C
image::images/mtln_0901.png["The Lightning Network Protocol Suite"]
=== Local (single channel) vs Routed (multiple channels)
=== Local (Single Channel) Vs Routed (Multiple 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 we 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 with Htlcs
We will revisit our example from <<routing>>, to demonstrate how the HTLCs from Alice to Dina gets 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>> below:
@ -26,7 +26,7 @@ image::images/mtln_0809.png["Alice pays Dina with an HTLC routed via Bob and Cha
We will focus on the payment channel between Alice and Bob and review the messages and transactions that they use to process this HTLC.
==== HTLC and commitment message flow
==== Htlc and Commitment Message Flow
The message flow between Alice and Bob (and also between any pair of channel partners) is shown in <<HTLC_commitment_message_flow>>:
@ -36,7 +36,7 @@ image::images/mtln_0903.png["The message flow for HTLC commitment between channe
We've already seen the +commitment_signed+ and +revoke_and_ack+ in <<payment_channels>>. Now we will see how HTLCs fit into the commitment scheme. The two new messages are +update_add_htlc+ which Alice uses to ask Bob to add an HTLC and +update_fulfill_htlc+ which Bob uses to redeem the HTLC once he has received the payment secret (Dina's secret).
=== Forwarding payments with HTLCs
=== Forwarding Payments with Htlcs
Alice and Bob start with a payment channel that has 70,000 satoshi balance on each side.
@ -46,14 +46,14 @@ As we saw in <<payment_channels>> this means that Alice and Bob have negotiated
.Alice and Bob's initial commitment transactions
image::images/mtln_0904.png["Alice and Bob's initial commitment transactions"]
==== Adding an HTLC
==== Adding an Htlc
Alice wants Bob to accept an HTLC worth 50,200 satoshis to forward to Dina. To do so, Alice must send the details of this HTLC, including the payment hash and amount to Bob. Bob will also need to know where to forward it, which is something we discuss in detail in <<onion_routing>>.
To add the HTLC, Alice starts the flow we saw in <<HTLC_commitment_message_flow>> by sending the +update_add_htlc+ message to Bob.
[[update_add_htlc]]
==== The +update_add_htlc+ message
==== The +Update_Add_Htlc+ Message
Alice sends the `update_add_HTLC` Lightning message to Bob. This message is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#adding-an-htlc-update_add_htlc[BOLT #2 - Peer Protocol - update_add_HTLC], and is shown below:
@ -87,7 +87,7 @@ Alice sends the `update_add_HTLC` Lightning message to Bob. This message is defi
As a reminder, accounting within the Lightning Network is in units of milli-satoshis (thousandths of a satoshi), whereas Bitcoin accounting is in satoshis. Any amounts in HTLCs are milli-satoshis, which are then rounded to the nearest satoshi in the Bitcoin commitment transactions.
====
==== HTLC in commitment transaction
==== Htlc in Commitment Transaction
The received information is enough for Bob to create a new commitment transaction. The new commitment transaction has the same two outputs +to_self+ and +to_remote+ for Alice and Bob's balance, and a *new* output representing the HTLC offered by Alice.
@ -123,7 +123,7 @@ OP_ENDIF
There are three ways to claim this output. Try to read the script and see if you can figure it out (remember, it is a stack-based language so things appear "backwards").
==== New commitment with HTLC output
==== New Commitment with Htlc Output
Bob now has the necessary information to add this HTLC script as an additional output and create a new commitment transaction. Bob's new commitment will have 50,200 satoshis in the HTLC output. That amount will come from Alice's channel balance, so Alice's new balance will be 19,800 satoshis (70,000 - 50,200 = 19,800). Bob constructs this commitment as a tentative "Commitment #3", shown in <<add_commitment_3b>>, below:
@ -131,7 +131,7 @@ Bob now has the necessary information to add this HTLC script as an additional o
.Bob's new commitment with an HTLC output
image::images/mtln_0905.png["Bob's new commitment with an HTLC output"]
==== Alice commits
==== Alice Commits
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.
@ -162,7 +162,7 @@ Now, Bob has a new signed commitment transaction, as shown in <<signed_commitmen
.Bob has a new signed commitment
image::images/mtln_0906.png[Bob has a new signed commitment]
==== Bob acknowledges new commitment and revokes old one
==== Bob Acknowledges New Commitment and Revokes Old One
Now that Bob has a new signed commitment, he needs to acknowledge it and revoke the old commitment. He does so by sending the +revoke_and_ack+ message, as we saw in <<payment_channels>> previously. As a reminder, that message is shown in <<revoke_and_ack_message_2>>, below:
@ -202,7 +202,7 @@ Next, the message flow for +commitment_signed+ and +revoke_and_ack+ is now repea
For completeness sake, let's quickly review the commitment transactions as this round of commitment/revocation happens.
==== Bob commits
==== Bob Commits
Bob now sends a +commitment_signed+ back to Alice, with his signatures for Alice's new commitment transaction, including the HTLC output she has added.
@ -220,7 +220,7 @@ The channel state is shown in <<revoked_commitment_2a>> below:
.Alice has revoked the old commitment
image::images/mtln_0910.png[Alice has revoked the old commitment]
=== Multiple HTLCs
=== Multiple Htlcs
At any point in time, Alice and Bob may have dozens or even hundreds of HTLCs across a single channel. Each HTLC is offered and added to the commitment transaction as an additional output. A commitment transaction therefore always has 2 outputs for the channel partner balances and any number of HTLC outputs, one per HTLC.
@ -230,7 +230,7 @@ The current maximum number of HTLCs allowed on a channel is 483 HTLCs to account
As we will see in the next section, the maximum is only for _pending_ HTLCs, since once an HTLC is fulfilled (or fails due to timeout/error), it is removed from the commitment transaction.
=== HTLC fulfillment
=== Htlc Fulfillment
Now Bob and Alice both have a new commitment transaction with an additional HTLC output and we have achieved a major step towards updating a payment channel.
@ -238,13 +238,13 @@ The new balance of Alice and Bob does not reflect yet that Alice has successfull
However the HTLCs are now set up in a way that secure settlement in exchange for the proof of payment will be possible.
==== HTLC propagation
==== Htlc Propagation
Let's assume that Bob continues the chain and sets up an HTLC with Chan for 50,100 satoshis. The process will be exactly the same as we just saw between Alice and Bob. Bob will send +update_add_htlc+ to Chan, then they will exchange +commitment_signed+ and +revoke_and_ack+ messages in two rounds, progressing their channel to the next state.
Next, Chan will do the same with Dina: offer a 50,000 satoshi HTLC, commit and revoke etc. However, Dina is the final recipient of the HTLC. Dina is the only one that knows the payment secret (the pre-image of the payment hash). Therefore, Dina can fulfill the HTLC with Chan immediately!
==== Dina fulfills the HTLC with Chan
==== 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:
@ -274,7 +274,7 @@ If the result +H+ matches the payment hash in the HTLC, Chan can do a little dan
Let's go back to Alice and Bob's channel and watch them unwind the HTLC. To get there, let's assume Dina sent the +update_fulfill_htlc+ to Chan, Chan sent +update_fulfill_htlc+ to Bob and Bob sent +update_fulfill_htlc+ to Alice. The payment pre-image has propagated all the way back to Alice.
==== Bob settles the HTLC with Alice
==== Bob Settles the Htlc with Alice
When Bob sends +update_fulfill_htlc+ to Alice, it will contain the same +payment_preimage+ that Dina selected for her invoice. That +payment_preimage+ has traveled backwards along the payment path. At each step, the +channel_id+ will be different and +id+ (HTLC ID) may be different. But the preimage is the same!
@ -306,7 +306,7 @@ Finally, Bob signs Alice's commitment by sending Alice a +commitment_signed+ mes
.Alice and Bob settle the HTLC and update balances
image::images/mtln_0914.png[Alice and Bob settle the HTLC and update balances]
=== Removing an HTLC due to error or expiry
=== Removing an Htlc Due to Error or Expiry
If an HTLC cannot be fulfilled, it can be removed from the channel commitment using the same process of commitment and revocation.
@ -327,7 +327,7 @@ It's pretty self-explanatory. The multi-byte +reason+ field is defined in https:
If Alice received a +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.
=== Making a local payment
=== Making a Local Payment
At this point, you will easily understand why HTLCs are used for both "remote" and "local" payments. When Alice pays Bob for a coffee, she doesn't just update the channel balance and commit to a new state. Instead, the payment is made with an HTLC, in the same way Alice paid Dina. The fact that there's only one channel "hop" makes no difference. It would work like this:

@ -17,13 +17,13 @@ The Lightning Network uses an implementation of onion routing protocol based on
The implementation of onion routing in the Lightning Network is defined in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md[BOLT #4 - Onion Routing Protocol]
=== A physical example illustrating onion routing
=== A Physical Example Illustrating Onion Routing
There are many ways to describe onion routing, but one of the easiest is to use the physical equivalent of sealed envelopes. An envelope represents a layer of encryption, allowing only the named recipient to open it and read the contents.
Let's say Alice wants to send a secret letter to Dina, indirectly via some intermediaries.
==== Selecting a path
==== Selecting a Path
The Lightning Network uses _source routing_, which means that the payment path is selected and specified by the sender, and only the sender. In this example, Alice's secret letter to Dina will be the equivalent of a payment. To make sure the letter reaches Dina, Alice will create a path from her to Dina, using Bob and Chan as intermediaries.
@ -47,7 +47,7 @@ Internet routing is based on _packet switching_ at each intermediary routing nod
However, the lack of privacy in such a routing mechanism, where every intermediary node sees the sender and recipient, make this a poor choice for use in a payment network.
****
==== Building the layers
==== Building the Layers
Alice starts by writing a secret letter to Dina. She then seals the letter inside an envelope and writes "To Dina" on the outside (see <<dina_envelope>>). The envelope represents encryption with Dina's public key, so that only Dina can open the envelope and read the letter.
@ -73,7 +73,7 @@ Now, if we could look through the envelopes (with X-rays!) we would see the enve
.Nested envelopes
image::images/mtln_1006.png[Nested envelopes]
==== Peeling the layers
==== Peeling the Layers
Alice now has an envelope that says "To Bob" on the outside. It represents an encrypted message that only Bob can open (decrypt). Alice will now begin the process by sending this to Bob. The entire process is shown in <<sending_nested_envelopes>> below:
@ -91,7 +91,7 @@ This is the essence of onion routing. The sender wraps a message in layers, spec
Now, let's look at the details of the onion routing implementation in the Lightning Network.
=== Introduction to onion routing of HTLCs
=== Introduction to Onion Routing of Htlcs
Onion routing in the Lightning Network appears complex at first glance, but once you understand the basic concept is really quite simple.
@ -103,7 +103,7 @@ Each intermediary node, or Bob and Chan in our example, is called a _hop_. Every
Now that we know the terminology used in Lightning Onion Routing, let's restate Alice's task: Alice must construct an _onion_ with _hop data_, telling each _hop_ how to construct an _outgoing HTLC_ in order to send a payment to the _final node_ (Dina).
==== Alice selects the path
==== Alice Selects the Path
From <<routing>> we know that Alice will send a 50,000 satoshi payment to Dina via Bob and Chan. This payment is transmitted via a series of HTLCs, as shown in <<alice_dina_htlc_path>>, below:
@ -131,7 +131,7 @@ image::images/mtln_1009.png[A path constructed from gossiped channel and node in
Alice already knows her own channel to Bob, and therefore doesn't need this info to construct the path. Note also that Alice didn't need a channel update from Dina, because she has the update from Chan for that last channel in the path.
==== Alice constructs the payloads
==== Alice Constructs the Payloads
There are two possible formats that Alice can use for the information communicated to each hop: A legacy fixed-length format called the _hop data_ and a more flexible Type-Length-Value (TLV) based format called the _hop payload_. The TLV message format is explained in more detail in <<tlv>>. It offers flexibility by allowing fields to be added to the protocol at will.
@ -142,7 +142,7 @@ Both formats are specified in https://github.com/lightningnetwork/lightning-rfc/
Alice will start building the hop data from the end of the path backwards: Dina, Chan, Bob.
===== Final node payload for Dina
===== Final node payload for dina
Alice first builds the payload that will be delivered to Dina. Dina will not be constructing an "outgoing HTLC", because Dina is the final node and payment recipient. For this reason, the payload for Dina is different than all the others (uses all zeros for the `short_channel_id`), but only Dina will know this since it will be encrypted in the innermost layer of the onion. Essentially, this is the "secret letter to Dina" we saw in our physical envelope example.
@ -173,7 +173,7 @@ Alice serializes it in TLV format as shown (simplified) <<dina_onion_payload>> b
.Dina's payload is constructed by Alice
image::images/mtln_1010.png[Dina's payload is constructed by Alice]
===== Hop payload for Chan
===== Hop payload for chan
Next, Alice constructs the hop payload for Chan. This will tell Chan how to setup an outgoing HTLC to Dina.
@ -191,7 +191,7 @@ Alice serializes this payload in TLV format, as shown (simplified) in <<chan_oni
.Chan's payload is constructed by Alice
image::images/mtln_1011.png[Chan's payload is constructed by Alice]
===== Hop payload for Bob
===== Hop payload for bob
Finally, Alice constructs the hop payload for Bob, which also contains the same three fields as the hop payload for Chan, but with different values:
@ -224,7 +224,7 @@ Alice has now built the three hop payloads that will be wrapped in an onion. A s
.Hop payloads for all the hops
image::images/mtln_1013.png[Hop payloads for all the hops]
==== Key generation
==== Key Generation
Alice must now generate several keys that will be used to encrypt the various layers in the onion.
@ -360,7 +360,7 @@ Note that the very first hop uses the original session key generated, as this ke
[[wrapping_the_onion]]
=== Wrapping the onion layers
=== Wrapping the Onion Layers
The process of wrapping the onion is detailed in https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md#packet-construction[BOLT #4 - Onion Routing - Packet Construction].
@ -368,7 +368,7 @@ In this section we will describe this process at a high-level and somewhat simpl
[[fixed_length_onions]]
==== Fixed-length Onions
==== Fixed-Length Onions
We've mentioned the fact that none of the "hop" nodes know how long the path is, or where they are in the path. How is this possible?
@ -400,7 +400,7 @@ A unique trait of Sphinx as a mix-net packet format is that rather than include
In practice, this little trick allows us to keep the onion packet as compact as possible while still retaining the desired security properties.
==== Wrapping the onion (outlined)
==== Wrapping the Onion (Outlined)
Here is the process of wrapping the onion, outlined below. Come back to this list, as we explore each step with our real-world example.
@ -440,7 +440,7 @@ Note that at each phase the _mu_ key is used to generate an HMAC over the _encry
This outer HMAC allows the node processing the packet to verify the integrity of the onion packet (no bytes modified).
The inner HMAC is then revealed during the inverse of the "shift and encrypt" routine described above, which serves as the _outer_ HMAC for the next hop.
==== Wrapping Dina's hop payload
==== Wrapping Dina's Hop Payload
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.
@ -490,7 +490,7 @@ Finally, Alice calculates a Hash-based Message Authentication Code (HMAC) for Di
.Adding an HMAC integrity checksum to Dina's hop payload
image::images/mtln_1019.png[]
===== Onion Routing Replay Protection & Detection
===== Onion routing replay protection & detection
The HMAC acts as a secure checksum and helps Dina verify the integrity of the hop payload. The 32-byte HMAC is appended to Dina's hop payload.
Note that we compute the HMAC over the _encrypted_ data rather then over the plaintext data.
@ -519,7 +519,7 @@ Once again, due to the unique attributes of the HTLC construct, we can make a fu
Given that HTLCs are _time locked_ contracts based on the absolute block height, once an HTLC has expired, then the contract is effectively permanently closed.
As a result, nodes can use this CLTV expiration height as an indicator to know when it's safe to garbage collect an entry in the anti-replay log.
==== Wrapping Chan's hop payload
==== Wrapping Chan's Hop Payload
In <<chan_onion_wrapping>> we see the steps used to wrap Chan's hop payload in the onion. These are the same steps Alice used to wrap Dina's hop payload.
@ -544,7 +544,7 @@ Now Chan's payload is in the front of the onion. When Chan sees this he has no i
Next, Alice obfuscates the entire payload by XOR with the byte-stream generated from the Alice-Chan +rho+ key. Only Alice and Chan have this +rho+ key and only they can produce the byte stream to obfuscate and de-obfuscate the onion.
Finally, as we did in the earlier step, we compute Chan's outer HMAC, which is what she'll use to verify the integrity of the encrypted onion packet.
==== Wrapping Bob's hop payload
==== Wrapping Bob's Hop Payload
In <<bob_onion_wrapping>> we see the steps used to wrap Bob's hop payload in the onion.
@ -565,7 +565,7 @@ Obfuscate the whole thing XOR with the _rho_ key from the Alice-Bob-shared-secre
Calculate the outer HMAC and stick it on the end of Bob's hop payload.
==== The final onion packet
==== The Final Onion Packet
The final onion payload is ready to be sent to Bob. Alice doesn't need to add any more hop payloads.
@ -583,11 +583,11 @@ The result can be seen in <<onion_packet_2>> below:
.The onion packet
image::images/mtln_1015.png[]
=== Sending the onion
=== Sending the Onion
In this section we will look at how the onion packet is forwarded and how HTLCs are deployed along the path.
==== The update_add_htlc message
==== The Update_Add_Htlc Message
Onion packets are sent as part of the +update_add_htlc+ message. If you recall from <<update_add_htlc>>, in <<channel_operation>>, we saw the contents of the +update_add_htlc+ message were as follows:
@ -602,7 +602,7 @@ Onion packets are sent as part of the +update_add_htlc+ message. If you recall f
You will recall that this message is sent by one channel partner to ask the other channel partner to add an HTLC. This is how Alice will ask Bob to add an HTLC to pay Dina. Now you understand the purpose of the last field +onion_routing_packet+, which is 1366 bytes long. It's the fully-wrapped onion packet we just constructed!
==== Alice sends the onion to Bob
==== Alice Sends the Onion to Bob
Alice will send the +update_add_htlc+ message to Bob. Let's look at what this message will contain:
@ -618,7 +618,7 @@ cltv_expiry:: The expiry timelock for the HTLC will be 700,058. Alice adds 20 bl
onion_routing_packet:: The final onion packet Alice constructed with all the hop payloads!
==== Bob checks the onion
==== Bob Checks the Onion
As we saw in <<channel_operation>>, Bob will add the HTLC to the commitment transactions and update the state of the channel with Alice.
@ -632,7 +632,7 @@ Now that Bob has generated the shared key and verified the HMAC, he can start un
If Bob extracts and removes his hop payload, the remaining onion will not be 1300 bytes, it will be shorter! So the next hop will know that they are not the first hop and will be able to detect how long the path is. To prevent this, Bob needs to add more filler to refill the onion.
==== Bob generates filler
==== Bob Generates Filler
Bob generates filler in a slightly different way than Alice, but following the same general principle.
@ -644,7 +644,7 @@ image::images/mtln_1023.png[Bob extends the onion payload by 1300 (zero-filled)
This empty space will become obfuscated and turn into "filler", by the same process that Bob uses to deobfuscate his own hop payload. Let's see how that works.
==== Bob de-obfuscates his hop payload
==== Bob De-Obfuscates His Hop Payload
Next, Bob will generate the +rho+ key from the Alice-Bob shared key. He will use this to generate a 2600 byte stream, using the +ChaCha20+ algorithm.
@ -663,12 +663,12 @@ At the same time, applying the +rho+ byte stream to the 1300 zeroes that were ad
.Bob de-obfuscates the onion, obfuscates the filler
image::images/mtln_1024.png["Bob de-obfuscates the onion, obfuscates the filler"]
==== Bob extracts the outer HMAC for the next hop
==== Bob Extracts the Outer Hmac for the Next Hop
Remember that an inner HMAC is included for each hop, then will then become the outer HMAC for the _next_ hop.
In this case, Bob extracts the inner HMAC (he's already verified the integrity of the encrypted packet w/ the outer HMAC), and puts it aside as he'll append it to the deobfuscated packet to allow Chan to verify the HMAC of her encrypted packet.
==== Bob removes his payload and left shifts the onion
==== Bob Removes His Payload and Left Shifts the Onion
Now Bob can remove his hop payload from the front of the onion and left-shift the remaining data. An amount of data equal to Bob's hop payload from the second-half 1300 bytes of filler will now shift into the onion payload space. This is shown in <<bob_removes_shifts>>:
@ -682,7 +682,7 @@ Bob now has a 1300 byte onion packet to send to the next hop. It is almost ident
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 disctinct locations, then they can tell the difference as the base protocol always uses the same payment hash across the entire route. Atomic Multipath Payments (AMP), and Point Time Locked Contrats (PTLCs) eliminate the correlation vector by randomizing the payment idenitifer across each route/hop.
==== Bob constructs the new onion packet
==== Bob Constructs the New Onion Packet
Bob now copies the onion payload into the onion packet, appends the outer HMAC for chan, re-randomizes the session key (the same way Alice the sender does) with the Elliptic Curve multiplication operation, and appends a fresh version byte.
@ -698,7 +698,7 @@ session_key_chan = session_key_bob * b_bob
The `session_key_chan` public key will then be appended to the front of the onion packet for processing by Chan.
==== Bob verifies the HTLC details
==== Bob Verifies the Htlc Details
Bob's hop payload contains the instructions needed to create an HTLC for Chan.
@ -710,7 +710,7 @@ Next, Bob confirms that the outgoing amount (50,100 satoshis) is less than the i
Similarly, Bob checks that the outgoing cltv_expiry is less than the incoming cltv_expiry giving Bob enough time to claim the incoming HTLC if there is a breach.
==== Bob sends the update_add_htlc to Chan
==== Bob Sends the Update_Add_Htlc to Chan
Bob now constructs and HTLC to send to Chan, as follows:
@ -726,7 +726,7 @@ cltv_expiry:: The expiry timelock for the HTLC will be 700,038.
onion_routing_packet:: The onion packet Bob reconstructed after removing his hop payload.
==== Chan forwards the onion
==== Chan Forwards the Onion
Chan repeats the exact same process as Bob:
@ -754,13 +754,13 @@ Chan repeats the exact same process as Bob:
12. Chan re-randomizes the session key as Bob did in the prior hop for Dina.
==== Dina receives the final payload
==== Dina Receives the Final Payload
When Dina receives the +update_add_htlc+ message from Chan, she knows from the +payment_hash+ that this is a payment for her. She knows she is the last hop in the onion.
Dina follows the exact same process as Bob and Chan to verify and unwrap the onion, except she doesn't construct new filler and doesn't forward anything. Instead, Dina responds to Chan with +update_fulfill_htlc+ to redeem the HTLC. The +update_fulfill_htlc+ will flow backwards along the path until it reaches Alice. All the HTLCs are redeemed and channel balances are updated. The payment is complete!
=== Returning errors
=== Returning Errors
This far we've looked at the forward propagation of the onion establishing the HTLCs, and the backwards propagation of the payment secret unwinding the HTLCs once payment is successful.
@ -829,7 +829,7 @@ However, this means that the sender of the HTLC has to wait until expiry, and th
One proposed solution to this problem is called "stuckless payments", and it depends on Point Time-Locked Contracts (PTLCs), which are payment contract that use a different cryptographic primitive than HTLCs (i.e. point addition on the elliptic curve instead of a hash and secret pre-image). PTLCs are cumbersome using ECDSA but much easier with Bitcoin's Taproot and Schnorr Signature features which were recently locked in for activation in November 2021. It is expected that PTLCs will be implemented in the Lightning Network after these Bitcoin features become activated.
[[keysend]]
=== keysend Spontaneous Payments
=== Keysend Spontaneous Payments
In the payment flow described earlier in the chapter, we assumed that Dina
received an invoice from Alice "out of band," or obtained it via some mechanism
@ -844,7 +844,7 @@ first? The `keysend` protocol is an end-to-end extension (only the sender and
receiver are aware) to the Lightning protocol that enables spontaneous push
payments.
==== Custom Onion TLV Records
==== Custom Onion Tlv Records
The modern Lightning protocol uses the TLV (Type-Length-Value) encoding in
the onion to encode information that tells each node _where_ and _how_ to
@ -867,7 +867,7 @@ packet is fixed-size, custom records don't _add_ any additional data to an
HTLC; rather, they reallocate bytes that would have been filled with random data
otherwise.
==== Sending and Receiving keysend payments
==== Sending and Receiving Keysend Payments
A `keysend` payment inverts the typical flow of an HTLC where the receiver
reveals a secret pre-image to the sender. Instead, the sender includes the
@ -879,7 +879,7 @@ obtaining an invoice from the receiver, as the pre-image is "pushed" over to
the receiver. A `keysend` payment uses a TLV custom record type of `5482373484`
to encode a 32-byte pre-image value.
==== keysend and Custom Records in Lightning Applications
==== Keysend and Custom Records in Lightning Applications
Many streaming Lightning applications use the `keysend` protocol to continually
stream satoshis to a destination identified by its public key in the network.

@ -1,5 +1,5 @@
[[gossip]]
== Gossip and the channel graph
== Gossip and the Channel Graph
In this chapter we will describe the Lightning Network's _Gossip Protocol_ and how it is used by nodes to construct and maintain a _Channel Graph_. We will also review the _DNS Bootstrap_ mechanism used to find peers to "gossip" with.
@ -91,7 +91,7 @@ existing Internet protocols to maintain and distribute a set of bootstrapping pe
Similar to the Bitcoin protocol, the primary initial peer discovery mechanism used in the Lightning Network happens via DNS. As initial peer discovery is a critical and universal task for the network, the process has been _standardized_ in https://github.com/lightningnetwork/lightning-rfc/blob/master/10-dns-bootstrap.md[BOLT #10 - DNS Bootstrap].
==== DNS Bootstrapping
==== Dns Bootstrapping
The https://github.com/lightningnetwork/lightning-rfc/blob/master/10-dns-bootstrap.md[BOLT #10] document describes a standardized way of implementing peer
discovery using the Domain Name System (DNS). Lightning's flavor of DNS based bootstrapping uses up to 3 distinct record types:
@ -217,7 +217,7 @@ peer and established its first connection! Now we can begin the second phase of
First, we'll explore more of the intricacies of BOLT 10 itself to take a deeper look into how things work under the hood.
==== SRV Query Options
==== Srv Query Options
The https://github.com/lightningnetwork/lightning-rfc/blob/master/10-dns-bootstrap.md[BOLT #10] standard is highly extensible due to its usage of nested
sub-domains as a communication layer for additional query options. The
@ -252,11 +252,11 @@ Try some combinations of the various flags using the +dig+ DNS command-line tool
dig @8.8.8.8 r0.a6.nodes.lightning.directory SRV
----
=== The channel graph
=== The Channel Graph
Now that our new node is able to use the DNS bootstrapping protocol to connect to their very first peer, it can start to sync the channel graph! However, before we sync the channel graph, we'll need to learn exactly _what_ we mean by the channel graph. In this section we'll explore the precise _structure_ of the channel graph and examine the unique aspects of the channel graph compared to the typical abstract "graph" data structure which is well known/used in the field of computer science.
==== A directed graph
==== A Directed Graph
A graph in computer science is a special data structure composed of vertices (typically referred to as nodes) and edges (also known as links). Two nodes may be connected by one or more edges. The channel graph is also _directed_ given that a payment is able to flow in either direction over a given edge (a channel). An example of a _directed graph_ is shown below:
@ -269,7 +269,7 @@ In the context of the Lightning Network, our vertices are the Lightning nodes th
As channels themselves are UTXOs (funded 2-of-2 multisig addresses), we can view the channel graph as a special subset of the Bitcoin UTXO set, on top of which we can add some additional information (the nodes, etc) to arrive at the final overlay structure which is the channel graph. This anchoring of fundamental components of the channel graph in the
base Bitcoin blockchain means that it's impossible to _fake_ a valid channel graph, which has useful properties when it comes to spam prevention as we'll see later.
=== Gossip protocol messages
=== Gossip Protocol Messages
The channel graph information is propagated across the Lightning P2P Network as three messages, which are described in https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md[BOLT #7]:
@ -285,7 +285,7 @@ themselves _authenticated_ allowing a 3rd party to ensure that the owner of a ch
With the high level structure of the channel graph laid out, we'll now dive down into the precise structure of each of the three messages used to gossip the channel graph. We'll also explain how one can also _verify_ each message and component of the channel graph.
[[node_announcement]]
==== The node_announcement message
==== The Node_Announcement Message
First, we have the +node_announcement+ message, which serves two primary
purposes:
@ -333,7 +333,7 @@ Validating an incoming +node_announcement+ is straight forward. The following as
* The included +alias+ bytes MUST be a valid UTF-8 string.
==== The channel_announcement message
==== The Channel_Announcement Message
Next, we have the +channel_announcement+ message, which is used to _announce_ a new _public_ channel to the wider network. Note that announcing a channel is _optional_. A channel only needs to be announced if it is intended to be used for routing by the Lightning network. Active routing nodes may wish to announce all their channels. However, certain nodes like mobile nodes likely don't have the
uptime or desire to be an active routing node. As a result, these
@ -345,7 +345,7 @@ An unannounced channel isn't part of the known public channel graph, but can sti
Due to the existence of unadvertised channels, the _true_ size of the channel graph (both the public and private components) is unknown.
===== Locating a channel on the Bitcoin blockchain
===== 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. In order 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 upfront 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.
@ -357,7 +357,7 @@ The +scid+ is used both in +channel_announcement+ (and +channel_update+) as well
[[short_channel_id]]
[[scid]]
===== The Short Channel ID
===== The short channel id
Based on the information above, we have three pieces of information we need to encode in order to uniquely reference a given channel. As we want a compact representation, we'll attempt to encode the information into a _single_ integer. Our integer format of choice is an unsigned 64-bit integer, comprised of 8 bytes.
@ -431,7 +431,7 @@ Finally, the verifier will reconstruct the multisig script from +bitcoin_key_1+
The verifier has now independently verified that the payment channel in the announcement is funded and confirmed on the Bitcoin blockchain!
==== The channel_update message
==== The Channel_Update Message
The third and final message used in the gossip protocol is the +channel_update+ message. Two of these are generated for each payment channel (one by each channel partner) announcing their routing fees, timelock expectations and capabilities.

@ -5,7 +5,7 @@ Payment delivery on the Lightning Network depends on finding a path from the sen
In this chapter we will examine the problem of path finding, understand how uncertainty about channel balances complicates this problem and look at how a typical path finding implementation attempts to solve it.
=== Path finding in the Lightning protocol suite
=== Path Finding in the Lightning Protocol Suite
Path finding, path selection, multi-path payments (MPP) and the payment attempt trial & error loop occupy the majority of the "Payment Layer" at the top of the protocol suite.
@ -15,13 +15,13 @@ These components are highlighted by a double outline in the protocol suite, show
.The Lightning Network Protocol Suite
image::images/mtln_1201.png["The Lightning Network Protocol Suite"]
==== Where is the BOLT?
==== Where Is the Bolt?
So far we've looked at several technologies that are part of the Lightning Network and we have seen their exact specification as part of a BOLT standard. You may be surprised to find that path finding is not part of the BOLTs!
That's because path finding isn't an activity that requires any form of coordination or interoperability between different implementations. As we've seen, the path is selected by the sender. Even though the routing details are specified in detail in the BOLTs, the path discovery and selection are left entirely up to the sender. So each node implementation can choose a different strategy/algorithm to find paths. In fact, the different node/client and wallet implementations can even compete and use their path finding algorithm as a point of differentiation.
=== Path finding: what problem are we solving?
=== Path Finding: What Problem Are We Solving?
The term path finding may be somewhat misleading, because it implies a search for _a single path_ connecting two nodes. In the beginning, when the Lightning Network was small and not well interconnected, the problem was indeed about finding a way to join payment channels to reach the recipient.
@ -38,7 +38,7 @@ The network visualization above was produced with a simple python script you can
If the sender and recipient are connected to other well-connected nodes and have at least one channel with adequate capacity - there will be thousands of paths. The problem becomes: selecting the _best_ path that will succeed in payment delivery, out of a list of thousands of possible paths.
==== Selecting the best path
==== Selecting the Best Path
To select the "best" path, we have to first define what we mean by "best". There may be many different criteria such as:
@ -51,13 +51,13 @@ To select the "best" path, we have to first define what we mean by "best". There
All of these criteria may be desirable to some extent and selecting paths that are favorable across many dimensions is not an easy task. Optimization problems like this may be too complex to solve for the "best" solution, but often can be solved for some approximation of the optimal. Which is good news, because otherwise path finding would be an intractable problem.
==== Path finding in math and computer science
==== Path Finding in Math and Computer Science
Path finding in the Lightning Network falls under a general category of _graph theory_ in mathematics and the more specific category of _graph traversal_ in computer science.
A network such as the Lightning Network can be represented as a mathematical construct called a _graph_, where _nodes_ are connected to each other by _edges_ (equivalent to the payment channels). The Lightning Network forms a _directed graph_ because the nodes are linked _asymmetrically_, since the channel balance is split between the two channel partners and the payment liquidity is different in each direction. A directed graph with numerical capacity constrains on its edges is called a _flow network_, a mathematical construct used to optimize transportation and other similar networks. Flow networks can be used as a framework when solutions need to achieve a specific flow while minimizing cost, known as the Minimum Cost Flow Problem (MCFP).
==== Capacity, balance, liquidity
==== Capacity, Balance, Liquidity
In order to better understand the problem of transporting satoshis from point A to point B, we need to better define three important terms: capacity, balance, and liquidity. We use these terms to describe a payment channel's ability to route a payment.
@ -76,7 +76,7 @@ capacity = balance(A) + balance(B)
liquidity(A) = balance(A) - channel_reserve(A) - pending_HTLCs(A)
----
==== Uncertainty of balances
==== Uncertainty of Balances
If we knew the exact channel balances of every channel, we could compute one or more payment paths using any of the standard path finding algorithms taught in good computer science programs. But we don't know the channel balances, we only know the aggregate channel capacity, which is advertised by nodes in channel announcements. In order for a payment to succeed, there must be adequate balance on the sending side of the channel. If we don't know how the capacity is distributed between the channel partners, we don't know if there is enough balance in the direction we are trying to send the payment.
@ -97,7 +97,7 @@ channel_reserve <= liquidity <= (capacity - channel_reserve)
Our channel liquidity uncertainty range is the range between the minimum and maximum possible liquidity. This is unknown to the network, except the two channel partners. However, as we will see we can use failed HTLCs returned from our payment attempts to update our liquidity estimate and reduce uncertainty. If for example we get an HTLC failure code that tells us that a channel cannot fulfill an HTLC that is smaller than our estimate for maximum liquidity, that means the maximum liquidity can be updated to the amount of the failed HTLC. In simpler terms, if we think the liquidity can handle an HTLC of N satoshis and we find out it fails to deliver M satoshis (where M is smaller), then we can update our estimate to M-1 as the upper bound. We tried to find the ceiling and bumped against it, so it's lower than we thought!
==== Path finding complexity
==== Path Finding Complexity
Finding a path through a graph is a problem modern computers can solve rather efficiently.
Developers mainly choose breadth-first search if the edges are all of equal weight.
@ -113,7 +113,7 @@ But we can't be certain unless we try it out or ask the channel owners directly.
Even if we were able to ask the channel owners directly, their balance might change by the time we have asked others, computed a path, constructed an onion and send it along.
Not only do we have limited information but the information we have is highly dynamic and might change at any point in time without our knowledge.
==== Keeping it simple
==== Keeping It Simple
The path finding mechanism implemented in Lightning nodes is to first create a list of candidate paths, filtered and sorted by some function. Then, the node or wallet will probe paths (by attempting to deliver a payment) in a trial-and-error loop until a path is found that successfully delivers the payment.
@ -127,7 +127,7 @@ While "blind probing" is not optimal and leaves ample room for improvement, it s
Most Lightning node and wallet implementations improve on this approach, by ordering/weighting the list of candidate paths. Some implementations order the candidate paths by cost (fees), or some combination of cost/capacity.
=== Path finding and payment delivery process
=== Path Finding and Payment Delivery Process
Path finding and payment delivery involves several steps, which we list below. Different implementations may use different algorithms and strategies, but the basic steps are likely to be very similar:
@ -151,7 +151,7 @@ These three activities can be repeated in a _payment round_ if we use the failur
In the next sections we will look at each of these steps in more detail, as well as more advanced payment strategies.
=== Channel graph construction
=== Channel Graph Construction
In <<gossip>> we covered the three main messages that nodes "gossip": +node_announcement+, +channel_announcement+, and +channel_update+. These three messages allow any node to gradually construct a "map" of the Lightning Network in the form of a _channel graph_. Each of these messages provides a critical piece of information for the channel graph:
@ -223,7 +223,7 @@ Once we attempt to send an HTLC we can learn more about channel balances: if we
You may be thinking "What's the point of learning from a successful HTLC?" After all, if it succeeded we're "done". But consider that we may be sending one part of a multi-part payment. We also may be sending other single-part payments within a short time. Anything we learn about liquidity is useful for the next attempt!
====
==== Liquidity uncertainty and probability
==== Liquidity Uncertainty and Probability
To quantify the uncertainty of a channel's liquidity, we can apply probability theory. A basic model of the probability of payment delivery will lead to some rather obvious, but important, conclusions:
@ -266,7 +266,7 @@ In other words, "The more channels (hops) you use, the lower the chance of succe
There is a lot of mathmatical theory and modelling 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 (co-author of this book) Pickhardt et. al.
====
==== Fees and other channel metrics
==== Fees and Other Channel Metrics
Next, our sender will add information to the graph from +channel_update+ messages received from the intermediary nodes. As a reminder, the +channel_update+ contains a wealth of information about a channel and the expectations of one of the channel partners.
@ -280,7 +280,7 @@ The fee and timelock information are very important not just as path selection m
It is also important to note that a channel must have liquidity that is sufficient not only for the payment amount but also for the cumulative fees of all the subsequent hops. Even though Selena's channel to Xavier (S-->X) has enough liquidity for a 1m satoshi payment, it *does not* have enough liquidity once we consider fees. We need to know fees because only paths that have sufficient liquidity for *both payment and all fees* will be considered.
=== Finding candidate paths
=== Finding Candidate Paths
Finding a suitable path through a directed graph like this is a well-studied computer science problem (known broadly as the "Shortest Path problem"), which can be solved by a variety of algorithms depending on the desired optimization and resource constraints.
@ -303,7 +303,7 @@ But, as we saw previously, the channel +S->X+ does not have enough liquidity for
With two possible paths, Selena is ready to attempt delivery!
=== Payment delivery (Trial-and-error loop)
=== Payment Delivery (Trial-And-Error Loop)
Selena's node starts the trial-and-error loop, by constructing the HTLCs, building the onion and attempting delivery of the payment. For each attempt, there are three possible outcomes:
@ -315,7 +315,7 @@ If the payment fails, then it can be re-tried via a different path by updating t
We'll look at what happens if the payment is "stuck" in <<stuck_payments>>. The important detail is that a stuck payment is the worst outcome because we cannot retry with another HTLC as both (the stuck one and the retry one) might go through eventually and cause a double payment.
==== First attempt (path #1)
==== First Attempt (Path #1)
Selena attempts the first path (S->A->B->R). She constructs the onion and sends it, but receives a failure code from Bob's node. Bob reports back a +temporary channel failure+ with a +channel_update+ identifying the channel B->R as the one that can't deliver. This attempt is shown in <<path_1_fail>>:
@ -327,7 +327,7 @@ image::images/mtln_1207.png[]
From this failure code, Selena will deduce that Bob doesn't have enough liquidity to deliver the payment to Rashid on that channel. Importantly, this failure narrows the uncertainty of the liquidity of that channel! Previously, Selena's node assumed that the liquidity on Bob's side of the channel was somewhere in the range (0, 4m). Now, she can assume that the liquidity is in the range (0, 999999). Similarly, Selena can now assume that the liquidity of that channel on Rashid's side is in the range (1m, 4m), instead of (0, 4m). Selena has learned a lot from this failure.
==== Second attempt (path #4)
==== Second Attempt (Path #4)
Now Selena attempts the fourth candidate path (S->A->B->X->Y->R). This is a longer path and will incur more fees, but it's now the best option for delivery of the payment.
@ -350,7 +350,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.
[[mpp]]
=== Multi-Path Payments (MPP)
=== Multi-Path Payments (Mpp)
_Multi-Path Payments (MPP)_ are a feature that was introduced in the Lightning Network in 2020 and is already very widely available. Multi-Path 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.
@ -361,7 +361,7 @@ Multi-Path Payments are a significant improvement in the Lightning Network as th
Now that MPP is available it is best to think of a single-path payment as a subcategory of a MPP. Essentially, a single-path is just a multi-path of size one. All payments can be considered as Multi-Path Payments unless the size of the payment and liquidity available make it possible to deliver with a single part.
====
==== Using MPP
==== Using Mpp
MPP is not something that a user will select, but rather it is a node path-finding and payment delivery strategy. The same basic steps are implemented: create a graph, select paths and the trial-and-error loop. The difference is that during path selection we must also consider how to split the payment in order to optimize delivery.
@ -400,7 +400,7 @@ image::images/mtln_1209.png[]
Because the S->X channel can now be utilized, and (luckily for Selena), the B->R channel has sufficient liquidity for 600k satoshis, the two parts are successful along paths that were previously not possible.
==== Trial-and-error over multiple "rounds"
==== Trial-And-Error Over Multiple "Rounds"
Multi-Path Payments lead to a somewhat modified "trial-and-error" loop for payment delivery. Because we are attempting multiple paths in each attempt, we have four possible outcomes:

@ -9,7 +9,7 @@ to being able to write a custom wire protocol parser, a reader of this chapter
will gain a deep understanding with respect of the various upgrade mechanisms
that have been built into the protocol.
=== Messaging Layer in the Lightning protocol suite
=== Messaging Layer in the Lightning Protocol Suite
The messaging layer, which is detailed in this chapter, consists of _Message Framing and Format_, _Type Length Value (TLV)_ encoding, and _Feature Bits_. These components are highlighted by a double outline in the protocol suite, shown in <<LN_protocol_wire_message_highlight>>:
@ -106,7 +106,7 @@ including the prefix type of the message along with the contents of its message
body.
[[tlv_message_extensions]]
=== Type Length Value (TLV) Message Extensions
=== Type Length Value (Tlv) Message Extensions
Earlier in this chapter we mentioned that messages can be up to 65 KB in size,
and if while parsing a messages, extra bytes are left over, then those bytes
@ -156,7 +156,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 (Tlv) Format
In order to be able to upgrade messages in both a forwards and backwards
compatible manner, in addition to feature bits (more on that later), the LN
@ -184,7 +184,7 @@ record:
Both the `type` and `length` are encoded using a variable sized integer that's inspired by the variable sized integer (varint) used in Bitcoin's p2p protocol, called `BigSize` for short.
==== BigSize Integer Encoding
==== Bigsize Integer Encoding
In its fullest form, a `BigSize`
integer can represent value up to 64-bits. In contrast to Bitcoin's varint
@ -207,14 +207,14 @@ integer follows one of the four following options:
4. Otherwise, we just encode the value as a full-size 64-bit integer.
==== TLV encoding constraints
==== Tlv Encoding Constraints
Within the context of a TLV message, record types below `2^16` are said to be _reserved_ for future use. Types beyond this
range are to be used for "custom" message extensions used by higher-level application protocols.
The `value` of a record depends on the `type`. In other words, it can take any form as parsers will attempt to interpret it depending on the context of the type itself.
==== TLV canonical encoding
==== Tlv Canonical Encoding
One issue with the Protobuf format is that encodings of the same message may
output an entirely different set of bytes when encoded by two different
@ -259,7 +259,7 @@ designers of the original Lightning Network knew that there were many possible f
extensibility mechanisms within the system, which can be used to upgrade it partially or fully in a decoupled, desynchronized, and decentralized
manner.
==== Feature Bits as an Upgrade Discoverability Mechanism
==== Feature Bits As an Upgrade Discoverability Mechanism
An astute reader may have noticed the various locations that "feature bits" are
included within the Lightning Protocol. A "feature bit" is a bitfield that can
@ -316,7 +316,7 @@ not. The feature bits within the `init` message allow peers to understand if
they can maintain a connection, and also which features are negotiated for the
lifetime of a given connection.
==== TLV for forwards & backwards compatibility
==== Tlv for Forwards & Backwards Compatibility
As we learned earlier in the chapter, Type-Length-Value, or TLV records can be
used to extend messages in a forwards and backwards compatible manner.
@ -340,14 +340,14 @@ consensus in order to adopt. Instead, at minimum, only two peers within the
network need to understand a new upgrade in order to start using it. Commonly these two peers may be the recipient and sender of a
payment, or may be the channel partners of a new payment channel.
==== A taxonomy of upgrade mechanisms
==== A Taxonomy of Upgrade Mechanisms
Rather than there being a single widely utilized upgrade mechanism within the
network (such as soft-forks for Bitcoin), there exist several possible upgrade mechanisms within the Lighting Network. In this
section, we enumerate these upgrade mechanisms, and
provide a real-world example of their use in the past.
===== Internal Network Upgrades
===== Internal network upgrades
We start with the upgrade type that requires the most protocol-level
coordination: internal network upgrades. An internal network upgrade is
@ -371,7 +371,7 @@ network upgrade, in that if a payment wasn't using any new feature beyond
that new routing information encoding, then a payment could be transmitted
using a mixed set of nodes.
===== End-to-End Upgrades
===== End-to-end upgrades
To contrast the internal network upgrade, in this section we describe the
_end to end_ network upgrade. This upgrade mechanism differs from the internal

@ -37,7 +37,7 @@ custom encrypted message transport Lightning uses, commonly referred to as
"Brontide" (more on that later) can be dropped into any context that requires
encrypted communication between two parties.
=== The Channel Graph as Decentralized Public Key Infrastructure
=== The Channel Graph As Decentralized Public Key Infrastructure
As we learned in the chapter on multi-hop forwarding, very node has a long-term
identity that is used as the identifier for a vertex during path finding and
@ -67,7 +67,7 @@ Lightning network is able to significantly simply its encrypted transport
protocol as it doesn't need to deal with all the complexities that come along
with TLS, the Transport Layer Security protocol.
=== Why Not TLS?
=== Why Not Tls?
Readers familiar with the TLS system may be wondering at this point: why wasn't
TLS used in spite of the drawbacks of the existing PKI system? It is indeed a
@ -133,11 +133,11 @@ Lightning Network, the flavor of Noise use will be referred to from here on as
"Brontide". A brontide is a low billowing noise, similar to what one would hear
during a thunderstorm when very far away.
=== Lightning Encrypted Transport in detail
=== Lightning Encrypted Transport in Detail
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.
==== Noise XK: LN's Noise Handshake
==== Noise Xk: Ln's Noise Handshake
The Noise protocol is extremely flexible in that it advertises several
handshakes, each with different security and privacy properties for a would be
@ -283,7 +283,7 @@ handshake as:
* `a || b` denotes the concatenation of two byte strings `a` and `b`
===== Handshake Session State Initialization
===== Handshake session state initialization
Before starting the handshake process, both sides need to initialize the
starting state that they'll use to advance the handshake process. To start,
@ -315,7 +315,7 @@ does indeed know the public key of the responder.
Bitcoin's compressed format:
* `h = SHA-256(h || ls.pub.serializeCompressed())`
===== Handshake Acts
===== Handshake acts
After the initial handshake initialization, we can begin the actual execution
of the handshake process. The Brontide handshake is compromised of a series of
@ -522,7 +522,7 @@ construction, and 16 bytes for a final authenticating tag.
10. `rn = 0, sn = 0`
* The sending and receiving nonces are initialized to 0.
===== Transport Message Encryption
===== Transport message encryption
At the conclusion of Act Three, both sides have derived the encryption keys, which
will be used to encrypt and decrypt messages for the remainder of the
@ -589,7 +589,7 @@ steps are completed:
plaintext packet `p`.
* The nonce `rn` MUST be incremented after this step.
===== Lightning Message Key Rotation
===== Lightning message key rotation
Changing keys regularly and forgetting previous keys is useful to prevent the
decryption of old messages, in the case of later key leakage (i.e. backwards

@ -24,7 +24,7 @@ to complete a payment from receiver to sender, is described in https://github.co
payment hash and destination are communicated in a payment request in order to
make the encoding more fully feature.
=== Lightning Payment Requests vs Bitcoin Addresses
=== Lightning Payment Requests Vs Bitcoin Addresses
A commonly asked question when people first encounter a Lightning Payment
request is: why can't a normal static address format be used instead?
@ -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 in order to allow a
degree of payment request re-use.
=== BOLT 11: Lightning Payment Request Serialization & Interpretation
=== Bolt 11: Lightning Payment Request Serialization & Interpretation
In this section, we'll describe the mechanism used to encode the set of
information required to complete a payment on the Lightning Network. As
@ -160,7 +160,7 @@ allows public key extraction. When verifying the signature, the verifies
extracts the public key, then verifies that against the public key included in
the invoice.
===== Tagged Invoice Fields
===== Tagged invoice fields
The tagged invoice fields are encoded in the main "body" of the invoice. These
fields represent different key=value pairs that express either additional

@ -2,20 +2,20 @@
== Security and Privacy of the Lightning Network
In this chapter, we look at some of the most important issues related to the security and privacy of the Lightning Network. First, we'll consider privacy, what it means, how to evaluate it, and some things you can do to protect your own privacy while using LN. Then we'll explore some common attacks and mitigation techniques.
=== Why is privacy important?
=== Why Is Privacy Important?
The key value proposition of cryptocurrency is censorship resistant money. Bitcoin offers participants the possibility of storing and transferring their wealth without interference by governments, banks, or corporations.The Lightning Network continues this mission.
Unlike trivial scaling solutions like custodial Bitcoin banks, LN aims to scale Bitcoin without compromising on self-custody, which should lead to greater censorship resistance in the Bitcoin ecosystem. However, the LN operates under a different security model, which introduces novel security and privacy challenges.
=== Definitions of privacy
=== Definitions of Privacy
The question: "Is Lightning private?" has no direct answer. Privacy is a complex topic; it is often difficult to precisely define what we mean by privacy, particularly if you are not a privacy researcher. Fortunately, privacy researchers use processes to analyze and evaluate the privacy characteristics of systems and we can use them too! Let's look at how a security researcher might seek to answer the question, "Is Lightning private?" in two general steps.
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
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.
@ -61,7 +61,7 @@ Finally, as a payment network, the LN depends on economic stimuli.
The size and structure of fees affect the routing algorithm and, therefore, can either aid the attacker by forwarding most payments through their nodes or prevent this from happening.
=== Anonymity set
=== Anonymity Set
What does it mean to deanonymize someone?
In simple terms, deanonymization implies linking some action with a person's "real world" identity, such as their name or physical address.
@ -102,7 +102,7 @@ However, the real network leaks information that allows an attacker to narrow do
The smaller the anonymity set, the higher the chance of successful deanonymization.
=== Differences between LN and Bitcoin in terms of privacy
=== Differences Between Ln and Bitcoin in Terms of Privacy
While it's true that transactions on the Bitcoin network do not associate real world identities with Bitcoin addresses, all transactions are broadcast in cleartext and can be analyzed.
Multiple companies have been established to deanonymize users of Bitcoin and other cryptocurrencies.
@ -147,11 +147,11 @@ The issues discussed in this part of the chapter summarize research available in
Now let's review some of the attacks on the Lightning Network privacy that have been described in academic literature.
=== Attacks on Lightning
=== Attacks On Lightning
Recent research describes various ways in which the security and privacy of the LN may be compromised.
==== Observing payment amounts
==== Observing Payment Amounts
One of the goals for a privacy-preserving payment system is to hide the payment amount from uninvolved parties.
The Lightning Network is an improvement over layer-one in this regard.
@ -162,7 +162,7 @@ The availability of payment amounts to intermediary nodes do not present an imme
However, an _honest-but-curious_ intermediary node may use it as a part of a larger attack.
==== Linking senders and receivers
==== Linking Senders and Receivers
An attacker might be interested in learning the sender and/or the receiver of a payment to reveal certain economic relationships.
This breach of privacy could harm censorship resistance, as an intermediary node could censor payments to or from certain receivers or senders.
@ -203,7 +203,7 @@ Even more, as it was recently shown, an attacker can successfully determine the
Finally, it's important to recognize that unknown or unstudied leakages probably exist that could aid deanonymizing attempts. For instance, because different Lightning wallets apply different routing algorithms, even knowing the applied routing algorithm could help exclude certain nodes from being a sender and/or receiver of a payment.
==== Revealing channel balances (probing)
==== Revealing Channel Balances (Probing)
The balances of Lightning channels are supposed to be hidden for privacy and efficiency reasons.
A Lightning node only knows the balances of its adjacent channels.
@ -275,7 +275,7 @@ Second, nodes that implement just-in-time or JIT routing may be less prone to th
Finally, as multi-part payments make the problem of insufficient capacity less severe, the protocol developers may consider hiding some of the error details without harming efficiency.
[[denial_of_service]]
==== Denial of service
==== Denial of Service
When resources are made publicly available, there is a risk that attackers may attempt to make that resource unavailable by executing a denial-of-service attack.
Generally, this is achieved by the attacker bombarding a resource with requests, which are indistinguishable from legitimate queries.
@ -284,7 +284,7 @@ The attacks seldom result in the target suffering financial loss aside from the
Typical mitigations for denial-of-service attacks require authentication for requests to separate legitimate users from malicious ones or to incur a trivial cost to regular users but will act as a sufficient deterrent to an attacker launching requests at scale.
Anti-denial-of-service measures can be seen everywhere on the internet - websites apply rate limits to ensure that no one user can consume all of their server's attention, film review sites require login authentication to keep angry r/prequelmemes (Reddit group) members at bay, and data services sell API keys to limit the number of queries.
===== DoS in Bitcoin
===== Dos in bitcoin
In Bitcoin, the bandwidth that nodes use to relay transactions and the space that they avail to the network in the form of their mempool are publicly available resources.
Any node on the network can consume bandwidth and mempool space by sending a valid transaction.
@ -297,7 +297,7 @@ This measure largely ensured that the transactions that consume network resource
The minimum relay fee is acceptable to regular users but would hurt attackers financially if they tried to spam the network.
While some transactions may not make it into valid blocks during high fee environments, these measures have largely been effective at disincentivizing this type of spam.
===== DoS in Lightning
===== Dos in lightning
Similarly to Bitcoin, the Lightning Network charges fees for the use of its public resources, but in this case, the resources are public channels, and the fees come in the form of routing fees.
The ability to route payments through nodes in exchange for fees provides the network with a large scalability benefit - nodes that are not directly connected can still transact - but it comes at the cost of exposing a public resource that must be protected against DoS attacks.
@ -310,14 +310,14 @@ This is great for legitimate users, who wouldn't like to pay for failed attempts
At the time of writing, a discussion is https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-June/002734.html[ongoing] on the lightning-dev mailing list as to how best address this issue.
===== Known DoS attacks
===== Known dos attacks
There are two known DoS attacks on public Lightning channels which render a target channel, or a set of target channels, unusable.
Both attacks involve routing payments through a public channel, then holding them until their timeout, thus maximizing the attack's duration.
The requirement to fail payments to not pay fees is fairly simple to meet because malicious nodes can simply reroute payments to themselves.
In the absence of fees for failed payments, the only cost to the attacker is the on-chain cost of opening a channel to dispatch these payments through, which can be trivial in low fee environments.
==== Commitment jamming
==== Commitment Jamming
Lightning nodes update their shared state using asymmetric commitment transactions, on which HTLCs are added and removed to facilitate payments.
Each party is limited to a total of https://github.com/lightningnetwork/lightning-rfc/blob/c053ce7afb4cbf88615877a0d5fc7b8dbe2b9ba0/02-peer-protocol.md#the-open_channel-message[483] HTLCs in the commitment transaction at a time.
@ -326,13 +326,13 @@ A channel jamming attack allows an attacker to render a channel unusable by rout
It should be noted that this limit was chosen in the specification to ensure that all the HTLCs can be swept in a https://github.com/lightningnetwork/lightning-rfc/blob/master/05-onchain.md#penalty-transaction-weight-calculation[single justice transaction].
While this limit _may_ be increased, transactions are still limited by the block size, so the number of slots available is likely to remain limited.
==== Channel liquidity lockup
==== Channel Liquidity Lockup
A channel liquidity lockup attack is comparable to a channel jamming attack in that it routes payments through a channel and holds them so that the channel is unusable.
Rather than locking up slots on the channel commitment, this attack routes large HTLCs through a target channel that consumes all the channel's available bandwidth.
This attack's capital commitment is higher than the commitment jamming attack because the attacking node needs more funds to route failed payments through the target.
=== Cross-layer deanonymization
=== Cross-Layer Deanonymization
Computer networks are often layered.
Layering allows for separation of concerns and makes the whole system manageable.
@ -414,7 +414,7 @@ The possible deanonymization of Bitcoin entities illustrates how important it is
//TODO from author: maybe here we should/could include the corresponding figures from the Romiti et al. paper. it would greatly improve and help the understanding of the section
=== Lightning graph
=== Lightning Graph
The Lightning Network, as the name suggests, is a peer-to-peer network of payment channels.
Therefore, many of its properties (privacy, robustness, connectivity, routing efficiency) are influenced and characterized by its network nature.
@ -422,7 +422,7 @@ Therefore, many of its properties (privacy, robustness, connectivity, routing ef
In this section, we discuss and analyze the LN from the point of view of network science.
We are particularly interested in understanding the LN channel graph, its robustness, connectivity, and other important characteristics.
==== How does the Lightning graph look in reality?
==== How Does the Lightning Graph Look in Reality?
One could have expected that the LN is a random graph, where edges are randomly formed between nodes.
If this was the case, then the LN's degree distribution would follow a Gaussian normal distribution.
In particular, most of the nodes would have approximately the same degree, and we would not expect nodes with extraordinarily large degrees.
@ -470,7 +470,7 @@ To conclude, even by design, it is possible to remove edges and nodes from the r
However, depending on the utilized attack vector, the adversary may have to provide more or fewer resources to carry out the attack.
===== Temporality of the LN
===== Temporality of the ln
The LN is a dynamically changing, permissionless network.
Nodes can freely join or leave the network, they can open and create payment channels anytime they want.
@ -493,7 +493,7 @@ This is counterintuitive and surprising given that nodes could have just routed
This may mean that routing inefficiencies incentivized users to close triangles and not fall back on routing.
Hopefully, multi-part payments will help increase the effectiveness of payment routing.
=== Centralization in the LN
=== Centralization in the Ln
A common metric to assess the centrality of a node in a graph is its _betweenness centrality_. Central point dominance is a metric derived from betweenness centrality, used to assess the centrality of a network.
For a precise definition of central point dominance, the reader is referred to https://doi.org/10.2307/3033543[Freeman's work].
@ -505,7 +505,7 @@ In general, our understanding of the dynamic nature of the LN channel graph is r
It is fruitful to analyze how protocol changes like multi-part payments can affect the dynamics of the LN.
It would be beneficial to explore the temporal nature of the LN graph in more depth.
=== Economic incentives and graph structure
=== Economic Incentives and Graph Structure
The Lightning graph forms spontaneously and nodes connect to each other based on mutual interest.
As a result, incentives drive graph development.
@ -524,13 +524,13 @@ This might change in the future if LN has significantly larger traffic or if a m
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.
=== Practical advice for users to protect their privacy
=== Practical Advice for Users to Protect Their Privacy
We're still in the early stages of the Lightning Network.
Many of the concerns listed in this chapter are likely to be addressed as it matures and grows.
In the meantime, there are some measures that you can take to guard your node against malicious users; something as simple as updating the default parameters that your node runs with can go a long way in hardening your node.
=== Unannounced channels
=== Unannounced Channels
If you intend to use the Lightning Network to send and receive funds between nodes and wallets you control, and have no interest in routing other users' payments, there is little need to announce your channels to the rest of the network.
You could open a channel between, say, your desktop PC running a full node and your mobile phone running a Lightning Wallet and simply forgo the channel announcement discussed in <<ch03_How_Lightning_Works>>.
@ -556,7 +556,7 @@ In addition, the Taproot update of 2021 makes it difficult to distinguish betwee
Hence, while unannouned channels are not completely private, they do provide some privacy benefits when used carefully.
[[routing_considerations]]
=== Routing considerations
=== Routing Considerations
As covered in the <<denial_of_service>> section, nodes that open public channels expose themselves to the risk of a series of attacks on their channels.
While mitigations are being developed on the protocol level, there are many steps that a node can take to protect against denial of service attacks on their public channels.
@ -570,7 +570,7 @@ Some useful guidelines for a custom rate limiter are as follows:
* Shadow channels: nodes that wish to open large channels to a single target can instead open a single public channel to the target and support it with further private channels called [shadow channels](joost on TFTC).
These channels can still be used for routing but are not announced to potential attackers.
==== Accepting channels
==== Accepting Channels
At present, Lightning nodes struggle with bootstrapping inbound liquidity. While there are some paid
solutions to acquiring inbound liquidity, like swap services, channel markets, and paid channel opening services from known hubs, many nodes will gladly accept any legitimate looking channel opening request to increase their inbound liquidity.
@ -598,7 +598,7 @@ Some potential strategies are:
=== Conclusion
In summary, privacy and security are nuanced, complex topics and while many researchers and developers are looking for network-wide improvements, it's important for everyone participating in the network to understand what they can do to protect their own privacy and increase security on an individual node level.
=== References and further reading
=== References and Further Reading
In this chapter, we used many references from ongoing research on Lightning security. You may find these useful articles and papers listed by topic below:

@ -1,73 +1,73 @@
[[conclusion_chapter]]
== Conclusion
In just a few years, the Lightning Network has gone from a whitepaper to a rapidly growing global network. As Bitcoin's second layer it has delivered on the promise of fast, inexpensive, and private payments. Additionally, it has started a tsunami of innovation, as it unleashes developers from the constraints of lock-step consensus that exist in Bitcoin development.
Innovation in the Lightning Network is happening in several different levels:
* At Bitcoin's Core protocol, providing use and demand for new Bitcoin Script opcodes, signing algorithms, and optimizations
* At the Lightning protocol level with new features deployed rapidly network-wide.
* At the payment channel level, with new channel constructs and enhancements
* As distinct opt-in features deployed end-to-end by independent implementations that senders and recipients can use if they want.
* With new and exciting Lightning Applications (LApps) build on top of the clients and protocols.
Let's look at how these innovations are changing Lightning now and in the near future.
=== Decentralized and asynchronous innovation
Lightning isn't bound by lock-step consensus, as is the case with Bitcoin. That means that different Lightning clients can implement different features and negotiate their interactions (see <<feature_bits>>). As a result, innovation in the Lightning Network is occurring at a much faster rate than in Bitcoin.
Not only is Lightning advancing rapidly, but it is creating demand for new features in the Bitcoin system. Many recent and planned innovations in Bitcoin are both motivated and justified by their use in the Lightning Network. In fact, the Lightning Network is often mentioned as an example use-case for many of the new features.
==== Bitcoin protocol and Bitcoin Script innovation
The Bitcoin system is, by necessity, a conservative system that has to preserve compatibility with consensus rules to avoid unplanned forks of the blockchain or partitions of the P2P network. As a result, new features require a lot of coordination and testing before they are implemented in "mainnet", the live production system.
Here are some of the current or proposed innovations spurred by Lightning:
Neutrino:: A lightweight client protocol with improved privacy features over the legacy SPV protocol. Neutrino is mostly used by Lightning clients to access the Bitcoin blockchain.
Schnorr signatures:: Introduced as part of the _Taproot_ soft fork, Schnorr signatures will enable flexible Point Time-Locked Contracts (PTLC) for channel construction in Lightning.
Taproot:: Also part of the November 2021 soft-fork that introduces Schnorr signatures, Taproot allows complex scripts to appear as single-payer, single-payee payments, and indistinguishable from the most common type of payment on Bitcoin. This will allow Lightning channel cooperative (mutual) closure transactions to appear indistinguishable from simple payments and increase privacy for LN users.
Input re-binding:: Also known by the names SIGHAS_NOINPUT, or SIGHASH_ANYPREVOUT, this planned upgrade to the Bitcoin Script language is primarily motivated by advanced smart contracts such as the eltoo channel protocol.
Covenants:: Currently in the early stages of research, coventants allow transactions to create outputs that constrain future transactions which spend them. This mechanism could increase security for Lightning channels, by making it possible to enforce address whitelisting in commitment transactions.
==== Lightning protocol innovation
The Lightning P2P protocol is highly extensible and has undergone a lot of change since its inception. The "It's OK to be odd" rule used in feature bits (see <<feature_bits>>) ensure that nodes can negotiate the features they support, enabling multiple independent upgrades to the protocol.
===== TLV extensibility
The Type-Length-Value (see <<tlv>>) mechanism for extending the messaging protocol is extremely powerful and has already enabled the introduction of several new capabilities in Lightning while maintaining both forward and backward compatibility.
==== Payment channel construction
Payment channels are an abstraction that is operated by two channel partners. As long as those two are willing to run new code, they can implement a variety of channel mechanisms simultaneously. In fact, recent research suggests that channels could even be upgraded to a new mechanism dynamically, without closing the old channel and opening a new channel type.
Eltoo:: A proposed channel mechanism that uses input-rebinding to significantly simplify the operation of payment channels and remove the need for the penalty mechanism. It needs a new Bitcoin signature type before it can be implemented
==== 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.
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.
Multi-Part Payments (MPP):: MPP was also introduced in an opt-in manner, but even better only requires the sender and recipient of a payment to be able to do MPP. The rest of the network simply routes HTLCs as if they are single-part payments.
Keysend:: An upgrade introduced independently by Lightning client implementations, it allows the sender to send money in an "unsolicited" and asynchronous way without requiring an invoice first.
HODL invoices:: Payments where the final HTLC is not collected, committing the sender to the payment, but allowing the recipient to delay collection until some other condition is satisfied, or cancel the invoice without collection. This was also implemented independently by different Lightning clients and can be used opt-in.
Onion routed message services:: The onion routing mechanism, and the underlying public key databse of nodes can be used to send data that is unrelated to payments, such as text messages or forum posts. The use of Lightning to enable paid messaging as a solution to spam posts and sybil attacks (spam) is another innovation that was implemented independently of the core protocol.
[[lapps]]
=== Lightning Applications (LApps)
While still in their infancy, we are already seeing the emergence of interesting Lightning Applications. Broadly defined as an application that uses the Lightning Protocol or a Lightning client as a component, LApps are the application layer of Lightning. LApps are being built for simple games, messaging applications, micro-services, payable-APIs, paid dispensers (eg. fuel pumps), derivative trading systems, and much more.
=== Ready, set, go!
The future is looking bright. The Lightning Network is taking Bitcoin to new unexplored markets and applications. Equipped with the knowledge in this book, you can explore this new frontier, or maybe even join as a pioneer and forge a new path.
[[conclusion_chapter]]
== Conclusion
In just a few years, the Lightning Network has gone from a whitepaper to a rapidly growing global network. As Bitcoin's second layer it has delivered on the promise of fast, inexpensive, and private payments. Additionally, it has started a tsunami of innovation, as it unleashes developers from the constraints of lock-step consensus that exist in Bitcoin development.
Innovation in the Lightning Network is happening in several different levels:
* At Bitcoin's Core protocol, providing use and demand for new Bitcoin Script opcodes, signing algorithms, and optimizations
* At the Lightning protocol level with new features deployed rapidly network-wide.
* At the payment channel level, with new channel constructs and enhancements
* As distinct opt-in features deployed end-to-end by independent implementations that senders and recipients can use if they want.
* With new and exciting Lightning Applications (LApps) build on top of the clients and protocols.
Let's look at how these innovations are changing Lightning now and in the near future.
=== Decentralized and Asynchronous Innovation
Lightning isn't bound by lock-step consensus, as is the case with Bitcoin. That means that different Lightning clients can implement different features and negotiate their interactions (see <<feature_bits>>). As a result, innovation in the Lightning Network is occurring at a much faster rate than in Bitcoin.
Not only is Lightning advancing rapidly, but it is creating demand for new features in the Bitcoin system. Many recent and planned innovations in Bitcoin are both motivated and justified by their use in the Lightning Network. In fact, the Lightning Network is often mentioned as an example use-case for many of the new features.
==== Bitcoin Protocol and Bitcoin Script Innovation
The Bitcoin system is, by necessity, a conservative system that has to preserve compatibility with consensus rules to avoid unplanned forks of the blockchain or partitions of the P2P network. As a result, new features require a lot of coordination and testing before they are implemented in "mainnet", the live production system.
Here are some of the current or proposed innovations spurred by Lightning:
Neutrino:: A lightweight client protocol with improved privacy features over the legacy SPV protocol. Neutrino is mostly used by Lightning clients to access the Bitcoin blockchain.
Schnorr signatures:: Introduced as part of the _Taproot_ soft fork, Schnorr signatures will enable flexible Point Time-Locked Contracts (PTLC) for channel construction in Lightning.
Taproot:: Also part of the November 2021 soft-fork that introduces Schnorr signatures, Taproot allows complex scripts to appear as single-payer, single-payee payments, and indistinguishable from the most common type of payment on Bitcoin. This will allow Lightning channel cooperative (mutual) closure transactions to appear indistinguishable from simple payments and increase privacy for LN users.
Input re-binding:: Also known by the names SIGHAS_NOINPUT, or SIGHASH_ANYPREVOUT, this planned upgrade to the Bitcoin Script language is primarily motivated by advanced smart contracts such as the eltoo channel protocol.
Covenants:: Currently in the early stages of research, coventants allow transactions to create outputs that constrain future transactions which spend them. This mechanism could increase security for Lightning channels, by making it possible to enforce address whitelisting in commitment transactions.
==== Lightning Protocol Innovation
The Lightning P2P protocol is highly extensible and has undergone a lot of change since its inception. The "It's OK to be odd" rule used in feature bits (see <<feature_bits>>) ensure that nodes can negotiate the features they support, enabling multiple independent upgrades to the protocol.
===== Tlv extensibility
The Type-Length-Value (see <<tlv>>) mechanism for extending the messaging protocol is extremely powerful and has already enabled the introduction of several new capabilities in Lightning while maintaining both forward and backward compatibility.
==== Payment Channel Construction
Payment channels are an abstraction that is operated by two channel partners. As long as those two are willing to run new code, they can implement a variety of channel mechanisms simultaneously. In fact, recent research suggests that channels could even be upgraded to a new mechanism dynamically, without closing the old channel and opening a new channel type.
Eltoo:: A proposed channel mechanism that uses input-rebinding to significantly simplify the operation of payment channels and remove the need for the penalty mechanism. It needs a new Bitcoin signature type before it can be implemented
==== 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.
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.
Multi-Part Payments (MPP):: MPP was also introduced in an opt-in manner, but even better only requires the sender and recipient of a payment to be able to do MPP. The rest of the network simply routes HTLCs as if they are single-part payments.
Keysend:: An upgrade introduced independently by Lightning client implementations, it allows the sender to send money in an "unsolicited" and asynchronous way without requiring an invoice first.
HODL invoices:: Payments where the final HTLC is not collected, committing the sender to the payment, but allowing the recipient to delay collection until some other condition is satisfied, or cancel the invoice without collection. This was also implemented independently by different Lightning clients and can be used opt-in.
Onion routed message services:: The onion routing mechanism, and the underlying public key databse of nodes can be used to send data that is unrelated to payments, such as text messages or forum posts. The use of Lightning to enable paid messaging as a solution to spam posts and sybil attacks (spam) is another innovation that was implemented independently of the core protocol.
[[lapps]]
=== Lightning Applications (Lapps)
While still in their infancy, we are already seeing the emergence of interesting Lightning Applications. Broadly defined as an application that uses the Lightning Protocol or a Lightning client as a component, LApps are the application layer of Lightning. LApps are being built for simple games, messaging applications, micro-services, payable-APIs, paid dispensers (eg. fuel pumps), derivative trading systems, and much more.
=== Ready, Set, Go!
The future is looking bright. The Lightning Network is taking Bitcoin to new unexplored markets and applications. Equipped with the knowledge in this book, you can explore this new frontier, or maybe even join as a pioneer and forge a new path.

@ -21,7 +21,7 @@ This chapter covers several important concepts from Bitcoin, including:
* Timelocks
=== Keys and digital signatures
=== Keys and Digital Signatures
You may have heard that bitcoin is based on _cryptography_, which is a branch of mathematics used extensively in computer security. Cryptography can also be used to prove knowledge of a secret without revealing that secret (digital signature), or prove the authenticity of data (digital fingerprint). These types of cryptographic proofs are the mathematical tools critical to bitcoin and used extensively in bitcoin applications.
@ -29,7 +29,7 @@ Ownership of bitcoin is established through _digital keys_, _bitcoin addresses_,
Most bitcoin transactions require a valid digital signature to be included in the blockchain, which can only be generated with a secret key; therefore, anyone with a copy of that key has control of the bitcoin. The digital signature used to spend funds is also referred to as a _witness_, a term used in cryptography. The witness data in a bitcoin transaction testifies to the true ownership of the funds being spent. Keys come in pairs consisting of a private (secret) key and a public key. Think of the public key as similar to a bank account number and the private key as similar to the secret PIN.
==== Private and public keys
==== Private and Public Keys
A private key is simply a number, picked at random. In practice, and to make managing many keys easy, most bitcoin wallets generate a sequence of private keys from a single random _seed_, using a deterministic derivation algorithm. Simply put, a single random number is used to produce a repeatable sequence of seemingly random numbers that are used as private keys. This allows users to only backup the seed and be able to _derive_ all the keys they need from that seed.
@ -107,7 +107,7 @@ Proof-of-Work/Hash Grinding:: You can use a hash to prove you have done computat
Atomicity:: You can make a secret pre-image a pre-requisite of spending funds in several linked transactions. If any one of the parties reveals the pre-image in order to spend one of the transactions, all the other parties can now spend their transactions too. All or none become spendable, achieving atomicity across several transactions.
==== Digital signatures
==== Digital Signatures
The private key is used to create signatures that are required to spend bitcoin by proving ownership of funds used in a transaction.
@ -133,12 +133,12 @@ Signatures are not always applied to the entire transaction. To provide signing
More information about signature hash types can be found in https://github.com/bitcoinbook/bitcoinbook/blob/develop/ch06.asciidoc#sighash_types[_Mastering Bitcoin Second Edition - Chapter 6 - Signature Hash Types_]
=== Bitcoin transactions
=== Bitcoin Transactions
Transactions are data structures that encode the transfer of value between participants in the bitcoin system.
[[utxo]]
==== Inputs and outputs
==== Inputs and Outputs
The fundamental building block of a bitcoin transaction is a transaction output. Transaction outputs are indivisible chunks of bitcoin currency, recorded on the blockchain, and recognized as valid by the entire network. A transaction spends "inputs" and creates "outputs". Transaction inputs are simply references to outputs of previously recorded transactions. This way, each transaction spends the outputs of previous transactions and creates new outputs.
@ -180,7 +180,7 @@ The illustrations and examples above show how a Bitcoin transaction combines (sp
While the transactions created by the Lightning Network have multiple outputs they do not have "change" per se, because the entire available balance of a channel is split between the two channel partners.
====
==== 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 spend 4,000 satoshi to pay Dina:
@ -194,7 +194,7 @@ The only type of transaction that doesn't have "inputs" is a special transaction
Since transactions are chained, if you pick a transaction at random, you can follow any one of its inputs backwards 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.
==== TxID: 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.
@ -215,7 +215,7 @@ or use the short link (case sensitive):
http://bit.ly/AliceTx
==== Outpoints: output identifiers
==== Outpoints: Output Identifiers
As every transaction has a unique ID, we can also identify a transaction output within that transaction uniquely by reference to the TxID and the output index number. The first output in a transaction is output index 0, the second output is output index 1 and so on. An output identifier is commonly known as an _outpoint_.
@ -274,7 +274,7 @@ Using a simplified model, for validation, the unlocking script and locking scrip
Obviously, this simplified example would make a very poor choice for locking an actual Bitcoin output because there is no secret, just basic arithmetic. Anyone could spend the output by providing the answer "2". Most locking scripts therefore require demonstrating knowledge of a secret.
==== Locking to a public key (signature)
==== Locking to a Public Key (Signature)
The simplest form of a locking script that requires a signature. Let's consider Alice's transaction that pays Bob 50,000 satoshis. The output Alice creates to pay Bob will have a locking script requiring Bob's signature and would look like this:
@ -309,7 +309,7 @@ To validate Bob's transaction, a Bitcoin node would do the following:
* Execute this script on the Bitcoin Script execution engine to see what result is produced
* If the result is +TRUE+, deduce that Bob's transaction is valid because it was able to fulfill the spending condition to spend that outpoint.
==== Locking to a hash (secret)
==== Locking to a Hash (Secret)
Another type of locking script, one that is used in the Lightning Network, is a _hash lock_. In order to unlock it you must know the secret _pre-image_ to the hash.
@ -354,7 +354,7 @@ Only Bob knows +R+, so only Bob can produce a transaction with an unlocking scri
Interestingly, Bob can give the +R+ value to anyone else, who can then spend that Bitcoin. This makes the secret value +R+ almost like a bitcoin "voucher", since anyone who has it can spend the output Alice created. We'll see how this is a useful property for the Lightning Network!
[[multisig]]
==== Multisignature scripts
==== Multisignature Scripts
The Bitcoin scripting language provides a multisignature building block (primitive), that can be used to build escrow services and complex ownership configurations between several stakeholders. An arrangement that requires multiple signatures to spend Bitcoin is called a _multisignature scheme_, further specified as an _K-of-N_ scheme, where:
@ -388,7 +388,7 @@ The two scripts together would form the combined validation script:
A multisignature locking script can be represented by a Bitcoin address, encoding the hash of the locking script. For example, the initial funding transaction of a Lightning payment channel is a transaction that pays to an address that encodes a locking script of a 2-of-2 multisig of the two channel partners.
==== Timelock scripts
==== Timelock Scripts
Another important building block that exists in Bitcoin and is used extensively in the Lightning Network is a _timelock_. A timelock is a restriction on spending that requires that a certain time or block height has elapsed before spending is allowed. It is a bit like a post-dated check drawn from a bank account that can't be "cashed" before the date on the check.
@ -403,7 +403,7 @@ Output-level absolute timelocks are implemented by the operator +CHECKLOCKTIMEVE
Output-level relative timelocks are implemented by the operator +CHECKSEQUENCEVERIFY+, often shortened in conversation as _CSV_. Relative timelocks implement a spending constraint that is relative to the confirmation of the transaction, expressing the equivalent of "can't be spent until 1024 blocks after confirmation".
[[conditional_scripts]]
==== Scripts with multiple conditions
==== Scripts with Multiple Conditions
One of the more powerful features of Bitcoin Script is flow control, also known as conditional clauses. You are probably familiar with flow control in various programming languages that use the construct +IF...THEN...ELSE+. Bitcoin conditional clauses look a bit different, but are essentially the same construct.

@ -34,7 +34,7 @@ This message shows that your installation appears to be working correctly.
[...]
----
=== Basic Docker commands
=== Basic Docker Commands
In this chapter, we use Docker quite extensively. We will be using the following Docker commands and arguments:

@ -3,7 +3,7 @@
This appendix contains license notices for material included by permission granted via open licenses.
=== BTCPay Server
=== Btcpay Server
BTCPay Server Logo, screenshots and other images used with permission under the MIT License:
@ -35,6 +35,6 @@ SOFTWARE.
++++
=== Lamassu Industries AG
=== Lamassu Industries Ag
Images of the _Gaia_ Bitcoin ATM (https://lamassu.is/product/gaia) seen in <<bitcoin-atm>> are used with permission of Lamassu Industries AG. The use of these images is not an endorsement of the product or company, but are provided as a visual example of a Bitcoin ATM.

@ -1,7 +1,7 @@
[role="pagenumrestart"]
[[part_1]]
[part]
== Understanding The Lightning Network
== Understanding the Lightning Network
[partintro]
--

@ -1,6 +1,6 @@
[[part_2]]
[part]
== The Lightning Network in detail
== The Lightning Network in Detail
[partintro]
--

@ -68,7 +68,7 @@ If you feel your use of code examples falls outside fair use or the permission g
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!
[[addresses_and_transactions_sec]]
=== Addresses and Transactions in this Book
=== Addresses and Transactions in This Book
The Bitcoin addresses, transactions, keys, QR codes, and blockchain data used in this book are, for the most part, real. That means you can browse the blockchain, look at the transactions offered as examples, retrieve them with your own scripts or programs, etc.
@ -154,13 +154,13 @@ René would also like to thank all of the patrons who support his work through m
Or you can support his work directly with Bitcoin (also via the Lightning Network) at link:$$https://donate.ln.rene-pickhardt.de$$[] for which René is equally thankful as for his patreons.
[[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 aquired 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 makes you my personal heros and I will never forget the help, patience and support I received when I was in need.

Loading…
Cancel
Save