You can contact Andreas M. Antonopoulos on his personal site: https://aantonop.com

Subscribe to Andreas’s channel on YouTube: https://www.youtube.com/aantonop

Like Andreas’s page on Facebook: https://www.facebook.com/AndreasMAntonopoulos

Follow Andreas on Twitter: https://twitter.com/aantonop

Connect with Andreas on LinkedIn: https://linkedin.com/company/aantonop

Andreas would also like to thank the patrons who support his work through monthly donations. You can support Andreas on Patreon at https://patreon.com/aantonop.

You can contact René Pickhardt on his personal site: https://ln.rene-pickhardt.de

Subscribe to René’s channel on YouTube: https://www.youtube.com/user/RenePickhardt

Follow René on Twitter: https://twitter.com/renepickhardt

Connect with René on LinkedIn: https://www.linkedin.com/in/rene-pickhardt-80313744

René would also like to thank all of the patrons who support his work through monthly donations. You can support René on Patreon at https://patreon.com/renepickhardt.

Or you can support his work directly with Bitcoin (also via the Lightning Network) at https://donate.ln.rene-pickhardt.de for which René is equally thankful as for his patreons.

You can contact Olaoluwa Osuntokun at his professional email address: laolu@lightning.engineering

Follow Olaoluwa on Twitter: https://twitter.com/roasbeef

The Bitcoin system offers an alternative chain for testing purposes called testnet, in contrast with the "normal" Bitcoin chain which is referred to as mainnet. On testnet, the currency is testnet bitcoin (tBTC), which is a worthless copy of bitcoin used exclusively for testing. Every function of Bitcoin is replicated exactly, but the money is worth nothing, so you literally have nothing to lose!

Some Lightning wallets can also operate on testnet, allowing you to make Lightning payments with testnet bitcoin, without risking real funds. This is a great way to experiment with Lightning safely. Eclair Mobile, which Alice uses in this chapter, is one example of a Lightning wallet that supports testnet operation.

You can get some tBTC to play with from a testnet bitcoin faucet, which gives out free tBTC on demand. Here are a few testnet faucets:

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.

As we mentioned at the beginning of this section, Eclair is a noncustodial 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.

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. Alice can use the mnemonic phrase to restore all the transactions and funds in the Eclair Mobile wallet in the case of a lost mobile device, a software bug, or memory corruption.

When Alice chooses to create a new wallet, she will see a screen with her mnemonic phrase, which looks like the screenshot in New wallet mnemonic phrase.

In New wallet mnemonic phrase, we have purposely obscured part of the mnemonic phrase to prevent readers of this book from reusing the mnemonic.

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.

Once Alice has recorded the mnemonic phrase, after touching "OK GOT IT" on her screen, she will be presented with a quiz to make sure that she correctly recorded the mnemonic. The quiz will ask for three or four of the words at random. Alice isn’t expecting a quiz, but since she recorded the mnemonic correctly, she passes without any difficulty.

Once Alice has recorded the mnemonic phrase and passed the quiz, she should store each copy in a separate secure location, such as a locked desk drawer or a fireproof safe.

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!

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.

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 A Lamassu 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.

To receive the bitcoin in her Eclair Lightning wallet, Alice will need to present a Bitcoin address from the Eclair Lightning wallet to the ATM. The ATM can then send Alice’s newly acquired bitcoin to this Bitcoin address.

To see a Bitcoin address on the Eclair wallet, Alice must swipe to the left column titled YOUR BITCOIN ADDRESS (see Alice’s bitcoin address, shown in Eclair), where she will see a square barcode (called a QR code) and a string of letters and numbers below that.

The QR code contains the same string of letters and numbers shown below it, in an easy to scan format. This way, Alice doesn’t have to type the Bitcoin address. In the screenshot (Alice’s bitcoin address, shown in Eclair), we have purposely blurred both, to prevent readers from inadvertently sending bitcoin to this address.

Alice will see the transaction from the ATM in the TRANSACTION HISTORY tab of the Eclair wallet. Although Eclair will detect the bitcoin transaction in just a few seconds, it will take approximately one hour for the bitcoin transaction to be "confirmed" on the Bitcoin blockchain. As you can see in Alice receives bitcoin, Alice’s Eclair wallet shows "6+ conf" below the transaction, indicating that the transaction has received the required minimum of six confirmations, and her funds are now ready to use.

Although in this example Alice used an ATM to acquire her first bitcoin, the same basic concepts would apply even if she used one of the other methods in Acquiring Bitcoin. For example, if Alice wanted to sell a product or provide a professional service in exchange for bitcoin, her customers could scan the Bitcoin address with their wallets and pay her in bitcoin.

Similarly, if she billed a client for a service offered over the internet, Alice could send an email or instant message with the Bitcoin address or the QR code to her client, and they could paste or scan the information into a Bitcoin wallet to pay her.

Alice could even print the QR code and affix it to a sign and display it publicly to receive tips. For example, she could have a QR code affixed to her guitar and receive tips while performing on the street!^[5]

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.

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.

Let’s review the definition of an LN channel at this point, to make things a bit clearer. Firstly, the word "channel" is a metaphor for a financial relationship between Alice’s Lightning wallet and another Lightning wallet. We call it a channel because it is a means for Alice’s wallet and this other wallet to exchange many payments with each other on the Lightning Network (off-chain) without committing transactions to the Bitcoin blockchain (on-chain).

The wallet or node that Alice opens a channel to is called her channel peer. Once "opened," a channel can be used to send many payments back and forth between Alice’s wallet and her channel peer.

Furthermore, Alice’s channel peer can forward payments via other channels further into the Lightning Network. This way, Alice can route a payment to any wallet (e.g., Bob’s Lightning wallet) as long as Alice’s wallet can find a viable path made by hopping from channel to channel, all the way to Bob’s wallet.

In other words, Alice needs one or more channels that connect her to one or more other nodes on the Lightning Network. She doesn’t need a channel to connect her wallet directly to Bob’s Cafe in order to send Bob a payment, though she can choose to open a direct channel, too. Any node in the Lightning Network can be used for Alice’s first channel. The more well-connected a node is, the more people Alice can reach. In this example, since we want to also demonstrate payment routing, we won’t have Alice open a channel directly to Bob’s wallet. Instead, we will have Alice open a channel to a well-connected node and then later use that node to forward her payment, routing it through any other nodes as necessary to reach Bob.

At first, there are no open channels, so as we see in LIGHTNING CHANNELS tab, the LIGHTNING CHANNELS tab displays an empty list. If you notice, in the bottom-right corner there is a plus symbol (+), which is a button to open a new channel.

A "node URI" is a Universal Resource Identifier (URI) that identifies a specific Lightning node. Alice can either paste such a URI from her clipboard or scan a QR code containing that same information. An example of a node URI is shown as a QR code in Node URI as a QR code and then as a text string.

While Alice could select a specific Lightning node, or use the "Random node" option to have the Eclair wallet select a node at random, she will select the ACINQ Node option to connect to one of ACINQ’s well-connected Lightning nodes.

Choosing the ACINQ node will slightly reduce Alice’s privacy, because it will give ACINQ the ability to see all of Alice’s transactions. It will also create a single point of failure, since Alice will only have one channel, and if the ACINQ node is not available, Alice will not be able to make payments. To keep things simple at first, we will accept these trade-offs. In subsequent chapters, we will gradually learn how to gain more independence and make fewer trade-offs!

Alice selects ACINQ Node and is ready to open her first channel on the Lightning Network.

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.^[6]

Alice allocates 0.018 BTC of her 0.020 BTC total to her channel and accepts the default fee rate, as shown in Opening a Lightning channel.

Once she clicks OPEN, her wallet constructs the special Bitcoin transaction that opens a Lightning channel, known as the funding transaction. The on-chain funding transaction is sent to the Bitcoin network for confirmation.

Alice now has to wait again (see Waiting for the funding transaction to open the channel) for the transaction to be recorded on the Bitcoin blockchain. As with the initial Bitcoin transaction that she used to acquire her bitcoin, she has to wait for six or more confirmations (approximately one hour).

Once the funding transaction is confirmed, Alice’s channel to the ACINQ node is open, funded, and ready, as shown in Channel is open.

Bob has a simple point-of-sale (PoS) application for the use of any customer who wants to pay with bitcoin over the Lightning Network. As we will see in the next chapter, Bob uses the popular open source platform BTCPay Server which contains all the necessary components for an ecommerce or retail solution, such as:

BTCPay Server makes it simple to install all the necessary software, upload pictures and product prices, and launch a store quickly.

On the counter at Bob’s Cafe, there is a tablet device showing what you see in Bob’s point-of-sale application.

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 Lightning invoice for Alice’s latte.

Alice selects the option to "scan a payment request," scans the QR code displayed on the screen of the tablet (see Lightning invoice for Alice’s latte), and is prompted to confirm her payment, as shown in Alice’s send confirmation.

Alice presses PAY, and a second later, Bob’s tablet shows a successful payment. Alice has completed her first LN payment! It was fast, inexpensive, and easy. Now she can enjoy her latte which was purchased using bitcoin through a payment system that is fast, cheap, and decentralized. From now on, Alice can simply select an item on Bob’s tablet screen, scan the QR code with her cell phone, click PAY, and be served a coffee, all within seconds and all without an on-chain transaction.

Lightning payments are better for Bob, too. He’s confident that he will be paid for Alice’s latte without waiting for an on-chain confirmation. In the future, whenever Alice feels like drinking a coffee at Bob’s Cafe, she can choose to pay with bitcoin on the Bitcoin network or the Lightning Network. Which one do you think she will choose?

Payment channels are built on top of 2-of-2 multisignature addresses.

In summary, a multisignature address is where bitcoin is locked so that it requires multiple signatures to unlock and spend. In a 2-of-2 multisignature address, as used in the Lightning Network, there are two participating signers and both need to sign to spend the funds.

Multisignature scripts and addresses are explained in more detail in Multisignature Scripts.

A commitment transaction is a transaction that pays each channel partner their channel balance and ensures that the channel partners do not have to trust each other. By signing a commitment transaction, each channel partner "commits" to the current balance and gives the other channel partner the ability to get their funds back whenever they want.

By holding a signed commitment transaction, each channel partner can get their funds even without the cooperation of the other channel partner. This protects them against the other channel partner’s disappearance, refusal to cooperate, or attempt to cheat by violating the payment channel protocol.

The commitment transaction that Alice prepared in the previous example was a refund of her initial payment to the multisignature address. More generally, however, a commitment transaction splits the funds of the payment channel, paying the two channel partners according to the distribution (balance) they each hold. At first, Alice holds all the balance, so it is a simple refund. But as funds flow from Alice to Bob, they will exchange signatures for new commitment transactions that represent the new balance distribution, with some part of the funds paid to Alice and some paid to Bob.

Let’s assume that Alice opens a channel with a capacity of 100,000 satoshi with Bob. Initially, Alice owns 100,000 satoshi, the entirety of the funds in the channel. Here’s how the payment channel protocol works:

By following this protocol, Alice does not give up ownership of her 100k satoshi even though the funds are sent to a 2-of-2 multisignature address for which Alice controls only one key. If Bob stops responding to Alice, she will be able to broadcast her commitment transaction and receive her funds back. Her only costs are the fees for the on-chain transactions. As long as she follows the protocol, this is her only risk when opening a channel.

After this initial exchange, commitment transactions are created each time the channel balance changes. In other words, each time a payment is sent between Alice and Bob, new commitment transactions are created and signatures are exchanged. Each new commitment transaction encodes the latest balance between Alice and Bob.

If Alice wants to send 30k satoshi to Bob, both would create a new version of their commitment transactions, which would now pay 70k satoshi to Alice and 30k satoshi to Bob. By encoding a new balance for Alice and Bob, the new commitment transactions are the means by which a payment is "sent" across the channel.

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.

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.

