Archives/lnbook
2
0
Fork 0
mirror of https://github.com/lnbook/lnbook synced 2024-11-04 18:00:26 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'develop' of https://github.com/lnbook/lnbook into develop

Browse Source
This commit is contained in:
Rene Pickhardt 2020-12-08 16:32:08 +01:00
commit c85af67476
4 changed files with 96 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
channel-operation.asciidoc
View File

@ -9,7 +9,7 @@ We are finally at the point to explain the communications protocol via Lightning
The same protocol will be executed along a path of channels if the network of channels is being utilized to make a payment between two participants without requiring them to have a dedicated payment channel connecting them directly.
Let us start with the payment channel with a capacity of 100 mBTC between Alice and Bob.
at its current state Alice and Bob have agreed that 20 mBTC belong to Bob and 80 mBTC belong to Alice.
At its current state Alice and Bob have agreed that 20 mBTC belong to Bob and 80 mBTC belong to Alice.
As Alice bought a coffee flatrate for the week she has to pay 15 mBTC to Bob and wants to use this channel.
Just creating a new pair of commitment transactions and signing them is not so easy as the old ones have to be invalidated by sharing the revocation secret.
This process should be executed in a way that it is atomic meaning the nodes will either be able to negotiate a new state without giving the other side the chance to play tricks or it should fail.
@ -31,20 +31,20 @@ The message type is 128 and has the following data fields:
As Bob and Alice might have more than one channel thus the `channel_id` is included to the message.
The `id` counter counts starts with 0 for the first HTLC that Alice offers to Bob and is increased by 1 with every subsequent offer.
The id of the HTLC is used to compute the derivation path of the bitcoin key that is used for the output of this particular HTLC.
In this way addresses changes with every payment and cannot be monitored by a third party.
In this way addresses change with every payment and cannot be monitored by a third party.
Next the amount that Alice wants to send to Bob is entered to the `amount_msat` field.
As the name suggests the amount is depicted in millisatoshi even those cannot be enforced within the commitment transaction and within bitcoin.
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 Gloria the payment hash would have been given to Alice by Gloria.
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.
Finally in the last data field there are 1336 Bytes of data included which is an `onion routing packet`.
The format of this packet will be discussed in the last section of this chapter.
For now it is important to note that it includes encrypted routing hints and information of the payment path that can only be partially decrypted by the recipient of the onion routing packet to extract information to whom to forward the payment or to learn that one as the final recipient.
In any case the onion roting packet is always of the same size preventing the possibility to guess the position of an intermediary node within a path.
In any case the onion routing packet is always of the same size preventing the possibility to guess the position of an intermediary node within a path.
In our particular case Bob will be able to decrypt the first couple bytes of the onion routing packet and learn that the payment is not to be forwarded but intended to be for him.
The received information is enough for Bob to create a new commitment transaction.
@ -105,16 +105,16 @@ It has 4 data fields:
First it again states which for which of the channels between Alice and Bob this message is intended.
Then it has included a signature for the entire commitment transaction.
As commitment transactions can have several HTLCs and HTLC success transactions need signatures which might not be provided at the time when they are needed those signatures are all already send over to Bob.
As commitment transactions can have several HTLCs and HTLC success transactions need signatures which might not be provided at the time when they are needed those signatures are all already sent over to Bob.
If all signatures are valid Bob has a new commitment transaction.
At this time he would be able to publish either the old one or the new one without getting a penality as the old one is not yet revoked and invalidated.
However this is save for Alice as Bob has less money in this old state and is economically not incentivised to publish the old commitment transaction.
However this is safe for Alice as Bob has less money in this old state and is economically not incentivised to publish the old commitment transaction.
Alice on the other side has no problem if Bob publishes the new commitment transaction as she wanted to send him money.
If Bob can provide the preimage he is by their agreement and expectation entitled to claim the HTLC output.
Should Bob decide to sabotage to future steps of the protocol Alice can either publish her commitment transaction without Bob being able to punish her.
Should Bob decide to sabotage to future steps of the protocol Alice can publish her commitment transaction without Bob being able to punish her.
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 seen his HTLC as being set up successfully.
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.
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.
@ -136,7 +136,7 @@ Alice checks that the `per_commitment_secret` produces the last `per_commitment_
Alice's version of the HTLC output is slightly different to the one that Bob had.
The reason is the asymmetries of the penalty based payment channel construction protocol.
Alice is offering in her commitment transaction an HTLC to the `remote` partner of the channel while Bob as accepting and offered HTLC to himself the `local` partner of the channel.
Thus the Bitcoin script is adopted slightly.
Thus the Bitcoin script is adapted slightly.
It is a very good exercise to go through both scripts and see where they differ.
You could also try to use Bob's HTLC output script to come up with Alice's and vice versa and check your result with the following script.
@ -196,7 +196,7 @@ Finally in the last field Bob provides the `payment_preimage` which Alice can ch
[WARNING]
====
When designing, implementing or studying a protocol one should ask: Is it safe to this or that in this moment of the protocol and can this be abused. We discussed for example the messages that where necessary for an HTLC to become valid. We pointed out that Bob should not see the received HTLC as valid even though he already has a new commitment transaction with signatures and invalidated his old commitment transaction before Alice also revoked her old commitment transaction. We also saw that no one is able to mess with the protocol of setting up a commitment transaction as in the worst case the protocol could be aborted and any dispute could be resolved by the Bitcoin Network. In the same way we should ask ourselves is it safe for Bob to just send out and release the preimage even though neither he nor alice have created the new pair of commitment transactions in which the HTLCs are removed. It is important to take a short break and ask yourself if Bob will in any case be able to claim the funds from the HTLC if the preimage is correct?
When designing, implementing or studying a protocol one should ask: Is it safe to this or that in this moment of the protocol and can this be abused. We discussed for example the messages that where necessary for an HTLC to become valid. We pointed out that Bob should not see the received HTLC as valid even though he already has a new commitment transaction with signatures and invalidated his old commitment transaction before Alice also revoked her old commitment transaction. We also saw that no one is able to mess with the protocol of setting up a commitment transaction as in the worst case the protocol could be aborted and any dispute could be resolved by the Bitcoin Network. In the same way we should ask ourselves is it safe for Bob to just send out and release the preimage even though neither he nor Alice have created the new pair of commitment transactions in which the HTLCs are removed. It is important to take a short break and ask yourself if Bob will in any case be able to claim the funds from the HTLC if the preimage is correct?
====
It is safe for Bob to tell Alice the preimage.

12
node_client.asciidoc
View File

@ -699,8 +699,8 @@ go version go1.13.4 linux/amd64
We have 1.13.4, so we're ready to... Go! Next we need to tell any programs where to find the Go code. This is accomplished by setting the environment variable +GOPATH+. Usually the Go code is located in a directory named +gocode+ directly in the user's home directory. With the following two commands we consistently set the +GOPATH+ and make sure your shell adds it to your executable +PATH+. Note that the user's home directory is referred to as +~+ in the shell.
----
export GOPATH=~/gocode
export PATH=$PATH:$GOPATH/bin
$ export GOPATH=~/gocode
$ export PATH=$PATH:$GOPATH/bin
----
To avoid having to set these environment variables every time you open a shell, you can add those two lines to the end of your bash shell configuration file +.bashrc+ in your home directory, using the editor of your choice.
@ -720,8 +720,8 @@ Once +go get+ finishes, you will have a sub-directory under +GOPATH+ that contai
LND uses the +make+ build system. To build the project, we change directory to LND's source code and then use +make+ like this:
----
cd $GOPATH/src/github.com/lightningnetwork/lnd
make && make install
$ cd $GOPATH/src/github.com/lightningnetwork/lnd
$ make && make install
----
After several minutes you will have two new commands +lnd+ and +lncli+ installed. Try them out and check their version to ensure they are installed:
@ -835,7 +835,7 @@ In this section we will build Eclair from scratch. Eclair is written in the Scal
https://github.com/ACINQ/eclair/blob/master/BUILD.md
The required Java compiler is part of OpenJDK 11. We will also need a buid framework called Maven, version 3.6.0 or above.
The required Java compiler is part of OpenJDK 11. We will also need a build framework called Maven, version 3.6.0 or above.
On a Debian/Ubuntu Linux system we can use the +apt+ command to install both OpenJDK11 and Maven as shown below:
@ -862,7 +862,7 @@ We have OpenJDK 11.0.7 and Maven 3.6.1, so we're ready.
The source code for Eclair is on Github. The +git clone+ command can create a local copy for us. Let's change to our home directory and run it there:
----
$ cd
$ cd ~
$ git clone https://github.com/ACINQ/eclair.git
----

76
p2p.asciidoc
View File

@ -46,3 +46,79 @@ Relevant questions to answer:
- How can TLV fields be used to extend the protocol, existing messages, and the onion itself?
- Sidenote that TLV can be used by upcoming Instant Messaging chat apps like `Whatsat`, `Sphinx Chat` or `Juggernaut`
### Feature Bits
#### What is are Feature Bits and why do we need them?
Feature bits, or feature flags, are a string of 1s and 0s that Lightning nodes use to communicate to each other which features and upgrades they have enabled.
But why would they need to do this?
As discussed in earlier chapters, the Lightning Network protocol does not require all nodes to be in agreement on a common ruleset and list of features, which is quite different to the Bitcoin protocol.
If someone wants to introduce a new feature into Bitcoin (such as Replace-by-Fee) then either all nodes will need to accept this feature or the feature needs to be backwards-compatible.
However, if a new feature is introduced into the Lightning Network, Lightning users don't need to wait for the rest of the network to upgrade.
They can start using the new feature immedietely.
Even if that feature is still in development, they can implement it as long as they can find other users willing to implement the feature along with them
footnote:[The Lightning Network itself was famously put into use before it's official "launch". Despite LN developers warning users that the software was still in beta and had bugs, users around the world set up their own nodes and used the software recklessly].
One example of a feature would be multi-part payments, discussed in the chapter on Path-Finding.
Despite being a feature still in development at the time of writing, it was already deployed by some nodes.
Given the inherent freedom in the Lightning Network's design there will never be a global consensus on the Lightning Network as to which features are supported and which aren't.
Some nodes may support multi-part payments, some may not, and some may never decide to support them.
As such, nodes need of a way of signalling to each other which features they support and which they do not.
They do so using pairs of 1s and 0s called Feature Bits.
#### How do Feature Bits work?
Whenever nodes communicate with each other, whether through invoices or other methods, a part of that message is reserved to signal which features the node has enabled.
For example, the `channel_announcement` and `node_announcement` messages described in BOLT #7 have a predefined `features` field reserved for this information.
The `features` field will take the form of a string of paired bits that will look something like this:
[feature-bits-example]
----
00101000001000000000
----
Flags are numbered from the least-significant bit (i.e. from right from left), starting from 0.
Flags are also paired, so that bits 0 and 1 form a pair, 2 and 3 form a pair, and so on.
BOLT #9 contains the full list of which digits stand for which features
footnote:[https://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md].
An odd-numbered bit pair (01) communicates that the feature is backwards-compatible.
An even-numbered bit pair (10) communicates that the feature is mandatory.
The rule of thumb is: "it's ok to be odd".
Using BOLT #9 we can break down the above string as follows:
[[feature-bits-breakdown]]
.Breakdown of a feature bit string
[options="header"]
|===
| Bit Number | Feature | Feature Bits | Status
| 0/1 | `option_data_loss_protect` | 00 | Not enabled
| 2/3 | `initial_routing_sync` | 00 | Not enabled
| 4/5 | `option_upfront_shutdown_script` | 00 | Not enabled
| 6/7 | `gossip_queries` | 00 | Not enabled
| 8/9 | `var_onion_optin` | 01 | Enabled (Backwards-Compatible)
| 10/11 | `gossip_queries_ex` | 00 | Not enabled
| 12/13 | `option_static_remotekey` | 00 | Not enabled
| 14/15 | `payment_secret` | 01 | Enabled (Backwards-Compatible)
| 16/17 | `basic_mpp` | 01 | Enabled (Backwards-Compatible)
| 18/19 | `option_support_large_channel` | 00 | Not enabled
|===
If Alice sees this string in a node announcement message from Bob's node, then she knows from bits 16 and 17 that Bob's node supports multi-part payments.
And because the pair is odd, Alice knows that the feature is backwards-compatible.
If Alice also has multi-part payments enabled, then Alice and Bob can make use of this feature.
If Alice does not have multi-part payments enabled, she can simply ignore this and get on with her life.
She could still open a channel with Bob without having the feature enabled herself.
However, if the feature bits were even then the feature would be mandatory.
If Alice did not also have this feature enabled, she would have to find another node to open a channel with.
Alice also knows from bits 18 and 19 that Bob does not have large channels enabled.
If she would like to open a large channel, then she would have to find someone else who has large channels enabled to open it with.
In this way, upgrades and new features can be rolled out on the Lightning Network in an asynchronous bottom-up way.
Users can enable the features they want when they are ready to do so.
Power users can use and test features without waiting for them to be formally released, and more conservative users are not pressured into using a new feature before they are comfortable to do so.
Users can simply signal to each other which features they support, and even if they do not agree on the feature set, they can still connect and transact as long they agree on all mandatory features.

8
routing.asciidoc
View File

@ -2,10 +2,10 @@
== Routing on a Network of Payment channels
In this section we will finally unpack how payment channels can be connected to a network of other payment channels via a process called _routing_.
Note that we separate the concept of _routing_ from the concept of _path finding_.
Routing refers to the series of interactions across the network that allow a payment to _flow_ from point A to point B, i.e. the _active_ process of process of sending a payment.
Routing refers to the series of interactions across the network that allow a payment to _flow_ from point A to point B, i.e. the _active_ process of sending a payment.
An important rule of thumb is that it's possible for a _path_ to exist between Alice and Bob, 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 theory, one can examine the _channel graph_ and connect a series of payment channels from Alice to Beb, hence a _path_ exists.
In theory, 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.
The innovation of routed payment channels allows our gamer Gloria to receive funds from her fans without maintaining a separate channel with every one of her fans who want to tip her.
@ -86,7 +86,7 @@ _I (Alice) will reimburse you (Bob) with 10 gold coins if you can prove to me (f
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 abd Wei must _already_ have 10 gold coins to send, otherwise they wouldn't be able to participate in the contract.
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.
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.
@ -250,7 +250,7 @@ The combination of the condition, and a timeout on the condition gives the payme
=== Conditional Chained Payment ===
Building upon our conditional payment, it may be possible to *chain* this payment, allowing it to involve the payer, the payee, and possibly several intermediaries.
Each intermediary, is able to present a _slightly_ modified version of the condition (without invalidating it all together), and so so in an iterated manner until the conditional payment reaches the payee.
Each intermediary, is able to present a _slightly_ modified version of the condition (without invalidating it all together), and so on in an iterated manner until the conditional payment reaches the payee.
Once it reaches the payee, then the payment should be able to be _iteratively_ resolved, starting at the payee all the way back to the payer.
Each chaining creates an "incoming" and "outgoing" conditional payment.