[[routing_on_a_network_of_payment_channels]] [[routing]] [[routing_htlcs]] == Routing on a Network of Payment channels In this chapter we will finally unpack how payment channels can be connected to form a _network of payment channels_ via a process called _routing_. Specifically, we will look at the first part of the routing layer, the Atomic & Trustless Multihop Payment protocol. This is highlighted by a double outline in the protocol suite, shown in <>: [[LN_protocol_routing_highlight]] .The Lightning Network Protocol Suite image::images/LN-protocol-routing-highlight.png["The Lightning Network Protocol Suite"] === Routing a payment In this section we will examine routing from the perspective of Dina, a gamer who receives donations from her fans while she streams her game sessions. The innovation of routed payment channels allows Dina to receive tips without maintaining a separate channel with every one of her fans who want to tip her. As long as there exists a path of well-funded channels from that viewer to Dina, she will be able to receive payment from that fan. In <> we see a possible network layout created by various payment channels between Lightning nodes. Everyone in this diagram can send Dina a payment by constructing a path. Imagine "Fan 4" wants to send Dina a payment, do you see the path that could allow that to happen? Fan 4 could route a payment to Dina via Fan 3, Bob, and Chan. Similarly, Alice could route a payment to Dina via Bob and Chan. [[dina_routing_diagram]] .Fans connected indirectly to Dina on the Lightning Network image::images/dina-routing-diagram.png["Fans connected indirectly to Dina on the Lightning Network"] The nodes along the path from the fan to Dina are intermediaries and called "routing nodes" in the context of routing a payment. There is no functional difference between the "routing nodes" and the nodes operated by Dina's fans. Any Lightning node is capable of routing payments across its payment channels. Importantly, the routing nodes are unable to steal the funds while routing a payment from a fan to Dina. Furthermore, routing nodes cannot lose money while participating in the routing process. Routing nodes can charge a routing fee for acting as an intermediary, although they don't have to and may choose to route payments for free. Another important detail is that due to the use of onion routing, intermediary nodes are only explicitly aware of the one node preceding them and the one node following them in the route. They will not necessarily know who is the sender and recipient of the payment. This enables fans to use intermediary nodes to pay Dina, without leaking private information and without risking theft. This process of connecting a series of payment channels with end-to-end security, and the incentive structure for nodes to _forward_ payments, is one of the key innovations of the Lightning Network. In this chapter, we'll dive into the mechanism of routing in the Lightning Network, detailing the precise manner in-which payments flow through the network. First, we will clarify the concept of "routing" and compare it to that of "path finding", as these are often confused and used interchangeably. Next, we will construct the fairness protocol: An atomic, trustless, multihop protocol used to route payments. To demonstrate how this fairness protocol works, we will be using a physical equivalent of transferring gold coins between 4 people. Finally, we will look at the atomic, trustless, multihop protocol implementation currently used in the Lightning Network, which is called a Hash Time-Locked Contract (HTLC). === Routing vs. Path Finding It's important to note that we separate the concept of _routing_ from the concept of _path finding_. These two concepts are often confused and the term "routing" is often used to describe both concepts. Let's remove the ambiguity, before we proceed any further. Path Finding, which is covered in <> is the process of finding and choosing a contiguous path made of payment channels which connects the sender A to the recipient B. The sender of a payment does the path finding, by examining the _channel graph_ which they have assembled from channel announcements gossiped by other nodes. Routing refers to the series of interactions across the network that attempt to forward a payment from some point A to another point B, across the path previously selected by path finding. Routing is the active process of sending a payment on a path, which involves the cooperation of all the intermediary nodes along that path. An important rule of thumb is that it's possible for a _path_ to exist between Alice and Bob (perhaps even more than one), yet there may not be an active _route_ on which to send the payment. One example is the scenario where all the nodes connecting Alice and Bob are currently off-line. In this example, one can examine the _channel graph_ and connect a series of payment channels from Alice to Bob, hence a _path_ exists. However, as the intermediary nodes are offline, the payment cannot be sent and so no _route_ exists. === Creating a network of payment channels Before we dive into the concept of an atomic trustless multihop payment, let's work through an example. Let's return to Alice who, in previous chapters, purchased a coffee from Bob with whom she has an open channel. Now Alice is watching a live stream from Dina, the gamer, and wants to send Dina a tip of 50,000 satoshis via the Lightning Network. But Alice has no direct channel with Dina. What can Alice do? Alice could open a direct channel with Dina, however that would require liquidity and on-chain fees which could be more than the value of the tip itself. Instead, Alice can use her existing open channels to send a tip to Dina _without_ the need to open a channel directly with Dina. This is possible, as long as there exists some path of channels from Alice to Dina with sufficient capacity to route the tip. As you can see in <>, Alice has an open channel with Bob, the coffee shop owner. Bob, in turn, has an open channel with the software developer Chan who helps him with the point of sale system he uses in his coffee shop. Chan is also the owner of a large software company which develops the game that Dina plays, and they already have an open channel which Dina uses to pay for the game's license and in-game items. [[routing_network]] .A network of payment channels between Alice and Dina image::images/routing-network.png["A network of payment channels between Alice and Dina"] It's possible to trace a _path_ from Alice to Dina that uses Bob and Chan as intermediary routing nodes. Alice can then craft a _route_ from this outlined path, and use it to send a tip of a few thousand satoshis to Dina, with the payment being _forwarded_ by Bob and Chan. Essentially, Alice will pay Bob, who will pay Chan, who will pay Dina. No direct channel from Alice to Dina is required. The main challenge is to do this in a way that prevents Bob and Chan from stealing the money that Alice wants delivered to Dina. ==== A physical example of "routing" To understand how the Lightning Network protects the payment while being routed, we can compare it to an example of routing physical payments with gold coins in the real world. Assume Alice wants to give 10 gold coins to Dina, but does not have direct access to Dina. However, Alice knows Bob, who knows Chan, who knows Dina and so she decides to ask Bob and Chan for help. This is shown in <>. [[alice_dina_routing_1]] .Alice wants to pay Dina 10 gold coins image::images/gold-coins-network1.png[] Alice can pay Bob to pay Chan to pay Dina, but how does she make sure that Bob or Chan don't run off with the coins after receiving them? In the physical world contracts could be used for safely carrying out a series of payments. Alice could negotiate a contract with Bob which reads: [[alice_bob_contract_1]] ==== _I Alice will give you Bob 10 gold coins if you pass them on to Chan_ ==== While this contract is nice in the abstract, in the real world, Alice runs the risk that Bob might breach the contract and hope not to get caught. Even if Bob is caught and prosecuted, Alice faces the risk that he might be bankrupt and be unable to return her 10 gold coins. Assuming these issues are magically solved, it's still unclear how to leverage such a contract to achieve our desired outcome: getting the coins delivered to Dina. Let's improve our contract, to incorporate these considerations, as follows: [[alice_bob_contract_2]] ==== _I Alice will reimburse you Bob with 10 gold coins if you can prove to me (for example via a receipt) that you have delivered 10 gold coins to Chan_ ==== You might ask yourself why should Bob sign such a contract. He has to pay Chan but ultimately gets nothing out of the exchange, and he runs the risk that Alice might not reimburse him. Bob could offer Chan a similar contract to pay Dina, but similarly Chan has no reason to accept it either. Even putting aside the risk, Bob and Chan must _already_ have 10 gold coins to send, otherwise they wouldn't be able to participate in the contract. Thus Bob and Chan face both risk and opportunity cost for agreeing to this contract, and they would need to be compensated to accept it. Alice can then make this attractive to both Bob and Chan, by offering them fees of 1 gold coin each, if they transmit her payment to Dina. The contract would then read: [[alice_bob_contract_3]] ==== _I Alice will reimburse you Bob with 12 gold coins if you can prove to me (for example via a receipt) that you have delivered 11 gold coins to Chan_ ==== Alice now promises Bob 12 gold coins. There are 10 to be delivered to Dina and 2 for the fees. She promises 12 to Bob if he can prove that he has forwarded 11 to Chan. The difference of 1 gold coin is the fee that Bob will earn for helping out with this particular payment. In <> we see how this arrangement would get 10 gold coins to Dina via Bob and Chan. [[alice_dina_routing_2]] .Alice pays Bob, Bob pays Chan, Chan pays Dina image::images/gold-coins-network2.png[] As there is still the issue of trust and the risk that either Alice or Bob won't honor the contract, all parties decide to use an escrow service. At the start of the exchange, Alice could "lock up" these 12 gold coins in escrow that will only be paid to Bob once he proves that he's paid 11 gold coins to Chan. This escrow service is an idealized one, which does not introduce other risks (e.g. counterparty risk). Later we will see how we can replace the escrow with a Bitcoin smart contract. Let's assume for now that everyone trusts this escrow service. In the Lightning Network, the receipt (proof of payment) could take the form of a secret that only Dina knows. In practice, this secret would be a large random number that is large enough to prevent others from guessing it (typically _very, very_ large number, encoded using 256 bits!). Dina generates this secret value +R+ from a random number generator. The secret could then be committed to the contract by including the SHA256 hash of the secret in the contract itself, as follows: latexmath:[\(H = SHA256(R)\)] We call this hash of the payment's secret the payment hash. The secret which "unlocks" the payment is called the payment secret. For now, we keep things simple and assume that Dina's secret is simply the text line: `+Dinas secret+`. This secret message is called the _payment secret_ or _payment pre-image_. In order to "commit" to this secret, Dina computes the SHA256 hash which when encoded in hex, can be displayed as: `+0575965b3b44be51e8057d551c4016d83cb1fba9ea8d6e986447ba33fe69f6b3+`. To facilitate Alice's payment, Dina will create the payment secret and the payment hash and send the payment hash to Alice. In <> we see that Dina sends the payment hash to Alice via some external channel (dashed line), such as an email or text message: [[alice_dina_routing_3]] .Dina sends the hashed secret to Alice image::images/gold-coins-network3.png["Dina sends the hashed secret to Alice"] Alice doesn't know the secret but she can rewrite her contract to use the hash of the secret as a proof of payment: [[alice_bob_contract_4]] ==== _I Alice will reimburse you Bob with 12 gold coins if you can show me a valid message that hashes to:`+057596...+`. You can acquire this message by setting up a similar contract with Chan who has to set up a similar contract with Dina. In order to assure you that you will be reimbursed I will provide the 12 gold coins to a trusted escrow before you set up your next contract._ ==== This new contract now protects Alice from Bob not forwarding to Chan, protects Bob from not being reimbursed by Alice, and ensures that there will be proof that Dina was ultimately paid via the hash of Dina's secret. After Bob and Alice agree to the contract, and Bob receives the message from the escrow that Alice has deposited the 12 gold coins, Bob can now negotiate a similar contract with Chan. Note that since Bob is taking a service fee of 1 coin, he will only forward 11 gold coins to Chan once Chan shows proof that he has paid Dina. Similarly, Chan will also demand a fee and will expect to receive 11 gold coins once he has proved that he has paid Dina the promised 10 gold coins. Bob's contract with Chan will read: [[alice_bob_contract_5]] ==== _I Bob will reimburse you Chan with 11 gold coins if you can show me a valid message that hashes to:`+057596...+`. You can acquire this message by setting up a similar contract with Dina. In order to assure you that you will be reimbursed I will provide the 11 gold coins to an trusted escrow before you set up your next contract._ ==== Once Chan gets the message from the escrow that Bob has deposited the 11 gold coins, Chan sets up a similar contract with Dina: [[alice_bob_contract_6]] ==== _I Chan will reimburse you Dina with 10 gold coins if you can show me a valid message that hashes to:`+057596...+`. In order to assure you that you will be reimbursed after revealing the secret I will provide the 10 gold coins to an trusted escrow._ ==== Everything is now in place. Alice has a contract with Bob and has placed 12 gold coins in escrow. Bob has a contract with Chan and has placed 11 gold coins in escrow. Chan has a contract with Dina and has placed 10 gold coins in escrow. It is now up to Dina to reveal the secret, which is the pre-image to the hash she has established as proof of payment. Dina now sends +"Dinas secret"+ to Chan. Chan checks that +"Dinas secret" hashes to +057596...+. Chan now has proof of payment and so instructs the escrow service to release the 10 gold coins to Dina. Chan now provides the secret to Bob. Bob checks it and instructs the escrow service to release the 11 gold coins to Chan. Bob now provides the secret to Alice. Alice checks it and instructs the escrow to release 12 gold coins to Bob. All the contracts are now settled. Alice has paid a total of 12 gold coins, 1 of which was received by Bob, 1 of which was received by Chan, and 10 of which were received by Dina. With a chain of contracts like this in place, Bob and Chan could not run away with the money because they deposited it in escrow first. However, one issue still remains. If Dina refused to release her secret pre-image, then Chan, Bob, and Alice would all have their coins stuck in escrow but wouldn't be reimbursed. And similarly if anyone else along the chain failed to pass on the secret, the same thing would happen. So while no one can steal money from Alice, everyone would still have their money stuck in escrow permanently. Luckily, this can be resolved by adding a deadline to the contract. We could amend the contract so that if it is not fulfilled by a certain deadline, then the contract expires and the escrow service returns the money to the person who made the original deposit. We call this deadline a "time lock". The deposit is locked with the escrow service for a certain amount of time, and is eventually released even if no proof of payment was provided. In order to factor this in, the contract between Alice and Bob is once again amended with a new clause: [[alice_bob_contract_7]] ==== _Bob has 24 hours to show the secret after the contract was signed. If Bob does not provide the secret by this time, Alice's deposit will be refunded by the escrow service and the contract becomes invalid._ ==== Bob, of course, now has to make sure he receives the proof of payment within 24 hours. Even if he successfully pays Chan, if he receives the proof of payment later than 24 hours he will not be reimbursed. To remove that risk, Bob must give Chan an even shorter deadline. In turn, Bob will alter his contract with Chan in the following way: [[alice_bob_contract_8]] ==== _Chan has 22 hours to show the secret after the contract was signed. If he does not provide the secret by this time, Bob's deposit will be refunded by the escrow service and the contract becomes invalid._ ==== As you might have guessed, Chan will also alter his contract with Dina: [[alice_bob_contract_9]] ==== _Dina has 20 hours to show the secret after the contract was signed. If she does not provide the secret by this time, Chan's deposit will be refunded by the escrow service and the contract becomes invalid._ ==== With such a chain of contracts we can ensure that, after 24 hours, the payment will successfully go from Alice to Bob to Chan to Dina, or it will fail and everyone will be refunded. Either the contract fails or succeeds, there's no middle ground. In the context of the Lightning Network, we call this "all or nothing" property ((("atomicity")))_atomicity_. As long as the escrow is trustworthy and faithfully performs its duty, then no party will have their coins stolen in the process. The pre-condition to this _route_ working at all, is that all parties in the path have enough money to satisfy the required series of deposits. While this seems like a minor detail we will see later in this chapter that this requirement is actually one of the more difficult issues for Lightning Network nodes. It becomes progressively more difficult as the size of the payment increases. Furthermore, the parties cannot use their money while it is locked in escrow. Thus users forwarding payments face an opportunity cost for locking the money, which is ultimately reimbursed through routing fees, as we saw in the example above. Now that we've seen a physical payment routing example, we will see how this can be implemented on the Bitcoin blockchain, without any need for third-party escrow. To do this we will be setting up the contracts between the participants using Bitcoin Script. We replace the third-party escrow with _smart contracts_ that implement a fairness protocol. Let's break that concept down and implement it! === Fairness Protocol As we saw in the first chapter of this book, the innovation of Bitcoin is the ability to use cryptographic primitives to implement a fairness protocol that substitutes trust in third parties (intermediaries), with a trusted protocol. In our gold coin example, we needed an "escrow" service in order to prevent any one of the parties from reneging on their obligations. The innovation of cryptographic fairness protocols allows us to replace the escrow service with a protocol. The properties of the fairness protocol we want to create are: Trustless Operation:: The participants in a routed payment do not need to trust each other, or any intermediary or third party. Instead, they trust the protocol to protect them from cheating. Atomicity:: The payment is fully executed, or it fails and everyone is refunded. There is no possibility of an intermediary collecting a routed payment and not forwarding it to the next hop. Thus, the intermediaries can't cheat or steal. Multihop:: The security of the system extends end-to-end for payments routed through multiple payment channels, just as it is for a payment between the two ends of a single payment channel. An optional, additional property, is the ability to split payments into multiple parts while maintaining atomicity for the entire payment. These are called _Multi-Part Payments (MPP)_ and are explored further in <>. ==== Implementing Atomic Trustless Multihop Payments 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 tradeoffs between 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 pre-image 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. === Revisiting our example Let's revisit our example from the first part of this chapter. Alice wants to "tip" Dina, with a Lightning payment. Let's say Alice wants to send Dina 50,000 satoshis as a tip. For Alice to pay Dina, Alice will need Dina's node to generate a Lightning invoice. We will discuss this in more detail in <>. For now, let's assume that Dina has a website that can produce a Lightning invoice for tips. [TIP] ==== Lightning payments can be sent without an invoice, using a feature called _keysend_, which we will discuss in more detail in <>. For now, we will explain the simpler payment flow using an invoice. ==== Alice visits Dina's site, enters the amount of 50,000 satoshis in a form and in response Dina's Lightning node generates a payment request for 50,000 satoshis in the form of a Lightning invoice. This interaction takes place over the web and outside the Lightning network, as shown in <>: [[alice_dina_invoice_1]] .Alice requests an invoice from Dina's website image::images/alice-dina-invoice-1.png["Alice requests an invoice from Dina's website"] As we saw in previous examples, we assume that Alice does not have a direct payment channel to Dina. Instead, Alice has a channel to Bob, Bob has a channel to Chan and Chan has a channel to Dina. To pay Dina, Alice must find a path that connects her to Dina. We will discuss that step in more detail in <>. For now, let's assume that Alice is able to gather information about available channels and sees that there is a path from her to Dina, via Bob and Chan. [NOTE] ==== Remember how Bob and Chan might expect a small compensation for routing the payment through their nodes? Alice wants to pay Dina 50,000 satoshis, but as you will see in the following sections she will send Bob 50,200 satoshis. The extra 200 satoshis will pay Bob and Chan 100 satohis each, as a routing fee. ==== Now, Alice's node can construct a Lightning payment. In the next few sections we will see how Alice's node constructs a Hash Time-Locked Contract (HTLCs) to pay Dina and how that HTLC is forwarded along the path from Alice to Dina. ==== On-chain vs Off-chain settlement of HTLCs 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. [[htlcs]] === Hash Time Locked Contracts (HTLCs) In this section we explain how Hash Time Locked Contracts (HTLCs) work. The first part of a Hash Time-Locked Contract is the "Hash". This refers to the use of a cryptographic hash algorithm to commit to a randomly generated secret. Knowledge of the secret allows redemption of the payment. The cryptographic hash function, guarantees that while it's infeasible for anyone to guess the secret pre-image, it's easy for anyone to verify the hash, and there's only one possible pre-image that resolves the payment condition. In <> we see Alice getting a Lightning invoice from Dina. Inside that invoice Dina has encoded a _payment hash_, which is the cryptographic hash of a secret that Dina's node produced. Dina's secret is called the _payment pre-image_. The payment hash acts as an identifier that can be used to route the payment to Dina. The payment pre-image acts as a receipt and proof of payment once the payment is complete. [[alice_dina_invoice_2]] .Alice gets a payment hash from Dina image::images/alice-dina-invoice-2.png["Alice gets a payment hash from Dina"] In the Lightning Network, Dina's payment pre-image won't be a phrase like "Dina's secret", but a random number generated by Dina's node. Let's call that random number +R+. Dina's node will calculate a cryptographic hash of +R+, such that: [[payment_hash_and_preimage]] .Calculating the payment hash ---- H = SHA256(R) ---- In <> +H+ is the hash, or _payment hash_ and +R+ is the secret or _payment pre-image_. The use of a cryptographic hash function is one element that guarantees ((("trustless")))_trustless operation_. The payment intermediaries do not need to trust each other because they know that no one can guess the secret or fake it. ==== HTLCs in Bitcoin Script In our gold coin example, Alice had a contract enforced by escrow like this: [[alice_bob_contract_10]] ==== _Alice will reimburse Bob with 12 gold coins if you can show a valid message that hashes to:_ +0575...f6b3+. _Bob has 24 hours to show the secret after the contract was signed. If Bob does not provide the secret by this time, Alice's deposit will be refunded by the escrow service and the contract becomes invalid._ ==== Let's see how we would implement this as an HTLC in Bitcoin Script. In <> we see an HTLC Bitcoin Script as currently used in the Lightning Network. You can find this definition in https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md#offered-htlc-outputs[BOLT3 - Transactions]: [[received_htlc]] .HTLC implemented in Bitcoin Script (BOLT3) [source,linenum] ---- # To remote node with revocation key OP_DUP OP_HASH160 OP_EQUAL OP_IF OP_CHECKSIG OP_ELSE OP_SWAP OP_SIZE 32 OP_EQUAL OP_IF # To local node via HTLC-success transaction. OP_HASH160 OP_EQUALVERIFY 2 OP_SWAP 2 OP_CHECKMULTISIG OP_ELSE # To remote node after timeout. OP_DROP OP_CHECKLOCKTIMEVERIFY OP_DROP OP_CHECKSIG OP_ENDIF OP_ENDIF ---- 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 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 <>. Let's build it up from scratch! ==== Payment pre-image and hash verification The core of an HTLC is the "hash", where payment can be made if the recipient knows the payment pre-image. Alice locks the payment to a specific payment hash and Bob has to present a payment pre-image to claim the funds. The Bitcoin system can verify that Bob's payment pre-image is correct by hashing it and comparing the result to the payment hash that Alice used to lock the funds. This part of an HTLC can be implemented in Bitcoin Script as follows: ---- OP_SHA256 OP_EQUAL ---- Alice can create a transaction output that pays, 50,200 satoshi with a locking script above, replacing with the hash value +0575...f6b3+ provided by Dina. Then, Alice can sign this transaction and offer it to Bob: .Alice's offers a 50,200 satoshi HTLC to Bob ---- OP_SHA256 0575...f6b3 OP_EQUAL ---- 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 pre-image value +R+ The unlocking script combined with the locking script would produce: ---- OP_SHA256 OP_EQUAL ---- The Bitcoin Script engine would evaluate this script as follows: 1. +R+ is pushed to the stack 2. The OP_SHA256 operator takes the value +R+ off the stack and hashes it, pushing the result H~R~ to the stack 3. +H+ is pushed to the stack 4. The OP_EQUAL operator compares +H+ and H~R~. If they are equal, the result is +TRUE+, the script is complete and the payment is verified. ==== Extending HTLCs from Alice to Dina Alice will now extend the HTLC across the network so that it reaches Dina. [[alice_dina_htlc_1]] .Propagating the HTLC across the network image::images/alice-dina-htlc-1.png["Propagating the HTLC across the network"] In <> 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! Since Alice's HTLC is 100 satoshi more that 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. ==== Back-propagating the secret Once Dina receives a 50,000 HTLC from Chan, she can now get paid. Dina could simply commit this HTLC on-chain and spend it by revealing the secret in the spending transaction. Or, instead, Dina can update the channel balance with Chan by giving him the secret. There's no reason to incur a transaction fee and go on-chain. So, instead, Dina sends the secret to Chan and they agree to update their channel balances to reflect a 50,000 satoshi Lightning payment to Dina. In <> we see Dina giving the secret to Chan, thereby fulfilling the HTLC. [[alice_dina_htlc_redeem_1]] .Dina settles Chan's HTLC off-chain image::images/alice-dina-htlc-redeem-1.png["Dina settles Chan's HTLC off-chain"] Notice 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 <> we see Chan sending the secret to Bob and receiving a payment in return. [[alice_dina_htlc_redeem_2]] .Chan settles Bob's HTLC off-chain image::images/alice-dina-htlc-redeem-2.png["Chan settles Bob's HTLC off-chain"] 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 <> 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. [[alice_dina_htlc_redeem_3]] .Bob settles Alice's HTLC off-chain image::images/alice-dina-htlc-redeem-3.png["Bob settles Alice's HTLC off-chain"] Bob has recieved 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 <> [[alice_dina_htlc_redeem_4]] .Channel balances after the payment image::images/alice-dina-htlc-redeem-4.png["Channel balances after the payment"] [[preventing_theft]] ==== Signature binding - preventing theft of HTLCs There's a catch. Did you notice it? If Alice, Bob and Chan create the HTLCs as shown above, 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 too? 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: ---- OP_SHA256 OP_EQUALVERIFY OP_CHECKSIG ---- [TIP] ==== Notice that we also changed +OP_EQUAL+ to +OP_EQUALVERIFY+. When an operator has the suffix +VERIFY+ it does not return +TRUE+ or +FALSE+ on the stack. Instead it *halts* execution and fails the script if the result is false and continues without any stack output if it is true. ==== 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 pre-image, like this: ---- ---- The unlocking and locking script are combined and evaluated by the scripting engine, as follows: ---- OP_SHA256 OP_EQUALVERIFY OP_CHECKSIG ---- 1. ++ is pushed on to the stack 2. +R+ is pushed on to the stack 3. OP_SHA256 pops and hashes +R+ from the top of the stack and pushes H~R~ on to the stack 4. +H+ is pushed on to the stack 5. OP_EQUALVERIFY pops H and H~R~ and compares them. If they are not the same, execution halts. Otherwise, we continue without output to the stack 6. ++ key is pushed to the stack 7. OP_CHECKSIG pops ++ and ++ and verifies the signature. The result (TRUE/FALSE) is pushed to the stack. 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. ==== Hash Optimization Let's look at the first part of the HTLC script so far: ---- OP_SHA256 OP_EQUALVERIFY ---- If we look at this in a symbolic representation above, 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 ++ 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 https://en.bitcoin.it/wiki/Script[Bitcoin Wiki: Script], or in https://github.com/bitcoinbook/bitcoinbook/blob/develop/appdx-scriptops.asciidoc[Mastering Bitcoin Appendix: Transaction Script Language Operators, Constants, and Symbols]. Represented in hexadecimal, our HTLC script would look like this: ---- a8 0575965b3b44be51e8057d551c4016d83cb1fba9ea8d6e986447ba33fe69f6b3 88 ---- 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 SHA256 algorithm, one that produces smaller hashes. The Bitcoin Script language provides the +OP_HASH160+ operator that "double hashes" a pre-image: first the pre-image is hashed with SHA256 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 SHA256 hash is +057596...69f6b3+. Putting that through another round of hasing with RIPEMD160 gives us the result: ---- R = "Dinas secret" H256 = SHA256(R) H256 = 0575965b3b44be51e8057d551c4016d83cb1fba9ea8d6e986447ba33fe69f6b3 H160 = RIPEMD160(H) H160 = 9e017f6767971ed7cea17f98528d5f5c0ccb2c71 ---- 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! The "optimized" HTLC script would look like this: ---- OP_HASH160 OP_EQUALVERIFY ---- Encoded in hex this is: ---- a9 9e017f6767971ed7cea17f98528d5f5c0ccb2c71 88 ---- 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 <>: ---- ... # To local node via HTLC-success transaction. OP_HASH160 OP_EQUALVERIFY... ---- ==== HTLC cooperative and timeout failure So far we looked at the "Hash" part of HTLC, and how it would work if everyone cooperated and was online at the time of payment. 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 <>. 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 time-lock. 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 not "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 +OP_CHECKLOCKTIMEVERIFY+ also known +OP_CLTV+ for short. Here's the script, as seen previously in line 13 of <>: ---- ... OP_DROP OP_CHECKLOCKTIMEVERIFY OP_DROP OP_CHECKSIG ... ---- 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 ++, 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 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+ in order to remove the ++ item from the top of the stack as 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 <>, this is necessary to ensure that only the rightful owner of the funds can claim them, by binding this output to their public key and requiring a signature. ==== Decrementing time-locks As the HTLCs are extended from Alice to Dina, the time-lock refund clause in each HTLC has a _different_ cltv_expiry value. We will see this in more detail as we talk about <>. But suffice it to say that to ensure an orderly unwinding of a payment that fails, each hop needs to wait a bit less for their refund. The difference between time-locks for each hop is called the cltv_expiry_delta and is set by each node and advertized to the network as we will see in <>. For example, Alice sets the refund time-lock on the first HTLC to a block height of current+500 blocks ("current" being the current block height). Bob would then set the time-lock cltv_expiry on the HTLC to Chan to current+450 blocks. Chan would set the time-lock 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 time-lock prevents race conditions and ensures the HTLC chain is unwound backwards, from the destination towards the origin. === Conclusion In this chapter we saw how Alice can pay Dina even if she doesn't have a direct payment channel. Alice can find a path that connects her to Dina and route a payment across several payment channels so that it reaches Dina. To ensure that the payment is _atomic_ and _trustless_ across _multiple hops_, Alice must implement a fairness protocol in cooperation with all the intermediary nodes in the path. The fairness protocol is currently implemented as a _Hash Time-Locked Contract (HTLC)_, which commits funds to a payment hash derived from a secret payment pre-image. Each of the participants in the payment route can extend an HTLC to the next participant, without worrying about theft or stuck funds. The HTLC can be redeemed by revealing the secret payment pre-image. Once an HTLC reaches Dina, she reveals the pre-image which flows backwards resolving all the HTLCs offered. Finally, we saw how a time-locked refund clause completes the HTLC, ensuring that every participant can get a refund if the payment fails but for whatever reason one of the participants doesn't cooperate in unwinding the HTLCs. By always having the option to go on-chain for a refund, the HTLC achieves the fairness goal of atomicity and trustless operation.