In the channel protocol we have seen so far, nothing stops Alice from publishing a previous commitment transaction. A cheating Alice could publish the commitment transaction that grants her 100k satoshi. Since that commitment transaction was signed by Bob, he can’t prevent Alice from transmitting it.

Some mechanism is needed to prevent Alice from publishing an old commitment transaction. Let’s now find out how this can be achieved and how it enables the Lightning Network to operate without requiring any trust between Alice and Bob.

Because Bitcoin is censorship resistant, no one can prevent someone from publishing an old commitment transaction. To prevent this form of cheating, commitment transactions are constructed so that if an old one is transmitted, the cheater can be punished. By making the penalty large enough, we create a strong incentive against cheating, and this makes the system secure.

The way the penalty works is by giving the cheated party an opportunity to claim the balance of the cheater. So if someone attempts to cheat by broadcasting an old commitment transaction, in which they are paid a higher balance than they are due, the other party can punish them by taking both their own balance and the balance of the cheater. The cheater loses everything.

Let us go through the channel construction scenario again, adding a penalty mechanism to protect against cheating:

With a strong penalty mechanism, Alice is not tempted to cheat by publishing an old commitment transaction because she risks losing her entire balance.

Now that we understand why a penalty mechanism is needed and how it will prevent cheating, let’s see how it works in detail.

Usually, the commitment transaction has at least two outputs, paying each channel partner. We change this to add a timelock delay and a revocation secret to one of the payments. The timelock prevents the owner of the output from spending it immediately once the commitment transaction is included in a block. The revocation secret allows either party to immediately spend that payment, bypassing the timelock.

So, in our example, Bob holds a commitment transaction that pays Alice immediately, but his own payment is delayed and revocable. Alice also holds a commitment transaction, but hers is the opposite: it pays Bob immediately but her own payment is delayed and revocable.

The two channel partners hold half of the revocation secret, so that neither one knows the whole secret. If they share their half, then the other channel partner has the full secret and can use it to exercise the revocation condition. When signing a new commitment transaction, each channel partner revokes the previous commitment by giving the other party their half of the revocation secret.

We will examine the revocation mechanism in more detail in Revoking and Recommitting, where we will learn the details of how revocation secrets are constructed and used.

In simple terms, Alice signs Bob’s new commitment transaction only if Bob offers his half of the revocation secret for the previous commitment. Bob only signs Alice’s new commitment transaction if she gives him her half of the revocation secret from the previous commitment.

With each new commitment, they exchange the necessary "punishment" secret that allows them to effectively revoke the prior commitment transaction by making it unprofitable to transmit. Essentially, they destroy the ability to use old commitments as they sign the new ones. What we mean is that while it is still technically possible to use old commitments, the penalty mechanism makes it economically irrational to do so.

The timelock is set to a number of blocks up to 2,016 (approximately two weeks). If either channel partner publishes a commitment transaction without cooperating with the other partner, they will have to wait for that number of blocks (e.g., two weeks) to claim their balance. The other channel partner can claim their own balance at any time. Furthermore, if the commitment they published was previously revoked, the channel partner can also immediately claim the cheating party’s balance, bypassing the timelock and punishing the cheater.

The timelock is adjustable and can be negotiated between channel partners. Usually, it is longer for larger capacity channels, and shorter for smaller channels, to align the incentives with the value of the funds.

For every new update of the channel balance, new commitment transactions and new revocation secrets have to be created and saved. As long as a channel remains open, all revocation secrets ever created for the channel need to be kept because they might be needed in the future. Fortunately, the secrets are rather small and it is only the channel partners who need to keep them, not the entire network. Furthermore, due to a smart derivation mechanism used to derive revocation secrets, we only need to store the most recent secret, because previous secrets can be derived from it (see Cheating and Penalty in Practice).

Nevertheless, managing and storing the revocation secrets is one of the more elaborate parts of Lightning nodes that require node operators to maintain backups.

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 fail-safe, ensuring they do not lose funds if there is a problem with their channel partner.

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.

Announcing channels publicly allows other nodes to use them for payment routing, thereby also generating routing fees for the channel partners.

By contrast, the channel partners may decide not to announce the channel, making it an unannounced channel.

Unannounced channels are still used to route payments but only by the nodes that are aware of their existence, or given "routing hints" about a path that includes an unannounced channel.

When a channel and its capacity are publicly announced using the gossip protocol, the announcement can also include information about the channel (metadata), such as its routing fees and timelock duration.

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.

The best way to close a channel is…​to not close it! Opening and closing channels requires an on-chain transaction, which will incur transaction fees. So it’s best to keep channels open as long as possible. You can keep using your channel to make and forward payments, as long as you have sufficient capacity on your end of the channel. But even if you send all the balance to the other end of the channel, you can then use the channel to receive payments from your channel partner. This concept of using a channel in one direction and then using it in the opposite direction is called "rebalancing," and we will examine it in more detail in another chapter. By rebalancing a channel, it can be kept open almost indefinitely and used for an essentially unlimited number of payments.

However, sometimes closing a channel is desirable or necessary. For example:

There are three ways to close a payment channel:

Each of these methods is useful for different circumstances, which we will explore in the next sections of this chapter. For example, if your channel partner is offline, you will not be able to follow "the good way" because a mutual close cannot be done without a cooperating partner. Usually, your LN software will automatically select the best closing mechanism available under the circumstances.

The most important part of the invoice is the payment hash. When constructing the invoice, Bob will make a payment hash as follows:

There is no known way to find the inverse of SHA-256 (i.e., compute a preimage from a hash). Only Bob knows the value r, so it is Bob’s secret. But once Bob reveals r, anyone who has the hash H can check that r is the correct secret, by calculating SHA-256(r) and seeing that it matches H.

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.

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.

The invoice can also include some routing hints, which allow the sender to use unannounced channels to construct a route to the recipient. Routing hints can also be used to suggest public channels, for example, channels known by the recipient to have enough inbound capacity to route the payment.

In case the sender’s Lightning node is unable to send the payment over the Lightning Network, invoices can optionally include an on-chain Bitcoin address as a fallback.

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.

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.

Channel announcements are communicated over a peer-to-peer gossip protocol. A peer-to-peer protocol is a communications protocol in which each node connects to a random selection of other nodes in the network, usually over TCP/IP. Each of the nodes that are directly connected (over TCP/IP) to your node are called your peers. Your node, in turn, is one of their peers. Keep in mind that when we say that your node is connected to other peers, we don’t mean that you have payment channels, but only that you are connected via the gossip protocol.

After opening a channel, a node may choose to send out an announcement of the channel via the channel_announcement message to its peers. Every peer validates the information from the channel_announcement message and verifies that the funding transaction is confirmed on the Bitcoin blockchain. After verification, the node will forward the gossip message to its own peers, and they will forward it to their peers, and so on, spreading the announcement across the entire network. To avoid excessive communication, the channel announcement is only forwarded by each node if it has not already forwarded that announcement previously.

The gossip protocol is also used to announce information about known nodes with the node_announcement message. For this message to be forwarded, a node has to have at least one public channel announced on the gossip protocol, again to avoid excessive communication traffic.

Payment channels have various metadata that are useful for other participants of the network. This metadata is mainly used for making routing decisions. Because nodes might occasionally change the metadata of their channels, this information is shared in a channel_update message. These messages will only be forwarded approximately four times a day (per channel) to prevent excessive communication. The gossip protocol also has a variety of queries and messages to initially synchronize a node with the view of the network or to update the node’s view after being offline for a while.

A major challenge for the participants of the Lightning Network is that the topology information being shared by the gossip protocol is only partial. For example, the capacity of the payment channels is shared on the gossip protocol via the channel_announcement message. However, this information is not as useful as the actual distribution of the capacity in terms of the local balance between the two channel partners. A node can only forward as much bitcoin as it actually owns (local balance) within that channel.

Although the Lightning Network could have been designed to share balance information of channels and a precise topology, this has not been done for several reasons:

We will examine the details of the gossip protocol in a later chapter.

For now, it is only important to know that the gossip protocol exists and that it is used to share topology information of the Lightning Network. This topology information is crucial for delivering payments through the network of payment channels.

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.

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.

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 Mix Format,^[8] which will be explained in detail in a later chapter.

A payment package used for routing is called an "onion."^[9]

Let’s use the onion analogy to follow a routed payment. On its route from payment sender (payer) to payment destination (payee) the onion is passed from node to node along the path. The sender constructs the entire onion, from the center out. First, the sender creates the payment information for the (final) recipient of the payment and encrypts it with a layer of encryption that only the recipient can decrypt. Then, the sender wraps that layer with instructions for the node in the path immediately preceding the final recipient and encrypts with a layer that only that node can decrypt.

The layers are built up with instructions, working backward until the entire path is encoded in layers. The sender then gives the complete onion to the first node in the path, which can only read the outermost layer. Each node peels a layer, finds instructions inside revealing the next node in the path, and passes the onion on. As each node peels one layer, it can’t read the rest of the onion. All it knows is where the onion has just come from and where it is going next, without any indication as to who is the original sender or the ultimate recipient.

This continues until the onion reaches the payment destination (payee). Then, the destination node opens the onion and finds there are no further layers to decrypt and can read the payment information inside.

The onion routing protocol used in Lightning has the following properties:

Onion routing will be examined in detail in 10 Onion Routing.

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.

Each intermediary node receives a Lightning message called update_add_htlc with a payment hash and an onion. The intermediary node executes a series of steps, called the payment forwarding algorithm:

Of course, these steps are interrupted and aborted if an error is detected, and an error message is sent back to the originator of the update_add_htlc message. The error message is also formatted as an onion and sent backward on the incoming channel.

As the error propagates backward on each channel along the path, the channel partners remove the pending payment, rolling back the payment in the opposite way from which it started.

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.

In a typical payment using Bitcoin, a user receives a Bitcoin address (e.g., scanning a QR code on a web page, or receiving it in an instant message or email from a friend). They then use their Bitcoin wallet to create a transaction to send funds to this address.

On the Lightning Network, the recipient of a payment creates an invoice. A Lightning invoice can be seen as analogous to a Bitcoin address. The intended recipient gives the Lightning invoice to the sender as a QR code or character string, just like a Bitcoin address.

The sender uses their Lightning wallet to pay the invoice, copying the invoice text or scanning the invoice QR code. A Lightning payment is analogous to a Bitcoin "transaction."

There are some differences in the user experience, however. A Bitcoin address is reusable. Bitcoin addresses never expire, and if the owner of the address still holds the keys, the funds held within are always accessible. A sender can send any amount of bitcoin to a previously used address, and a recipient can post a single static address to receive many payments. While this goes against the best practices for privacy reasons, it is technically possible and in fact quite common.

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 Spontaneous Payments.

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. For instance, a user making a payment of 1 BTC can use a single output with value 1 BTC, two outputs with value 0.25 BTC and 0.75 BTC, or four outputs with value 0.25 BTC each.

On Lightning, payments do not require inputs to be consumed. Instead, each payment results in an update of the channel balance, redistributing it between the two channel partners. The sender experiences this as "moving" the channel balance from their end of a channel to the other end, to their channel partner. Lightning payments use a series of channels to route from sender to recipient. Each of these channels must have sufficient capacity to route the payment.

Because many possible channels and paths can be used to make a payment, the Lightning user’s choice of channels and paths is somewhat analogous to the Bitcoin user’s choice of UTXO.

With technologies such as atomic multipath payments (AMP) and multipart payments (MPP), which we will review in subsequent chapters, several Lightning paths can be aggregated into a single atomic payment, just like several Bitcoin UTXOs can be aggregated into a single atomic Bitcoin transaction.

To make a payment on the Bitcoin network, the sender needs to consume one or more unspent transaction outputs (UTXOs). UTXOs can only be spent in full; they cannot be divided and partially spent. So if a user wishes to spend 0.8 BTC, but only has a 1 BTC UTXO, they need to spend the entire 1 BTC UTXO by sending 0.8 BTC to the recipient and 0.2 BTC back to themselves as change. The 0.2 BTC change payment creates a new UTXO called a "change output."

