From 482786062e7dfaee8129726d17b3901da10c072b Mon Sep 17 00:00:00 2001 From: lp74 Date: Sat, 13 Jun 2020 16:54:29 +0200 Subject: [PATCH 1/5] fix a typo (#238) --- 03_how_ln_works.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03_how_ln_works.asciidoc b/03_how_ln_works.asciidoc index 9e548c1..1349cd5 100644 --- a/03_how_ln_works.asciidoc +++ b/03_how_ln_works.asciidoc @@ -289,7 +289,7 @@ The output of your channel partner is not encumbered with a time lock and can be The on-chain fees will be higher than in "the good way" of the mutual close for several reasons: * The most obvious reason is that when the commitment transaction was negotiated you and your channel partner didn't know how high the on-chain fees will be at the future time the "force close" is taking place. -As the fees cannot be changed without reasigning outputs of the commitment transaction which needs two signatures and as the force close usually happens in an urgent situation, the protocol developers decided to be very generous with the fee rate included in the commitment transactions. It can be up to 5 times higher than the fee estimators suggest at the time the commitment transaction is negotiated. +As the fees cannot be changed without reassigning outputs of the commitment transaction which needs two signatures and as the force close usually happens in an urgent situation, the protocol developers decided to be very generous with the fee rate included in the commitment transactions. It can be up to 5 times higher than the fee estimators suggest at the time the commitment transaction is negotiated. * The pending routing attempts in the commitment transaction are encoded as additional outputs which take up additional on-chain transaction space. * The pending routing attempts will have to be resolved on-chain causing additional on-chain spend transactions. These additional spend transactions don't have to overestimate the fees but they nonetheless incur costs. From 53c49f309db4fac135c0742dd148c4cd0b1af4c4 Mon Sep 17 00:00:00 2001 From: HAOYUatHZ <37070449+HAOYUatHZ@users.noreply.github.com> Date: Sat, 13 Jun 2020 22:54:53 +0800 Subject: [PATCH 2/5] add Haoyu into contributor list (#236) --- preface.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/preface.asciidoc b/preface.asciidoc index 9f41348..0ba6c46 100644 --- a/preface.asciidoc +++ b/preface.asciidoc @@ -181,6 +181,7 @@ Following is an alphabetically sorted list of all the GitHub contributors, inclu * Doru Muntean (@chriton) * Eduardo Lima III (@elima-iii) * Emilio Norrmann (@enorrmann) +* Haoyu Lin (@HAOYUatHZ) * Hatim Boufnichel (@boufni95) * Imran Lorgat (@ImranLorgat) * Kory Newton (@korynewton) From d7143f3e72b638f81e1773176e02bcf23477dc82 Mon Sep 17 00:00:00 2001 From: Josh Akeman Date: Sat, 13 Jun 2020 09:55:35 -0500 Subject: [PATCH 3/5] removed an extra 'the' in this sentence (#239) --- 01_introduction.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/01_introduction.asciidoc b/01_introduction.asciidoc index b48c689..c5596d5 100644 --- a/01_introduction.asciidoc +++ b/01_introduction.asciidoc @@ -18,7 +18,7 @@ Because blockchains are gossip protocols, each node is required to know and vali [NOTE] ==== -The side effects of increasing the block size or the decreasing the block time with respect to centralization of the network are severe as a few calculations with the numbers show. +The side effects of increasing the block size or decreasing the block time with respect to centralization of the network are severe as a few calculations with the numbers show. Let us assume the usage of Bitcoin grows so that the network has to process 40,000 transactions per second. Assuming 250 Bytes on average per transaction this would result in a data stream of 10 Megabyte per second or 80 Mbit/s just to be able to receive all the transactions. This does not include the traffic overhead of forwarding the transaction information to other peers. From e485dc8f098a73d5021e5c450648b3844aebe6b1 Mon Sep 17 00:00:00 2001 From: Josh Akeman Date: Sat, 13 Jun 2020 09:57:14 -0500 Subject: [PATCH 4/5] Joshakeman (#240) * removed an extra 'the' in this sentence * suggested rephrasing of an unclear sentence in bullet five under What is the Lightning Network? * fixed typo in own edit * bolded headers in Table 1 and 2 of Getting Started * fixed typo (reasigning should be reassigning) * fixed typo (later should be latter) * fixed typo (node_announcment should be node_announcement) * fixed typo, crucually should be crucially * fixed typo (abroated should be aborted) * fixed typo (subsecquent should be subsequent) * fixed typo (discoveres should be discovers) * removed extra 'the' in sentence * fixed typo (send should be sent) * fixed typo (nods should be nodes ) --- 01_introduction.asciidoc | 2 +- 02_getting_started.asciidoc | 2 ++ 03_how_ln_works.asciidoc | 16 ++++++++-------- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/01_introduction.asciidoc b/01_introduction.asciidoc index c5596d5..2ce8a11 100644 --- a/01_introduction.asciidoc +++ b/01_introduction.asciidoc @@ -70,7 +70,7 @@ The Lightning Network is a network that operates as a "second layer" protocol on * Users who exchange value over the Lightning Network do not need to wait for block confirmations for payments. * Once a payment on the Lightning Network has completed, usually within a few seconds, it is final and cannot be reversed. Like a Bitcoin transaction, a payment on the Lightning Network can only be refunded by the recipient. * While "on-chain" Bitcoin transactions are broadcast and verified by all nodes in the network, payments routed on the Lightning Network are transmitted between pairs of nodes and are not visible to everyone, resulting in much greater privacy. - * Unlike transactions on the Bitcoin Network, payments routed on the Lightning Network do not need to be stored permanently. This makes Lightning use less resources, and hence cheaper, as well as more private. + * Unlike transactions on the Bitcoin Network, payments routed on the Lightning Network do not need to be stored permanently. Lightning thus uses fewer resources, hence it is cheaper. This property also has benefits for privacy. * The Lightning Network uses onion routing, similar to the protocol used by The Onion Router (TOR) privacy network, so that even the nodes involved in routing a payment are only directly aware of their predecessor and successor in the payment route. [[user-stories]] diff --git a/02_getting_started.asciidoc b/02_getting_started.asciidoc index 504c6d7..ea330ac 100644 --- a/02_getting_started.asciidoc +++ b/02_getting_started.asciidoc @@ -40,6 +40,7 @@ In <> we see the three broad categories of lightning wallet [[lnwallet-categories]] .Broad Categories of "Lightning Wallets" +[options="header"] |=== | Wallet Type | LN Node | Keystore/Custody | Technical Skill | Full Node & Wallet | Full Node | Non-Custodial | High @@ -54,6 +55,7 @@ In <> we see some examples of currently popular Lightning nod // TODO: Add a lot more wallet/node examples, confirm the details for correctness [[lnwallet-examples]] .Examples of Popular LN Wallets +[options="header"] |=== | Application | Device | LN Node | Bitcoin Node | Keystore | lnd | Server | Full Node | Bitcoin Core/btcd | User Control diff --git a/03_how_ln_works.asciidoc b/03_how_ln_works.asciidoc index 1349cd5..245504c 100644 --- a/03_how_ln_works.asciidoc +++ b/03_how_ln_works.asciidoc @@ -328,7 +328,7 @@ While Lightning Nodes usually use the encrypted communication channels over the This could be via a Webservice or Email. Invoices are usually encoded either as long bech32 strings or as QR codes which enables them to be easily scanned by smartphones. Obviously the invoices contains the amount of bitcoin that is requested and a signature of the payee. -The later is used to extract the address of the payee so that the payer knows whom to send the money. +The latter is used to extract the address of the payee so that the payer knows whom to send the money. Besides some other meta data the most important but not quite obvious data in the invoice is a Payment Hash. ==== Payment Hash @@ -362,7 +362,7 @@ After opening a channel a node will send out an announcement of the channel via Every peer can validate the information from the `channel_announcement` message and verify that the funding transaction was indeed confirmed by the Bitcoin network. Upon verification the node will forward the gossip message to its peers. In order to avoid spam this will only be done if the message was not forwarded by that node already. -Similarly nodes can be announced via the gossip protocol with the `node_announcment` message. +Similarly nodes can be announced via the gossip protocol with the `node_announcement` message. For this message to be forwarded a node has to have at least one public channel that was announced on the gossip protocol. This again is a spam reduction measure of the gossip protocol. Payment channels have various meta data that are useful for other participants of the network. @@ -372,7 +372,7 @@ These messages will only be forwarded about four times a day for every channel t The gossip protocol also comes with a variety of queries and tools to initially synchronize a node with the view of the network or to update the node's view after being offline for a while. We will investigate the details of the gossip protocol in a later chapter. For now it is only important to know that it exists and that it is used to share topology information of the Lightning Network with its participants. -This topology information is crucually needed for delivering payments through the network of payment channels. +This topology information is crucially needed for delivering payments through the network of payment channels. [NOTE] ==== @@ -452,14 +452,14 @@ Upon receiving a Lightning Message called `update_add_htlc` which contains the ` 5. It will then follow the routing hints from its layer of the onion to forward the modified onion package on its outgoing payment channel by also sending and `update_add_htlc` message which includes the same `Payment Hash` and the onion. 6. Obviously it also has to collaborate with its peer on the outgoing channel to move foward the state to also include the offered `HTLC`. -Of course those steps will be interrupted and abroated if an error is detected. +Of course those steps will be interrupted and aborted if an error is detected. In most of those cases an error message will be send back to the originator of the received `update_add_htlc` message. -If for example in the first step the node detects that the onion was corrupted it will not proceed to the second and subsecquent steps to move forward the channel state on the receiving channel to include the HTLC. -Similarly if in the second step the node discoveres that it won't be able to fulfill the routing request or that the not enough fees have been included it will also abort the payment forwarding algorithm and rather send back an error. +If for example in the first step the node detects that the onion was corrupted it will not proceed to the second and subsequent steps to move forward the channel state on the receiving channel to include the HTLC. +Similarly if in the second step the node discovers that it won't be able to fulfill the routing request or that not enough fees have been included it will also abort the payment forwarding algorithm and rather send back an error. We node that the error is also an onion reply package. Even though the node sending the error does not know who initially sent out the payment the error message will be encrypted with the key that was used to encrypt the forwarding nodes layer. -The reply onion is then send back on the incoming channel. +The reply onion is then sent back on the incoming channel. The node on the other side knows on which channel it received an onion and with which other channel it has an HTLC with the same `Payment Hash`. Thus the error can safely propagate back towards the originator. Nodes that are sending back an error Onion must on their way remove the HTLCs from their payment channels to make sure that they cannot be enforced. @@ -468,7 +468,7 @@ Nodes that are sending back an error Onion must on their way remove the HTLCs fr ==== It is important to understand that HTLCs have a time measured in absolute blockheight through which they are valid. Once the sender of a payment sends away the onion it is completely out if their controll what happens. -Honest nods SHOULD either forward the onion as quickly as possible or send an error back the original. +Honest nodes SHOULD either forward the onion as quickly as possible or send an error back the original. While sender expects nodes along the path to be honest it has according to the protocol no power of making sure that nodes act quickly. Thus payment can currently get stuck if nodes want to behave malicously. While the likelihood for a payment to fail is pretty high if it does not settle quickly a node SHOULD never initate another payment attempt along a different path before the onion returned with an error as a node might just have delayed the forwarding of the payment. From 8aac9f57c56a31e22b24c1fd61a640184cea841d Mon Sep 17 00:00:00 2001 From: 8go Date: Sat, 13 Jun 2020 15:04:41 +0000 Subject: [PATCH 5/5] change wallet categories into wallet quadrant (#213) * change wallet categories into wallet quadrant The original categorization was not perfect. It was not ideal. It was sort of misleading. It sort of implies that a "Full Node & Wallet" is not a "Non-Custodial Wallet" because they are 2 different categories. It also states that a "Non-Custodial Wallet" uses "3rd-party node" for LN Node which is not the true definition.Things were getting mixed up here and we are not communicating a clear message. The term "Custodial Wallet" is independent of which LN Node is used. We should rethink this table and categorization. I wrote an Issue about it #176 . The Quadrant seems to be more useful and certainly more accurate. Then I explained the terms "Lightweight" and "Node" because these terms were suddenly used, out of nowhere with no explanation. * various improvements - Following suggestions from @Roasbeef - worked in his commentaries, ideas - also added a bit more details * added BIPs to Neutrino Co-authored-by: Rene Pickhardt --- 02_getting_started.asciidoc | 52 +++++++++++++++++++++++++++---------- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/02_getting_started.asciidoc b/02_getting_started.asciidoc index ea330ac..d94fbd5 100644 --- a/02_getting_started.asciidoc +++ b/02_getting_started.asciidoc @@ -36,20 +36,46 @@ If users decide to outsource some functionality to a third party they usually gi Finally, those seeking simplicity and convenience, even at the expense of control and security, may choose a custodial Lightning wallet. This is the least technically challenging option, but it _undermines the trust model of cryptocurrency_ and should therefore be considered only as a stepping stone towards more control and self-reliance. -In <> we see the three broad categories of lightning wallets and the relative degree of control they offer to the user. +There are many ways wallets can be characterized or categorized. +The most important questions to ask about a specific wallet are: + +- Does this Lightning wallet have a full LN Node or does it use a third-party LN Node? +- Does this Lightning wallet have a full Bitcoin Node or does it use a third-party Bitcoin Node? footnote:[If a Lightning wallet uses a third-party Lightning node, it is this third-party Lightning node who decides how to communicate with Bitcoin. Hence, using a third-party Lightning node implies that you as a wallet user also use a third-party Bitcoin node. Only in the other case, when the Lightning wallet uses its own Lightning node, does the choice "full Bitcoin-node" vs. "thrid-party Bitcoin node" exist. ] +- Does this Lightning wallet store its own keys under user control (self-custody) or are the keys held be a third-party custodian? + +At the highest level of abstraction, question 1 and 3 are the most elementary ones. +From these two questions we can derive four possible categories. +We can place these four categories into a quadrant as seen in Table <>. +But remember that this is just one way of categorizing Lightning wallets. [[lnwallet-categories]] -.Broad Categories of "Lightning Wallets" +.Lightning Wallets Quadrant [options="header"] |=== -| Wallet Type | LN Node | Keystore/Custody | Technical Skill -| Full Node & Wallet | Full Node | Non-Custodial | High -| Non-Custodial Wallet | 3rd-party node | Non-Custodial | Medium -| Custodial Wallet | 3rd-party node | Custodial | Low +| | *Full LN Node* | *3rd-party LN Node* +| *Self-Custody* | Q1: High technical skill, least trust in 3rd parties, most permissionless | Q2: Below medium technical skills, below medium trust in 3rd parties, requires some permissions +| *Custodial* | Q3: Above medium technical skills, above medium trust in 3rd parties, requires some permissions | Q4: Low technical skills, high trust in 3rd parties, least permissionless |=== +Q3, quadrant 3, where a full LN node is used but the keys are held by a custodian is currently not common. +Future wallets from that quadrant would let a user worry about the operational aspects of their node, but then delegate the access to the keys to a third party which may use primarily cold storage. + Lightning wallets can be installed on a variety of devices, including laptops, servers, and mobile devices. To run a full Lightning node (one that participates in "gossip" and creates its own map of the network for path finding and routing) you will need to use a server or desktop computer, as mobile devices and laptops are usually not powerful enough in terms of capacity, processing, battery life, and connectivity. +The category "Third-party Ligntning Nodes" can again be subdivided into: + +- Lightweight: means that the Lightning Node is operated by a third party and that the wallet obtains the required information through an API that connects wallet and third-party LN node. +- None: means that not only is the Lightning Node operated by a third party but most of the wallet is operated by a third party in the cloud such that the wallet does not even need to make calls on a Lightning node API. + +These subcategories are used in Table <>. + +Other terms that need explanation in Table <> in column "Bitcoin Node" are: + +- Neutrino: Neutrino is a specific implementation of a protocol to get data from Bitcoin as outlined in BIP 157 and BIP 158. The Bitcoin Node is run by a third-party and accessed via "neutrino". +- Electrum: This means the wallet connects to an Electrum Server. The Bitcoin Node is run by a third-party and accessed via the "Electrum" protocol. +- Bitcoin Core: implementation of Bitcoin full node +- btcd: another implementation of Bitcoin full node + In <> we see some examples of currently popular Lightning node and wallet applications for different types of devices. // TODO: Add a lot more wallet/node examples, confirm the details for correctness @@ -58,13 +84,13 @@ In <> we see some examples of currently popular Lightning nod [options="header"] |=== | Application | Device | LN Node | Bitcoin Node | Keystore -| lnd | Server | Full Node | Bitcoin Core/btcd | User Control -| c-lightning | Server | Full Node | Bitcoin Core | User Control -| Eclair Server | Server | Full Node | Bitcoin Core/Electrum | User Control -| Zap Desktop | Desktop | Full Node | Bitcoin Core/btcd | User Control -| Eclair Mobile | Mobile | Lightweight | Electrum | User Control -| Breez Wallet | Mobile | Full Node | Bitcoin Core/btcd | User Control -| Phoenix Wallet | Mobile | Lightweight | Electrum | User Control +| lnd | Server | Full Node | Bitcoin Core/btcd | Self-Custody +| c-lightning | Server | Full Node | Bitcoin Core | Self-Custody +| Eclair Server | Server | Full Node | Bitcoin Core/Electrum | Self-Custody +| Zap Desktop | Desktop | Full Node | Neutrino | Self-Custody +| Eclair Mobile | Mobile | Lightweight | Electrum | Self-Custody +| Breez Wallet | Mobile | Full Node | Neutrino | Self-Custody +| Phoenix Wallet | Mobile | Lightweight | Electrum | Self-Custody | Blue Wallet | Mobile | None | None | Custodial |===