@ -67,20 +67,20 @@ But first, how do their peers verify that the channel announcement is legitimate
#### Verifying the channel
Let's assume Wei receives this announcement from Bob.
Let's assume Chan receives this announcement from Bob.
How does he know that this is a real channel, and why should he even bother to check it?
Well, verifying a channel is pretty important.
If Wei tries to forward any payments through a channel that doesn't exist, his payments are going to fail.
Even if the channel does exist, Wei still needs assurances that Bob and Alice actually control the funds inside of it.
If Chan tries to forward any payments through a channel that doesn't exist, his payments are going to fail.
Even if the channel does exist, Chan still needs assurances that Bob and Alice actually control the funds inside of it.
Alice and Bob could potentially dupe him by claiming ownership of a channel that actually belongs to someone else.
So Wei will definitely want to verify before he updates his channel graph.
So Chan will definitely want to verify before he updates his channel graph.
Firstly, Wei will check the channel ID to discover which Bitcoin transaction contains the channel funds.
Firstly, Chan will check the channel ID to discover which Bitcoin transaction contains the channel funds.
He will then look up this transaction on the Bitcoin blockchain and he should discover a P2WSH bitcoin UTXO that is signed by both Alice and Bob.
Secondly, Wei will verify the signatures in the channel announcement message and confirm that the two nodes who signed the channel announcement are actually Alice and Bob.
Secondly, Chan will verify the signatures in the channel announcement message and confirm that the two nodes who signed the channel announcement are actually Alice and Bob.
Once he's done so, he's convinced that the channel is funded and that Alice and Bob are the funders and owners of that channel.
If any of these checks fail, he'll ignore the channel announcement.
Once Wei is satisfied that the channel announcement checks out, he'll update his channel graph.
Once Chan is satisfied that the channel announcement checks out, he'll update his channel graph.
He will also send information about this channel to his peers, and they will verify it for themselves.
@ -37,7 +37,7 @@ As the name suggests the amount is depicted in millisatoshi even those cannot be
Still Lightning nodes keep track of subsatoshi amounts to avoid rounding issues.
As in the offline example Alice includes the `payment_hash` in the next data field.
This was told to Alice by Bob in case she wants to just send money to him.
If Alice was to send Money to Gloria the payment hash would have been given to Alice by Gloria.
If Alice was to send Money to Dina the payment hash would have been given to Alice by Dina.
We discussed the potential of time lock or deadline of the contract.
This is encoded in the `cltv_expiry`.
cltv stands for OP_CHECKTIMELOCKVERIFY and is the OP_CODE that will be used in the HTLC output and serve as the deadline in which the contract is valid.
@ -116,7 +116,7 @@ He will just not have received the funds from Alice.
This is important!
Despite the fact that Bob has a new commitment transaction with two valid signatures and an HTLC output inside he cannot consider his HTLC as being set up successfully.
He first needs to have Alice invalidate her old state.
That is why - in the case that he is not the final recipient of the funds - he should not forward the HTLC yet by setting up a new HTLC on the next channel with Wei.
That is why - in the case that he is not the final recipient of the funds - he should not forward the HTLC yet by setting up a new HTLC on the next channel with Chan.
Alice will not invalidate her commitment transaction yet as she has to first get her new commitment transaction and she wants Bob to invalidate his old commitment transaction which he can safely do at this time.
@ -944,7 +944,7 @@ Congratulations! You have built Eclair from source and you are ready to code, te
Our final example, presented in this section, will bring together all the various containers we have built to form a Lightning network made of diverse (LND, c-lightning, Eclair) node implementations. We will compose the network by connecting the nodes together and opening channels from one node to another. As the final step we route a payment across these channels.
In this example, we will replicate the Lighting network example from <<routing_on_a_network_of_payment_channels>>. Specifically, we will create four Lightning nodes named Alice, Bob, Wei, and Gloria. We will connect Alice to Bob, Bob to Wei, and Wei to Gloria. Finally, we will have Gloria create an invoice and have Alice pay that invoice. Since Alice and Gloria are not directly connected, the payment will be routed as an HTLC across all the payment channels.
In this example, we will replicate the Lighting network example from <<routing_on_a_network_of_payment_channels>>. Specifically, we will create four Lightning nodes named Alice, Bob, Chan, and Dina. We will connect Alice to Bob, Bob to Chan, and Chan to Dina. Finally, we will have Dina create an invoice and have Alice pay that invoice. Since Alice and Dina are not directly connected, the payment will be routed as an HTLC across all the payment channels.
==== Using docker-compose to orchestrate docker containers
@ -991,7 +991,7 @@ services:
container_name: Alice
----
The fragment above 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), "Wei" (Eclair) and "Gloria" (LND again).
The fragment above defines a network called +lnnet+ and a container called +bitcoind+ which will attach to the +lnnet+ network. The container is the same one we built at the beginning of this chapter. We expose three of the container's ports allowing us to send commands to it and monitor blocks and transactions. Next, the configuration specifies an LND container called "Alice". Further down you will also see specifications for containers called "Bob" (c-lightning), "Chan" (Eclair) and "Dina" (LND again).
Since all these diverse implementations follow the Basis of Lightning Technologies (BOLT) specification and have been extensively tested for interoperability, they have no difficulty working together to build a Lightning network.
@ -1010,16 +1010,16 @@ To start the example, we switch to the directory that contains the +docker-compo
$ cd code/docker
$ docker-compose up
Creating network "docker_lnnet" with the default driver
Dina invoice lnbcrt100u1p00w5sypp5fw2gk98v6s4s2ldfwxa6jay0yl3f90j82kv6xx97jfwpa3s964vqdqqcqzpgsp5jpasdchlcx85hzfp9v0zc7zqs9sa3vyasj3nm0t4rsufrl7xge6s9qy9qsqpdd5d640agrhqe907ueq8n8f5h2p42vpheuzen58g5fwz94jvvnrwsgzd89v70utn4d7k6uh2kvp866zjgl6g85cxj6wtvdn89hllvgpflrnex
Wait for channel establishment - 60 seconds for 6 blocks
@ -1077,8 +1077,8 @@ Looking inside the script, we see the part that gets all the node IDs and stores
If you have followed the first part of the chapter you will recognise these commands and be able to "decipher" their meaning. It looks quite complex, but we will walk through it step-by-step and you'll quickly get the hang of it.
@ -1106,29 +1106,29 @@ We do the same with the other nodes, setting up connections and channels. Each n
To Bob's node (c-lightning) we send these commands:
[source,bash]
----
docker-compose exec -T Bob lightning-cli connect ${wei_address//\"}@Wei
docker-compose exec -T Bob lightning-cli connect ${wei_address//\"}@Chan
docker-compose exec -T Bob lightning-cli fundchannel ${wei_address//\"} 1000000
The +addinvoice+ command creates an invoice for the specified amount in satoshis and produces a JSON object with the invoice details. From that JSON object we only need the actual bech32-encoded payment request, which we extract with +jq+.
Next, we have to wait. We just created a bunch of channels. Hence, our nodes broadcast several funding transactions. The channels can't be used until the funding transactions are mined and collect 6 confirmations. Since our Bitcoin +regtest+ blockchain is set to mine blocks every ten seconds, we have to wait 60 seconds for all the channels to be ready to use.
The final command is the actual invoice payment. We connect to Alice's node and present Gloria's invoice for payment.
The final command is the actual invoice payment. We connect to Alice's node and present Dina's invoice for payment.
We ask Alice's node to pay the invoice, but also ask for +inflight_updates+ in +json+ format. That will give us detailed output about the invoice, the route, the HTLCs, and the final payment result. We can study this additional output and learn from it!
Since Alice's node doesn't have a direct channel to Gloria, her node has to find a route. There is only one viable route here (Alice->Bob->Wei->Gloria), which Alice will be able to discover now that all the channels are active and have been advertised to all the nodes by the Lightning gossip protocol. Alice's node will construct the route and create an onion packet to establish HTLCs across the channels. All of this happens in a fraction of a second and Alice's node will report the result of the payment attempt. If all goes well, you will see the last line of the JSON output showing:
Since Alice's node doesn't have a direct channel to Dina, her node has to find a route. There is only one viable route here (Alice->Bob->Chan->Dina), which Alice will be able to discover now that all the channels are active and have been advertised to all the nodes by the Lightning gossip protocol. Alice's node will construct the route and create an onion packet to establish HTLCs across the channels. All of this happens in a fraction of a second and Alice's node will report the result of the payment attempt. If all goes well, you will see the last line of the JSON output showing:
@ -77,19 +77,19 @@ Furthermore, there is no guarantee that the route chosen was the cheapest in ter
At the time of writing this book, this is a design trade-off made to protect user privacy.
=== Paths are constructed from destination to source
Let us use our standard example in which Alice wants to send a payment of 100k satoshi on a path via Bob and Wei to Gloria.
The _path_ obviously looks like (Alice)-->(Bob)-->(Wei)-->Gloria.
Bob and Wei will charge routing fees to forward the _onion_.
Let us use our standard example in which Alice wants to send a payment of 100k satoshi on a path via Bob and Chan to Dina.
The _path_ obviously looks like (Alice)-->(Bob)-->(Chan)-->Dina.
Bob and Chan will charge routing fees to forward the _onion_.
As you already know, nodes can charge two types of fees.
First, the _base fee_ will be charged for any successful forwarding and settlement of an HTLC.
This fee is constant and independent of the amount that the node is forwarding.
Secondly, nodes might charge a _fee rate_ which is proportional to the forwarded amount.
For simplicity assume that the fee rate of Bob and Wei is expensive with 1% for Bob and 2% for Wei.
For simplicity furthermore assume neither Bob nor Wei take a base fee.
For simplicity assume that the fee rate of Bob and Chan is expensive with 1% for Bob and 2% for Chan.
For simplicity furthermore assume neither Bob nor Chan take a base fee.
When Alice constructs the onion she has to include the routing fees as the difference of the incoming HTLC and the outgoing HTLC.
Let us assume she computes the routing fees for the onion incorrectly.
Alice knows that 1% of 100k satoshi is 1k satoshi which she belives she should include in Bob's onion.
Similarly she knows that 2% of 100k satoshi is 2k satoshi which she belives she should include in Wei's onion.
Similarly she knows that 2% of 100k satoshi is 2k satoshi which she belives she should include in Chan's onion.
An inexperienced Alice would incorrectly believe her total fee to be 3k satoshi. But she is wrong.
Look at the incorrect onion from our naive Alice. Bob would reject this onion.
@ -104,7 +104,7 @@ Look at the incorrect onion from our naive Alice. Bob would reject this onion.
"dealy": 187,
},
{
"id": "Wei",
"id": "Chan",
"channel": "74",
"direction": 1,
"satoshi": 102000,
@ -112,7 +112,7 @@ Look at the incorrect onion from our naive Alice. Bob would reject this onion.
"dealy": 183,
},
{
"id": "Gloria",
"id": "Dina",
"channel": "452",
"direction": 0,
"satoshi": 100000,
@ -125,8 +125,8 @@ Look at the incorrect onion from our naive Alice. Bob would reject this onion.
The reason for Bob to not forward the onion is that he expects the incoming amount to be 1% larger then the amount he is supposed to forward.
Thus he would like to receive an incoming ammount of `103020` satoshi (102000 + 1%) which is 20 satoshi more than our uninformed Alice actually sent him.
According to Bob's fee schedule Bob will reject this onion.
If Alice constructed the onion from the destinatin towards the source, she would have started with 100k satoshi for Gloria.
In the next step she would have added Wei's 2% fee to compute 102k for Wei's input.
If Alice constructed the onion from the destinatin towards the source, she would have started with 100k satoshi for Dina.
In the next step she would have added Chan's 2% fee to compute 102k for Chan's input.
In the last step she would have applied Bob's fee (1%) to 102k to derive 102k + 1020 satoshi.
That makes a total of 103,020 satoshi that she needs to send to Bob.
As the routing fees can increase the amount that is being forwarded even beyond the capacity of small channels, it makes sense to start the construction of the onion and the path finding at the destination and work from the destination back towards the sender.
@ -378,15 +378,15 @@ It is quite clear that after already one single payment such a 50 - 50 state wou
You can see this in the following graph.
[[rebalancing-2]]
.The Bob - Wei channel becomes now imbalanced
.The Bob - Chan channel becomes now imbalanced
image:images/rebalancing-2.png[]
you can see that after Bob made a payment of 1 million satoshi to Wei the channel balance was shifted.
you can see that after Bob made a payment of 1 million satoshi to Chan the channel balance was shifted.
Bob now has 1.5 million satoshi on the channel and wei has 3.5 million satoshi on the channel.
The balance ratio went from 50/50 to 30/70.
The other 2 channels however styed with 50/50.
Wei decides that he wants to have a 50/50 channel with Bob.
Chan decides that he wants to have a 50/50 channel with Bob.
There are 3 ways of how he can achieve this.
. He can send back 1 milion satoshi to Bob
@ -396,21 +396,21 @@ There are 3 ways of how he can achieve this.
Sending back the money would be quite expensive and does not seem to be a realistic option.
Using an onchain swapping service after every payment to rebalance channels seems also problematic.
The entire idea of creating the Lightning Network was to have less on chain transaction and be able to send money between people without the necessity to do on chain transactions.
Thus there is only the last option which means that Wei could move the money from the Bob-Wei channel via the Bob-Erica channel to hhis Erica-Wei channel.
Thus there is only the last option which means that Chan could move the money from the Bob-Chan channel via the Bob-Erica channel to hhis Erica-Chan channel.
[[rebalancing-4]]
.Wei tries to rebalance the Bob-Wei channel in the unbalanced network via a circular onion of 1 mio Satoshi.
.Chan tries to rebalance the Bob-Chan channel in the unbalanced network via a circular onion of 1 mio Satoshi.
image:images/rebalancing-4.png[]
The problem in the new network can easily be seen on the next picture.
While the Bob-Wei channel now becomes 50/50 again all the other channel turned into a 30/70 split ratio.
While the Bob-Chan channel now becomes 50/50 again all the other channel turned into a 30/70 split ratio.
[[rebalancing-5]]
.Rebalancing one channel produces imbalanced other channels
image:images/rebalancing-5.png[]
An interesting oversvation about this rebalancing can be made though!
After the payment and the rebalancing it looked like Bob initially had sent Money not via the Bob-Wei channel but via the path along Erica.
After the payment and the rebalancing it looked like Bob initially had sent Money not via the Bob-Chan channel but via the path along Erica.
[[rebalancing-6]]
.Rebalancing is equivalent to having selected a different payment path to begin with.
@ -423,7 +423,7 @@ However this is not true!
When rebalancing comes into place we can use the local knowledge of the distribution of balances that nodes might have to help with selection of paths and finding a total payment path / multi path or flow.
We will explore this idea a little bit more in the upcoming section about JIT routing.
Remember in our example after Bob has paid Wei Bob had a total amount of 4 million satoshi, Wei had a total of 6 million satoshi and Erica still had 5 million satoshi as before.
Remember in our example after Bob has paid Chan Bob had a total amount of 4 million satoshi, Chan had a total of 6 million satoshi and Erica still had 5 million satoshi as before.
Of course it would be possible to have payment channels between these three people with that distribution of funds so that everyone has 50% of the capacity on their side of the payment channel.
[[rebalancing-7]]
@ -484,9 +484,9 @@ The just in time Routing scheme has 2 major advantages over source based routing
. It increases the privacy of channels. If nodes that do not have sufficient liquidity return the onions an attacker can use that behavior to probe for the channel balance. However if nodes rebalance their channels they will always be able to forward the payment and protect themselves from probing attacks.
. More importantly it resembles multipart payments in which the splitting of the payment is not been decided by the sender who would not know how balances remotely are distributed but the splitting would be achieved by the routing node that knows its local topology.
Let us elaborate on the second point and take the example in which Bob was supposed to forward the onion from Alice to Wei but does have enough liquidity on the channel with Wei.
Let us elaborate on the second point and take the example in which Bob was supposed to forward the onion from Alice to Chan but does have enough liquidity on the channel with Chan.
If Bob now does a cebalancing operation through Erica and is able to afterwards forward the payment along to Bob he has effectively split the payment at his node to flow along two paths.
One part flows directly to Wei and the other part takes the path over Erica to Wei.
One part flows directly to Chan and the other part takes the path over Erica to Chan.
It is obvious that splitting a payment at the node that can't forward the entire payment is much more reliable and effective than letting the sender decide how to split a payment and into which amounts.
We thus can see that with the help of JIT-Routing rebalancing and multipart payments are actually not so different concepts and ideas.
@ -19,23 +19,23 @@ In theory, one can examine the _channel graph_ and connect a series of payment c
=== Routing a payment
In this section we will examine routing from the perspective of Gloria, a gamer who receives donations from her fans while she livestreams her game sessions.
In this section we will examine routing from the perspective of Dina, a gamer who receives donations from her fans while she livestreams her game sessions.
The innovation of routed payment channels allows Gloria to receive tips without maintaining a separate channel with every one of her fans who want to tip her.
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 Glori, she will be able to receive payment from that fan.
The nodes along the path from the fan to Gloria are intermediaries and called "routing nodes" in the context of routing a payment.
The nodes along the path from the fan to Dina are intermediaries and called "routing nodes" in the context of routing a payment.
[[gloria-routing-diagram]]
.Any one of Gloria's fans in the diagram can pay her by routing via the nodes in between them and Gloria
image:images/gloria-routing-diagram.PNG["Any one of Gloria's fans in the diagram can pay her by routing via the nodes in between them and Gloria"]
.Any one of Dina's fans in the diagram can pay her by routing via the nodes in between them and Dina
image:images/gloria-routing-diagram.PNG["Any one of Dina's fans in the diagram can pay her by routing via the nodes in between them and Dina"]
Importantly, the routing nodes are unable to steal the funds while routing a payment from a fan to Gloria.
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 Gloria, without leaking private information and without risking theft.
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.
@ -50,143 +50,143 @@ We will discuss how the _structure_ (edges, fees, time-locks, etc) of the route
Before we dive into the concept of a conditional chained end-to-end secure payment, let's work through an example.
Let us to return to Alice who, in previous chapters, purchased a coffee from Bob with whom she has an open channel.
Alice now watches a live stream from Gloria the gamer, and wants to send her a tip via the Lightning Network.
However, Alice has no direct channel with Gloria.
Alice now watches a live stream from Dina the gamer, and wants to send her a tip via the Lightning Network.
However, Alice has no direct channel with Dina.
Alice could open a direct channel, 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 Gloria _without_ the need to open a channel directly with Gloria.
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 Gloria with sufficient capacity to route the tip.
This is possible, as long as there exists some path of channels from Alice to Dina with sufficient capacity to route the tip.
From previous chapters, we know Alice has an open channel with Bob, the coffee shop owner.
Bob, in turn, has an open channel with the software developer Wei who helps him with the point of sale system he uses in his coffee shop.
Wei is also the owner of a large software company which develops the game that Gloria plays, and they already have an open channel which Gloria uses to pay for the game's license and in-game items.
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.
If we draw out this series of payment channels, it's possible to manually trace a _path_ from Alice to Gloria that uses Bob and Wei 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 Gloria, with the payment being _forwarded_ by Bob and Wei.
Essentially, Alice will pay Bob, who will pay Wei, who will pay Gloria.
And no direct channel from Alice to Gloria is required.
If we draw out this series of payment channels, it's possible to manually 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.
And no direct channel from Alice to Dina is required.
[[routing-network]]
.The network of payment channels of our friends can be seen here:
image:images/routing-network.png[]
The main challenge is to do this in a way that prevents Bob and Wei from stealing the money that Alice wants delivered to Gloria.
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.
To understand how the Lightning Network protects the payment while being routed, we can compare to an example of routing physical payments with golden coins in the real world.
Assume Alice wants to give 10 gold coins to Gloria, but does not have direct access to Gloria.
However, Alice knows Bob, who knows Wei, who knows Gloria and so she decides to ask Bob and Wei for help.
She can pay Bob to pay Wei to pay Gloria, but how does she make sure that Bob or Wei don't run off with the coins after receiving them?
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.
She 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-gloria-routing-1]
====
_I (Alice) will give you (Bob) 10 gold coins if you pass them on to Wei_
_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 to not get caught by law enforcement.
Even if Bob gets caught by law enforcement, 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: the coins ultimately being delivered to Gloria.
Assuming these issues are magically solved, it's still unclear how to leverage such a contract to achieve our desired outcome: the coins ultimately being delivered to Dina.
We thus improve our contract:
[alice-gloria-routing-2]
====
_I (Alice) will reimburse you (Bob) with 10 gold coins if you can prove to me (for example via a receipt) that you already have delivered 10 gold coins to Wei_
_I (Alice) will reimburse you (Bob) with 10 gold coins if you can prove to me (for example via a receipt) that you already have delivered 10 gold coins to Chan_
====
You might ask yourself why should Bob sign such a contract.
He has to pay Wei but ultimately gets nothing out of the exchange, and he runs the risk that Alice might not reimburse him.
Bob could offer Wei a similar contract to pay Gloria, but similarly Wei has no reason to accept it either.
Even putting aside the risk, Bob and Wei must _already_ have 10 gold coins to send, otherwise they wouldn't be able to participate in the contract.
Thus Bob and Wei face both risk and opportunity cost for agreeing to this contract, and they would need to be compensated in order for them to accept it.
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 in order for them to accept it.
Alice can this make this attractive to both Bob and Wei, by offering them fees of 1 gold coin each, if they transmit her payment to Gloria.
Alice can this 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 final contract would instead read:
[alice-gloria-routing-3]
====
_I (Alice) will reimburse you (Bob) with 12 gold coins if you can prove to me (for example via a receipt) that you already have delivered 11 golden coins to Wei_
_I (Alice) will reimburse you (Bob) with 12 gold coins if you can prove to me (for example via a receipt) that you already have delivered 11 golden coins to Chan_
====
Alice now promises Bob 12 gold coins.
There are 10 to be delivered to Gloria and 2 for the fees.
She promises 12 to Bob if he can prove that he has forwarded 11 to Wei.
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.
As there is still the issue of trust and the risk that either Alice or Bob don't honor the contract, all parties decide to use an escrow service.
At the start of the exchange, Alice could "lock up" these 12 golden coins in escrow that will only be paid to Bob once he proves that he's paid 11 golden coins to Wei.
At the start of the exchange, Alice could "lock up" these 12 golden coins in escrow that will only be paid to Bob once he proves that he's paid 11 golden coins to Chan.
This escrow service is an "ideal functionality", which will later be replaced by a more trust-minimized mechanism.
Let's assume for now that everyone trusts this escrow.
In the Lightning Network, the receipt (proof of payment) could take the form of a secret that only Gloria knows.
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!).
The secret could then be committed to the contract by including the SHA256 hash of the secret in the contract itself.
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 Gloria's secret is simply the text line: `+Glorias secret+`.
For now, we keep things simple and assume that Dina's secret is simply the text line: `+Dinas secret+`.
In order to "commit" to this secret, she computes the SHA256 hash which when encoded in hex, can be displayed as: `+f23c83babfb0e5f001c5030cf2a06626f8a940af939c1c35bd4526e90f9759f5+`.
footnote:[You can verify this by typing `echo -n "Glorias secret" | sha256sum` to your Linux command line shell.]
footnote:[You can verify this by typing `echo -n "Dinas secret" | sha256sum` to your Linux command line shell.]
To facilitate Alice's payment, Gloria will create the secret and the payment hash and send the payment hash 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:
To facilitate Alice's payment, Dina will create the secret and the payment hash and send the payment hash 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-gloria-routing-4]
====
_I (Alice) will reimburse you (Bob) with 12 gold coins if you can show me a valid message that hashes to:`+f23c83...+`.
You can acquire this message by setting up a similar Contract with Wei who has to set up a similar contract with Gloria.
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 get reimbursed I will provide the 12 gold coins to an trusted escrow before you set up your next contract._
====
This new contract now protects Alice from Bob not forwarding to Wei, protects Bob from not being reimbursed by Alice, and ensures that there will be proof that Gloria was ultimately paid via the hash of Gloria's secret.
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.
This secret message that hashes to the +f23c83...+ is called a _pre-image_.
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 Wei.
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 Wei once Wei shows proof that he has paid Gloria.
Similarly, Wei will also demand a fee and will expect to receive 11 gold coins once he has proved that he has paid Gloria the promised 10 gold coins.
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 Wei will read:
Bob's contract with Chan will read:
[alice-gloria-routing-5]
====
_I (Bob) will reimburse you (Wei) with 11 gold coins if you can show me a valid message that hashes to:`+f23c83...+`.
You can acquire this message by setting up a similar contract with Gloria.
_I (Bob) will reimburse you (Chan) with 11 gold coins if you can show me a valid message that hashes to:`+f23c83...+`.
You can acquire this message by setting up a similar contract with Dina.
In order to assure you that you will get reimbursed I will provide the 11 gold coins to an trusted escrow before you set up your next contract._
====
Once Wei gets the message from the escrow that Bob has deposited the 11 gold coins, Wei sets up a similar contract with Gloria:
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-gloria-routing-6]
====
_I (Wei) will reimburse you (Gloria) with 10 golden coins if you can show me a valid message that hashes to:`+f23c83...+`.
_I (Chan) will reimburse you (Dina) with 10 golden coins if you can show me a valid message that hashes to:`+f23c83...+`.
In order to assure you that you will get 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 Wei and has placed 11 gold coins in escrow
Wei has a contract with Gloria and has placed 10 gold coins in escrow.
It is now up to Gloria to reveal the secret, which is the pre-image to the hash she has established as proof of payment.
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.
Gloria now sends +"Glorias secret"+ to Wei.
Dina now sends +"Dinas secret"+ to Chan.
He checks that +"Glorias secret" hashes to +f23c83...+. Wei now has proof of payment and so instructs the escrow service to release the 10 golden coins to Gloria.
He checks that +"Dinas secret" hashes to +f23c83...+. Chan now has proof of payment and so instructs the escrow service to release the 10 golden coins to Dina.
Wei now provides the secret to Bob. Bob checks it and instructs the escrow service to release the 11 gold coins to Wei.
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 Wei, and 10 of which were received by Gloria.
With a chain of contracts like this in place, Bob and Wei could not run away with the money because they deposited it in escrow first.
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 Gloria refused to release her secret pre-image, then Wei, Bob, and Alice would all have their coins stuck in escrow but wouldn't be reimbursed.
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 can still lose money.
@ -206,25 +206,25 @@ If Bob does not provide the secret by this time, Alice's deposit will be refunde
====
Bob, of course, now has to make sure he receives the proof of payment within 24 hours.
Even if he successfully pays Wei, if he receives the proof of payment later than 24 hours he will not be reimbursed. To remove that risk, Bob must give Wei and even shorter deadline.
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 and even shorter deadline.
In turn, Bob will alter his contract with Wei in the following way:
In turn, Bob will alter his contract with Chan in the following way:
[alice-gloria-routing-8]
====
_Wei has 22 hours to show the secret after the contract was signed.
_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, Wei is now incentivized to also alter his contract with Gloria:
As you might have guessed, Chan is now incentivized to also alter his contract with Dina:
[alice-gloria-routing-9]
====
_Gloria has 20 hours to show the secret after the contract was signed.
_Dina has 20 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._
====
With such a chain of contracts we can ensure that, after 24 hours, the payment will successfully deliver from Alice to Bob to Wei to Gloria, or it will fail and everyone will be refunded.
With such a chain of contracts we can ensure that, after 24 hours, the payment will successfully deliver 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_.
@ -390,38 +390,38 @@ Last but not least the Lightning Network can actually run on Tor to use it as a
This means that all connections of a node with its peers and the resulting communication will by obfuscated once more through the TOR network.
====
Lets stick to our example in which Alice still wants to tip Gloria and has decided to use the path via Bob and Wei.
We note that there might have been alternative paths from Alice to Gloria but for now we will just assume it is this path that Alice has decided to use.
Lets stick to our example in which Alice still wants to tip Dina and has decided to use the path via Bob and Chan.
We note that there might have been alternative paths from Alice to Dina but for now we will just assume it is this path that Alice has decided to use.
In order to kick off the transfer, Alice needs to send a special message to Bob to kick off the multi-hop transfer.
You'll learn about the specific structure of this message in later chapters, but for now we'll call it an "HTLC Add" message.
Aside from the amount, the payment hash, and the time-lock, this message also contains an opaque field use to store encrypted forwarding information.
Today in the network, this field is 1366 bytes, as that's the _fixed_ size length of the onion packet. #TODO(roasbeef): explain security properties earlier
This onion contains all the information about the path that Alice intends to use to send the payment to Gloria.
This onion contains all the information about the path that Alice intends to use to send the payment to Dina.
However Bob who receives the onion cannot read all the information about the path as most of the onion is hidden from him through a sequence of encryptions.
The name onion comes from the analogy to an onion that consists of several layers. In our case every layer corresponds to one round of encryption.
Each round of encryption uses different encryption keys.
They are chosen by Alice in a way that only the rightful recipient of an onion can peel of (decrypt) the top layer of the onion.
For example after Bob received the onion from Alice he will be able to decrypt the first layer and he will only see the information that he is supposed to forward the onion to Wei by setting up an HTLC with Wei.
The HTLC with Wei should use the same Payment Hash as the receiving HTLC from Alice.
For example after Bob received the onion from Alice he will be able to decrypt the first layer and he will only see the information that he is supposed to forward the onion to Chan by setting up an HTLC with Chan.
The HTLC with Chan should use the same Payment Hash as the receiving HTLC from Alice.
The amount of the forwarded HTLC was specified in Bob decrypted layer of the onion.
It will be slightly smaller than the amount of his incoming HTLC from Alice.
The difference of these two amounts has to be at least as big as to cover the routing fees that Bob's node announced earlier on the gossip protocol.
In order to set up the HTLC Bob will modify the onion a little bit in a deterministic manner.
He removes the information that he could read from it and passes it along to Wei.
He removes the information that he could read from it and passes it along to Chan.
Wei in turn is only able to see that he is supposed to forward the package to Gloria.
Wei knows he received the onion from Bob but has no clue that it was actually Alice who initiated the onion in the first place.
Chan in turn is only able to see that he is supposed to forward the package to Dina.
Chan knows he received the onion from Bob but has no clue that it was actually Alice who initiated the onion in the first place.
In this way every participant is only able to peel of one layer of the onion by decrypting it.
Each participant will only learn the information it has to learn to fulfill the routing request.
For example Bob will explicitly be told that Alice offered him an HTLC and sent him an onion and that he is supposed to offer an HTLC to Wei and forward a slightly modified onion.
For example Bob will explicitly be told that Alice offered him an HTLC and sent him an onion and that he is supposed to offer an HTLC to Chan and forward a slightly modified onion.
Bob isn't explicitly told if Alice is the originator of this payment as she could also just have forwarded the payment to him.
Due to the layered encryption he cannot see the inside of Wei's, and Gloria's layer.
The only thing Bob is told explicitly is that he was involved in a path that involved Alice, him and Wei.
Due to the layered encryption he cannot see the inside of Chan's, and Dina's layer.
The only thing Bob is told explicitly is that he was involved in a path that involved Alice, him and Chan.
While the Onion is decrypted layer by layer while it travels along the path from Alice via Bob and Wei to Gloria it is created from the inside layer to the outside layers via several rounds of encryption.
Being created from the inside means that the construction starts with the Onion Package that Gloria is supposed to receive in plain text.
While the Onion is decrypted layer by layer while it travels along the path from Alice via Bob and Chan to Dina it is created from the inside layer to the outside layers via several rounds of encryption.
Being created from the inside means that the construction starts with the Onion Package that Dina is supposed to receive in plain text.
Let us now look at the construction of the Onion that Alice has to follow and at the exact information that is being put inside each layer of the onion.
The onions are a data structure that at every hop consists of four parts:
@ -449,7 +449,7 @@ A node needs three pieces of information to forward the package:
For easier readability we have used just a small integer as `short_channel_ids` in the following example and graphics.
[[routing-onion-1]]
.`per_hop` payload of Glorias onion and the encrypted
.`per_hop` payload of Dinas onion and the encrypted
image:images/routing-onion-1.png[]
We can see that Alice has created some per hop data for David.
@ -472,7 +472,7 @@ These arbitrary key-value pairs can be used to extend the protocol in an end-to-
In the next diagram we can see how the per hop payload for David looks like.
[[routing-onion-2]]
.`per_hop` payload of Glorias onion and the encrypted
.`per_hop` payload of Dinas onion and the encrypted
image:images/routing-onion-2.png[]
On important feature to protect the privacy is to make sure that onions are always of equal length in depend of their position along the payment path.
@ -489,7 +489,7 @@ As we want each node to use a new shared secret to authenticate and encrypt its
Rather than occupying space in the routing payload for N public keys, with this little trick, we're able to only include a single public key, which is used for ECDH at each step, and randomized in a deterministic manner for the next hop.
[[routing-onion-3]]
.`per_hop` payload of Glorias onion and the encrypted
.`per_hop` payload of Dinas onion and the encrypted
image:images/routing-onion-3.png[]
You can see that Alice put the encrypted payload inside the full Onion Package which contains the public keys from the secret key that she used to derive the shared secret.
@ -498,54 +498,54 @@ When David receives the Onion packet he will extract the public key from the une
David then uses ECDH to derive the shared secret using that ephemeral public key which he'll use to process the packet in full.
The properties of ECDH make is such that only Alice and David are able to derive the corresponding shared secret.
After the encrypted Onion for David is created Alice will create the next outer layer by creating the onion for Wei.
After the encrypted Onion for David is created Alice will create the next outer layer by creating the onion for Chan.
She truncates 65 Bytes from the end of the encrypted onion and prepends the truncated onion with 65 Byte per Hop data for Wei.
She truncates 65 Bytes from the end of the encrypted onion and prepends the truncated onion with 65 Byte per Hop data for Chan.
The per hop data follows the same structure as the per hop data for David.
Thus she starts with the Realm Byte that she will set to 0 again.
Then comes the short channel id.
This is set to 452 as Wei is meant to use the channel with this channel ID as the next outgoing channel.
This is set to 452 as Chan is meant to use the channel with this channel ID as the next outgoing channel.
She sets the amount to 3000 satoshi as this is the amount that David is supposed to receive.
Finally she uses the CLTV delta added to the current height that was announced for this channel on the gossip protocol and that Wei should use for the HTLC when he forwards the Onion.
Finally she uses the CLTV delta added to the current height that was announced for this channel on the gossip protocol and that Chan should use for the HTLC when he forwards the Onion.
Notice how this CTLV expiry (the expiry is the current height plus the delta) increase as we travel forwards (towards the sender) in the route.
As we'll see later, this series of decrementing time-locks must carefully be set in order to avoid time-based race conditions in the created contracts.
Again 12 Bytes of zeros are padded and an HMAC is computed.
Note that she did not have to compute filler this time as she already has too much data with the encrypted inner onion.
That is why the inner onion had to be truncated at the end.
This is the plain text version of Weis Onion payload and can be seen in the following diagram:
This is the plain text version of Chans Onion payload and can be seen in the following diagram:
[[routing-onion-4]]
.`per_hop` payload of Glorias onion and the encrypted
.`per_hop` payload of Dinas onion and the encrypted
image:images/routing-onion-4.png[]
We emphasize that Wei cannot decrypt the inner part of the onion (that's still encrypted from his PoV), as he cannot derive the encryption keys.
However the information for Wei should also be protected from others.
We emphasize that Chan cannot decrypt the inner part of the onion (that's still encrypted from his PoV), as he cannot derive the encryption keys.
However the information for Chan should also be protected from others.
Thus Alice conducts another ECDH.
This time with Wei's public key and the randomized ephemeral key pair.
This time with Chan's public key and the randomized ephemeral key pair.
She uses the shared secret to encrypt the onion payload.
She would be able to construct the entire onion for Wei - which actually Bob does while he forwards the onion.
The Onion that Wei would receive can be seen in the following diagram:
She would be able to construct the entire onion for Chan - which actually Bob does while he forwards the onion.
The Onion that Chan would receive can be seen in the following diagram:
[[routing-onion-5]]
.`per_hop` payload of Glorias onion and the encrypted
.`per_hop` payload of Dinas onion and the encrypted
image:images/routing-onion-5.png[]
Note that in the entire onion there will be Wei's ephemeral public key.
Note that in the entire onion there will be Chan's ephemeral public key.
We've omitted the details here for brevity, but notice how only a single ephemeral key is communicated.
During processing each node will re-randomize the ephemeral key for the following node.
Luckily the ephemeral keys that Alice used for the ECDH with David can be derived from the ephemeral key that she used for Wei.
Thus after Wei decrypts his layer he can use the shared secret and his ephemeral public key to derive the ephemeral public key that David is supposed to use and store it in the header of the Onion that he forwards to David.
Luckily the ephemeral keys that Alice used for the ECDH with David can be derived from the ephemeral key that she used for Chan.
Thus after Chan decrypts his layer he can use the shared secret and his ephemeral public key to derive the ephemeral public key that David is supposed to use and store it in the header of the Onion that he forwards to David.
The exact progress to generate the ephemeral keys for every hope will be explained at the very end of the chapter.
Similarly it is important to recognize that Alice removed data from the end of Davids onion payload to create space for the per hop data in Wei's onion.
Thus when Wei has received his onion and removed his routing hints and per hop data the onion would be to short and he somehow needs to be able to append the 65 Bytes of filled junk data in a way that the HMACs will still be valid.
Similarly it is important to recognize that Alice removed data from the end of Davids onion payload to create space for the per hop data in Chan's onion.
Thus when Chan has received his onion and removed his routing hints and per hop data the onion would be to short and he somehow needs to be able to append the 65 Bytes of filled junk data in a way that the HMACs will still be valid.
This process is of filler generation as well as the process of deriving the ephemeral keys is described in the end of this chapter.
What is important to know is that every hop can derive the Ephemeral Public key that is necessary for the next hop and that the onions save space by always storing only one ephemeral key instead of all the keys for all the hops.
Finally after Alice has computed the encrypted version for Wei she will use the exact same process to compute the encrypted version for Bob.
Finally after Alice has computed the encrypted version for Chan she will use the exact same process to compute the encrypted version for Bob.
For Bobs onion she actually computes the header and provides the ephemeral public key herself.
Note how Wei was still supposed to forward 3000 satoshis but How Bob was supposed to forward a different amount.
The difference is the routing fee for Wei.
Note how Chan was still supposed to forward 3000 satoshis but How Bob was supposed to forward a different amount.
The difference is the routing fee for Chan.
Bob on the other hand will only forward the onion if the difference between the mount to forward and the HTLC that Alice sets up while transferring the Onion to him is large enough to cover for the fees that he would like to earn.
[NOTE]
@ -556,7 +556,7 @@ For readers seeking more details with respect to the cryptographic algorithms us
====
[[routing-onion-6]]
.`per_hop` payload of Glorias onion and the encrypted
.`per_hop` payload of Dinas onion and the encrypted
image:images/routing-onion-6.png[]
Since we use the network itself for transport of these onion packets, Alice is able to construct the entire onion without needing to communicate directly with each node in the route.
@ -611,13 +611,13 @@ The innermost onion contains the error message and an HMAC for the error message
The process makes sure that the sender of the onion and recipient of the reply can be sure that the error really originated from the node that the error messages says.
Another important step in the process of handling errors is to abort the routing process.
We discussed that the sender of a payment cannot just remove the HTLC on the channel along which the sender sent the payment.
Recall for example the situation in which Alice sent and onion to Bob who set up an HTLC with Wei.
Recall for example the situation in which Alice sent and onion to Bob who set up an HTLC with Chan.
If Alice wanted to remove the HTLC with Bob this would put a financial risk on Bob.
He fears that his HTLC with Wei still might be fulfilled meaning that he could not claim the reimbursement from Alice.
Thus Bob would never agree to remove the HTLC with Alice unless he already has removed his HTLC with Wei.
If however the HTLC between Alice and Bob are set up and the HTLC between Bob and Wei are set up but Wei encounters problems with forwarding the onion it is perfectly Wei has more options than Alice.
While sending back the error Onion to Bob Wei could ask him to remove the HTLC.
Bob has no risk in removing the HTLC with Wei and Wei also has no risk as there is no downstream HTLC.
He fears that his HTLC with Chan still might be fulfilled meaning that he could not claim the reimbursement from Alice.
Thus Bob would never agree to remove the HTLC with Alice unless he already has removed his HTLC with Chan.
If however the HTLC between Alice and Bob are set up and the HTLC between Bob and Chan are set up but Chan encounters problems with forwarding the onion it is perfectly Chan has more options than Alice.
While sending back the error Onion to Bob Chan could ask him to remove the HTLC.
Bob has no risk in removing the HTLC with Chan and Chan also has no risk as there is no downstream HTLC.
Removing an HTLC is the reverse of adding one in the first place from the PoV the commitment transaction.
In the case of errors peers signals that they wish to remove the HTLC by sending an `update_fail_htlc` or `update_fail_malformed_htlc` message.
These messages contain the id of an HTLC that should be removed in the next version of the commit transaction.
Andreas M. Antonopoulos
3 years ago