On Lightning, the funding transaction spends some Bitcoin UTXO, creating a multisignature UTXO to open the channel. Once the bitcoin is locked within that channel, portions of it can be sent back and forth within the channel, without the need to create any change. This is because the channel partners simply update the channel balance and only create a new UTXO when the channel is eventually closed using the channel closing transaction.

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. The amount of the fee is based on the size of the transaction in bytes that the transaction is using in a block, as well as how quickly the user wants that transaction mined. Because miners will typically mine the most profitable transactions first, a user who wants their transaction mined immediately will pay a higher fee per byte, while a user who is not in a hurry will pay a lower fee per byte.

On the Lightning Network, users pay fees to other (intermediary node) users to route payments through their channels. To route a payment, an intermediary node will have to move funds in two or more channels they own, as well as transmit the data for the sender’s payment. Typically, the routing user will charge the sender based on the value of the payment, having established a minimum base fee (a flat fee for each payment) and a fee rate (a prorated fee proportional to the value of the payment). Higher value payments will thus cost more to route, and a market for liquidity is formed, where different users charge different fees for routing through their channels.

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.

If there are more transactions in the queue (called the mempool) than can fit in a block, they will begin by mining the transactions that pay the highest fees per unit (bytes) of transaction weight. Thus, when there are many transactions in the queue, users have to pay a higher fee to be included in the next block, or they have to wait until there are fewer transactions in the queue. This naturally leads to the emergence of a fee market where users pay based on how urgently they need their transaction included in the next block.

The scarce resource on the Bitcoin network is the space in the blocks. Bitcoin users compete for block space, and the Bitcoin fee market is based on available block space. The scarce resources in the Lightning Network are the channel liquidity (capacity of funds available for routing in channels) and channel connectivity (how many well-connected nodes channels can reach). Lightning users compete for capacity and connectivity; therefore, the Lightning fee market is driven by capacity and connectivity.

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.

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.

LN payments, on the other hand, are almost completely private. Typically, only the sender and the recipient are fully aware of the source, destination, and amount transacted in a particular payment. Furthermore, the receiver may not even know the source of the payment. Because payments are onion routed, the users who route the payment are only aware of the amount of the payment, and they can determine neither the source nor the destination.

In summary, Bitcoin transactions are broadcast publicly and stored forever. Lightning payments are executed between a few selected peers, and information about them is privately stored only until the channel is closed. Creating mass surveillance and analysis tools equivalent to those used on Bitcoin will be much harder on Lightning.

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.

On the Lightning Network, confirmations only matter for opening and closing channels on-chain. Once a funding transaction has reached a suitable number of confirmations (e.g., 3), the channel partners consider the channel open. Because the bitcoin in the channel is secured by a smart contract that manages that channel, payments settle instantly once received by the final recipient. In practical terms, instant settlement means that payments take only a few seconds to execute and settle. As with Bitcoin, Lightning payments are not reversible.

Finally, when the channel is closed, a transaction is made on the Bitcoin network; once that transaction is confirmed, the channel is considered closed.

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.

On the Lightning Network, a user can only send as much bitcoin as currently exists on their side of a particular channel to a channel partner. For instance, if a user owns one channel with 0.4 BTC on their side, and another channel with 0.2 BTC on their side, then the maximum they can send with one payment is 0.4 BTC. This is true regardless of how much bitcoin the user currently has in their Bitcoin wallet.

Multipart payments (MPP) is a feature which, in the preceding example, allows the user to combine both their 0.4 BTC and 0.2 BTC channels to send a maximum of 0.6 BTC with one payment. MPPs are currently being tested across the Lightning Network and are expected to be widely available and used by the time this book is completed. For more detail on MPP, see Multipart Payments.

If the payment is routed, every routing node along the routing path must have channels with capacity at least the same as the payment amount being routed. This must hold true for every single channel that the payment is routed through. The capacity of the lowest-capacity channel in a path sets the upper limit for the capacity of the entire path.

Hence, capacity and connectivity are critical and scarce resources in the Lightning Network.

The fee structure in Bitcoin is independent of the transaction value. A $1 million transaction has the same fee as a $1 transaction on Bitcoin, assuming a similar transaction size, in bytes (more specifically "virtual" bytes after SegWit [Segregated Witness protocol]). In Lightning the fee is a fixed-base fee plus a percentage of the transaction value. Therefore, in Lightning the payment fee increases with payment value. These opposing fee structures create different incentives and lead to different usage in regards to transaction value. A transaction of greater value will be cheaper on Bitcoin; hence, users will prefer Bitcoin for large value transactions. Similarly, on the other end of the scale, users will prefer Lightning for small value transactions.

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. Once a transaction is included in the blockchain, it is final. Thus, no disputes can arise and it is unambiguous how much bitcoin is controlled by a particular address at a particular point in the blockchain.

On the Lightning Network, the balance in a channel at a particular time is known only to the two channel partners, and is only made visible to the rest of the network when the channel is closed. When the channel is closed, the final balance of the channel is submitted to the Bitcoin blockchain, and each partner receives their share of the bitcoin in that channel. For instance, if the opening balance was 1 BTC paid by Alice, and Alice made a payment of 0.3 BTC to Bob, then the final balance of the channel is 0.7 BTC for Alice and 0.3 BTC for Bob. If Alice tries to cheat by submitting the opening state of the channel to the Bitcoin blockchain, with 1 BTC for Alice and 0 BTC for Bob, then Bob can retaliate by submitting the true final state of the channel, as well as creating a penalty transaction that gives him all the bitcoin in the channel. 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.

When a Bitcoin user sends funds to a destination address, they do not need to know anything about the recipient. The recipient might be offline or online, and no interaction between sender and recipient is needed. The interaction is between sender and the Bitcoin blockchain. Receiving bitcoin on the Bitcoin blockchain is a passive and asynchronous activity that does not require any interaction by the recipient or for the recipient to be online at any time. Bitcoin addresses can even be generated offline and are never "registered" with the Bitcoin network. Only spending bitcoin requires interaction.

In Lightning, the recipient must be online to complete the payment before it expires. The recipient must run a node or have someone that runs a node on their behalf (a third-party custodian). To be precise, both nodes, the sender’s and the recipient’s, must be online at the time of payment and must coordinate. Receiving a Lightning payment is an active and synchronous activity between sender and recipient, without the participation of most of the Lightning Network or the Bitcoin network (except for the intermediary routing nodes, if any).

The synchronous and always-online nature of the Lightning Network is probably the biggest difference in the user experience, and this often confounds users who are accustomed to Bitcoin.

On the Bitcoin network, the smallest amount is a satoshi, which cannot be divided any further. Lightning is a bit more flexible, and Lightning nodes work with millisatoshis (thousandths of a satoshi). This allows tiny payments to be sent via Lightning. A single millisatoshi payment can be sent across a payment channel, an amount so small it should properly be characterized as a nanopayment.

The millisatoshi unit cannot, of course, be settled on the Bitcoin blockchain at that granularity. Upon channel closure, balances are rounded to the nearest satoshi. But over the lifetime of a channel, millions of nanopayments are possible at millisatoshi levels. The Lightning Network breaks through the micropayment barrier.

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 multisignature addresses as part of payment channels on the Lightning Network.

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.

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. Because 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.

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.

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 that operate as open systems and open networks. Global, open, and free.

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 macOS, with small modifications to the commands. The biggest difference between operating systems is the package manager that installs the various software libraries and their prerequisites. In the given examples, we will use apt, which is the package manager for Ubuntu. On macOS, a common package manager used for open source development is Homebrew, which is accessed by the command brew.

In most of the examples here, we will be building the software directly from the source code. While this can be quite challenging, it gives us the most power and control. You may choose to use Docker containers, precompiled packages, or other installation mechanisms instead if you get stuck!

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 macOS, and it comes installed by default on most Linux systems.

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.

You can download the repository as a ZIP bundle by visiting GitHub and selecting the green Code button on the right.

Alternatively, you can use the git command to create a version-controlled clone of the repository on your local computer. Git is a distributed version control system that is used by most developers to collaborate on software development and track changes to software repositories. Download and install git by following the instructions from the Git Project.

To make a local copy of the repository on your computer, run the git command as follows:

You now have a complete copy of the book repository in a folder called lnbook. You will want to change to the newly downloaded directory by running:

All subsequent examples will assume that you are running commands from inside this folder.

Let’s prepare the bitcoind container. The easiest way is to pull the latest container from Docker Hub:

Alternatively, you can build the container yourself from the local container definition that is in code/docker/bitcoind/Dockerfile.

Building the container locally will use a bit less of your network bandwidth, but will take more of your CPU time to build. We use the docker build command to build it:

As you can see, bitcoind starts up and mines 101 simulated blocks to get the chain started. This is because under the Bitcoin consensus rules, newly mined bitcoin is not spendable until 100 blocks have elapsed. By mining 101 blocks, we make the first block’s coinbase spendable. After that initial mining activity, 6 new blocks are mined every 10 seconds to keep the chain moving forward.

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.

The c-lightning software distribution has a Docker container, but it is designed for running c-lightning in production systems and alongside a bitcoind node. We will be using a somewhat simpler container configured to run c-lightning for demonstration purposes.

Let’s pull the c-lightning container from the book’s Docker Hub repository:

Alternatively, we can build the c-lightning Docker container from the book’s files which you previously downloaded into a directory named lnbook. As before, we will use the docker build command in the code/docker subdirectory. We will tag the container image with the tag lnbook/c-lightning, like this:

Our container is now built and ready to run. However, before we run the c-lightning container, we need to start the bitcoind container in another terminal because c-lightning depends on bitcoind. We will also need to set up a Docker network that allows the containers to connect to each other as if residing on the same local area 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:

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, because it is automatically managed.

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:

You should see bitcoind start up and start mining blocks every 10 seconds. Leave it running and open a new terminal window to start c-lightning. We use a similar docker run command with the network and name arguments to start c-lightning as follows:

The c-lightning container starts up and connects to the bitcoind container over the Docker network. First, our c-lightning node will wait for bitcoind to start, and then it will wait until bitcoind has mined some bitcoin into its wallet. Finally, as part of the container startup, a script will send an RPC command to the bitcoind node, which creates a transaction that funds the c-lightning wallet with 10 test BTC. Now our c-lightning node is not only running, but it even has some test bitcoin to play with!

As we demonstrated with the bitcoind container, we can issue commands to our c-lightning container in another terminal to extract information, open channels, etc. The command that allows us to issue command-line instructions to the c-lightning node is called lightning-cli. This lightning-cli command is also aliased as cli inside this container. To get the c-lightning node’s information, use the following docker exec command in another terminal window:

We now have our first Lightning node running on a virtual network and communicating with a test Bitcoin blockchain. Later in this chapter we will start more nodes and connect them to each other to make some Lightning payments.

In the next section we will also look at how to download, configure, and compile c-lightning directly from the source code. This is an optional and advanced step that will teach you how to use the build tools and allow you to make modifications to c-lightning source code. With this knowledge you can write some code, fix some bugs, or create a plug-in for c-lightning.

The c-lightning developers have provided detailed instructions for building c-lightning from source code. We will be following the instructions from GitHub.

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 Elements Project repository.

The common first step is the installation of prerequisite libraries. We use the apt package manager to install these:

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 are needed for software development in general.

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:

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.

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:

Running configure with the help option will show us all the available options:

We don’t need to change any of the defaults for this example. Hence we run configure again without any options to use the defaults:

Next, we use the make command to build the libraries, components, and executables of the c-lightning project. This part will take several minutes to complete and will use your computer’s CPU and disk heavily. Expect some noise from the fans! Run make:

If all goes well, you will not see any ERROR message stopping the execution of the preceding command. The c-lightning software package has been compiled from source, and we are now ready to install the executable components we created in the previous step:

To verify that the lightningd and lightning-cli commands have been installed correctly, we will ask each executable for its version information:

