From 68ebd75d5b6b98cc30fc6848f22885686670d50a Mon Sep 17 00:00:00 2001 From: jerzybrzoska <51721153+jerzybrzoska@users.noreply.github.com> Date: Mon, 28 Dec 2020 19:42:53 +0100 Subject: [PATCH 1/2] Consistency in spelling out the numbers that are < 10 It would be well to maintain consistency in spelling out the numbers (provided that they are not code/math/ BTC amounts) that are < 10. I left out "chapter 6" and the like unchanged. [A post about style][1] for the reference. >In scientific and technical writing, the prevailing style is to write out numbers under ten. While there are exceptions to these rules, your predominant concern should be expressing numbers consistently. [1]: https://www.grammarly.com/blog/when-to-spell-out-numbers/ --- 03_how_ln_works.asciidoc | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/03_how_ln_works.asciidoc b/03_how_ln_works.asciidoc index 7b33952..b6ae709 100644 --- a/03_how_ln_works.asciidoc +++ b/03_how_ln_works.asciidoc @@ -22,7 +22,7 @@ A payment channel is a _financial relationship_ between two nodes on the Lightni The payment channel is managed by a _cryptographic protocol_, meaning a pre-defined process based on cryptography, used by the channel partners to re-distribute the balance of the channel in favor of one or the other channel partner. The cryptographic protocol ensures that one channel partner cannot cheat the other, so that the partners do not need to trust each other. -The cryptographic protocol is established by the funding of a 2-of-2 _multi-signature address_ that requires the two channel partners to cooperate and prevents either channel partner from spending the funds unilaterally. +The cryptographic protocol is established by the funding of a two-of-two _multi-signature address_ that requires the two channel partners to cooperate and prevents either channel partner from spending the funds unilaterally. To summarize: @@ -30,7 +30,7 @@ A payment channel is a financial relationship between nodes, allocating funds fr === Payment channels basics -Underlying the payment channel is simply a 2-of-2 multisignature address on the Bitcoin blockchain, for which you hold one key and your channel partner holds the other key. +Underlying the payment channel is simply a two-of-two multisignature address on the Bitcoin blockchain, for which you hold one key and your channel partner holds the other key. You and your channel partner negotiate a sequence of transactions that spend from this multisignature address. Instead of transmitting and recording these transactions on the Bitcoin blockchain, you both hold on to them, unspent. @@ -43,7 +43,7 @@ The smart contract is set up to penalize a channel member if they try to submit [NOTE] ==== -If you have an unpublished transaction from a 2-of-2 multisignature address, that pays you part of the balance, then a signature from the other party ensures that you can independently publish this transaction anytime by adding your own signature. +If you have an unpublished transaction from a two-of-two multisignature address, that pays you part of the balance, then a signature from the other party ensures that you can independently publish this transaction anytime by adding your own signature. The ability to hold a partially-signed transaction, offline and unpublished, with the option to publish and own that balance at any time, is the basis of the Lightning Network. ==== @@ -95,7 +95,7 @@ Payment channels have a few very interesting and useful properties: * Payments made in a payment channel are only known to you and your partner. In that sense, you gain privacy compared to Bitcoin, where every transaction is public. Only the final balance, which is the aggregate of all payments in that channel, will become visible on the Bitcoin blockchain. -Bitcoin was about 5 years old when talented developers first figured out how payment channels could be constructed and by now there are at least 3 different methods known. +Bitcoin was about five years old when talented developers first figured out how payment channels could be constructed and by now there are at least three different methods known. This chapter will focus on the channel construction method first described in the Lightning Network whitepaper by Joseph Poon and Thaddeus Dryja in 2015. These are known as _Poon-Dryja_ channels, and are the channel construction method currently used in the Lightning Network. The other two proposed methods are _Duplex Micropayment_ channels, introduced by Christian Decker around the same time as the "Poon-Dryja" channels and _eltoo_ channels, introduced in 2018 by Christian Decker, Rusty Russel and (author of this book) Olaoluwa Osuntokun. @@ -103,7 +103,7 @@ Eltoo channels have some interesting properties and simplify the implementation ==== Multisig addresses -Payment channels are built on top of 2-of-2 multisignature addresses, timelocks and Segregated Witness transaction outputs. We will not revise these relatively advanced concepts of the Bitcoin system. Instead, in this section we will provide a high-level overview of multisignature scripts and how they allow us to construct payment channels. +Payment channels are built on top of two-of-two multisignature addresses, timelocks and Segregated Witness transaction outputs. We will not revise these relatively advanced concepts of the Bitcoin system. Instead, in this section we will provide a high-level overview of multisignature scripts and how they allow us to construct payment channels. If you have already studied Bitcoin and are familiar with multisignature addresses, feel free to skip this section. [TIP] @@ -127,7 +127,7 @@ K ... N CHECKMULTISIG where N is the total number of listed public keys (Public Key 1 through Public Key N) and K is the threshold of required signatures to spend the output. -The Lightning Network uses a 2-of-2 multisignature scheme to build a payment channel. For example, a payment channel between Alice and Bob would be built on a 2-of-2 multisignature like this: +The Lightning Network uses a two-of-two multisignature scheme to build a payment channel. For example, a payment channel between Alice and Bob would be built on a two-of-two multisignature like this: ---- 2 2 CHECKMULTISIG @@ -146,7 +146,7 @@ The two scripts together would form the combined validation script: ==== Funding Transaction -The fundamental building block of a payment channel, is a 2-of-2 multisignature address. The two channel partners fund the payment channel by sending bitcoin to the multisignature address. This transaction is called the _funding transaction_, and is recorded on the Bitcoin blockchain. footnote:[While the original Lightning whitepaper described channels funded by both channel partners, the current specification, as of 2020, assumes that just one partner commits funds to the channel.] +The fundamental building block of a payment channel, is a two-of-two multisignature address. The two channel partners fund the payment channel by sending bitcoin to the multisignature address. This transaction is called the _funding transaction_, and is recorded on the Bitcoin blockchain. footnote:[While the original Lightning whitepaper described channels funded by both channel partners, the current specification, as of 2020, assumes that just one partner commits funds to the channel.] Even though the funding transaction is public, it is not obvious that it is a Lightning payment channel until it is closed. Furthermore, channel payments are still not visible to anyone other than the channel partners, nor is the distribution of the channel balance between them. @@ -160,9 +160,9 @@ The funds sent to the multisignature address in the funding transaction are some ===== Example of a poor channel opening procedure -If you think carefully about 2-of-2 multisignature addresses, you will realize that putting your funds into such an address seems to carry some risk. What if your channel partner refuses to sign a transaction to "release" the funds? Are they stuck forever? Let's look at that scenario and how the Lightning Network protocol avoids it, next. +If you think carefully about two-of-two multisignature addresses, you will realize that putting your funds into such an address seems to carry some risk. What if your channel partner refuses to sign a transaction to "release" the funds? Are they stuck forever? Let's look at that scenario and how the Lightning Network protocol avoids it, next. -Alice and Bob want to create a payment channel. They each create a private/public key pair and then exchange public keys. Now, they can construct a multisignature 2-of-2 with the two public keys, forming the foundation for their payment channel. +Alice and Bob want to create a payment channel. They each create a private/public key pair and then exchange public keys. Now, they can construct a multisignature two-of-two with the two public keys, forming the foundation for their payment channel. Next, Alice constructs a Bitcoin transaction sending a few mBTC to the multisignature address created from Alice's and Bob's public keys. If Alice doesn't take any additional steps and simply broadcasts this transaction, she has to trust that Bob will provide his signature to spend from the multisignature address. Bob on the other hand has the chance to blackmail Alice by withholding his signature and denying Alice access to her funds. @@ -191,7 +191,7 @@ Initially, Alice owns 100k satoshi, the entirety of the funds in the channel. He . Bob provides a signature for Alice's Commitment Transaction and sends this back to Alice via the `funding_signed` message. . Now that signatures have been exchanged Alice will broadcast the funding transaction to the Bitcoin network. -By following this protocol, Alice does not give up ownership of her 100k satoshi even though the funds are sent to a 2-of-2 multisignature address for which Alice controls only one key. +By following this protocol, Alice does not give up ownership of her 100k satoshi even though the funds are sent to a two-of-two multisignature address for which Alice controls only one key. If Bob stops responding to Alice she will be able to broadcast her commitment transaction and receive her funds back. Her only costs are the fees for the on-chain transactions. As long as she follows the protocol this is her only risk when opening a channel. @@ -306,7 +306,7 @@ However, sometimes closing a channel is desirable or necessary. For example: * The channel is not being used often because your channel partner is not a well-connected node, so you want to use the funds for another channel with a better-connected node. * Your channel partner has breached the protocol either due to a software bug or on purpose forcing you to close the channel to protect your funds. -There are 3 ways to close a payment channel: +There are three ways to close a payment channel: * Mutual close (the good way) * Force close (the bad way) @@ -353,7 +353,7 @@ In the case that you broadcasted an earlier commitment transaction, the timelock When publishing a commitment transaction during a force close, the on-chain fees will be higher than a mutual close for several reasons: -. When the commitment transaction was negotiated, the channel partners didn't know how much the on-chain fees would be at the future time the transaction would be broadcast. Since the fees cannot be changed without changing the outputs of the commitment transaction (needs both signatures) and since the force close happens when a channel partner is not available to sign, 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. +. When the commitment transaction was negotiated, the channel partners didn't know how much the on-chain fees would be at the future time the transaction would be broadcast. Since the fees cannot be changed without changing the outputs of the commitment transaction (needs both signatures) and since the force close happens when a channel partner is not available to sign, the protocol developers decided to be very generous with the fee rate included in the commitment transactions. It can be up to five times higher than the fee estimators suggest at the time the commitment transaction is negotiated. . The commitment transaction includes additional outputs for any pending routing attempts (HTLCs), which makes the commitment transaction larger (in terms of bytes) than a mutual close transaction. Larger transactions incur more fees. . Any pending routing attempts will have to be resolved on-chain causing additional on-chain transactions. @@ -777,7 +777,7 @@ The milli-satoshi unit cannot, of course, be settled on the Bitcoin blockchain a ==== Monetary Unit -Both the Bitcoin network and the Lightning network use the same monetary units: bitcoin. Lightning payments use the very same bitcoin as Bitcoin transactions. As an implication, because the monetary unit is the same, the monetary limit is the same: less than 21 million bitcoin. Of Bitcoin's 21 million total bitcoin, some are already allocated to 2-of-2 multi-signature addresses as part of payment channel on the Lightning Network. +Both the Bitcoin network and the Lightning network use the same monetary units: bitcoin. Lightning payments use the very same bitcoin as Bitcoin transactions. As an implication, because the monetary unit is the same, the monetary limit is the same: less than 21 million bitcoin. Of Bitcoin's 21 million total bitcoin, some are already allocated to two-of-two multi-signature addresses as part of payment channel on the Lightning Network. ==== Irreversibility and finality of payments From 28f1552be8e48c83fb88b123763935dd4dda2dc9 Mon Sep 17 00:00:00 2001 From: jerzybrzoska <51721153+jerzybrzoska@users.noreply.github.com> Date: Wed, 30 Dec 2020 09:41:27 +0100 Subject: [PATCH 2/2] Update 03_how_ln_works.asciidoc You are right [Umar](@bolatovumar) , I have not found a single source on the web with _two-of-two_, _2-of-2_ seems to be the standard. I edited my pull request, so now the changes do not include 2-of-2 modification. I find the issue of '2-of-2' vs 'two-of-two' interesting and may soon create a question on [English Stack Exchange](https://english.stackexchange.com/) in order to get their opinion. --- 03_how_ln_works.asciidoc | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/03_how_ln_works.asciidoc b/03_how_ln_works.asciidoc index b6ae709..6b7cfd6 100644 --- a/03_how_ln_works.asciidoc +++ b/03_how_ln_works.asciidoc @@ -22,7 +22,7 @@ A payment channel is a _financial relationship_ between two nodes on the Lightni The payment channel is managed by a _cryptographic protocol_, meaning a pre-defined process based on cryptography, used by the channel partners to re-distribute the balance of the channel in favor of one or the other channel partner. The cryptographic protocol ensures that one channel partner cannot cheat the other, so that the partners do not need to trust each other. -The cryptographic protocol is established by the funding of a two-of-two _multi-signature address_ that requires the two channel partners to cooperate and prevents either channel partner from spending the funds unilaterally. +The cryptographic protocol is established by the funding of a 2-of-2 _multi-signature address_ that requires the two channel partners to cooperate and prevents either channel partner from spending the funds unilaterally. To summarize: @@ -30,7 +30,7 @@ A payment channel is a financial relationship between nodes, allocating funds fr === Payment channels basics -Underlying the payment channel is simply a two-of-two multisignature address on the Bitcoin blockchain, for which you hold one key and your channel partner holds the other key. +Underlying the payment channel is simply a 2-of-2 multisignature address on the Bitcoin blockchain, for which you hold one key and your channel partner holds the other key. You and your channel partner negotiate a sequence of transactions that spend from this multisignature address. Instead of transmitting and recording these transactions on the Bitcoin blockchain, you both hold on to them, unspent. @@ -43,7 +43,7 @@ The smart contract is set up to penalize a channel member if they try to submit [NOTE] ==== -If you have an unpublished transaction from a two-of-two multisignature address, that pays you part of the balance, then a signature from the other party ensures that you can independently publish this transaction anytime by adding your own signature. +If you have an unpublished transaction from a 2-of-2 multisignature address, that pays you part of the balance, then a signature from the other party ensures that you can independently publish this transaction anytime by adding your own signature. The ability to hold a partially-signed transaction, offline and unpublished, with the option to publish and own that balance at any time, is the basis of the Lightning Network. ==== @@ -103,7 +103,7 @@ Eltoo channels have some interesting properties and simplify the implementation ==== Multisig addresses -Payment channels are built on top of two-of-two multisignature addresses, timelocks and Segregated Witness transaction outputs. We will not revise these relatively advanced concepts of the Bitcoin system. Instead, in this section we will provide a high-level overview of multisignature scripts and how they allow us to construct payment channels. +Payment channels are built on top of 2-of-2 multisignature addresses, timelocks and Segregated Witness transaction outputs. We will not revise these relatively advanced concepts of the Bitcoin system. Instead, in this section we will provide a high-level overview of multisignature scripts and how they allow us to construct payment channels. If you have already studied Bitcoin and are familiar with multisignature addresses, feel free to skip this section. [TIP] @@ -127,7 +127,7 @@ K ... N CHECKMULTISIG where N is the total number of listed public keys (Public Key 1 through Public Key N) and K is the threshold of required signatures to spend the output. -The Lightning Network uses a two-of-two multisignature scheme to build a payment channel. For example, a payment channel between Alice and Bob would be built on a two-of-two multisignature like this: +The Lightning Network uses a 2-of-2 multisignature scheme to build a payment channel. For example, a payment channel between Alice and Bob would be built on a 2-of-2 multisignature like this: ---- 2 2 CHECKMULTISIG @@ -146,7 +146,7 @@ The two scripts together would form the combined validation script: ==== Funding Transaction -The fundamental building block of a payment channel, is a two-of-two multisignature address. The two channel partners fund the payment channel by sending bitcoin to the multisignature address. This transaction is called the _funding transaction_, and is recorded on the Bitcoin blockchain. footnote:[While the original Lightning whitepaper described channels funded by both channel partners, the current specification, as of 2020, assumes that just one partner commits funds to the channel.] +The fundamental building block of a payment channel, is a 2-of-2 multisignature address. The two channel partners fund the payment channel by sending bitcoin to the multisignature address. This transaction is called the _funding transaction_, and is recorded on the Bitcoin blockchain. footnote:[While the original Lightning whitepaper described channels funded by both channel partners, the current specification, as of 2020, assumes that just one partner commits funds to the channel.] Even though the funding transaction is public, it is not obvious that it is a Lightning payment channel until it is closed. Furthermore, channel payments are still not visible to anyone other than the channel partners, nor is the distribution of the channel balance between them. @@ -160,9 +160,9 @@ The funds sent to the multisignature address in the funding transaction are some ===== Example of a poor channel opening procedure -If you think carefully about two-of-two multisignature addresses, you will realize that putting your funds into such an address seems to carry some risk. What if your channel partner refuses to sign a transaction to "release" the funds? Are they stuck forever? Let's look at that scenario and how the Lightning Network protocol avoids it, next. +If you think carefully about 2-of-2 multisignature addresses, you will realize that putting your funds into such an address seems to carry some risk. What if your channel partner refuses to sign a transaction to "release" the funds? Are they stuck forever? Let's look at that scenario and how the Lightning Network protocol avoids it, next. -Alice and Bob want to create a payment channel. They each create a private/public key pair and then exchange public keys. Now, they can construct a multisignature two-of-two with the two public keys, forming the foundation for their payment channel. +Alice and Bob want to create a payment channel. They each create a private/public key pair and then exchange public keys. Now, they can construct a multisignature 2-of-2 with the two public keys, forming the foundation for their payment channel. Next, Alice constructs a Bitcoin transaction sending a few mBTC to the multisignature address created from Alice's and Bob's public keys. If Alice doesn't take any additional steps and simply broadcasts this transaction, she has to trust that Bob will provide his signature to spend from the multisignature address. Bob on the other hand has the chance to blackmail Alice by withholding his signature and denying Alice access to her funds. @@ -191,7 +191,7 @@ Initially, Alice owns 100k satoshi, the entirety of the funds in the channel. He . Bob provides a signature for Alice's Commitment Transaction and sends this back to Alice via the `funding_signed` message. . Now that signatures have been exchanged Alice will broadcast the funding transaction to the Bitcoin network. -By following this protocol, Alice does not give up ownership of her 100k satoshi even though the funds are sent to a two-of-two multisignature address for which Alice controls only one key. +By following this protocol, Alice does not give up ownership of her 100k satoshi even though the funds are sent to a 2-of-2 multisignature address for which Alice controls only one key. If Bob stops responding to Alice she will be able to broadcast her commitment transaction and receive her funds back. Her only costs are the fees for the on-chain transactions. As long as she follows the protocol this is her only risk when opening a channel. @@ -777,7 +777,7 @@ The milli-satoshi unit cannot, of course, be settled on the Bitcoin blockchain a ==== Monetary Unit -Both the Bitcoin network and the Lightning network use the same monetary units: bitcoin. Lightning payments use the very same bitcoin as Bitcoin transactions. As an implication, because the monetary unit is the same, the monetary limit is the same: less than 21 million bitcoin. Of Bitcoin's 21 million total bitcoin, some are already allocated to two-of-two multi-signature addresses as part of payment channel on the Lightning Network. +Both the Bitcoin network and the Lightning network use the same monetary units: bitcoin. Lightning payments use the very same bitcoin as Bitcoin transactions. As an implication, because the monetary unit is the same, the monetary limit is the same: less than 21 million bitcoin. Of Bitcoin's 21 million total bitcoin, some are already allocated to 2-of-2 multi-signature addresses as part of payment channel on the Lightning Network. ==== Irreversibility and finality of payments