The version consists of the latest release version (v0.10.1), followed by the number of changes since the release (34), and finally a hash identifying exactly which revision (fe86c11). You may see a different version from that shown previously as the software continues to evolve long after this book is published. However, no matter what version you see, the fact that the commands execute and respond with version information means that you have succeeded in building the c-lightning software.

We can pull the LND example Docker container from the book’s Docker Hub repository:

Alternatively, we can build the LND container locally. The container is located in code/docker/lnd. We change the working directory to code/docker and perform the docker build command:

Our container is now ready to run. As with the c-lightning container we built previously, the LND container also depends on a running instance of Bitcoin Core. As before, we need to start the bitcoind container in another terminal and connect LND to it via a Docker network. We have already set up a Docker network called lnbook and will be using that again here.

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:

Next, we start the LND container we just built. As done before, we need to attach it to the lnbook network and give it a name:

The LND container starts up and connects to the bitcoind container over the Docker network. First, our LND node will wait for bitcoind to start, and then it will wait until bitcoind has mined some bitcoin into its wallet. Finally, as part of the container startup, a script will send an RPC command to the bitcoind node, thereby creating a transaction that funds the LND wallet with 10 test BTC.

As we demonstrated previously, we can issue commands to our container in another terminal to extract information, open channels, etc. The command that allows us to issue command-line instructions to the lnd daemon is called lncli. Once again, in this container we have provided the alias cli that runs lncli with all the appropriate parameters. Let’s get the node information using the docker exec command in another terminal window:

We now have another Lightning node running on the lnbook network and communicating with bitcoind. If you are still running the c-lightning container, then there are now two nodes running. They’re not yet connected to each other, but we will be connecting them to each other soon.

If desired, you can run any combination of LND and c-lightning nodes on the same Lightning Network. For example, to run a second LND node you would issue the docker run command with a different container name, like so:

In the preceding command, we start another LND container, naming it lnd2. The names are entirely up to you, as long as they are unique. If you don’t provide a name, Docker will construct a unique name by randomly combining two English words such as "naughty_einstein." This was the actual name Docker chose for us when we wrote this paragraph. How funny!

In the next section we will look at how to download and compile LND directly from the source code. This is an optional and advanced step that will teach you how to use the Go language build tools and allow you to make modifications to LND source code. With this knowledge you can write some code or fix some bugs.

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 because 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.

We will follow the installation instructions found in the LND project documentation.

First, we will install the golang package and associated libraries. We strictly require Go version 1.13 or later. The official Go language packages are distributed as binaries from the Go Project. For convenience they are also packaged as Debian packages available through the apt command. You can follow the instructions from the Go Project or use the following apt commands on a Debian/Ubuntu Linux system as described on GitHub’s wiki page on the Go language:

Check that you have the correct version installed and ready to use by running:

We have 1.13.4, so we’re ready to…​Go! Next we need to tell any programs where to find the Go code. This is accomplished by setting the environment variable GOPATH. Usually the Go code is located in a directory named gocode directly in the user’s home directory. With the following two commands we consistently set the GOPATH and make sure your shell adds it to your executable PATH. Note that the user’s home directory is referred to as ~ in the shell.

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.

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:

Once go get finishes, you will have a subdirectory under GOPATH that contains 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:

After several minutes you will have two new commands, lnd and lncli, installed. Try them out and check their version to ensure they are installed:

You will likely see a different version from that shown previously, as the software continues to evolve long after this book is published. However, no matter what version you see, the fact that the commands execute and show you version information means that you have succeeded in building the LND software.

Let’s pull the book’s Eclair container from the Docker Hub repository:

Alternatively, we can build the container locally, instead. By now, you are almost an expert in the basic operations of Docker! In this section we will repeat many of the previously seen commands to build the Eclair container. The container is located in code/docker/eclair. We start in a terminal by switching the working directory to code/docker and issuing the docker build command:

Our image is now ready to run. The Eclair container also depends on a running instance of Bitcoin Core. As before, we need to start the bitcoind container in another terminal and connect Eclair to it via a Docker network. We have already set up a Docker network called lnbook, and will be reusing it here.

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.

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:

Next, we start the Eclair container we just built. We will need to attach it to the lnbook network and give it a name, just as we did with the other containers:

The Eclair container starts up and connects to the bitcoind container over the Docker network. First, our Eclair node will wait for bitcoind to start, and then it will wait until bitcoind has mined some bitcoin into its wallet.

As we demonstrated previously, we can issue commands to our container in another terminal to extract information, open channels, etc. The command that allows us to issue command-line instructions to the eclair daemon is called eclair-cli. As before, in this container we have provided a useful alias to eclair-cli, called simply cli, which offers the necessary arguments and parameters. Using the docker exec command in another terminal window, we get the node info from Eclair:

We now have another Lightning node running on the lnbook network and communicating with bitcoind. You can run any number and any combination of Lightning nodes on the same Lightning network. Any number of Eclair, LND, and c-lightning nodes can coexist. For example, to run a second Eclair node you would issue the docker run command with a different container name, as follows:

In the preceding command we start another Eclair container named eclair2.

In the next section we will also look at how to download and compile Eclair directly from the source code. This is an optional and advanced step that will teach you how to use the Scala and Java language build tools and allow you to make modifications to Eclair’s source code. With this knowledge, you can write some code or fix some bugs.

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.

The required Java compiler is part of OpenJDK 11. We will also need a build framework called Maven, version 3.6.0 or above.

On a Debian/Ubuntu Linux system, we can use the apt command to install both OpenJDK 11 and Maven, as shown in the following:

Verify that you have the correct version installed by running:

We have OpenJDK 11.0.7 and Maven 3.6.1, so we’re ready.

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:

Once git clone finishes, you will have a subdirectory eclair containing the source code for the Eclair server.

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:

After several minutes, the build of the Eclair package should complete. However, the "package" action will also run tests, and some of these connect to the internet and could fail. If you want to skip tests, add -DskipTests to the command.

Now, unzip and run the build package by following the instructions for installing Eclair from GitHub.

Congratulations! You have built Eclair from source and you are ready to code, test, fix bugs, and contribute to this project!

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.

First, let’s install docker-compose. The instructions depend on your operating system.

Once you have completed installation, you can verify your installation by running docker-compose like this:

The most common docker-compose commands we will use are up and down, e.g., docker-compose up.

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:

The preceding fragment defines a network called lnnet and a container called bitcoind which will attach to the lnnet network. The container is the same one we built at the beginning of this chapter. We expose three of the container’s ports, allowing us to send commands to it and monitor blocks and transactions. Next, the configuration specifies an LND container called "Alice." Further down you will also see specifications for containers called "Bob" (c-lightning), "Chan" (Eclair), and "Dina" (LND again).

Since all these diverse implementations follow the BOLT specification and have been extensively tested for interoperability, they have no difficulty working together to build a 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!

Following the startup, you will see a whole stream of logfiles as each node starts up and reports its progress. It may look quite jumbled on your screen, but each output line is prefixed by the container name, as seen previously. If you wanted to watch the logs from only one container, you can do so in another terminal window by using the docker-compose logs command with the f (follow) flag and the specific container name:

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.

The payment demo is contained in a Bash shell script called run-payment-demo.sh. To run this demo you must have the Bash shell installed on your computer. Most Linux and Unix-like systems (e.g., macOS) have bash preinstalled. Windows users can install the Windows Subsystem for Linux and use a Linux distribution like Ubuntu to get a native bash command on their computer.

Let’s run the script to see its effect, and then we will look at how it works internally. We use bash to run it as a command:

As you can see from the output, the script first gets the node IDs (public keys) for each of the four nodes. Then, it connects the nodes and sets up a 1,000,000 satoshi channel from each node to the next in the network. Finally, it issues an invoice for 10,000 satoshis from Dina’s node and pays the invoice from Alice’s node.

There is a lot to review in that script, but as you gain understanding of the underlying technology, more and more of that information will become clear. You are invited to revisit this example later.

Of course, you can do a lot more with this test network than a three-channel, four-node payment. Here are some ideas for your experiments:

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. If a Bitcoin node goes down for an extended period of time, the user can simply reboot the node, and once it connects to the rest of the network, it will resync the blockchain.

In Lightning, however, the user needs to be online both to send and to receive payments. If the Lightning node is offline, it cannot receive any payments from anyone, and thus its open invoices cannot be fulfilled. Furthermore, the open channels of an offline node cannot be used to route payments. Your channel partners will notice that you are offline and cannot contact you to route a payment. If you are offline too often, they may consider the bitcoin locked up in their channels with you to be underutilized capacity, and may close those channels. We already discussed the case of a protocol attack in which your channel partner tries to cheat you by submitting an earlier commitment transaction. If you are offline and your channels aren’t being monitored, then the attempted theft could succeed, and you will have no recourse once the timelock expires. Hence, node reliability is extremely important for a Lightning node.

There are also the issues of hardware failure and loss of data. In Bitcoin, a hardware failure can be a trivial problem if the user has a backup of their mnemonic phrase or private keys. The Bitcoin wallet and the bitcoin inside the wallet can be easily restored from the private keys on a new computer. Most information can be redownloaded from the blockchain.

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.

There are three main types of hardware Lightning nodes:

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.

However, as the saying goes, "‘Cloud’ is just other people’s computers." Using these services means running your node on other people’s computers. This brings along the corresponding advantages and disadvantages. The key advantages are convenience, efficiency, uptime, and possibly even cost. The cloud operator manages and runs the node to a high degree, automatically providing you with convenience and efficiency. They provide excellent uptime and availability, often much better than what an individual can achieve at home. If you consider that just the electricity cost of running a server in many Western countries is around $10 per month, then add to that the cost of network bandwidth and the hardware itself, the VPS offering becomes financially competitive. Lastly, with a VPS you need no space for a PC at home and don’t have any issues with PC noise or heat. On the other hand, there are several notable disadvantages. A Lightning node running in the "cloud" will always be less secure and less private than one running on your own computer. Additionally, these cloud computing services are very centralized. The vast majority of Bitcoin and Lightning nodes running on such services are located in a handful of data centers in Virginia, Sunnyvale, Seattle, London, and Frankfurt. When the networks or data centers of these providers have service problems, it affects thousands of nodes on so-called "decentralized" networks.

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.

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.

While you can run a Lightning node (and even a Bitcoin node) on your laptop, it will become annoying quite fast. These programs consume your computer’s resources and need to run 24/7. Your user applications like your browser or your spreadsheet will be competing against the Lightning background services for your computer’s resources. In other words, your browser and other desktop workloads will be slowed down. And when your word-processing app freezes up your laptop, your Lightning node will go down as well, leaving you unable to receive transactions and potentially vulnerable to attacks. Furthermore, you should never turn off your laptop. All this combined together results in a setup that is not ideal. The same will apply to your daily-use personal desktop PC.

Instead, most users will choose to run a node on a dedicated computer. Fortunately, you don’t need a "server" class computer to do this. You can run a Lightning node on a single-board computer, such as a Raspberry Pi or on a mini PC (usually marketed as home theater PCs). These are simple computers which are commonly used as a home automation hub or a media server. They are relatively inexpensive when compared to a PC or a laptop. The advantage of a dedicated device as a platform for Lightning and Bitcoin nodes is that it can run continuously, silently, and unobtrusively on your home network, tucked behind your router or TV. No one will even know that this little box is actually part of a global banking system!

At a minimum, the following are required to run a Lightning node:

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 IBD (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.

For example, on Amazon’s cloud, we would use an 8–16 GB RAM, 8-core CPU (e.g., t3-large or m3.large) and faster 400 GB SSD (1000+ provisioned input/output operations per second [IOPS]) for the IBD, reducing its time to just 6-8 hours. Once that is complete, we would switch the server instance to a 2 GB RAM, 2-core CPU (e.g., t3.small) and storage to a general purpose 1 TB HDD. This will cost about the same as if you ran it on the slower server the entire time, but it will get you up and running in less than a day instead of having to wait almost a week for the IBD.

One of the most popular and complete "helpers" is RaspiBlitz (A RaspiBlitz node), 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 on GitHub.

In addition to a Bitcoin and Lightning node, RaspiBlitz can install a number of additional services, such as:

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 because 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.

In addition to a Bitcoin and Lightning node, myNode can optionally install a variety of additional services, such as:

Famous for their UX/UI (shown in The Umbrel web interface), Umbrel provides a very easy and accessible way to get your Bitcoin and Lightning node up and running in no time, especially for beginners. A very distinctive feature is that Umbrel utilizes Neutrino/SPV during the IBD so you can instantly start using your node. Once Bitcoin Core is fully synced in the background, it automatically switches over and disables SPV mode. Umbrel OS supports the Raspberry Pi 4 and can also be installed on any Linux-based OS or on a virtual machine on macOS or Windows. You can also connect any wallet that supports Bitcoin Core P2P, Bitcoin Core RPC, the Electrum protocol, or lndconnect.

There’s no need to wait for a rainy day—you can go right to Umbrel to learn more.

In addition to a Bitcoin and Lightning node, Umbrel introduced the Umbrel App Store, where you can easily install additional services, such as:

Umbrel is currently still in beta and is not considered secure.

While not initially designed as an installation "helper," the ecommerce 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 (4 GB recommended) to a mini PC or old laptop, desktop, or server.

BTCPay Server is a fully featured self-hosted, self-custody ecommerce platform that can be integrated with many ecommerce platforms, such as WordPress WooCommerce and others. The installation of the full node is only a step of the ecommerce platform installation. While originally developed as a feature-for-feature replacement of the BitPay commercial payment service and API, it has evolved past that to be a complete platform for BTC and Lightning services related to ecommerce. For many sellers or shops it is a one-shop turnkey solution to ecommerce.

In addition to a Bitcoin and Lightning node, BTCPay Server can also install a variety of services, including:

The number of additional services and features is growing rapidly, so the preceding list is only a small subset of what is available on the BTCPay Server platform.

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.

A second consideration is whether you will run an archival Bitcoin node with a full copy of the blockchain (some 350 GB in mid-2021) or a pruned blockchain that only keeps the most recent blocks. A pruned blockchain can save you some disk space, but you will still need to download the full blockchain at least once (during the IBD). Hence it won’t save you any network traffic. Using a pruned node to run a Lightning node is still an experimental capability and might not support all the functionality. However, many people are running a node like that successfully.

Finally, you also have the option of not running a Bitcoin node at all. Instead you can operate the LND Lightning node in "lightweight" mode, using the Neutrino Protocol to retrieve blockchain information from public Bitcoin nodes operated by others. Running like this means that you are taking resources from the Bitcoin network without offering any in return. Instead, you are offering your resources and contributing to the LN community. For smaller Lightning nodes this will generally reduce network traffic in comparison to running a full Bitcoin node.

Keep in mind that operating a Bitcoin node allows you to support other services, besides and on top of a Lightning node. These other services may require an archival (not pruned) Bitcoin node and often can’t run without a Bitcoin node. Consider up front what other services you may want to run now or in the future to make an informed decision on the type of Bitcoin node you select.

The bottom line for this decision is: if you can afford a disk larger than 500 GB, 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.

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.

Ultimately, most of the services can be run on any modern POSIX operating system, which includes macOS, Windows, and of course Linux. Your choice should be driven more by your familiarity and comfort with an operating system and your learning objectives. If you want to expand your knowledge and learn how to operate a Linux system, this is a great opportunity to do so with a specific project and a clear goal. If you just want to get a node up and running, go with what you know.

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.

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.

Background services usually run under a specific user account 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.

In addition, if you have connected an external drive, you will need to tell the operating system to relocate the user’s home directory to that drive. That’s because a service like Bitcoin Core will create files under the user’s home directory. If you are setting it up to download the full Bitcoin blockchain, these files will take up several hundred gigabytes. Here, we assume you have connected the external drive and it is located on the /external_drive/ path of the operating system.

On most Linux systems you can create a new user with the useradd command, like this:

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.

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 subdirectory 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.

Here’s an example of what a Bitcoin node’s startup script looks like, taken from the Bitcoin Core code repository:

As the root user, install the script by copying it into the systemd service folder /lib/systemd/system/ and then reload systemd:

You can now start and stop the service. Don’t start it yet, as we haven’t configured the Bitcoin node.

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 /etc/bitcoin/bitcoin.conf and /etc/lnd/lnd.conf, respectively.

These configuration files are text files with each line expressing one configuration option and its value. Default values are assumed for anything not defined in the configuration file. You can see what options can be set in the configuration in two ways. First, running the node application with a help argument will show the options that can be defined on the command line. These same options can be defined in the configuration file. Second, you can usually find an example configuration file, with all the default options, in the code repository of the software.

You can find one example of a configuration file in each of the Docker images we used in 04 Lightning Node Software. For example, the file code/docker/bitcoind/bitcoind/bitcoin.conf:

That particular configuration file configures Bitcoin Core for operation as a regtest node and provides a weak username and password for remote access, so you shouldn’t use it for your node configuration. However, it serves to illustrate the syntax of a configuration file and you can make adjustments to it in the Docker container to experiment with different options. See if you can use the bitcoind -help command to understand what each of the options does in the context of the Docker network we built in 04 Lightning Node Software.

Often, the defaults suffice, and with a few modifications your node software can be configured quickly. To get a Bitcoin Core node running with minimal customization, you only need four lines of configuration:

Even the txindex option is not strictly necessary, though it will ensure your Bitcoin node creates an index of all transactions, which is required for some applications. The txindex option is not required to run a Lightning node.

A c-lightning Lightning node running on the same server also requires only a few lines in the configuration:

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 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.

In a centralized service, your computer connects to the "big servers" of some corporation, and not vice versa. Your home internet connection is actually configured on the assumption that you are simply a consumer of services provided by others. But in a peer-to-peer system, every peer both consumes from and provides services to other nodes. If you’re running a Bitcoin or Lightning node at your home, you’re providing a service to other computers on the internet. Your internet service by default is not configured to allow you to run servers and may need some additional configuration to enable others to reach your node.

If you want to run a Bitcoin or Lightning node, you need to make it possible for other nodes on the internet to connect to you. That means enabling incoming TCP connections to the Bitcoin port (port 8333 by default) or Lightning port (port 9735 by default). While you can run a Bitcoin node without incoming connectivity, you can’t do that with a Lightning node. A Lightning node must be accessible to others from outside your network.

By default, your home internet router does not expect incoming connections from the outside, and in fact incoming connections are blocked. Your internet router IP address is the only externally accessible IP address, and all the computers you run inside your home network share that single IP address. This is achieved by a mechanism called Network Address Translation (NAT), which allows your internet router to act as an intermediary for all outbound connections. If you want to allow an inbound connection, you have to set up port forwarding, which tells your internet router that incoming connections on specific ports should be forwarded to specific computers inside the network. You can do this manually by changing your internet router configuration or, if your router supports it, through an automatic port forwarding mechanism called Universal Plug and Play (UPnP).

An alternative mechanism to port forwarding is to enable The Onion Router (Tor), which provides a kind of virtual private network overlay that allows incoming connections to an onion address. If you run Tor, you don’t need to do port forwarding or enable incoming connections to Bitcoin or Lightning ports. If you run your nodes using Tor, all traffic goes through Tor and no other ports are used.

Let’s look at different ways you can make it possible for others to connect to your node. We’ll look at these alternatives in order, from easiest to most difficult.

Securing an operating system is a vast topic that is beyond the scope of this book. However, we can establish some basic principles.

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.

Your Lightning node will expose a remote procedure call (RPC) API. This means that your node can be controlled remotely by commands sent to a specific TCP port. Access control to that RPC API is achieved by some form of user authentication. Depending on the type of Lightning node you set up, this will either be done by username/password authentication or by a mechanism called an authentication macaroon. As the name implies, a macaroon is a more sophisticated type of cookie. Unlike a cookie, it is cryptographically signed and can express a set of access capabilities.

For example, LND uses macaroons to grant access to the RPC API. By default, the LND software creates three macaroons with different levels of access, called admin, invoice, and readonly. Depending on which macaroon you copy and use in your RPC client, you either have read-only access, invoice access (which includes the read-only capabilities), or admin access, which gives you full control. There is also a macaroon bakery function in LND that can construct macaroons with any combination of capabilities with very fine-grained control.

If you use a username/password authentication model, make sure you select a long and random password. You will not have to type this password often, because it will be stored in the configuration files. You should therefore pick one that cannot be guessed. Many of the examples you will see include poorly chosen passwords, and often people copy these into their own systems, providing easy access to anyone. Don’t do that! Use a password manager to generate a long random alphanumeric password. Since certain special characters such as $?/!*\&%`"' can interfere with the command line, it is best to avoid these for passwords that will be used in a shell environment. To avoid problems, stick with long random alphanumeric passwords.

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.

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.

Even if you start small, as time passes you may still find you have a significant amount of money in a Lightning wallet. This is a typical scenario for store owners. If you use a Lightning node for an ecommerce operation, your wallet will likely receive funds often, but send funds rarely. You will therefore end up having two problems simultaneously. First, your channels will be imbalanced, with large local balances outweighing small remote balances. Secondly, you will have too much money in the wallet. Fortunately, you can also solve both of these problems simultaneously.

Let’s look at some of the solutions you can use to reduce the funds exposed in a hot wallet.

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 of these options in the next few sections.

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:

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.

There are a number of ways to do this, but most require some customization. You can use generic infrastructure monitoring or application monitoring tools, but you have to customize them specifically to query the Lightning node API to ensure the node is running, synchronized to the blockchain, and connected to channel peers.

Lightning.watch provides a specialized service that offers Lightning node monitoring. It uses a Telegram bot to notify you of any interruptions in service. This is a free service, though you can pay (over Lightning, of course) to get faster alerts.

Over time, we expect more third-party services to provide specialized Lightning node monitoring payable via micropayments. Perhaps such services and their APIs will become standardized and will one day be directly supported by Lightning node software.

Watchtowers are a mechanism for outsourcing the monitoring and penalty resolution of Lightning protocol violations.

As we mentioned in previous chapters, the Lightning protocol maintains security through a penalty mechanism. If one of your channel partners broadcasts an old commitment transaction, your node will need to exercise the revocation clause and broadcast a penalty transaction to avoid losing money. But if your node is down during the protocol violation, you might lose money.

To solve this problem, we can use one or more watchtowers to outsource the job of monitoring protocol violations and issuing penalty transactions. There are two parts to a watchtower setup: a watchtower server (or simply watchtower) that monitors the blockchain and a watchtower client that asks the watchtower server for this monitoring service.

Watchtower technology is still in the early stages of development and is not widely supported. However, in the following passage we list some experimental implementations that you can try.

LND software includes both a watchtower server and a watchtower client. You can activate the watchtower server by adding the following configuration options:

You can use LND’s watchtower client by activating it in the configuration and then using the command line to connect it to a watchtower server. The configuration is:

LND’s command-line client lncli shows the following options for managing the watchtower client:

c-lightning has the API hooks necessary for a watchtower client plug-in, though no such plug-in has been implemented yet.

Finally, a popular standalone watchtower server is The Eye of Satoshi (TEOS). It can be found on GitHub.

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.

You must choose channel partners carefully because your node’s ability to send payments depends on who your channel partners are and how well connected they are to the rest of the Lightning Network. You also want to have more than one channel to avoid being susceptible to a single point of failure. Since Lightning now supports multipart payments, you can split your initial funds into several channels and route bigger payments by combining their capacity. At the same time, avoid making your channels too small. Since you need to pay Bitcoin transaction fees to open and close a channel, the channel balance should not be so small that the on-chain fees consume a significant portion. It’s all about balance!

To summarize:

One way to find well-connected nodes is to open a channel to a popular merchant selling products on the Lightning Network. These nodes tend to be well funded and well connected. So, when you are ready to buy something online via Lightning, you can open a channel directly to the merchant’s node. The merchant’s node ID will be in the invoice you will receive when you try to buy something. That makes it easy.

Another way to find well-connected nodes is to use a Lightning Explorer (see Lightning Explorers) such as 1ML and browse the list of nodes sorted by channel capacity and number of channels. Don’t go for the biggest nodes, because that encourages centralization. Go for a node in the middle of the list so that you can help them grow. Another factor to consider might be the time span a node has been in operation. Nodes established for more than a year are likely to be more reputable and less risky than nodes that started operation a week ago.

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. There are three typical ways of getting inbound liquidity:

Creating inbound liquidity is challenging from both practical and user experience perspectives. Inbound liquidity does not happen automatically, so you have to find ways to build it for your node. This asymmetry of payment channels is also not intuitive. In most other payment systems, you get paid first (inbound) before you pay others (outbound).

The challenge of creating inbound liquidity is most noticeable if you are a merchant or sell your services for Lightning payments. In that case, you need to be vigilant to ensure that you have enough inbound liquidity to be able to continue to receive payments. What if there is a surge of buyers on your store, but they can’t actually pay you because there is no more inbound capacity?

In the future, these challenges can be partially mitigated by the implementation of dual-funded channels, which are funded from both sides and offer balanced inbound and outbound capacity. The burden could also be mitigated by more sophisticated autopilot software, which could request and pay for inbound capacity as needed.

Ultimately, Lightning users need to be strategic and proactive about channel management to ensure that sufficient inbound capacity is available to meet their needs.

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.

Some examples:

In the course of transacting and routing payments on Lightning, the combination of inbound and outbound capacities can become unbalanced.

For example, if one of your channel partners is frequently routing payments through your node, you will exhaust the inbound capacity on that channel, while also exhausting the outbound capacity on the outgoing channels. Once that happens, you can no longer route payments through that route.

There are many ways to rebalance channels, each with different advantages and disadvantages. One way is to use a submarine swap (e.g., Loop Out), as described previously in this chapter. Another way to rebalance is to simply wait for routed payments that flow in the opposite direction. If your node is well connected, when a specific route becomes exhausted in one direction, the same route becomes available in the opposite direction. Other nodes may "discover" that route in the opposite direction and start using it as part of their payment path, thereby rebalancing the funds again.

A third way to rebalance channels is to purposefully create a circular route that sends a payment from your node back to your node, via the Lightning Network. By sending a payment out on a channel with large local capacity and arranging the path so that it returns to your node on a channel with large remote capacity, both of those channels will become more balanced. An example of a circular route rebalancing strategy can be seen in Circular route rebalancing.

Circular rebalancing is supported by most Lightning node implementations and can be done on the command line or via one of the web management interfaces such as Ride The Lightning (see Ride The Lightning).

Channel rebalancing is a complex issue that is the subject of active research and covered in more detail in Rebalancing Channels.

Ride The Lightning (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 Shahana Farooqui and many other contributors. You can find the RTL software on GitHub.

Example RTL web interface shows an example screenshot of RTL’s web interface, as provided on the project repository.

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 on GitHub.

ThunderHub is 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.

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 Multisignature Scripts). 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 1 (K) of 10 (N) signers to spend a bitcoin amount locked in that address. This is similar to the scenario where 10 people have a copy of the same private key and any of them can independently spend it.

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.

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."

Payment channels in Lightning are based on a 2-of-2 multisig address, with the two channel partners as signers in the multisig. At this time, channels are funded only by one of the two channel partners: when you choose to "open" a channel, you deposit funds into the 2-of-2 multisig address with a transaction. Once that transaction is mined and the funds are in the multisig, you can’t get them back without cooperation from your channel partner, because you need their signature (also) to spend the bitcoin.

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 presigned 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.

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, René Pickhardt currently runs a Lightning Node (ln.rene-pickhardt.de) that is identified by the following node public key:

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 that 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.

Additionally, every node also advertises a network address where it can be reached, in one of several possible formats:

The network address identifier is written as Address:Port, which is consistent with international standards for network identifiers, as used, for example, on the web.

For example, René’s node with node public key 02a1ceb...45ea7b8 currently advertises its network address as the TCP/IP address:

Together, the node public key and network address are written in the following format, separated by an @ sign, as NodeID@Address:Port.

So the full identifier for René’s node would be:

The preceding identifier is often encoded in a QR code, making it easier for users to scan if they want to connect their own node to the specific node identified by that address.

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.

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.

Once Alice has connected to Bob’s node, their nodes are now directly connected peers.

The Lightning Peer Protocol for Channel Management is defined in 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 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 The channel establishment message flow.

In The channel establishment message flow, Alice and Bob’s nodes are represented by the vertical lines "A" and "B" on either side of the diagram. A time-sequence diagram like this shows time flowing downward, and messages flowing from one side to the other between the two communication peers. The lines are sloped down to represent the elapsed time needed to transmit each message, and the direction of the message is shown by an arrow at the end of each line.

The channel establishment involves three parts. First, the two peers communicate their capabilities and expectations, with Alice initiating a request through open_channel and Bob accepting the channel request through accept_channel.

Second, Alice constructs the funding and refund transactions (as we will see later in this section) and sends funding_created to Bob. Another name for the "refund" transaction is a "commitment" transaction, as it commits to the current distribution of balances in the channel. Bob responds by sending back the necessary signatures with funding_signed. This interaction is the basis for the cryptographic protocol to secure the channel and prevent theft. Alice will now broadcast the funding transaction (on-chain) to establish and anchor the payment channel. The transaction will need to be confirmed on the Bitcoin blockchain.

Once the transaction has sufficient confirmations (as defined by the minimum_depth field in the accept_channel message), Alice and Bob exchange funding_locked messages, and the channel enters normal operating mode.

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 to allow us to construct the funding transaction (and the refund transaction as described subsequently).

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.

Alice’s node constructs a multisignature script as shown here:

Note that, in practice, the funding keys are deterministically sorted (using lexicographical order of the serialized compressed form of the public keys) before being placed in the witness script. By agreeing to this sorted order ahead of time, we ensure that both parties will construct an identical funding transaction output, which is signed by the exchanged commitment transaction signature.

This script is encoded as a Pay-to-Witness-Script-Hash (P2WSH) Bitcoin address, which looks something like this:

Alice’s node can now construct a funding transaction, sending the amount agreed on with Bob (funding_satoshis) to the 2-of-2 multisig address. Let’s assume that funding_satoshis was 140,000 and Alice is spending a 200,000 satoshi output and creating 60,000 satoshi change. The transaction will look something like Alice constructs the funding transaction.

Alice does not broadcast this transaction because doing so would put her 140,000 satoshi at risk. Once spent to the 2-of-2 multisig, there is no way for Alice to recover her money without Bob’s signature.

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 because 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.

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.

Consider the legal construct of a prenuptial agreement, also known as a "prenup." When two people enter into a marriage their money is bound together by law (depending on jurisdiction). Prior to entering into the marriage, they can sign an agreement that specifies how to separate their assets if they dissolve their marriage through divorce.

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.

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 because it commits both channel partners to distributing the channel balance fairly. Since Alice funded the channel on her own, she gets the entire balance, and both Alice and Bob commit to refunding Alice with this transaction.

In practice, it is a bit more complicated as we will see in subsequent chapters, but for now let’s keep things simple and assume it looks like 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.

So now, Alice has constructed the two transactions shown in Alice also constructs the refund transaction. But you might be wondering how this is 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?

The refund transaction is not yet a valid transaction. For it to become a valid transaction two things must happen:

Notice how Alice has calculated 6da3c2...387710 as the funding transaction hash? If and when the funding transaction is broadcast, that hash will be recorded as the transaction ID of the funding transaction. Therefore, the 0 output of the funding transaction (the 2-of-2 address output) will then be referenced as output ID 6da3c2...387710:0. The refund transaction can be constructed to spend that funding transaction output even though it doesn’t exist yet, because Alice knows what its identifier will be once confirmed.

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.

Alice has to depend on the transaction ID of the funding transaction being known before confirmation. But before the introduction of Segregated Witness (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 prior to SegWit, this problem made it difficult to implement indefinite lifetime payment channels securely.

If Bob could modify Alice’s funding transaction before it was confirmed, and produce a replica that had a different transaction ID, Bob could make Alice’s refund transaction invalid and hijack her bitcoin. Alice would be at Bob’s mercy to get a signature to release her funds and could easily be blackmailed. Bob couldn’t steal the funds, but he could prevent Alice from getting them back.

The introduction of SegWit made unconfirmed transaction IDs immutable from the point of view of third parties, meaning that Alice could be sure that the transaction ID of the funding transaction would not change. As a result, Alice can be confident that if she gets Bob’s signature on the refund transaction, she has a way to recover her money. She now has a way to implement the Bitcoin equivalent of a "prenup" before locking her funds into the multisig.

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.

Alice now sends the funding transaction to the Bitcoin network so that it can be mined into the blockchain. Both Alice and Bob will be watching for this transaction and waiting for minimum_depth confirmations (e.g., six confirmations) on the Bitcoin blockchain.

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.

Therefore, all Alice and Bob have to do is create and sign a transaction that spends the 2-of-2 multisig to two outputs paying Alice and Bob their corresponding balances. We call this updated transaction a commitment transaction.

Alice and Bob operate the payment channel by advancing the channel state through a series of commitments. Each commitment updates the balances to reflect payments that have flowed across the channel. Both Alice and Bob can initiate a new commitment to update the channel.

In Multiple commitment transactions we see several commitment transactions.

The first commitment transaction shown in Multiple commitment transactions is the refund transaction that Alice constructed before funding the channel. In the diagram, this is Commitment #0. After Alice pays Bob 70,000 satoshis, the new commitment transaction (Commitment #1) has two outputs paying Alice and Bob their respective balances. We have included two subsequent commitment transactions (Commitment #2 and Commitment #3) which represent Alice paying Bob an additional 10,000 satoshis and then 20,000 satoshis, respectively.

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.

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?

It is indeed! In fact, we rely on Bitcoin’s ability to prevent a double-spend to make Lightning work. No matter how many commitment transactions Alice and Bob construct and sign, only one of them can actually get confirmed.

As long as Alice and Bob hold these transactions and don’t broadcast them, the funding output is unspent. But if a commitment transaction is broadcast and confirmed, it will spend the funding output. If Alice or Bob attempts to broadcast more than one commitment transaction, only one of them will be confirmed and the others will be rejected as attempted (and failed) double-spends.

If more than one commitment transaction is 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.

Let’s look more carefully at the commitment transactions in Multiple commitment transactions. 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 Commitment #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 (see Bitcoin Protocol and Bitcoin Script Innovation).

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?

The solution used in Lightning is another example of a fairness protocol. Instead of trying to control the ability to broadcast a transaction, there is a built-in penalty mechanism that ensures it is not in the best interest of a would-be cheater to transmit an old commitment transaction. They can always broadcast it, but they will most likely lose money if they do so.

There are three elements that make up the Lightning protocol’s revocation and penalty mechanism:

Let’s look at these three elements in turn.

Alice and Bob hold slightly different commitment transactions. Let’s look specifically at Commitment #2 from Multiple commitment transactions, in more detail in Commitment transaction #2.

Alice and Bob hold two different variations of this transaction, as illustrated in Asymmetric commitment transactions.

By convention, within the Lightning protocol, we refer to the two channel partners as self (also known as local) and remote, depending on which side we’re looking at. The outputs that pay each channel partner are called to_local and to_remote, respectively.

In Asymmetric commitment transactions we see that Alice holds a transaction that pays 60,000 satoshis to_self (can be spent by Alice’s keys), and 80,000 satoshis to_remote (can be spent by Bob’s keys).

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).

Using asymmetric transactions allows the protocol to easily ascribe blame to the cheating party. An invariant that the broadcasting party must always wait ensures that the "honest" party has time to refute the claim and revoke their funds. This asymmetry is manifested in the form of differing outputs for each side: the to_local output is always timelocked and can’t be spent immediately, whereas the to_remote output is not timelocked and can be spent immediately.

In the commitment transaction held by Alice, for example, the to_local output that pays her is timelocked for 432 blocks, whereas the to_remote output that pays Bob can be spent immediately (see Asymmetric and delayed commitment transactions). Bob’s commitment transaction for Commitment #2 is the mirror image: his own (to_local) output is timelocked and Alice’s to_remote output can be spent immediately.

The delay is there for one reason: to allow the remote party to exercise a penalty option if an old (revoked) commitment should be broadcast by the other channel partner. Let’s look at the revocation keys and penalty option next.

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 finds 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 The Shutdown Message).

As we discussed previously, the word "revocation" is a bit misleading because it implies that the "revoked" transaction cannot be used.

In fact, the revoked transaction can be used, but if it is used, and it has been revoked, then one of the channel partners can take all of the channel funds by creating a penalty transaction.

The way this works is that the to_local output is not only timelocked, but it also has two spending conditions in the script: it can be spent by self after the timelock delay or it can be spent by remote immediately with a revocation key for this commitment.

So, in our example, each side holds a commitment transaction that includes a revocation option in the to_local output, as shown in Asymmetric, delayed, and revocable commitments.

The structure of the commitment_signed message is defined in BOLT #2: Peer Protocol, commitment_signed, and shown here:

Alice’s commitment_signed message gives Bob the signature needed (Alice’s part of the 2-of-2) for a new commitment transaction.

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.

The revoke_and_ack message is defined in BOLT #2: Peer Protocol, revoke_and_ack, and shown here:

Let’s look at this interaction between Alice and Bob more closely.

Alice is giving Bob the means to create a new commitment. In return, Bob is revoking the old commitment to assure Alice that he won’t use it. Alice can only trust the new commitment if she has the revocation key to punish Bob for publishing the old commitment. From Bob’s perspective, he can safely revoke the old commitment by giving Alice the keys to penalize him, because he has a signature for a new commitment.

When Bob responds with revoke_and_ack, he gives Alice a per_commitment_secret. This secret can be used to construct the revocation signing key for the old commitment, which allows Alice to seize all channel funds by exercising a penalty.

As soon as Bob has given this secret to Alice, he must not ever broadcast that old commitment. If he does, he will give Alice the opportunity to penalize him by taking the funds. Essentially, Bob is giving Alice the ability to hold him accountable for broadcasting an old commitment, and in effect he has revoked his ability to use that old commitment.

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.

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.

To more easily allow both sides to keep track of the commitment numbers of the passed revoke commitments, each commitment actually encodes the number of the commitment within the lock time and sequence fields in a transition. Within the protocol, this special encoding is referred to as state hints. Assuming a party knows the current commitment number, they’re able to use the state hints to easily recognize if a broadcasted commitment was a revoked one, and if so, which commitment number was breached, as that number is used to easily look up which revocation secret should be used in the revocation secret tree (shachain).

Rather than encode the state hint in plain sight, an obfuscated state hint is used in its place. This obfuscation is achieved by first XORing the current commitment number with a set of random bytes generated deterministically using the funding public keys of both sides of the channel. A total of 6 bytes across the lock time and sequence (24 bits of the locktime and 24 bits of the sequence) are used to encode the state hint within the commitment transaction, so 6 random bytes are needed to use for XORing. To obtain these 6 bytes, both sides obtain the SHA-256 hash of the initiator’s funding key concatenated to the responder’s funding key. Before encoding the current commitment height, the integer is XORed with this state hint obfuscator, and then encoded in the lower 24 bits of the locktime, and the upper 64 bits of the sequence.

Let’s review our channel between Alice and Bob and show a specific example of a penalty transaction. In Revoked and current commitments we see the four commitments on Alice and Bob’s channel. Alice has made three payments to Bob:

With each commitment, Alice has revoked the previous (older) commitment. The current state of the channel and the correct balance is represented by Commitment #3. All previous commitments have been revoked, and Bob has the keys necessary to issue penalty transactions against them, in case Alice tries to broadcast one of them.

Alice might have an incentive to cheat because all the previous commitment transactions would give her a higher proportion of the channel balance than she is entitled to. Let’s say for example that Alice tried to broadcast Commitment #1. That commitment transaction would pay Alice 70,000 satoshis and Bob 70,000 satoshis. If Alice was able to broadcast and spend her to_local output, she would effectively be stealing 30,000 satoshis from Bob by rolling back her last two payments to Bob.

Alice decides to take a huge risk and broadcast the revoked Commitment #1, to steal 30,000 satoshis from Bob. In Alice cheating we see Alice’s old commitment that she broadcasts to the Bitcoin blockchain.

As you can see, Alice’s old commitment has two outputs, one paying herself 70,000 satoshis (to_local output) and one paying Bob 70,000 satoshis. Alice can’t yet spend her 70,000 to_local output because it has a 432 block (3 day) timelock. She is now hoping that Bob doesn’t notice for three days.

Unfortunately for Alice, Bob’s node is diligently monitoring the Bitcoin blockchain and sees an old commitment transaction broadcast and (eventually) confirmed on-chain.

Bob’s node will immediately broadcast a penalty transaction. Since this old commitment was revoked by Alice, Bob has the per_commitment_secret that Alice sent him. He uses that secret to construct a signature for the revocation_pubkey. While Alice has to wait for 432 blocks, Bob can spend both outputs immediately. He can spend the to_remote output with his private keys because it was meant to pay him anyway. He can also spend the output meant for Alice with a signature from the revocation key. His node broadcasts the penalty transaction shown in 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!

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.

Channel closing starts with one of the two channel partners sending the shutdown message. The contents of this message are shown here:

Let’s say Alice sends the shutdown message to Bob to close their channel. Alice will specify a Bitcoin script that corresponds to the Bitcoin address of her wallet. She’s telling Bob: let’s make a closing transaction that pays my balance to this wallet.

Bob will respond with his own shutdown message indicating that he agrees to cooperatively close the channel. His shutdown message includes the script for his wallet address.

Now both Alice and Bob have each other’s preferred wallet address, and they can construct identical closing transactions to settle the channel balance.

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.

The funder of the channel (Alice in our example) starts by sending a closing_signed message to Bob. This message proposes a transaction fee for the on-chain transaction, and Alice’s signature (the 2-of-2 multisig) for the closing transaction. The closing_signed message is shown here:

When Bob receives this, he can reply with a closing_signed message of his own. If he agrees with the fee, he simply returns the same proposed fee and his own signature. If he disagrees, he must propose a different fee_satoshis fee.

This negotiation may continue with back-and-forth closing_signed messages until the two channel partners agree on a fee.

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 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.

Typically the addresses used in this cooperative close transaction are generated freshly for each channel being closed. However, it’s also possible for both sides to lock in a "delivery" address to be used to send their cooperatively settled funds to. Within the TLV namespace of both the open_channel and accept_channel messages, both sides are free to specify an "up-front shutdown script." Commonly, this address is derived from keys that reside in cold storage. This practice serves to increase the security of channels: if a channel partner is somehow hacked, then the hacker isn’t able to cooperatively close the channel using an address they control. Instead, the uncompromised honest channel partner will refuse to cooperate on a channel closure if the specified up-front shutdown address isn’t used. This feature effectively creates a "closed loop," restricting the flow of funds out of a given channel.

Alice broadcasts a transaction shown in The cooperative close transaction to close the channel.

As soon as this closing transaction is confirmed on the Bitcoin blockchain, the channel is closed. Now, Alice and Bob can spend their outputs as they please.

Bitcoin Script is flexible enough that there are dozens of ways to implement a fairness protocol that has the properties of atomicity, trustless operation, and multihop security. Choosing a specific implementation is dependent on certain trade-offs among privacy, efficiency, and complexity.

The fairness protocol for routing used in the Lightning Network today is called a hash time-locked contract (HTLC). HTLCs use a hash preimage as the secret that unlocks a payment, as we saw in the gold coin example in this chapter. The recipient of a payment generates a random secret number and calculates its hash. The hash becomes the condition of payment, and once the secret is revealed, all the participants can redeem their incoming payments. HTLCs offer atomicity, trustless operation, and multihop security.

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.

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.

The mere fact that any transaction can be taken on-chain at any time is precisely the reason that all those transactions can be kept off-chain. If you know you have recourse, you can continue to cooperate with the other participants and avoid the need for on-chain settlement and extra fees.

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.

In our gold coin example, Alice had a contract enforced by escrow like this:

Wow, that looks complicated! Don’t worry though, we will take it one step at a time and simplify it.

The Bitcoin Script currently used in the Lightning Network is quite complex because it is optimized for on-chain space efficiency, which makes it very compact but difficult to read.

In the following sections, we will focus on the main elements of the script and present simplified scripts that are slightly different from what is actually used in Lightning.

The main part of the HTLC is in line 10 of HTLC implemented in Bitcoin Script (BOLT #3). Let’s build it up from scratch!

The core of an HTLC is the hash, where payment can be made if the recipient knows the payment preimage. Alice locks the payment to a specific payment hash, and Bob has to present a payment preimage to claim the funds. The Bitcoin system can verify that Bob’s payment preimage is correct by hashing it and comparing the result to the payment hash that Alice used to lock the funds.

This part of an HTLC can be implemented in Bitcoin Script as follows:

Alice can create a transaction output that pays, 50,200 satoshi with a locking script above, replacing <H> with the hash value 0575...f6b3 provided by Dina. Then, Alice can sign this transaction and offer it to Bob:

Bob can’t spend this HTLC until he knows Dina’s secret, so spending the HTLC is conditional on Bob’s fulfillment of the payment all the way to Dina.

Once Bob has Dina’s secret, Bob can spend this output with an unlocking script containing the secret preimage value R.

The unlocking script combined with the locking script would produce:

The Bitcoin Script engine would evaluate this script as follows:

Alice will now extend the HTLC across the network so that it reaches Dina.

In Propagating the HTLC across the network, we see the HTLC propagated across the network from Alice to Dina. Alice has given Bob an HTLC for 50,200 satoshi. Bob can now create an HTLC for 50,100 satoshi and give it to Chan.

Bob knows that Chan can’t redeem Bob’s HTLC without broadcasting the secret, at which point Bob can also use the secret to redeem Alice’s HTLC. This is a really important point because it ensures end-to-end atomicity of the HTLC. To spend the HTLC, one needs to reveal the secret, which then makes it possible for others to spend their HTLC also. Either all the HTLCs are spendable, or none of the HTLCs are spendable: atomicity!

Because Alice’s HTLC is 100 satoshi more than the HTLC Bob gave to Chan, Bob will earn 100 satoshi as a routing fee if this payment completes.

Bob isn’t taking a risk and isn’t trusting Alice or Chan. Instead, Bob is trusting that a signed transaction together with the secret will be redeemable on the Bitcoin blockchain.

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.

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 Dina settles Chan’s HTLC off-chain we see Dina giving the secret to Chan, thereby fulfilling the HTLC.

Notice that Dina’s channel balance goes from 50,000 satoshi to 100,000 satoshi. Chan’s channel balance is reduced from 200,000 satoshi to 150,000 satoshi. The channel capacity hasn’t changed, but 50,000 has moved from Chan’s side of the channel to Dina’s side of the channel.

Chan now has the secret and has paid Dina 50,000 satoshi. He can do this without any risk, because the secret allows Chan to redeem the 50,100 HTLC from Bob. Chan has the option to commit that HTLC on-chain and spend it by revealing the secret on the Bitcoin blockchain. But, like Dina, he’d rather avoid transaction fees. So instead, he sends the secret to Bob so they can update their channel balances to reflect a 50,100 satoshi Lightning payment from Bob to Chan. In Chan settles Bob’s HTLC off-chain we see Chan sending the secret to Bob and receiving a payment in return.

Chan has paid Dina 50,000 satoshi, and received 50,100 satoshi from Bob. So Chan has 100 satoshi more in his channel balances, which he earned as a routing fee.

Bob now has the secret too. He can use it to spend Alice’s HTLC on-chain. Or, he can avoid transaction fees by settling the HTLC in the channel with Alice. In Bob settles Alice’s HTLC off-chain we see that Bob sends the secret to Alice and they update the channel balance to reflect a 50,200 satoshi Lightning payment from Alice to Bob.

Bob has received 50,200 satoshi from Alice and paid 50,100 satoshi to Chan, so he has an extra 100 satoshi in his channel balances from routing fees.

Alice receives the secret and has settled the 50,200 satoshi HTLC. The secret can be used as a receipt to prove that Dina got paid for that specific payment hash.

The final channel balances reflect Alice’s payment to Dina and the routing fees paid at each hop, as shown in Channel balances after the payment.

There’s a catch. Did you notice it?

If Alice, Bob, and Chan create the HTLCs as shown in Channel balances after the payment, they face a small but not insignificant risk of loss. Any of those HTLCs can be redeemed (spent) by anyone who knows the secret. At first only Dina knows the secret. Dina is supposed to only spend the HTLC from Chan. But Dina could spend all three HTLCs at the same time, or even in a single spending transaction! After all, Dina knows the secret before anyone else. Similarly, once Chan knows the secret, he is only supposed to spend the HTLC offered by Bob. But what if Chan also spends Alice’s offered HTLC?

This is not trustless! It fails the most important security feature. We need to fix this.

The HTLC script must have an additional condition that binds each HTLC to a specific recipient. We do this by requiring a digital signature that matches the public key of each recipient, thereby preventing anyone else from spending that HTLC. Since only the designated recipient has the ability to produce a digital signature matching that public key, only the designated recipient can spend that HTLC.

Let’s look at the scripts again with this modification in mind. Alice’s HTLC for Bob is modified to include Bob’s public key and the OP_CHECKSIG operator.

Here’s the modified HTLC script:

To redeem this HTLC, Bob has to present an unlocking script that includes a signature from Bob’s private key as well as the secret payment preimage, like this:

The unlocking and locking scripts are combined and evaluated by the scripting engine, as follows:

As you can see, this is slightly more complicated, but now we have fixed the HTLC and made sure only the intended recipient can spend it.

Let’s look at the first part of the HTLC script so far:

If we look at this in the preceding symbolic representation, it looks like the OP_ operators take up the most space. But that’s not the case. Bitcoin Script is encoded in binary, with each operator representing one byte. Meanwhile, the <H> value we use as a placeholder for the payment hash is a 32-byte (256-bit) value. You can find a listing of all the Bitcoin Script operators and their binary and hex encoding in Bitcoin Wiki: Script, or in Appendix D, "Transaction Script Language Operators, Constants, and Symbols," in Mastering Bitcoin.

Represented in hexadecimal, our HTLC script would look like this:

In hexadecimal encoding, OP_SHA256 is a8 and OP_EQUALVERIFY is 88. The total length of this script is 34 bytes, of which 32 bytes are the hash.

As we’ve mentioned previously, any participant in the Lightning Network should be able to take an off-chain transaction they hold and put it on-chain if they need to enforce their claim to funds. To take a transaction on-chain, they’d have to pay transaction fees to the miners, and these fees are proportional to the size, in bytes, of the transaction.

Therefore, we want to find ways to minimize the on-chain "weight" of transactions by optimizing the script as much as possible. One way to do that is to add another hash function on top of the SHA-256 algorithm, one that produces smaller hashes. The Bitcoin Script language provides the OP_HASH160 operator that "double hashes" a preimage: first the preimage is hashed with SHA-256, and then the resulting hash is hashed again with the RIPEMD160 hash algorithm. The hash resulting from RIPEMD160 is 160 bits or 20 bytes—​much more compact. In Bitcoin Script this is a very common optimization that is used in many of the common address formats.

So, let’s use that optimization instead. Our SHA-256 hash is 057596...69f6b3. Putting that through another round of hashing with RIPEMD160 gives us the result:

Alice can calculate the RIPEMD160 hash of the payment hash that Dina provides and use the shorter hash in her HTLC, as can Bob and Chan!

Encoded in hex, this is:

Where OP_HASH160 is a9 and OP_EQUALVERIFY is 88. This script is only 22 bytes long! We’ve saved 12 bytes from every transaction that redeems an HTLC on-chain.

With that optimization, you now see how we arrive at the HTLC script shown in line 10 of HTLC implemented in Bitcoin Script (BOLT #3):

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.

What happens if someone goes offline or fails to cooperate? What happens if the payment cannot succeed?

We need to ensure a way to "fail gracefully," because occasional routing failures are inevitable. There are two ways to fail: cooperatively and with a time-locked refund.

Cooperative failure is relatively simple: the HTLC is unwound by every participant in the route, removing the HTLC output from their commitment transactions without changing the balance. We’ll look at how that works in detail in 09 Channel Operation and Payment Forwarding.

Let’s look at how we can reverse an HTLC without the cooperation of one or more participants. We need to make sure that if one of the participants does not cooperate, the funds are not simply locked in the HTLC forever. This would give someone the opportunity to ransom the funds of another participant: "I’ll leave your funds tied up forever if you don’t pay me ransom."

To prevent this, every HTLC script includes a refund clause that is connected to a timelock. Remember our original escrow contract? "Bob has 24 hours to show the secret after the contract is signed. If Bob does not provide the secret by this time, Alice’s deposit will be refunded."

The time-locked refund is an important part of the script that ensures atomicity, so that the entire end-to-end payment either succeeds or fails gracefully. There is no "half paid" state to worry about. If there is a failure, every participant can either unwind the HTLC cooperatively with their channel partner or put the time-locked refund transaction on-chain unilaterally to get their money back.

To implement this refund in Bitcoin Script, we use a special operator O⁠P⁠_⁠C⁠H⁠E⁠C⁠K⁠L⁠O⁠C⁠K⁠T⁠I⁠M⁠E​V⁠E⁠R⁠I⁠F⁠Y also known OP_CLTV for short. Here’s the script, as seen previously in line 13 of HTLC implemented in Bitcoin Script (BOLT #3):

The OP_CLTV operator takes an expiry time defined as the block height after which this transaction is valid. If the transaction timelock is not set the same as <cltv_expiry>, the evaluation of the script fails and the transaction is invalid. Otherwise, the script continues without any output to the stack. Remember, the VERIFY suffix means this operator does not output TRUE or FALSE but instead either halts/fails or continues without stack output.

Essentially, the OP_CLTV acts as a "gatekeeper" preventing the script from proceeding any further if the <cltv_expiry> block height has not been reached on the Bitcoin blockchain.

The OP_DROP operator simply drops the topmost item on the script stack. This is necessary in the beginning because there is a "leftover" item from the previous script lines. It is necessary after OP_CLTV to remove the <cltv_expiry> item from the top of the stack because it is no longer necessary.

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 Signature Binding: Preventing Theft of HTLCs, 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.

As the HTLCs are extended from Alice to Dina, the time-locked refund clause in each HTLC has a different cltv_expiry value. We will see this in more detail in 10 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 timelocks for each hop is called the cltv_expiry_delta, and is set by each node and advertised to the network, as we will see in 11 Gossip and the Channel Graph.

For example, Alice sets the refund timelock on the first HTLC to a block height of current + 500 blocks ("current" being the current block height). Bob would then set the timelock cltv_expiry on the HTLC to Chan to current + 450 blocks. Chan would set the timelock to current + 400 blocks from the current block height. This way, Chan can get a refund on the HTLC he offered to Dina before Bob gets a refund on the HTLC he offered to Chan. Bob can get a refund of the HTLC he offered to Chan before Alice can get a refund for the HTLC she offered to Bob. The decrementing timelock prevents race conditions and ensures the HTLC chain is unwound backward, from the destination toward the origin.

The message flow between Alice and Bob (and also between any pair of channel partners) is shown in The message flow for HTLC commitment between channel partners.

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 10 Onion Routing.

To add the HTLC, Alice starts the flow we saw in The message flow for HTLC commitment between channel partners by sending the update_add_htlc message to Bob.

Alice sends the update_add_HTLC Lightning message to Bob. This message is defined in BOLT #2: Peer Protocol, update_add_HTLC, and is shown in Example 9-1.

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.

We’ve already seen the basic structure of an HTLC in 08 Routing on a Network of Payment Channels. The complete script of an offered HTLC is defined in BOLT #3: Transactions, Offered HTLC Output and is shown in Offered HTLC output script.

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 "backward").

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 Bob’s new commitment with an HTLC output.

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 07 Payment Channels previously. As a reminder, that message is shown in The revoke_and_ack message.

Bob sends the per_commitment_secret that allows Alice to construct a revocation key to build a penalty transaction spending Bob’s old commitment. Once Bob has sent this, he can never publish "Commitment #2" without risking a penalty transaction and losing all his money. So, the old commitment is effectively revoked.

Bob has effectively moved the channel state forward, as shown in Bob has revoked the old commitment.

Despite the fact that Bob has a new (signed) commitment transaction and an HTLC output inside, he cannot consider his HTLC as being set up successfully.

He first needs to have Alice revoke her old commitment, because otherwise, Alice can roll back her balance to 70,000 satoshis. Bob needs to make sure that Alice also has a commitment transaction containing the HTLC and has revoked the old commitment.

That is why, if Bob is not the final recipient of the HTLC funds, he should not forward the HTLC yet by offering an HTLC on the next channel with Chan.

Alice has constructed a mirror-image new commitment transaction containing the new HTLC, but it is yet to be signed by Bob. We can see it in Alice’s new commitment with an HTLC output.

As we described in 07 Payment Channels, Alice’s commitment is the mirror image of Bob’s, as it contains the asymmetric, delayed, revocable construct for revocation and penalty enforcement of old commitments. Alice’s 19,800 satoshi balance (after deducting the HTLC value), is delayed and revocable. Bob’s 70,000 satoshi balance is immediately redeemable.

Next, the message flow for commitment_signed and revoke_and_ack is now repeated, but in the opposite direction. Bob sends commitment_signed to sign Alice’s new commitment, and Alice responds by revoking her old commitment.

For completeness sake, let’s quickly review the commitment transactions as this round of commitment/revocation happens.

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 preimage of the payment hash). Therefore, Dina can fulfill the HTLC with Chan immediately!

Dina can settle the HTLC by sending an update_ful&#x2060;fill_&#x200b;htlc message to Chan. The update_fulfill_htlc message is defined in BOLT #2: Peer Protocol, update_fulfill_htlc and is shown here:

It’s a really simple message:

When Chan receives this message, he will immediately check if the payment_preimage (let’s call it R) produces the payment hash (let’s call it H) in the HTLC that he offered to Dina. He hashes it like this:

If the result H matches the payment hash in the HTLC, Chan can do a little dance of celebration. This long-awaited secret can be used to redeem the HTLC, and will be passed back along the chain of payment channels all the way to Alice, resolving every HTLC that was part of this payment to Dina.

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 preimage has propagated all the way back to Alice.

When Bob sends the update_fulfill_htlc to Alice, it will contain the same payment_preimage that Dina selected for her invoice. That payment_preimage has traveled backward 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!

Alice will also validate the payment_preimage received from Bob. She will compare its hash to the HTLC payment hash in the HTLC she offered Bob. She will also find this preimage matches the hash in Dina’s invoice. This is proof that Dina was paid.

The message flow between Alice and Bob is shown in The HTLC fulfillment message flow.

Both Alice and Bob can now remove the HTLC from the commitment transactions and update their channel balances.

They create new commitments (Commitment #4), as shown in The HTLC is removed and balances are updated in new commitments.