From 504fe33885ab95c2e471f0ce84e2e831a68c2f64 Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Wed, 29 Nov 2017 14:54:28 -0800 Subject: [PATCH 1/8] BOLT-5 Edits Besides standard edits and clarification, there were some notable rewrites in the "Our Offers" and "Their Offers" sections that will need to be examined very carefully. They had to do with opaque and sometimes inconsistent use of "our" and "their". There's additional explanation in email. --- 05-onchain.md | 270 +++++++++++++++++++------------------------------- 1 file changed, 101 insertions(+), 169 deletions(-) diff --git a/05-onchain.md b/05-onchain.md index b5716e593..32ea9064e 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -2,15 +2,15 @@ ## Abstract -Lightning allows for two parties (A and B) to make transactions off-chain, by both holding a cross-signed *commitment transaction*, which describes the current state of the channel (basically the current balance). This *commitment transaction* is updated every time a new payment is made, and is spendable at all times. +Lightning allows for two parties (nodes A and B) to conduct transactions off-chain by giving each of them a cross-signed *commitment transaction*, which describes the current state of the channel (basically, the current balance). This *commitment transaction* is updated every time a new payment is made, and is spendable at all times. There are three ways a channel can end: -1. The good way (*mutual close*): at some point A and B agree on closing the channel, they generate a *closing transaction* (which is similar to a *commitment transaction* without any pending payments), and publish it on the blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)). -2. The bad way (*unilateral close*): something goes wrong, without necessarily any evil intent on either side (maybe one party crashed, for instance). Anyway, one side publishes its latest *commitment transaction*. +1. The good way (*mutual close*): at some point nodes A and B agree to close the channel. They generate a *closing transaction* (which is similar to a *commitment transaction* without any pending payments) and publish it on the blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)). +2. The bad way (*unilateral close*): something goes wrong, possibly without evil intent on either side. Perhaps one party crashed, for instance. One side publishes its latest *commitment transaction*. 3. The ugly way (*revoked transaction close*): one of the parties deliberately tries to cheat by publishing an outdated version of its *commitment transaction* (presumably one that was more in her favor). -Because Lightning is designed to be trustless, there is no risk of loss of funds in any of these 3 cases, provided that the situation is properly handled. The goal of this document is to explain exactly how node A should react to seeing any of these on-chain. +Because Lightning is designed to be trustless, there is no risk of loss of funds in any of these three cases, provided that the situation is properly handled. The goal of this document is to explain exactly how node A should react to seeing any of these transactions appear on-chain. # Table of Contents * [General Nomenclature](#general-nomenclature) @@ -25,83 +25,69 @@ Because Lightning is designed to be trustless, there is no risk of loss of funds * [Penalty Transactions Weight Calculation](#penalty-transactions-weight-calculation) * [General Requirements](#general-requirements) * [Appendix A: Expected weights](#appendix-a-expected-weights) - * [Expected weight of the `to_local` penalty transaction witness](#expected-weight-of-the-to-local-penalty-transaction-witness) - * [Expected weight of the received-htlc penalty transaction witness](#expected-weight-of-the-received-htlc-penalty-transaction-witness) + * [Expected Weight of the `to_local` Penalty Transaction Witness](#expected-weight-of-the-to-local-penalty-transaction-witness) + * [Expected Weight of the `received_htlc` Penalty Transaction Witness](#expected-weight-of-the-received-htlc-penalty-transaction-witness) + * [Expected Weight of the `accepted_htlc` Penalty Transaction Witness](#expected-weight-of-the-accepted-htlc-penalty-transaction-witness) * [Authors](#authors) # General Nomenclature We consider any unspent output to be *unresolved*, and *resolve* them -as detailed in this document. Usually this means spending it with -another *resolving* transaction. Sometimes it simply means noting it +as detailed in this document. Usually this means spending it with +another *resolving* transaction. Sometimes it simply means noting the output for later wallet spending, in which case the transaction containing the output is considered to be its own *resolving* transaction. - -Outputs which are *resolved* are considered *irrevocably resolved* +Outputs that are *resolved* are considered *irrevocably resolved* once their *resolving* transaction is included in a block at least 100 -deep on the most-work blockchain. 100 blocks is far greater than the +deep on the most-work blockchain. 100 blocks is far greater than the longest known Bitcoin fork, and the same value used to wait for confirmations of miner's rewards (see [Reference Implementation](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223)). - ## Requirements - Once a node has broadcast a funding transaction or sent a commitment -signature for a commitment transaction which contains an HTLC output, -it MUST monitor the blockchain for transactions which spend any output -which is not *irrevocably resolved* until all outputs are *irrevocably +signature for a commitment transaction that contains an HTLC output, +it MUST monitor the blockchain for transactions that spend any output +that is not *irrevocably resolved*, until all outputs are *irrevocably resolved*. - -A node MUST *resolve* all outputs as specified below, and MUST be +A node MUST *resolve* all outputs as specified below and MUST be prepared to resolve them multiple times in case of blockchain reorganizations. - A node SHOULD fail the channel if it is not already closed when it -sees the funding transaction spent. A node MAY send a descriptive +sees the funding transaction spent. A node MAY send a descriptive error packet in this case. - Invalid transactions SHOULD be ignored. - ## Rationale - Once a node has had some money at stake, monitoring is required to ensure the other side does not close unilaterally. - Invalid transactions (eg. bad signatures) can be generated by anyone, (and will be ignored by the blockchain anyway), so they should not trigger any action. - # Commitment Transaction +Nodes A and B each hold a *commitment transaction*, each of which has four types of outputs: -A and B each hold a *commitment transaction*, which has 4 types of outputs: - - -1. _A's main output_: Zero or one outputs which pay to A's commitment key. -2. _B's main output_: Zero or one outputs which pay to B's commitment key. +1. _A's main output_: Zero or one outputs that pay to A's commitment key. +2. _B's main output_: Zero or one outputs that pay to B's commitment key. 3. _A's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay B in return for a payment preimage. 4. _B's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay A in return for a payment preimage. - -As an incentive for A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers A's outputs in A's *commitment transaction*, and B's outputs in B's *commitment transaction*. If A publishes its commitment transaction, she won't be able to get her funds immediately but B will. As a consequence, A and B's *commitment transactions* are not identical, they are (usually) symmetrical. - +As an incentive for nodes A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers node A's outputs in A's *commitment transaction*, and node B's outputs in B's *commitment transaction*. If node A publishes its commitment transaction, they won't be able to get their funds immediately but node B will. As a consequence, node A and B's *commitment transactions* are not identical, they are (usually) symmetrical. See [BOLT #3: Commitment Transaction](03-transactions.md#commitment-transaction) for more details. - # Failing A Channel -Various error cases involve closing a channel, and this can be done in -several ways; the most efficient is preferred. Note that there are +Various error cases involve closing a channel. This can be done in +several ways; the most efficient is preferred. Note that there are requirements around sending the error message to the peer in [BOLT #1: The `error` message](01-messaging.md#the-error-message). @@ -124,47 +110,38 @@ Since `dust_limit_satoshis` is supposed to prevent uneconomic output creation (which would be left unspent forever in the blockchain), we insist on spending the commitment transaction outputs. -In the early stages of a channel, it's common for one side to have +In the early stages of a channel it's common for one side to have little or no money in the channel; with nothing to lose, there's no reason to consume resources monitoring the channel state. There's a bias towards using mutual close over unilateral because -outputs are unencumbered by delay, directly spendable by wallets, and +outputs are unencumbered by delay and directly spendable by wallets and because fees tend to be less exaggerated than commitment transactions: thus the only reason not to use the signature from `closing_signed` would be if the fee offered was too small for it to be processed. - # Mutual Close Handling - A mutual close transaction *resolves* the funding transaction output. - A node doesn't need to do anything else as it has already agreed to the output, which is sent to its specified `scriptpubkey` (see [BOLT #2: Closing initiation: `shutdown`](02-peer-protocol.md#closing-initiation-shutdown)). - # Unilateral Close Handling - There are two cases to consider here: in the first case, node A sees -its own *commitment transaction*, in the second, it sees the node B's unrevoked +its own *commitment transaction*; in the second, it sees the node B's unrevoked *commitment transaction*. - Either transaction *resolves* the funding transaction output. - ## Requirements - When node A sees its own *commitment transaction*: - 1. _A's main output_: A node SHOULD spend this output to a convenient address. A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other - node's `to_self_delay` field) before spending the output. If the + node's `to_self_delay` field) before spending the output. If the output is spent (as recommended), the output is *resolved* by the spending transaction, otherwise it is considered *resolved* by the *commitment transaction* itself. 2. _B's main output_: No action required, this output is considered *resolved* @@ -175,7 +152,6 @@ When node A sees its own *commitment transaction*: Similarly, when node A sees a *commitment transaction* from B: - 1. _A's main output_: No action is required; this is a simple P2WPKH output. This output is considered *resolved* by the *commitment transaction* itself. 2. _B's main output_: No action required, this output is considered *resolved* @@ -185,231 +161,193 @@ Similarly, when node A sees a *commitment transaction* from B: A node MUST handle the broadcast of any valid *commitment transaction* -from B in this way; if it is unable to do so it MUST warn about lost funds. - +from node B in this way; if it is unable to do so it MUST warn about lost funds. ## Rationale - Spending the `to_local` output avoids having to remember the complicated witness script associated with that particular channel for later spending. - Note that there can be more than one valid, unrevoked *commitment transaction* after a signature has been received via `commitment_signed` and -before the corresponding `revoke_and_ack`. Either commitment can serve as -B's *commitment transaction*, hence the requirement to handle both. +before the corresponding `revoke_and_ack`. Either commitment can serve as +a node's *commitment transaction*, hence the requirement to handle both. - -In the case of data loss, a node can reach a state where we don't -recognize all of B's commitment transaction HTLC outputs. It can tell +In the case of data loss, a node can reach a state where it doesn't +recognize all of the other node's commitment transaction HTLC outputs. It can tell this has happened because the commitment number will be greater than -expected, and the fact that the transaction has been signed by this -node. If both nodes support `option-data-loss-protect` the node will -know the B's `per_commitment_point` and thus be able to derive its own -`remotekey` for the transaction and salvage its own funds (but not +expected, and because it has signed the transaction. +If both nodes support `option-data-loss-protect` the node will +know B's `per_commitment_point` and thus be able to derive its own +`remotekey` for the transaction and salvage its own funds (but not its HTLCs). - # On-chain HTLC Output Handling: Our Offers +Each HTLC output can only be spent by us, as the payer, after it's timed out, +or by them, as the recipient, if they have the payment preimage. -Each HTLC output can only be spent by us after it's timed out, -or them if they have the payment preimage. - -There can be HTLCs which are not represented by an output: either -because they were trimmed as dust, or in the case where B has two -valid commitment transactions, and the HTLCs differ in each. - -The HTLC has *timed out* once the depth of the latest block is equal +The HTLC output has *timed out* once the depth of the latest block is equal or greater than the HTLC `cltv_expiry`. +The method by which the HTLC times out differs depending +on which party the commitment transaction belongs to. -The method by which we time out the HTLC output differs depending -on whether it's our own commitment transaction, or theirs. +There can be HTLCs that are not represented by an output: either +because they were trimmed as dust or because the receipient has two +valid commitment transactions, and the HTLCs differ in each. ## Requirements - If the HTLC output is spent using the payment preimage, the HTLC output is considered *irrevocably resolved*, and the node MUST extract the payment preimage from the transaction input witness. - If the HTLC output has *timed out* and not been *resolved*, the node MUST *resolve* the output and MUST fail the corresponding incoming HTLC (if any) once the resolving transaction has reached reasonable -depth. If the transaction is the node's own +depth. If the transaction is the node's own commitment transaction, it MUST *resolve* the output by spending it using the HTLC-timeout transaction, and the HTLC-timeout transaction output MUST be *resolved* as described in "On-chain HTLC -Transaction Handling". Otherwise it MUST resolve the +Transaction Handling". Otherwise it MUST resolve the output by spending it to a convenient address. - -For any committed HTLC which does not have an output in this +For any committed HTLC that does not have an output in this commitment transaction, the node MUST fail the corresponding incoming HTLC (if any) once the commitment transaction has reached reasonable depth, and MAY fail it sooner if no valid commitment transaction contains an output corresponding to the HTLC. - ## Rationale - -If the commitment transaction is theirs, the only way to spend the +If the commitment transaction is the recipient's, the only way to spend the HTLC output using a payment preimage is for them to use the -HTLC-success transaction. If the commitment transaction is ours, they +HTLC-success transaction. If the commitment transaction is the payer's, the recipient could create any transaction using the preimage. - -The payment preimage either serves to prove payment (if this node -originated the payment), or to redeem the corresponding incoming HTLC -from another peer. Note that we don't care about the fate of the -HTLC-spending transaction itself once we've extracted the payment +The payment preimage either serves to prove payment (for the payer) or +to redeem the corresponding incoming HTLC from another peer (for the +recipient). Note that the parties don't care about the fate of the +HTLC-spending transaction itself once they've extracted the payment preimage; the knowledge is not revocable. - -Note that in cases where both resolutions are possible (payment -success seen after timeout, for example), either interpretation is -acceptable; it is the responsibility of the other node spend it +In cases where both resolutions are possible (when payment +success is seen after timeout, for example), either interpretation is +acceptable; it is the responsibility of the recipient to spend it before this occurs. - -If the commitment transaction is theirs, our signature alone is enough +If the commitment transaction is the recipient's, the payer's signature alone is enough to spend the HTLC output (see -[BOLT #3](03-transactions.md#received-htlc-outputs)), but we need to -do so, otherwise they could fulfill the HTLC after the timeout. If -the commitment transaction is ours, we need to use the HTLC-timeout +[BOLT #3](03-transactions.md#received-htlc-outputs)), but the payer needs to +do so, otherwise the recipient could fulfill the HTLC after the timeout. If +the commitment transaction is the payer's, they need to use the HTLC-timeout transaction. - The fulfillment of an on-chain HTLC delivers the `payment_preimage` -required to fulfill the incoming HTLC (if it, too, is on-chain) or use +required to fulfill the incoming HTLC (if it, too, is on-chain) or to use in the `update_fulfill_htlc` message for the incoming HTLC. -Otherwise, it needs to send the `update_fail_htlc` (presumably with +Otherwise, the node needs to send the `update_fail_htlc` (presumably with reason `permanent_channel_failure`) as detailed in [BOLT 02](https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#forwarding-htlcs). - If an HTLC is too small to appear in *any* commitment transaction, it can be safely failed immediately and `update_fail_htlc` returned to -the incoming HTLC (if any: it might be locally-generated). Otherwise, -if a HTLC isn't in the commitment transaction we need to make sure +the incoming HTLC (if any: it might be locally-generated). + +If a HTLC isn't in the commitment transaction a node needs to make sure that a blockchain reorganization or race does not switch to a -commitment transaction which does contain it, before we fail it, hence -the wait. The requirement that we fail the incoming HTLC before its +commitment transaction that does contain it before the node fails it, hence +the wait. The requirement that that the incoming HTLC be failed before its own timeout still applies as an upper bound. - # On-chain HTLC Output Handling: Their Offers - -Each HTLC output can only be spent by us if we have the payment -preimage, or them if it has timed out. +Each HTLC output can only be spent by us, as the recipient, if we have the payment +preimage, or them, as the payer, if it has timed out. There are actually several possible cases for an offered HTLC: -1. The other node is not irrevocably committed to it; this can only - happen if we have not received `revoke_and_ack` so that the other - node holds two valid commitment transactions, one with the HTLC and - one without. We won't normally know the preimage here, unless it's - a payment to ourselves, and revealing that would be an information leak, +1. The payer is not irrevocably committed to the offered HTLC; this can only + happen if the recipient has not received `revoke_and_ack` so that the payer + holds two valid commitment transactions, one with the HTLC and + one without. The recipient won't normally know the preimage here, unless it's + a payment to themselves, and revealing that would be an information leak, so it's best to allow the HTLC to time out in this case. -2. The other node is irrevocably committed to it, but we haven't yet - committed to an outgoing HTLC. In this case we can either forward +2. The payer is irrevocably committed to the offered HTLC, but the recipient hasn't yet + committed to an outgoing HTLC. In this case the recipient can either forward or timeout. -3. We have committed to an outgoing HTLC for this incoming one. In - this case we have to use the preimage if we receive it from the - outgoing HTLC, otherwise we will lose funds by making an outgoing +3. The recipient has committed to an outgoing HTLC for the offered one. In + this case the recipient has to use the preimage if they receive it from the + outgoing HTLC, otherwise they will lose funds by making an outgoing payment without redeeming the incoming one. ## Requirements - If the node receives (or already knows) a payment preimage for an unresolved HTLC output it was offered for which it has committed to an outgoing HTLC, it MUST *resolve* the output by spending it. Otherwise, if the other node is not irrevocably committed to the HTLC, it MUST NOT *resolve* the output by spending it. - To spend an offered HTLC output: if the transaction is the node's own commitment transaction, then it MUST use the HTLC-success transaction, and the HTLC-success transaction output MUST be *resolved* as described in "On-chain HTLC Transaction Handling", otherwise, it MUST spend the output to a convenient address. - If not otherwise resolved, once the HTLC output has expired, it is considered *irrevocably resolved*. - ## Rationale - -If this is our commitment transaction, we can only use a payment +If this is the recipient's commitment transaction, they can only use a payment preimage with the HTLC-success transaction (which preserves the -`to_self_delay` requirement). Otherwise we can create any transaction we want to +`to_self_delay` requirement). Otherwise they recipient can create any transaction they want to resolve it. - -We don't care about expired offers: we should have ensured that the +The recipient doesn't care about expired offers: they should have ensured that the HTLC can only expire long it is needed. - # On-chain HTLC Transaction Handling - Because to-self payments have to be delayed (to allow time for a -penalty transaction), HTLC outputs can only be spent by the node which +penalty transaction), HTLC outputs can only be spent by the node that broadcast the *commitment transaction* using the HTLC-timeout or the HTLC-success transaction, which include that delay. - ## Requirements - A node SHOULD resolve its own HTLC transaction output by spending it -to a convenient address. A node MUST wait until the +to a convenient address. A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other node's `open_channel` `to_self_delay` field) before spending the output. - If the output is spent (as recommended), the output is *resolved* by the spending transaction, otherwise it is considered *resolved* by the *commitment transaction* itself. - ## Rationale - Spending the `to_local` output avoids having to remember the complicated witness script associated with that particular channel for later spending. - # Revoked Transaction Close Handling - -If a node tries to broadcast old state, we can use the revocation key +If a node tries to broadcast old state, its peer can use the revocation key to claim all the funds. - ## Requirements - A node MUST NOT broadcast a *commitment transaction* for which it has exposed the revocation key. - If a node sees a *commitment transaction* for which it has a revocation key, that *resolves* the funding transaction output. - A node MUST resolve all unresolved outputs as follows: - 1. _A's main output_: No action is required; this is a simple P2WPKH output. This output is considered *resolved* by the *commitment transaction*. 2. _B's main output_: The node MUST *resolve* this by spending using the @@ -424,52 +362,48 @@ A node MUST resolve all unresolved outputs as follows: 5. _B's HTLC-timeout transaction_: The node MUST *resolve* this by spending using the revocation key. 6. _B's HTLC-success transaction_: The node MUST *resolve* this by - spending using the revocation key. The node SHOULD extract + spending using the revocation key. The node SHOULD extract the payment preimage from the transaction input witness if not already known. - The node MAY use a single transaction to *resolve* all the outputs, but MUST handle its transactions being invalidated by HTLC transactions. - ## Rationale - -A single transaction which resolves all the outputs will be under the +A single transaction that resolves all the outputs will be under the standard size limit thanks to the 483 HTLC-per-party limit (see [BOLT #2](02-peer-protocol.md#the-open_channel-message)). -Note that if a single transaction is used, it may be invalidated as B +Note that if a single transaction is used it may be invalidated as node B broadcasts HTLC-timeout and HTLC-success transactions, but the -requirement that we persist until all outputs are irrevocably resolved +requirement of persistence until all outputs are irrevocably resolved should cover this. [FIXME: May have to divide and conquer here, since they may be able to delay us long enough to avoid successful penalty spend? ] ## Penalty Transactions Weight Calculation -There are three different scripts for penalty transactions, with the following witnesses weight (details of the computation in [Appendix A](#appendix-a-expected-weights)): +There are three different scripts for penalty transactions, with the following witnesses weight (details of the computation are in [Appendix A](#appendix-a-expected-weights)): to_local_penalty_witness: 160 bytes offered_htlc_penalty_witness: 243 bytes accepted_htlc_penalty_witness: 249 bytes -The penalty txinput itself takes 41 bytes, thus has a weight of 164, making the weight of each input: +The penalty txinput itself takes 41 bytes, which has a weight of 164, making the weight of each input: to_local_penalty_input_weight: 324 bytes offered_htlc_penalty_input_weight: 407 bytes accepted_htlc_penalty_input_weight: 413 bytes - The rest of the penalty transaction takes 4+1+1+8+1+34+4=53 bytes of non-witness -data, assuming it has a pay-to-witness-script-hash (the largest standard output -script), in addition to a 2 byte witness header. +data, assuming that it has a pay-to-witness-script-hash (the largest standard output +script), in addition to a 2-byte witness header. In addition to outputs being swept under as penalty, the node MAY also sweep the -`to_remote` output of the commitment transaction, e.g. to reduce the total -amount paid in fees. Doing so requires the inclusion of a p2wpkh witness and +`to_remote` output of the commitment transaction (e.g. to reduce the total +amount paid in fees). Doing so requires the inclusion of a p2wpkh witness and additional txinput, resulting in an additional 108 + 164 = 272 bytes. -In a worst case scenario, we have only incoming HTLCs and the HTLC-timeout -transactions are not published, forcing us to spend from the commitment +In a worst case scenario, a node holds only incoming HTLCs and the HTLC-timeout +transactions are not published, forcing them to spend from the commitment transaction. With a maximum standard weight of 400000, the maximum number of HTLCs that can @@ -477,21 +411,19 @@ be swept in a single transaction: max_num_htlcs = (400000 - 324 - 272 - 4*53 - 2) / 413 = 966 -Thus we could allow 483 HTLCs in each direction (with both `to_local` and -`to_remote` outputs) and still resolve it with a single penalty transaction. +This allows 483 HTLCs in each direction (with both `to_local` and +`to_remote` outputs) to still be resolved in a single penalty transaction. Note that even if the `to_remote` output is not swept, the resulting `max_num_htlcs` is 967, which yields the same unidirectional limit of 483 HTLCs. # General Requirements - A node SHOULD report an error to the operator if it sees a transaction spend the funding transaction output which does not fall into one of these categories (mutual close, unilateral close, or revoked transaction close). Such a transaction implies its private key has leaked, and funds may be lost. - A node MAY simply watch the contents of the most-work chain for transactions, or MAY watch for (valid) broadcast transactions a.k.a mempool. Considering mempool transactions should cause lower latency @@ -500,7 +432,7 @@ that speed cannot be considered critical. # Appendix A: Expected weights -## Expected weight of the `to_local` penalty transaction witness +## Expected Weight of the `to_local` Penalty Transaction Witness As described in [BOLT #3](03-transactions.md), the witness for this transaction is: @@ -532,7 +464,7 @@ The *expected weight* is calculated as follows: - witness_script (to_local_script) -## Expected weight of the offered-htlc penalty transaction witness +## Expected Weight of the `offered_htlc` Penalty Transaction Witness The *expected weight* is calculated as follows (some calculations have already been made in [BOLT #3](03-transactions.md)): @@ -548,7 +480,7 @@ The *expected weight* is calculated as follows (some calculations have already b - witness_script (offered_htlc_script) -## Expected weight of the received-htlc penalty transaction witness +## Expected Weight of the `accepted_htlc` Penalty Transaction Witness The *expected weight* is calculated as follows (some calculations have already been made in [BOLT #3](03-transactions.md)): From c2faf323e748fd9d223628733f354cd8bed76ee0 Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Thu, 30 Nov 2017 14:00:31 -0800 Subject: [PATCH 2/8] BOLT-5 Fixes Some fixes to the pull request based on Rusty's comments. --- 05-onchain.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/05-onchain.md b/05-onchain.md index 32ea9064e..979ebcfad 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -180,12 +180,12 @@ this has happened because the commitment number will be greater than expected, and because it has signed the transaction. If both nodes support `option-data-loss-protect` the node will know B's `per_commitment_point` and thus be able to derive its own -`remotekey` for the transaction and salvage its own funds (but not its +`remotekey` for the transaction and salvage its own funds (but not the HTLCs). # On-chain HTLC Output Handling: Our Offers -Each HTLC output can only be spent by us, as the payer, after it's timed out, +Each HTLC output can only be spent by us, as the offerer, after it's timed out, or by them, as the recipient, if they have the payment preimage. The HTLC output has *timed out* once the depth of the latest block is equal @@ -223,12 +223,11 @@ contains an output corresponding to the HTLC. If the commitment transaction is the recipient's, the only way to spend the HTLC output using a payment preimage is for them to use the -HTLC-success transaction. If the commitment transaction is the payer's, the recipient +HTLC-success transaction. If the commitment transaction is the offerer's, the recipient could create any transaction using the preimage. -The payment preimage either serves to prove payment (for the payer) or -to redeem the corresponding incoming HTLC from another peer (for the -recipient). Note that the parties don't care about the fate of the +The payment preimage either serves to prove payment (for the offerer originating the payment) or +to redeem the corresponding incoming HTLC from another peer (for an offerer forwarding the payment). Note that the parties don't care about the fate of the HTLC-spending transaction itself once they've extracted the payment preimage; the knowledge is not revocable. @@ -237,11 +236,11 @@ success is seen after timeout, for example), either interpretation is acceptable; it is the responsibility of the recipient to spend it before this occurs. -If the commitment transaction is the recipient's, the payer's signature alone is enough +If the commitment transaction is the recipient's, the offerer's signature alone is enough to spend the HTLC output (see -[BOLT #3](03-transactions.md#received-htlc-outputs)), but the payer needs to +[BOLT #3](03-transactions.md#received-htlc-outputs)), but the offerer needs to do so, otherwise the recipient could fulfill the HTLC after the timeout. If -the commitment transaction is the payer's, they need to use the HTLC-timeout +the commitment transaction is the offerer's, they need to use the HTLC-timeout transaction. The fulfillment of an on-chain HTLC delivers the `payment_preimage` @@ -258,23 +257,23 @@ the incoming HTLC (if any: it might be locally-generated). If a HTLC isn't in the commitment transaction a node needs to make sure that a blockchain reorganization or race does not switch to a commitment transaction that does contain it before the node fails it, hence -the wait. The requirement that that the incoming HTLC be failed before its +the wait. The requirement that the incoming HTLC be failed before its own timeout still applies as an upper bound. # On-chain HTLC Output Handling: Their Offers Each HTLC output can only be spent by us, as the recipient, if we have the payment -preimage, or them, as the payer, if it has timed out. +preimage, or them, as the offerer, if it has timed out. There are actually several possible cases for an offered HTLC: -1. The payer is not irrevocably committed to the offered HTLC; this can only - happen if the recipient has not received `revoke_and_ack` so that the payer +1. The offerer is not irrevocably committed to the offered HTLC; this can only + happen if the recipient has not received `revoke_and_ack` so that the offerer holds two valid commitment transactions, one with the HTLC and one without. The recipient won't normally know the preimage here, unless it's a payment to themselves, and revealing that would be an information leak, so it's best to allow the HTLC to time out in this case. -2. The payer is irrevocably committed to the offered HTLC, but the recipient hasn't yet +2. The offerer is irrevocably committed to the offered HTLC, but the recipient hasn't yet committed to an outgoing HTLC. In this case the recipient can either forward or timeout. 3. The recipient has committed to an outgoing HTLC for the offered one. In @@ -302,7 +301,7 @@ If not otherwise resolved, once the HTLC output has expired, it is considered If this is the recipient's commitment transaction, they can only use a payment preimage with the HTLC-success transaction (which preserves the -`to_self_delay` requirement). Otherwise they recipient can create any transaction they want to +`to_self_delay` requirement). Otherwise the recipient can create any transaction they want to resolve it. The recipient doesn't care about expired offers: they should have ensured that the From 871462b1956f3452e68b93f5d5f30147d57f8f78 Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Wed, 29 Nov 2017 14:54:28 -0800 Subject: [PATCH 3/8] BOLT-5 Edits Besides standard edits and clarification, there were some notable rewrites in the "Our Offers" and "Their Offers" sections that will need to be examined very carefully. They had to do with opaque and sometimes inconsistent use of "our" and "their". There's additional explanation in email. --- 05-onchain.md | 270 +++++++++++++++++++------------------------------- 1 file changed, 101 insertions(+), 169 deletions(-) diff --git a/05-onchain.md b/05-onchain.md index b5716e593..32ea9064e 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -2,15 +2,15 @@ ## Abstract -Lightning allows for two parties (A and B) to make transactions off-chain, by both holding a cross-signed *commitment transaction*, which describes the current state of the channel (basically the current balance). This *commitment transaction* is updated every time a new payment is made, and is spendable at all times. +Lightning allows for two parties (nodes A and B) to conduct transactions off-chain by giving each of them a cross-signed *commitment transaction*, which describes the current state of the channel (basically, the current balance). This *commitment transaction* is updated every time a new payment is made, and is spendable at all times. There are three ways a channel can end: -1. The good way (*mutual close*): at some point A and B agree on closing the channel, they generate a *closing transaction* (which is similar to a *commitment transaction* without any pending payments), and publish it on the blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)). -2. The bad way (*unilateral close*): something goes wrong, without necessarily any evil intent on either side (maybe one party crashed, for instance). Anyway, one side publishes its latest *commitment transaction*. +1. The good way (*mutual close*): at some point nodes A and B agree to close the channel. They generate a *closing transaction* (which is similar to a *commitment transaction* without any pending payments) and publish it on the blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)). +2. The bad way (*unilateral close*): something goes wrong, possibly without evil intent on either side. Perhaps one party crashed, for instance. One side publishes its latest *commitment transaction*. 3. The ugly way (*revoked transaction close*): one of the parties deliberately tries to cheat by publishing an outdated version of its *commitment transaction* (presumably one that was more in her favor). -Because Lightning is designed to be trustless, there is no risk of loss of funds in any of these 3 cases, provided that the situation is properly handled. The goal of this document is to explain exactly how node A should react to seeing any of these on-chain. +Because Lightning is designed to be trustless, there is no risk of loss of funds in any of these three cases, provided that the situation is properly handled. The goal of this document is to explain exactly how node A should react to seeing any of these transactions appear on-chain. # Table of Contents * [General Nomenclature](#general-nomenclature) @@ -25,83 +25,69 @@ Because Lightning is designed to be trustless, there is no risk of loss of funds * [Penalty Transactions Weight Calculation](#penalty-transactions-weight-calculation) * [General Requirements](#general-requirements) * [Appendix A: Expected weights](#appendix-a-expected-weights) - * [Expected weight of the `to_local` penalty transaction witness](#expected-weight-of-the-to-local-penalty-transaction-witness) - * [Expected weight of the received-htlc penalty transaction witness](#expected-weight-of-the-received-htlc-penalty-transaction-witness) + * [Expected Weight of the `to_local` Penalty Transaction Witness](#expected-weight-of-the-to-local-penalty-transaction-witness) + * [Expected Weight of the `received_htlc` Penalty Transaction Witness](#expected-weight-of-the-received-htlc-penalty-transaction-witness) + * [Expected Weight of the `accepted_htlc` Penalty Transaction Witness](#expected-weight-of-the-accepted-htlc-penalty-transaction-witness) * [Authors](#authors) # General Nomenclature We consider any unspent output to be *unresolved*, and *resolve* them -as detailed in this document. Usually this means spending it with -another *resolving* transaction. Sometimes it simply means noting it +as detailed in this document. Usually this means spending it with +another *resolving* transaction. Sometimes it simply means noting the output for later wallet spending, in which case the transaction containing the output is considered to be its own *resolving* transaction. - -Outputs which are *resolved* are considered *irrevocably resolved* +Outputs that are *resolved* are considered *irrevocably resolved* once their *resolving* transaction is included in a block at least 100 -deep on the most-work blockchain. 100 blocks is far greater than the +deep on the most-work blockchain. 100 blocks is far greater than the longest known Bitcoin fork, and the same value used to wait for confirmations of miner's rewards (see [Reference Implementation](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223)). - ## Requirements - Once a node has broadcast a funding transaction or sent a commitment -signature for a commitment transaction which contains an HTLC output, -it MUST monitor the blockchain for transactions which spend any output -which is not *irrevocably resolved* until all outputs are *irrevocably +signature for a commitment transaction that contains an HTLC output, +it MUST monitor the blockchain for transactions that spend any output +that is not *irrevocably resolved*, until all outputs are *irrevocably resolved*. - -A node MUST *resolve* all outputs as specified below, and MUST be +A node MUST *resolve* all outputs as specified below and MUST be prepared to resolve them multiple times in case of blockchain reorganizations. - A node SHOULD fail the channel if it is not already closed when it -sees the funding transaction spent. A node MAY send a descriptive +sees the funding transaction spent. A node MAY send a descriptive error packet in this case. - Invalid transactions SHOULD be ignored. - ## Rationale - Once a node has had some money at stake, monitoring is required to ensure the other side does not close unilaterally. - Invalid transactions (eg. bad signatures) can be generated by anyone, (and will be ignored by the blockchain anyway), so they should not trigger any action. - # Commitment Transaction +Nodes A and B each hold a *commitment transaction*, each of which has four types of outputs: -A and B each hold a *commitment transaction*, which has 4 types of outputs: - - -1. _A's main output_: Zero or one outputs which pay to A's commitment key. -2. _B's main output_: Zero or one outputs which pay to B's commitment key. +1. _A's main output_: Zero or one outputs that pay to A's commitment key. +2. _B's main output_: Zero or one outputs that pay to B's commitment key. 3. _A's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay B in return for a payment preimage. 4. _B's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay A in return for a payment preimage. - -As an incentive for A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers A's outputs in A's *commitment transaction*, and B's outputs in B's *commitment transaction*. If A publishes its commitment transaction, she won't be able to get her funds immediately but B will. As a consequence, A and B's *commitment transactions* are not identical, they are (usually) symmetrical. - +As an incentive for nodes A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers node A's outputs in A's *commitment transaction*, and node B's outputs in B's *commitment transaction*. If node A publishes its commitment transaction, they won't be able to get their funds immediately but node B will. As a consequence, node A and B's *commitment transactions* are not identical, they are (usually) symmetrical. See [BOLT #3: Commitment Transaction](03-transactions.md#commitment-transaction) for more details. - # Failing A Channel -Various error cases involve closing a channel, and this can be done in -several ways; the most efficient is preferred. Note that there are +Various error cases involve closing a channel. This can be done in +several ways; the most efficient is preferred. Note that there are requirements around sending the error message to the peer in [BOLT #1: The `error` message](01-messaging.md#the-error-message). @@ -124,47 +110,38 @@ Since `dust_limit_satoshis` is supposed to prevent uneconomic output creation (which would be left unspent forever in the blockchain), we insist on spending the commitment transaction outputs. -In the early stages of a channel, it's common for one side to have +In the early stages of a channel it's common for one side to have little or no money in the channel; with nothing to lose, there's no reason to consume resources monitoring the channel state. There's a bias towards using mutual close over unilateral because -outputs are unencumbered by delay, directly spendable by wallets, and +outputs are unencumbered by delay and directly spendable by wallets and because fees tend to be less exaggerated than commitment transactions: thus the only reason not to use the signature from `closing_signed` would be if the fee offered was too small for it to be processed. - # Mutual Close Handling - A mutual close transaction *resolves* the funding transaction output. - A node doesn't need to do anything else as it has already agreed to the output, which is sent to its specified `scriptpubkey` (see [BOLT #2: Closing initiation: `shutdown`](02-peer-protocol.md#closing-initiation-shutdown)). - # Unilateral Close Handling - There are two cases to consider here: in the first case, node A sees -its own *commitment transaction*, in the second, it sees the node B's unrevoked +its own *commitment transaction*; in the second, it sees the node B's unrevoked *commitment transaction*. - Either transaction *resolves* the funding transaction output. - ## Requirements - When node A sees its own *commitment transaction*: - 1. _A's main output_: A node SHOULD spend this output to a convenient address. A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other - node's `to_self_delay` field) before spending the output. If the + node's `to_self_delay` field) before spending the output. If the output is spent (as recommended), the output is *resolved* by the spending transaction, otherwise it is considered *resolved* by the *commitment transaction* itself. 2. _B's main output_: No action required, this output is considered *resolved* @@ -175,7 +152,6 @@ When node A sees its own *commitment transaction*: Similarly, when node A sees a *commitment transaction* from B: - 1. _A's main output_: No action is required; this is a simple P2WPKH output. This output is considered *resolved* by the *commitment transaction* itself. 2. _B's main output_: No action required, this output is considered *resolved* @@ -185,231 +161,193 @@ Similarly, when node A sees a *commitment transaction* from B: A node MUST handle the broadcast of any valid *commitment transaction* -from B in this way; if it is unable to do so it MUST warn about lost funds. - +from node B in this way; if it is unable to do so it MUST warn about lost funds. ## Rationale - Spending the `to_local` output avoids having to remember the complicated witness script associated with that particular channel for later spending. - Note that there can be more than one valid, unrevoked *commitment transaction* after a signature has been received via `commitment_signed` and -before the corresponding `revoke_and_ack`. Either commitment can serve as -B's *commitment transaction*, hence the requirement to handle both. +before the corresponding `revoke_and_ack`. Either commitment can serve as +a node's *commitment transaction*, hence the requirement to handle both. - -In the case of data loss, a node can reach a state where we don't -recognize all of B's commitment transaction HTLC outputs. It can tell +In the case of data loss, a node can reach a state where it doesn't +recognize all of the other node's commitment transaction HTLC outputs. It can tell this has happened because the commitment number will be greater than -expected, and the fact that the transaction has been signed by this -node. If both nodes support `option-data-loss-protect` the node will -know the B's `per_commitment_point` and thus be able to derive its own -`remotekey` for the transaction and salvage its own funds (but not +expected, and because it has signed the transaction. +If both nodes support `option-data-loss-protect` the node will +know B's `per_commitment_point` and thus be able to derive its own +`remotekey` for the transaction and salvage its own funds (but not its HTLCs). - # On-chain HTLC Output Handling: Our Offers +Each HTLC output can only be spent by us, as the payer, after it's timed out, +or by them, as the recipient, if they have the payment preimage. -Each HTLC output can only be spent by us after it's timed out, -or them if they have the payment preimage. - -There can be HTLCs which are not represented by an output: either -because they were trimmed as dust, or in the case where B has two -valid commitment transactions, and the HTLCs differ in each. - -The HTLC has *timed out* once the depth of the latest block is equal +The HTLC output has *timed out* once the depth of the latest block is equal or greater than the HTLC `cltv_expiry`. +The method by which the HTLC times out differs depending +on which party the commitment transaction belongs to. -The method by which we time out the HTLC output differs depending -on whether it's our own commitment transaction, or theirs. +There can be HTLCs that are not represented by an output: either +because they were trimmed as dust or because the receipient has two +valid commitment transactions, and the HTLCs differ in each. ## Requirements - If the HTLC output is spent using the payment preimage, the HTLC output is considered *irrevocably resolved*, and the node MUST extract the payment preimage from the transaction input witness. - If the HTLC output has *timed out* and not been *resolved*, the node MUST *resolve* the output and MUST fail the corresponding incoming HTLC (if any) once the resolving transaction has reached reasonable -depth. If the transaction is the node's own +depth. If the transaction is the node's own commitment transaction, it MUST *resolve* the output by spending it using the HTLC-timeout transaction, and the HTLC-timeout transaction output MUST be *resolved* as described in "On-chain HTLC -Transaction Handling". Otherwise it MUST resolve the +Transaction Handling". Otherwise it MUST resolve the output by spending it to a convenient address. - -For any committed HTLC which does not have an output in this +For any committed HTLC that does not have an output in this commitment transaction, the node MUST fail the corresponding incoming HTLC (if any) once the commitment transaction has reached reasonable depth, and MAY fail it sooner if no valid commitment transaction contains an output corresponding to the HTLC. - ## Rationale - -If the commitment transaction is theirs, the only way to spend the +If the commitment transaction is the recipient's, the only way to spend the HTLC output using a payment preimage is for them to use the -HTLC-success transaction. If the commitment transaction is ours, they +HTLC-success transaction. If the commitment transaction is the payer's, the recipient could create any transaction using the preimage. - -The payment preimage either serves to prove payment (if this node -originated the payment), or to redeem the corresponding incoming HTLC -from another peer. Note that we don't care about the fate of the -HTLC-spending transaction itself once we've extracted the payment +The payment preimage either serves to prove payment (for the payer) or +to redeem the corresponding incoming HTLC from another peer (for the +recipient). Note that the parties don't care about the fate of the +HTLC-spending transaction itself once they've extracted the payment preimage; the knowledge is not revocable. - -Note that in cases where both resolutions are possible (payment -success seen after timeout, for example), either interpretation is -acceptable; it is the responsibility of the other node spend it +In cases where both resolutions are possible (when payment +success is seen after timeout, for example), either interpretation is +acceptable; it is the responsibility of the recipient to spend it before this occurs. - -If the commitment transaction is theirs, our signature alone is enough +If the commitment transaction is the recipient's, the payer's signature alone is enough to spend the HTLC output (see -[BOLT #3](03-transactions.md#received-htlc-outputs)), but we need to -do so, otherwise they could fulfill the HTLC after the timeout. If -the commitment transaction is ours, we need to use the HTLC-timeout +[BOLT #3](03-transactions.md#received-htlc-outputs)), but the payer needs to +do so, otherwise the recipient could fulfill the HTLC after the timeout. If +the commitment transaction is the payer's, they need to use the HTLC-timeout transaction. - The fulfillment of an on-chain HTLC delivers the `payment_preimage` -required to fulfill the incoming HTLC (if it, too, is on-chain) or use +required to fulfill the incoming HTLC (if it, too, is on-chain) or to use in the `update_fulfill_htlc` message for the incoming HTLC. -Otherwise, it needs to send the `update_fail_htlc` (presumably with +Otherwise, the node needs to send the `update_fail_htlc` (presumably with reason `permanent_channel_failure`) as detailed in [BOLT 02](https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#forwarding-htlcs). - If an HTLC is too small to appear in *any* commitment transaction, it can be safely failed immediately and `update_fail_htlc` returned to -the incoming HTLC (if any: it might be locally-generated). Otherwise, -if a HTLC isn't in the commitment transaction we need to make sure +the incoming HTLC (if any: it might be locally-generated). + +If a HTLC isn't in the commitment transaction a node needs to make sure that a blockchain reorganization or race does not switch to a -commitment transaction which does contain it, before we fail it, hence -the wait. The requirement that we fail the incoming HTLC before its +commitment transaction that does contain it before the node fails it, hence +the wait. The requirement that that the incoming HTLC be failed before its own timeout still applies as an upper bound. - # On-chain HTLC Output Handling: Their Offers - -Each HTLC output can only be spent by us if we have the payment -preimage, or them if it has timed out. +Each HTLC output can only be spent by us, as the recipient, if we have the payment +preimage, or them, as the payer, if it has timed out. There are actually several possible cases for an offered HTLC: -1. The other node is not irrevocably committed to it; this can only - happen if we have not received `revoke_and_ack` so that the other - node holds two valid commitment transactions, one with the HTLC and - one without. We won't normally know the preimage here, unless it's - a payment to ourselves, and revealing that would be an information leak, +1. The payer is not irrevocably committed to the offered HTLC; this can only + happen if the recipient has not received `revoke_and_ack` so that the payer + holds two valid commitment transactions, one with the HTLC and + one without. The recipient won't normally know the preimage here, unless it's + a payment to themselves, and revealing that would be an information leak, so it's best to allow the HTLC to time out in this case. -2. The other node is irrevocably committed to it, but we haven't yet - committed to an outgoing HTLC. In this case we can either forward +2. The payer is irrevocably committed to the offered HTLC, but the recipient hasn't yet + committed to an outgoing HTLC. In this case the recipient can either forward or timeout. -3. We have committed to an outgoing HTLC for this incoming one. In - this case we have to use the preimage if we receive it from the - outgoing HTLC, otherwise we will lose funds by making an outgoing +3. The recipient has committed to an outgoing HTLC for the offered one. In + this case the recipient has to use the preimage if they receive it from the + outgoing HTLC, otherwise they will lose funds by making an outgoing payment without redeeming the incoming one. ## Requirements - If the node receives (or already knows) a payment preimage for an unresolved HTLC output it was offered for which it has committed to an outgoing HTLC, it MUST *resolve* the output by spending it. Otherwise, if the other node is not irrevocably committed to the HTLC, it MUST NOT *resolve* the output by spending it. - To spend an offered HTLC output: if the transaction is the node's own commitment transaction, then it MUST use the HTLC-success transaction, and the HTLC-success transaction output MUST be *resolved* as described in "On-chain HTLC Transaction Handling", otherwise, it MUST spend the output to a convenient address. - If not otherwise resolved, once the HTLC output has expired, it is considered *irrevocably resolved*. - ## Rationale - -If this is our commitment transaction, we can only use a payment +If this is the recipient's commitment transaction, they can only use a payment preimage with the HTLC-success transaction (which preserves the -`to_self_delay` requirement). Otherwise we can create any transaction we want to +`to_self_delay` requirement). Otherwise they recipient can create any transaction they want to resolve it. - -We don't care about expired offers: we should have ensured that the +The recipient doesn't care about expired offers: they should have ensured that the HTLC can only expire long it is needed. - # On-chain HTLC Transaction Handling - Because to-self payments have to be delayed (to allow time for a -penalty transaction), HTLC outputs can only be spent by the node which +penalty transaction), HTLC outputs can only be spent by the node that broadcast the *commitment transaction* using the HTLC-timeout or the HTLC-success transaction, which include that delay. - ## Requirements - A node SHOULD resolve its own HTLC transaction output by spending it -to a convenient address. A node MUST wait until the +to a convenient address. A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other node's `open_channel` `to_self_delay` field) before spending the output. - If the output is spent (as recommended), the output is *resolved* by the spending transaction, otherwise it is considered *resolved* by the *commitment transaction* itself. - ## Rationale - Spending the `to_local` output avoids having to remember the complicated witness script associated with that particular channel for later spending. - # Revoked Transaction Close Handling - -If a node tries to broadcast old state, we can use the revocation key +If a node tries to broadcast old state, its peer can use the revocation key to claim all the funds. - ## Requirements - A node MUST NOT broadcast a *commitment transaction* for which it has exposed the revocation key. - If a node sees a *commitment transaction* for which it has a revocation key, that *resolves* the funding transaction output. - A node MUST resolve all unresolved outputs as follows: - 1. _A's main output_: No action is required; this is a simple P2WPKH output. This output is considered *resolved* by the *commitment transaction*. 2. _B's main output_: The node MUST *resolve* this by spending using the @@ -424,52 +362,48 @@ A node MUST resolve all unresolved outputs as follows: 5. _B's HTLC-timeout transaction_: The node MUST *resolve* this by spending using the revocation key. 6. _B's HTLC-success transaction_: The node MUST *resolve* this by - spending using the revocation key. The node SHOULD extract + spending using the revocation key. The node SHOULD extract the payment preimage from the transaction input witness if not already known. - The node MAY use a single transaction to *resolve* all the outputs, but MUST handle its transactions being invalidated by HTLC transactions. - ## Rationale - -A single transaction which resolves all the outputs will be under the +A single transaction that resolves all the outputs will be under the standard size limit thanks to the 483 HTLC-per-party limit (see [BOLT #2](02-peer-protocol.md#the-open_channel-message)). -Note that if a single transaction is used, it may be invalidated as B +Note that if a single transaction is used it may be invalidated as node B broadcasts HTLC-timeout and HTLC-success transactions, but the -requirement that we persist until all outputs are irrevocably resolved +requirement of persistence until all outputs are irrevocably resolved should cover this. [FIXME: May have to divide and conquer here, since they may be able to delay us long enough to avoid successful penalty spend? ] ## Penalty Transactions Weight Calculation -There are three different scripts for penalty transactions, with the following witnesses weight (details of the computation in [Appendix A](#appendix-a-expected-weights)): +There are three different scripts for penalty transactions, with the following witnesses weight (details of the computation are in [Appendix A](#appendix-a-expected-weights)): to_local_penalty_witness: 160 bytes offered_htlc_penalty_witness: 243 bytes accepted_htlc_penalty_witness: 249 bytes -The penalty txinput itself takes 41 bytes, thus has a weight of 164, making the weight of each input: +The penalty txinput itself takes 41 bytes, which has a weight of 164, making the weight of each input: to_local_penalty_input_weight: 324 bytes offered_htlc_penalty_input_weight: 407 bytes accepted_htlc_penalty_input_weight: 413 bytes - The rest of the penalty transaction takes 4+1+1+8+1+34+4=53 bytes of non-witness -data, assuming it has a pay-to-witness-script-hash (the largest standard output -script), in addition to a 2 byte witness header. +data, assuming that it has a pay-to-witness-script-hash (the largest standard output +script), in addition to a 2-byte witness header. In addition to outputs being swept under as penalty, the node MAY also sweep the -`to_remote` output of the commitment transaction, e.g. to reduce the total -amount paid in fees. Doing so requires the inclusion of a p2wpkh witness and +`to_remote` output of the commitment transaction (e.g. to reduce the total +amount paid in fees). Doing so requires the inclusion of a p2wpkh witness and additional txinput, resulting in an additional 108 + 164 = 272 bytes. -In a worst case scenario, we have only incoming HTLCs and the HTLC-timeout -transactions are not published, forcing us to spend from the commitment +In a worst case scenario, a node holds only incoming HTLCs and the HTLC-timeout +transactions are not published, forcing them to spend from the commitment transaction. With a maximum standard weight of 400000, the maximum number of HTLCs that can @@ -477,21 +411,19 @@ be swept in a single transaction: max_num_htlcs = (400000 - 324 - 272 - 4*53 - 2) / 413 = 966 -Thus we could allow 483 HTLCs in each direction (with both `to_local` and -`to_remote` outputs) and still resolve it with a single penalty transaction. +This allows 483 HTLCs in each direction (with both `to_local` and +`to_remote` outputs) to still be resolved in a single penalty transaction. Note that even if the `to_remote` output is not swept, the resulting `max_num_htlcs` is 967, which yields the same unidirectional limit of 483 HTLCs. # General Requirements - A node SHOULD report an error to the operator if it sees a transaction spend the funding transaction output which does not fall into one of these categories (mutual close, unilateral close, or revoked transaction close). Such a transaction implies its private key has leaked, and funds may be lost. - A node MAY simply watch the contents of the most-work chain for transactions, or MAY watch for (valid) broadcast transactions a.k.a mempool. Considering mempool transactions should cause lower latency @@ -500,7 +432,7 @@ that speed cannot be considered critical. # Appendix A: Expected weights -## Expected weight of the `to_local` penalty transaction witness +## Expected Weight of the `to_local` Penalty Transaction Witness As described in [BOLT #3](03-transactions.md), the witness for this transaction is: @@ -532,7 +464,7 @@ The *expected weight* is calculated as follows: - witness_script (to_local_script) -## Expected weight of the offered-htlc penalty transaction witness +## Expected Weight of the `offered_htlc` Penalty Transaction Witness The *expected weight* is calculated as follows (some calculations have already been made in [BOLT #3](03-transactions.md)): @@ -548,7 +480,7 @@ The *expected weight* is calculated as follows (some calculations have already b - witness_script (offered_htlc_script) -## Expected weight of the received-htlc penalty transaction witness +## Expected Weight of the `accepted_htlc` Penalty Transaction Witness The *expected weight* is calculated as follows (some calculations have already been made in [BOLT #3](03-transactions.md)): From 301085936da4b74c351bd9a6b450e3d30e762cb7 Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Thu, 30 Nov 2017 14:00:31 -0800 Subject: [PATCH 4/8] BOLT-5 Fixes Some fixes to the pull request based on Rusty's comments. --- 05-onchain.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/05-onchain.md b/05-onchain.md index 32ea9064e..979ebcfad 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -180,12 +180,12 @@ this has happened because the commitment number will be greater than expected, and because it has signed the transaction. If both nodes support `option-data-loss-protect` the node will know B's `per_commitment_point` and thus be able to derive its own -`remotekey` for the transaction and salvage its own funds (but not its +`remotekey` for the transaction and salvage its own funds (but not the HTLCs). # On-chain HTLC Output Handling: Our Offers -Each HTLC output can only be spent by us, as the payer, after it's timed out, +Each HTLC output can only be spent by us, as the offerer, after it's timed out, or by them, as the recipient, if they have the payment preimage. The HTLC output has *timed out* once the depth of the latest block is equal @@ -223,12 +223,11 @@ contains an output corresponding to the HTLC. If the commitment transaction is the recipient's, the only way to spend the HTLC output using a payment preimage is for them to use the -HTLC-success transaction. If the commitment transaction is the payer's, the recipient +HTLC-success transaction. If the commitment transaction is the offerer's, the recipient could create any transaction using the preimage. -The payment preimage either serves to prove payment (for the payer) or -to redeem the corresponding incoming HTLC from another peer (for the -recipient). Note that the parties don't care about the fate of the +The payment preimage either serves to prove payment (for the offerer originating the payment) or +to redeem the corresponding incoming HTLC from another peer (for an offerer forwarding the payment). Note that the parties don't care about the fate of the HTLC-spending transaction itself once they've extracted the payment preimage; the knowledge is not revocable. @@ -237,11 +236,11 @@ success is seen after timeout, for example), either interpretation is acceptable; it is the responsibility of the recipient to spend it before this occurs. -If the commitment transaction is the recipient's, the payer's signature alone is enough +If the commitment transaction is the recipient's, the offerer's signature alone is enough to spend the HTLC output (see -[BOLT #3](03-transactions.md#received-htlc-outputs)), but the payer needs to +[BOLT #3](03-transactions.md#received-htlc-outputs)), but the offerer needs to do so, otherwise the recipient could fulfill the HTLC after the timeout. If -the commitment transaction is the payer's, they need to use the HTLC-timeout +the commitment transaction is the offerer's, they need to use the HTLC-timeout transaction. The fulfillment of an on-chain HTLC delivers the `payment_preimage` @@ -258,23 +257,23 @@ the incoming HTLC (if any: it might be locally-generated). If a HTLC isn't in the commitment transaction a node needs to make sure that a blockchain reorganization or race does not switch to a commitment transaction that does contain it before the node fails it, hence -the wait. The requirement that that the incoming HTLC be failed before its +the wait. The requirement that the incoming HTLC be failed before its own timeout still applies as an upper bound. # On-chain HTLC Output Handling: Their Offers Each HTLC output can only be spent by us, as the recipient, if we have the payment -preimage, or them, as the payer, if it has timed out. +preimage, or them, as the offerer, if it has timed out. There are actually several possible cases for an offered HTLC: -1. The payer is not irrevocably committed to the offered HTLC; this can only - happen if the recipient has not received `revoke_and_ack` so that the payer +1. The offerer is not irrevocably committed to the offered HTLC; this can only + happen if the recipient has not received `revoke_and_ack` so that the offerer holds two valid commitment transactions, one with the HTLC and one without. The recipient won't normally know the preimage here, unless it's a payment to themselves, and revealing that would be an information leak, so it's best to allow the HTLC to time out in this case. -2. The payer is irrevocably committed to the offered HTLC, but the recipient hasn't yet +2. The offerer is irrevocably committed to the offered HTLC, but the recipient hasn't yet committed to an outgoing HTLC. In this case the recipient can either forward or timeout. 3. The recipient has committed to an outgoing HTLC for the offered one. In @@ -302,7 +301,7 @@ If not otherwise resolved, once the HTLC output has expired, it is considered If this is the recipient's commitment transaction, they can only use a payment preimage with the HTLC-success transaction (which preserves the -`to_self_delay` requirement). Otherwise they recipient can create any transaction they want to +`to_self_delay` requirement). Otherwise the recipient can create any transaction they want to resolve it. The recipient doesn't care about expired offers: they should have ensured that the From 8634b8592b5e458a9f3bd8257a90d2480215beef Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Mon, 4 Dec 2017 13:54:28 -0800 Subject: [PATCH 5/8] BOLT-5 Reviewer Responses Edits per @toadlyBroodle's review. --- 05-onchain.md | 49 +++++++++++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/05-onchain.md b/05-onchain.md index 979ebcfad..d9310f2f3 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -80,7 +80,7 @@ Nodes A and B each hold a *commitment transaction*, each of which has four types 3. _A's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay B in return for a payment preimage. 4. _B's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay A in return for a payment preimage. -As an incentive for nodes A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers node A's outputs in A's *commitment transaction*, and node B's outputs in B's *commitment transaction*. If node A publishes its commitment transaction, they won't be able to get their funds immediately but node B will. As a consequence, node A and B's *commitment transactions* are not identical, they are (usually) symmetrical. +As an incentive for nodes A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers node A's outputs in A's *commitment transaction*, and node B's outputs in B's *commitment transaction*. If node A publishes its commitment transaction, it won't be able to get its funds immediately but node B will. As a consequence, node A and B's *commitment transactions* are not identical, but they are (usually) symmetrical. See [BOLT #3: Commitment Transaction](03-transactions.md#commitment-transaction) for more details. @@ -110,12 +110,12 @@ Since `dust_limit_satoshis` is supposed to prevent uneconomic output creation (which would be left unspent forever in the blockchain), we insist on spending the commitment transaction outputs. -In the early stages of a channel it's common for one side to have +In the early stages of a channel, it's common for one side to have little or no money in the channel; with nothing to lose, there's no reason to consume resources monitoring the channel state. -There's a bias towards using mutual close over unilateral because -outputs are unencumbered by delay and directly spendable by wallets and +There's a bias towards using mutual close over unilateral, because +outputs are unencumbered by a delay and are directly spendable by wallets, and because fees tend to be less exaggerated than commitment transactions: thus the only reason not to use the signature from `closing_signed` would be if the fee offered was too small for it to be processed. @@ -185,8 +185,8 @@ HTLCs). # On-chain HTLC Output Handling: Our Offers -Each HTLC output can only be spent by us, as the offerer, after it's timed out, -or by them, as the recipient, if they have the payment preimage. +Each HTLC output can only be spent by us, the offerer, after it's timed out, +or by them, the recipient, if they have the payment preimage. The HTLC output has *timed out* once the depth of the latest block is equal or greater than the HTLC `cltv_expiry`. @@ -194,7 +194,7 @@ The method by which the HTLC times out differs depending on which party the commitment transaction belongs to. There can be HTLCs that are not represented by an output: either -because they were trimmed as dust or because the receipient has two +because they were trimmed as dust, or because the receipient has two valid commitment transactions, and the HTLCs differ in each. ## Requirements @@ -226,13 +226,10 @@ HTLC output using a payment preimage is for them to use the HTLC-success transaction. If the commitment transaction is the offerer's, the recipient could create any transaction using the preimage. -The payment preimage either serves to prove payment (for the offerer originating the payment) or -to redeem the corresponding incoming HTLC from another peer (for an offerer forwarding the payment). Note that the parties don't care about the fate of the -HTLC-spending transaction itself once they've extracted the payment -preimage; the knowledge is not revocable. +The payment preimage either serves to prove payment (when the offering node originated the payment) or +to redeem the corresponding incoming HTLC from another peer (when the offering node is forwarding the payment). Once a node has extracted the payment, it no longer cares about the fate of the HTLC-spending transaction itself. -In cases where both resolutions are possible (when payment -success is seen after timeout, for example), either interpretation is +In cases where both resolutions are possible (e.g., when a node receives payment success after timeout), either interpretation is acceptable; it is the responsibility of the recipient to spend it before this occurs. @@ -240,7 +237,7 @@ If the commitment transaction is the recipient's, the offerer's signature alone to spend the HTLC output (see [BOLT #3](03-transactions.md#received-htlc-outputs)), but the offerer needs to do so, otherwise the recipient could fulfill the HTLC after the timeout. If -the commitment transaction is the offerer's, they need to use the HTLC-timeout +the commitment transaction is the offerer's, the offerer must use the HTLC-timeout transaction. The fulfillment of an on-chain HTLC delivers the `payment_preimage` @@ -262,8 +259,8 @@ own timeout still applies as an upper bound. # On-chain HTLC Output Handling: Their Offers -Each HTLC output can only be spent by us, as the recipient, if we have the payment -preimage, or them, as the offerer, if it has timed out. +Each HTLC output can only be spent by us, the recipient, if we have the payment +preimage, or them, the offerer, if it has timed out. There are actually several possible cases for an offered HTLC: @@ -271,14 +268,14 @@ There are actually several possible cases for an offered HTLC: happen if the recipient has not received `revoke_and_ack` so that the offerer holds two valid commitment transactions, one with the HTLC and one without. The recipient won't normally know the preimage here, unless it's - a payment to themselves, and revealing that would be an information leak, + a payment to itself, and revealing that would be an information leak, so it's best to allow the HTLC to time out in this case. 2. The offerer is irrevocably committed to the offered HTLC, but the recipient hasn't yet committed to an outgoing HTLC. In this case the recipient can either forward or timeout. 3. The recipient has committed to an outgoing HTLC for the offered one. In - this case the recipient has to use the preimage if they receive it from the - outgoing HTLC, otherwise they will lose funds by making an outgoing + this case the recipient has to use the preimage if it receives it from the + outgoing HTLC, otherwise it will lose funds by making an outgoing payment without redeeming the incoming one. @@ -299,12 +296,12 @@ If not otherwise resolved, once the HTLC output has expired, it is considered ## Rationale -If this is the recipient's commitment transaction, they can only use a payment +If this is the recipient's commitment transaction, it can only use a payment preimage with the HTLC-success transaction (which preserves the -`to_self_delay` requirement). Otherwise the recipient can create any transaction they want to +`to_self_delay` requirement). Otherwise the recipient can create any transaction it wants to resolve it. -The recipient doesn't care about expired offers: they should have ensured that the +The recipient doesn't care about expired offers: it's the sender's responsibility to ensure that the HTLC can only expire long it is needed. # On-chain HTLC Transaction Handling @@ -334,7 +331,7 @@ spending. # Revoked Transaction Close Handling -If a node tries to broadcast old state, its peer can use the revocation key +If a node tries to broadcast old state, the other node can use the revocation key to claim all the funds. ## Requirements @@ -375,7 +372,7 @@ standard size limit thanks to the 483 HTLC-per-party limit (see Note that if a single transaction is used it may be invalidated as node B broadcasts HTLC-timeout and HTLC-success transactions, but the -requirement of persistence until all outputs are irrevocably resolved +requirement of persistence, until all outputs are irrevocably resolved, should cover this. [FIXME: May have to divide and conquer here, since they may be able to delay us long enough to avoid successful penalty spend? ] ## Penalty Transactions Weight Calculation @@ -401,8 +398,8 @@ In addition to outputs being swept under as penalty, the node MAY also sweep the amount paid in fees). Doing so requires the inclusion of a p2wpkh witness and additional txinput, resulting in an additional 108 + 164 = 272 bytes. -In a worst case scenario, a node holds only incoming HTLCs and the HTLC-timeout -transactions are not published, forcing them to spend from the commitment +In a worst case scenario, a node holds only incoming HTLCs, and the HTLC-timeout +transactions are not published, which forces the node to spend from the commitment transaction. With a maximum standard weight of 400000, the maximum number of HTLCs that can From 35f6444aeda22236b76d274b563ae409367693d4 Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Mon, 4 Dec 2017 13:58:55 -0800 Subject: [PATCH 6/8] BOLT-5 Clarification Better text for that one section where I disagreed with the review. --- 05-onchain.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/05-onchain.md b/05-onchain.md index d9310f2f3..2dcbaff2f 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -259,8 +259,8 @@ own timeout still applies as an upper bound. # On-chain HTLC Output Handling: Their Offers -Each HTLC output can only be spent by us, the recipient, if we have the payment -preimage, or them, the offerer, if it has timed out. +Each HTLC output can only be spent by us, the recipient (if we have the payment +preimage), or them, the offerer (if it has timed out). There are actually several possible cases for an offered HTLC: From 609a605499ba87d12332932f29c5b112bda39cd7 Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Wed, 6 Dec 2017 15:14:38 -0800 Subject: [PATCH 7/8] Edits to BOLT-7 A variety of edits, mostly cleanup. --- 07-routing-gossip.md | 205 ++++++++++++++++++++++--------------------- 1 file changed, 106 insertions(+), 99 deletions(-) diff --git a/07-routing-gossip.md b/07-routing-gossip.md index c58790e40..ec915dfca 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -1,19 +1,25 @@ # BOLT #7: P2P Node and Channel Discovery -This specification describes simple node discovery, channel discovery and channel update mechanisms which do not rely on a third-party to disseminate the information. +This specification describes simple node discovery, channel discovery, and channel update mechanisms that do not rely on a third-party to disseminate the information. Node and channel discovery serve two different purposes: - - Channel discovery allows the creation and maintenance of a local view of the network's topology such that the node can discover routes to the desired destination. - - Node discovery allows nodes to broadcast their ID, host and port, such that other nodes can open connections and establish payment channels. + - Channel discovery allows the creation and maintenance of a local view of the network's topology, so that the node can discover routes to the desired destination. + - Node discovery allows nodes to broadcast their ID, host, and port, so that other nodes can open connections and establish payment channels. -Peers in the network exchange `channel_announcement` messages that contain information about new channels between two nodes. They can also exchange `node_announcement` messages which supply additional information about nodes, and `channel_update` messages which update information about a channel. +To support channel discovery, peers in the network exchange +`channel_announcement` messages, which contain information about new +channels between two nodes. They can also exchange `channel_update` +messages, which update information about a channel. There can only be +one valid `channel_announcement` for any channel, but at least two +`channel_update` messages are expected. -There can only be one valid `channel_announcement` for any channel, -but multiple `node_announcement` messages are possible (to update node -information), and at least two `channel_update` messages are expected. +To support node discovery, peers exchange `node_announcement` +messages, which supply additional information about nodes There can be +multiple `node_announcement` messages, to update node information. + +## The `announcement_signatures` Message -## The `announcement_signatures` message This is a direct message between two endpoints of a channel and serves as an opt-in mechanism to allow the announcement of the channel to the rest of the network. It contains the necessary signatures by the sender to construct the `channel_announcement` message. @@ -28,49 +34,50 @@ The willingness of the initiating node to announce the channel is signaled durin ### Requirements -If the `open_channel` message had the `announce_channel` bit set, then both nodes must send the `announcement_signatures` message, otherwise they MUST NOT. - -If sent, `announcement_signatures` messages MUST NOT be sent until `funding_locked` has been sent and the funding transaction has at least 6 confirmations. +The `announcement_signatures` message is created by constructing a `channel_announcement` message corresponding to the newly established channel and signing it with the secrets matching an endpoint's `node_id` and `bitcoin_key`. The message is then sent using an `announcement_signatures`. The `short_channel_id` is the unique description of the funding transaction. -It is constructed with the most significant 3 bytes as the block +It is constructed with the most significant 3 bytes indicating the block height, the next 3 bytes indicating the transaction index within the block, and the least significant two bytes indicating the output -index which pays to the channel. +index that pays to the channel. + +If the `open_channel` message had the `announce_channel` bit set, then both nodes must send the `announcement_signatures` message, otherwise they MUST NOT. + +If sent, `announcement_signatures` messages MUST NOT be sent until `funding_locked` has been sent and the funding transaction has at least 6 confirmations. -The `announcement_signatures` message is created by constructing a `channel_announcement` message corresponding to the newly established channel, and sign it with the secrets matching their `node_id` and `bitcoin_key`, and send them using an `announcement_signatures`. The recipient MAY fail the channel if the `node_signature` or `bitcoin_signature` is incorrect. The recipient SHOULD queue the `channel_announcement` message for its peers if it has sent and received a valid `announcement_signatures` message. On reconnection, a node SHOULD retransmit the `announcement_signatures` message if it has not received an `announcement_signatures` message, and MUST respond to the first `announcement_signatures` message after reconnection with its own `announcement_signatures` message. -## The `channel_announcement` message +## The `channel_announcement` Message -This message contains ownership information about a channel. It ties -each on-chain Bitcoin key to the lightning node key, and vice-versa. +This message contains ownership information about a channel. It ties +each on-chain Bitcoin key to the Lightning node key, and vice-versa. The channel is not really usable until at least one side has announced its fee levels and expiry using `channel_update`. -In order to prove the existence of channel between `node_1` and -`node_2` we need to: +Proving the existence of a channel between `node_1` and +`node_2` requires: -1. Prove that the funding transaction pays to `bitcoin_key_1` and +1. Proving that the funding transaction pays to `bitcoin_key_1` and `bitcoin_key_2`. -2. Prove `node_1` owns `bitcoin_key_1` -3. Prove `node_2` owns `bitcoin_key_2` +2. Proving that `node_1` owns `bitcoin_key_1` +3. Proving that `node_2` owns `bitcoin_key_2` -The first one is done by assuming that all nodes know the unspent +The first proof is accomplished by assuming that all nodes know the unspent transaction outputs, and thus can find the output given by `short_channel_id` and validate that it is indeed a P2WSH funding -transaction output as to those keys specified in +transaction output for those keys specified in [BOLT #3](03-transactions.md#funding-transaction-output). -The second two are done by explicit signatures (`bitcoin_signature_1` +The second two proofs are accomplished through explicit signatures (`bitcoin_signature_1` and `bitcoin_signature_2`, generated by each `bitcoin_key` and signing -the corresponding `node_id`. +the corresponding `node_id`). -We also need to prove that `node_1` and `node_2` both agree on this -announcement message; that is done by having a signature from each +It is also necessary to prove that `node_1` and `node_2` both agree on this +announcement message; that is accomplished by having a signature from each `node_id` signing the message (`node_signature_1` and `node_signature_2`). @@ -92,17 +99,17 @@ announcement message; that is done by having a signature from each ### Requirements The creating node MUST set `chain_hash` to the 32-byte hash that uniquely -identifies the chain the channel was opened within. For the Bitcoin +identifies the chain that the channel was opened within. For the Bitcoin blockchain, the `chain_hash` value MUST be (encoded in hex): `000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`. The creating node MUST set `short_channel_id` to refer to the confirmed -funding transaction as specified in [BOLT #2](02-peer-protocol.md#the-funding_locked-message). The corresponding output MUST be a +funding transaction as specified in [BOLT #2](02-peer-protocol.md#the-funding_locked-message). The corresponding output MUST be a P2WSH as described in [BOLT #3](03-transactions.md#funding-transaction-output). The creating node MUST set `node_id_1` and `node_id_2` to the public keys of the two nodes who are operating the channel, such that -`node_id_1` is the numerically-lesser of the two DER encoded keys sorted in +`node_id_1` is the numerically-lesser of the two DER-encoded keys sorted in ascending numerical order, and MUST set `bitcoin_key_1` and `bitcoin_key_2` to `funding_pubkey`s of `node_id_1` and `node_id_2` respectively. @@ -137,9 +144,9 @@ ignore the message. Otherwise, if the transaction referred to was not previously announced as a channel, the receiving node SHOULD queue the message for rebroadcasting, but MAY choose not to for messages longer than -the minimum expected length. If it has previously received a valid +the minimum expected length. If it has previously received a valid `channel_announcement` for the same transaction in the same block, but -different `node_id_1` or `node_id_2`, it SHOULD blacklist the +for a different `node_id_1` or `node_id_2`, it SHOULD blacklist the previous message's `node_id_1` and `node_id_2` as well as this `node_id_1` and `node_id_2` and forget channels connected to them, otherwise it SHOULD store this `channel_announcement`. @@ -150,10 +157,10 @@ been spent or reorganized out. ### Rationale Requiring both nodes to sign indicates they are both willing to route -other payments via this node (ie. take part of the public network). -Requiring the Bitcoin signatures proves they control the channel. +other payments via this channel (i.e. be part of the public network). +Requiring the Bitcoin signatures proves that they control the channel. -The blacklisting of conflicting nodes means that we disallow multiple +The blacklisting of conflicting nodes disallows multiple different announcements: no node should ever do this, as it implies that keys have leaked. @@ -173,7 +180,7 @@ Incompatible features will result in the announcement not being forwarded by nod ## The `node_announcement` message This allows a node to indicate extra data associated with it, in -addition to its public key. To avoid trivial denial of service attacks, +addition to its public key. To avoid trivial denial of service attacks, nodes for which a channel is not already known are ignored. 1. type: 257 (`node_announcement`) @@ -195,12 +202,12 @@ and WISTFULTOLL and use the color black. `addresses` allows the node to announce its willingness to accept incoming network connections: it contains series of `address -descriptor`s for connecting to the node. The first byte describes the +descriptor`s for connecting to the node. The first byte describes the address type, followed by the appropriate number of bytes for that type. The following `address descriptor` types are defined: - * `0`: padding. data = none (length 0). + * `0`: padding. data = none (length 0). * `1`: ipv4. data = `[4:ipv4_addr][2:port]` (length 6) * `2`: ipv6. data = `[16:ipv6_addr][2:port]` (length 18) * `3`: tor v2 onion service. data = `[10:onion_addr][2:port]` (length 12) @@ -213,14 +220,14 @@ The following `address descriptor` types are defined: ### Requirements -The creating node MUST set `timestamp` to be greater than any previous -`node_announcement` it has created. It MAY base it on a UNIX -timestamp. It MUST set `signature` to the signature of -the double-SHA256 of the entire remaining packet after `signature` using the -key given by `node_id`. It MAY set `alias` and `rgb_color` to customize their node's appearance in maps and graphs, where the first byte of `rgb` is the red value, the second byte is the green value and the last byte is the blue value. It MUST set `alias` to a valid UTF-8 string, with any `alias` bytes following equal to zero. +The creating node MUST set `timestamp` to be greater than that for any previous +`node_announcement` it has created. It MAY base it on a UNIX +timestamp. It MUST set `signature` to the signature of +the double-SHA256 of the entire remaining packet after `signature`, using the +key given by `node_id`. It MAY set `alias` and `rgb_color` to customize the node's appearance in maps and graphs, where the first byte of `rgb` is the red value, the second byte is the green value and the last byte is the blue value. It MUST set `alias` to a valid UTF-8 string, with any `alias` bytes following equal to zero. The creating node SHOULD fill `addresses` with an address descriptor -for each public network address which expects incoming connections, +for each public network address that expects incoming connections, and MUST set `addrlen` to the number of bytes in `addresses`. Non-zero typed address descriptors MUST be placed in ascending order; any number of zero-typed address descriptors MAY be placed anywhere, @@ -228,7 +235,7 @@ but SHOULD only be used for aligning fields following `addresses`. The creating node MUST NOT create a type 1 or type 2 address descriptor with `port` equal to zero, and SHOULD ensure `ipv4_addr` -and `ipv6_addr` are routable addresses. The creating node MUST NOT include +and `ipv6_addr` are routable addresses. The creating node MUST NOT include more than one `address descriptor` of the same type. The creating node SHOULD set `flen` to the minimum length required to @@ -245,8 +252,8 @@ following `alias`), and MUST NOT further process the message. If the `features` field contains unknown even bits the receiving node MUST NOT parse the remainder of the message and MAY discard the message altogether. The node MAY forward `node_announcement`s that contain unknown `features` bit set, even though it hasn't parsed the announcement. -The receiving node SHOULD ignore the first `address descriptor` which -does not match the types defined above. The receiving node SHOULD +The receiving node SHOULD ignore the first `address descriptor` that +does not match the types defined above. The receiving node SHOULD fail the connection if `addrlen` is insufficient to hold the address descriptors of the known types. @@ -256,26 +263,26 @@ if `port` is zero. The receiving node SHOULD ignore the message if `node_id` is not previously known from a `channel_announcement` message, or if `timestamp` is not greater than the last-received -`node_announcement` from this `node_id`. Otherwise, if the +`node_announcement` from this `node_id`. Otherwise, if the `timestamp` is greater than the last-received `node_announcement` from this `node_id` the receiving node SHOULD queue the message for rebroadcasting, but MAY choose not to for messages longer than the minimum expected length. The receiving node SHOULD NOT connect to a node which has an unknown -`features` bit set in the `node_announcement` which is even. +`features` bit set in the `node_announcement` that is even. The receiving node MAY use `rgb_color` and `alias` to reference nodes in interfaces, but SHOULD insinuate their self-signed origin. ### Rationale -New node features are possible in future; backwards compatible (or +New node features are possible in the future; backwards compatible (or optional) ones will have odd feature bits, incompatible ones will have even feature bits. These may be propagated by nodes even if they can't use the announcements themselves. -New address types can be added in future; as address descriptors have -to be ordered in ascending order so they will be safely ignored. +New address types can be added in the future; as address descriptors have +to be ordered in ascending order, unknown ones can be safely ignored. Future fields beyond `addresses` can still be added, optionally with padding within `addresses` if they require certain alignment. @@ -283,23 +290,24 @@ padding within `addresses` if they require certain alignment. After a channel has been initially announced, each side independently announces the fees and minimum expiry delta it requires to relay HTLCs -through this channel. It uses the 8-byte -channel shortid which matches the `channel_announcement` and one bit +through this channel. They use the 8-byte +channel shortid that matches the `channel_announcement` and one bit in the `flags` field -to indicate which end this is. It can do this multiple times, if +to indicate which end this is. A node can do this multiple times, if it wants to change fees. Note that the `channel_update` message is only useful in the context of *relaying* payments, not *sending* payments. When making a payment `A` -> `B` -> `C` -> `D`, only the `channel_update`s related to channels `B` -> `C` (announced by `B`) and `C` -> `D` (announced by `C`) will - come into play. When building the route, amounts and expiries for htlcs need - to be calculated backwards from the destination to the source. The initial + come into play. When building the route, amounts and expiries for HTLCs need + to be calculated backward from the destination to the source. The initial exact value for `amount_msat` and minimal value for `htlc_expiry`, which are to be used for the last HTLC in the route, are provided in the payment request (see [BOLT #11](11-payment-encoding.md#tagged-fields)). A node MAY still create a `channel_update` to communicate the channel parameters to the other endpoint, even though the channel has not been announced, e.g., because the `announce_channel` bit was not set. + For further privacy such a `channel_update` MUST NOT be forwarded to other peers. Note that such a `channel_update` that is not preceded by a `channel_announcement` is invalid to any other peer and would be discarded. @@ -315,7 +323,7 @@ Note that such a `channel_update` that is not preceded by a `channel_announcemen * [`4`:`fee_base_msat`] * [`4`:`fee_proportional_millionths`] -The `flags` bitfield is used to indicate the direction of the channel this update concerns, i.e., it identifies the node that this update originated from, and signal various options concerning the channel. +The `flags` bitfield is used to indicate the direction of the channel this update concerns: it identifies the node that this update originated from and signals various options concerning the channel. The following table specifies the meaning of the individual bits: | Bit Position | Name | Meaning | @@ -326,26 +334,25 @@ The following table specifies the meaning of the individual bits: ### Requirements The creating node MUST set `signature` to the signature of the -double-SHA256 of the entire remaining packet after `signature` using its own `node_id`. +double-SHA256 of the entire remaining packet after `signature`, using its own `node_id`. The creating node MUST set `chain_hash` and `short_channel_id` to match the 32-byte hash and 8-byte channel ID that uniquely identifies the channel within the `channel_announcement` message. -The creating node MUST set `short_channel_id` to match those in the already-sent `channel_announcement` message, and MUST set the `direction` bit of `flags` to 0 if the creating node is `node_id_1` in that message, otherwise 1. +The creating node MUST set the `direction` bit of `flags` to 0 if the creating node is `node_id_1` in that message, otherwise 1. Bits which are not assigned a meaning must be set to 0. A node MAY create and send a `channel_update` with the `disable` bit set to signal the temporary unavailability of a channel, e.g., due to loss of connectivity, or the permanent unavailability, e.g., ahead of an on-chain settlement. A subsequent `channel_update` with the `disable` bit unset MAY re-enable the channel. The creating node MUST set `timestamp` to greater than zero, and MUST set it to greater than any previously-sent `channel_update` for this `short_channel_id`. +It MUST set `cltv_expiry_delta` to the number of blocks it will subtract from an incoming HTLCs `cltv_expiry`. It MUST set `htlc_minimum_msat` to the minimum HTLC value it will accept, in millisatoshi. It MUST set `fee_base_msat` to the base fee it will charge for any HTLC, in millisatoshi, and `fee_proportional_millionths` to the amount it will charge per transferred satoshi in millionths of a satoshi. -It MUST set `cltv_expiry_delta` to the number of blocks it will subtract from an incoming HTLCs `cltv_expiry`. It MUST set `htlc_minimum_msat` to the minimum HTLC value it will accept, in millisatoshi. It MUST set `fee_base_msat` to the base fee it will charge for any HTLC, in millisatoshi, and `fee_proportional_millionths` to the amount it will charge per transferred satoshi in millionths of a satoshi. - -The receiving nodes MUST ignore the `channel_update` if it does not correspond to one of its own channels, if the `short_channel_id` does not match a previous `channel_announcement`, or the channel has been closed in the meantime. +The receiving nodes MUST ignore the `channel_update` if it does not correspond to one of its own channels, if the `short_channel_id` does not match a previous `channel_announcement`, or if the channel has been closed in the meantime. It SHOULD accept `channel_update`s for its own channels in order to learn the other end's forwarding parameters, even for non-public channels. -The `node_id` for the signature verification is taken from the corresponding `channel_announcement`: `node_id_1` if least-significant bit of flags is 0 or `node_id_2` otherwise. +The `node_id` for the signature verification is taken from the corresponding `channel_announcement`: `node_id_1` if the least-significant bit of flags is 0 or `node_id_2` otherwise. The receiving node SHOULD fail the connection if `signature` is not a valid signature using `node_id` of the double-SHA256 of the entire message following the `signature` field (including unknown fields @@ -356,11 +363,11 @@ The receiving node MUST ignore the channel update if the specified chain. The receiving node SHOULD ignore the message if `timestamp` -is not greater than than the last-received `channel_announcement` for -this `short_channel_id` and `node_id`. Otherwise, if the `timestamp` is equal to +is not greater than that of the last-received `channel_announcement` for +this `short_channel_id` and `node_id`. Otherwise, if the `timestamp` is equal to the last-received `channel_announcement` and the fields other than `signature` differ, the node MAY blacklist this `node_id` and forget all -channels associated with it. Otherwise the receiving node SHOULD +channels associated with it. Otherwise the receiving node SHOULD queue the message for rebroadcasting, but MAY choose not to for messages longer than the minimum expected length. @@ -368,23 +375,21 @@ messages longer than the minimum expected length. Upon establishing a connection, the two endpoints negotiate whether to perform an initial sync by setting the `initial_routing_sync` flags in the `init` message. The endpoint SHOULD set the `initial_routing_sync` flag if it requires a full copy of the other endpoint's routing state. -Upon receiving an `init` message with the `initial_routing_sync` flag set the node sends `channel_announcement`s, `channel_update`s and `node_announcement`s for all known channels and nodes as if they were just received. +Upon receiving an `init` message with the `initial_routing_sync` flag set, the node sends `channel_announcement`s, `channel_update`s and `node_announcement`s for all known channels and nodes as if they were just received. -If the `initial_routing_sync` flag is not set, or initial sync was completed, then the node resumes normal operation, see the _Rebroadcasting_ section for details. +If the `initial_routing_sync` flag is not set, or initial sync was completed, then the node resumes normal operation: see the _Rebroadcasting_ section for details. ## Rebroadcasting Nodes receiving a new `channel_announcement` or a `channel_update` or -`node_announcement` with an updated timestamp update their local view of the network's topology accordingly. - -Once the announcement has been processed it is added to a list of outgoing announcements (perhaps replacing older updates) to the processing node's peers, which will be flushed at regular intervals. -This store and delayed forward broadcast is called a _staggered broadcast_ +`node_announcement` with an updated timestamp SHOULD update their local view of the network's topology accordingly. If, after applying the changes from the announcement, there are no channels associated with the announcing node, then the receiving node MAY purge the announcing node from the set of known nodes. Otherwise the receiving node updates the metadata and stores the signature associated with the announcement. This will later allow the receiving node to rebuild the announcement for its peers. -After processing the announcement the receiving node adds the announcement to a list of outgoing announcements. +Once the announcement has been processed, it is added to a list of outgoing announcements for the processing node's peers, perhaps replacing older updates. This list will be flushed at regular intervals. +This store-and-delayed-forward broadcast is called a _staggered broadcast_ ### Requirements @@ -398,20 +403,20 @@ connection establishment. ### Rationale -Batching announcements form a natural ratelimit with low overhead. +Batching announcements forms a natural rate limit with low overhead. The sending of all announcements on reconnection is naive, but simple, -and allows bootstrap for new nodes as well as updating for nodes which +and allows bootstrapping for new nodes as well as updating for nodes that have been offline for some time. ## HTLC Fees -The node creating `channel_update` SHOULD accept HTLCs which pay a fee equal or greater than: +The node creating `channel_update` SHOULD accept HTLCs that pay a fee equal or greater than: - fee_base_msat + amount_msat * fee_proportional_millionths / 1000000 + fee_base_msat + ( amount_msat * fee_proportional_millionths / 1000000 ) -The node creating `channel_update` SHOULD accept HTLCs which pay an -older fee for some time after sending `channel_update` to allow for +The node creating `channel_update` SHOULD accept HTLCs that pay an +older fee for some time after sending `channel_update`, to allow for propagation delay. ## Pruning the Network View @@ -419,15 +424,15 @@ propagation delay. Nodes SHOULD monitor the funding transactions in the blockchain to identify channels that are being closed. If the funding output of a channel is being spent, then the channel is to be considered closed and SHOULD be removed from the local network view. -Nodes MAY prune nodes added through `node_announcement` messages from their local view if the announced node no longer has any open channels associated. +Nodes MAY prune nodes added through `node_announcement` messages from their local view if the announced node no longer has any associated open channels. This is a direct result from the dependency of a `node_announcement` being preceded by a `channel_announcement`. -### Recommendation on pruning stale entries +### Recommendation on Pruning Stale Entries Several scenarios may result in channels becoming unusable and the endpoints unable to send updates for these channels. -This happens for example in the case that both endpoints lose access to their private keys and cannot sign a `channel_update` nor close the channel on-chain. -These channels are unlikely to be part of a computed route since they would be partitioned off from the rest of the network, however they would remain in the local network view and be forwarded to other nodes forever. -For this reason nodes MAY prune channels should the timestamp of the latest `channel_update` be older than 2 weeks (1209600 seconds). +For example, this happens in the case where both endpoints lose access to their private keys and cannot sign a `channel_update` nor close the channel on-chain. +These channels are unlikely to be part of a computed route since they would be partitioned off from the rest of the network, however they would remain in the local network view and information on them would be forwarded to other nodes forever. +For this reason, nodes MAY prune channels should the timestamp of the latest `channel_update` be older than 2 weeks (1209600 seconds). In addition nodes MAY ignore channels with a timestamp older than 2 weeks. Notice that this is a node policy and MUST NOT be enforced by peers, e.g., by closing channels when receiving outdated gossip messages. @@ -435,7 +440,7 @@ Notice that this is a node policy and MUST NOT be enforced by peers, e.g., by cl When calculating a route for an HTLC, the `cltv_expiry_delta` and the fee both need to be considered: the `cltv_expiry_delta` contributes to the time that funds -will be unavailable on worst-case failure. The tradeoff between these +will be unavailable on worst-case failure. The tradeoff between these two is unclear, as it depends on the reliability of nodes. If a route is computed by simply routing to the intended recipient, summing up the `cltv_expiry_delta`s, then nodes along the route may guess their position in the route. @@ -445,7 +450,7 @@ In order to create a plausible offset the sender MAY start a limited random walk This effectively creates a _shadow route extension_ to the actual route, providing better protection against this kind of attack than simply picking a random offset. Other more advanced considerations involve diversity of routes to -avoid single points of failure and detection, and channel balance +avoid single points of failure and detection and channel balance of local channels. ### Routing Example @@ -474,13 +479,13 @@ channel: C also uses a`min_final_cltv_expiry` of 9 (the default) when requesting payments. -Also, each node has the same fee scheme which it uses for each of its +Also, each node has a set fee scheme that it uses for each of its channels: 1. A: 100 base + 1000 millionths -1. B: 200 base + 2000 millionths -1. C: 300 base + 3000 millionths -1. D: 400 base + 4000 millionths +2. B: 200 base + 2000 millionths +3. C: 300 base + 3000 millionths +4. D: 400 base + 4000 millionths The network will see eight `channel_update` messages: @@ -493,11 +498,11 @@ The network will see eight `channel_update` messages: 1. C->B: `cltv_expiry_delta` = 30, `fee_base_msat` = 300, `fee_proportional_millionths` = 3000 1. C->D: `cltv_expiry_delta` = 30, `fee_base_msat` = 300, `fee_proportional_millionths` = 3000 -If B were to send 4,999,999 millisatoshi directly to C, it wouldn't +**B->C.** If B were to send 4,999,999 millisatoshi directly to C, it wouldn't charge itself a fee nor add its own `cltv_expiry_delta`, so it would -use C's requested `min_final_cltv_expiry` of 9. We also assume it adds a -"shadow route" to give an extra CLTV of 42. It could also add extra -cltv deltas at other hops, as these values are a minimum, but we don't +use C's requested `min_final_cltv_expiry` of 9. Assume it also adds a +"shadow route" to give an extra CLTV of 42. It could additionally add extra +CLTV deltas at other hops, as these values are a minimum, but it doesn't here for simplicity: * `amount_msat`: 4999999 @@ -506,11 +511,13 @@ here for simplicity: * `amt_to_forward` = 4999999 * `outgoing_cltv_value` = current-block-height + 9 + 42 -If A were to send an 4,999,999 millisatoshi to C via B, it needs to +**A->B->C.** If A were to send an 4,999,999 millisatoshi to C via B, it needs to pay B the fee it specified in the B->C `channel_update`, calculated as per [HTLC Fees](#htlc_fees): - 200 + 4999999 * 2000 / 1000000 = 10199 + fee_base_msat + ( amount_msat * fee_proportional_millionths / 1000000 ) + + 200 + ( 4999999 * 2000 / 1000000 ) = 10199 Similarly, it would need to add the `cltv_expiry` from B->C's `channel_update` (20), plus C's requested `min_final_cltv_expiry` (9), plus 42 for the @@ -526,7 +533,7 @@ be: The `update_add_htlc` from B to C would be the same as the B->C direct payment above. -Finally, if for some reason A chose the more expensive route via D, it +**A->D->C.** Finally, if for some reason A chose the more expensive route via D, it would send the following `update_add_htlc` to D: * `amount_msat`: 5020398 From ddce0e5f944626a1ee7be2f48599507ec4f94b00 Mon Sep 17 00:00:00 2001 From: Shannon Appelcline Date: Wed, 6 Dec 2017 15:26:03 -0800 Subject: [PATCH 8/8] Revising bolt-5 for this branch. --- 05-onchain.md | 268 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 170 insertions(+), 98 deletions(-) diff --git a/05-onchain.md b/05-onchain.md index 2dcbaff2f..b5716e593 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -2,15 +2,15 @@ ## Abstract -Lightning allows for two parties (nodes A and B) to conduct transactions off-chain by giving each of them a cross-signed *commitment transaction*, which describes the current state of the channel (basically, the current balance). This *commitment transaction* is updated every time a new payment is made, and is spendable at all times. +Lightning allows for two parties (A and B) to make transactions off-chain, by both holding a cross-signed *commitment transaction*, which describes the current state of the channel (basically the current balance). This *commitment transaction* is updated every time a new payment is made, and is spendable at all times. There are three ways a channel can end: -1. The good way (*mutual close*): at some point nodes A and B agree to close the channel. They generate a *closing transaction* (which is similar to a *commitment transaction* without any pending payments) and publish it on the blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)). -2. The bad way (*unilateral close*): something goes wrong, possibly without evil intent on either side. Perhaps one party crashed, for instance. One side publishes its latest *commitment transaction*. +1. The good way (*mutual close*): at some point A and B agree on closing the channel, they generate a *closing transaction* (which is similar to a *commitment transaction* without any pending payments), and publish it on the blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)). +2. The bad way (*unilateral close*): something goes wrong, without necessarily any evil intent on either side (maybe one party crashed, for instance). Anyway, one side publishes its latest *commitment transaction*. 3. The ugly way (*revoked transaction close*): one of the parties deliberately tries to cheat by publishing an outdated version of its *commitment transaction* (presumably one that was more in her favor). -Because Lightning is designed to be trustless, there is no risk of loss of funds in any of these three cases, provided that the situation is properly handled. The goal of this document is to explain exactly how node A should react to seeing any of these transactions appear on-chain. +Because Lightning is designed to be trustless, there is no risk of loss of funds in any of these 3 cases, provided that the situation is properly handled. The goal of this document is to explain exactly how node A should react to seeing any of these on-chain. # Table of Contents * [General Nomenclature](#general-nomenclature) @@ -25,69 +25,83 @@ Because Lightning is designed to be trustless, there is no risk of loss of funds * [Penalty Transactions Weight Calculation](#penalty-transactions-weight-calculation) * [General Requirements](#general-requirements) * [Appendix A: Expected weights](#appendix-a-expected-weights) - * [Expected Weight of the `to_local` Penalty Transaction Witness](#expected-weight-of-the-to-local-penalty-transaction-witness) - * [Expected Weight of the `received_htlc` Penalty Transaction Witness](#expected-weight-of-the-received-htlc-penalty-transaction-witness) - * [Expected Weight of the `accepted_htlc` Penalty Transaction Witness](#expected-weight-of-the-accepted-htlc-penalty-transaction-witness) + * [Expected weight of the `to_local` penalty transaction witness](#expected-weight-of-the-to-local-penalty-transaction-witness) + * [Expected weight of the received-htlc penalty transaction witness](#expected-weight-of-the-received-htlc-penalty-transaction-witness) * [Authors](#authors) # General Nomenclature We consider any unspent output to be *unresolved*, and *resolve* them -as detailed in this document. Usually this means spending it with -another *resolving* transaction. Sometimes it simply means noting the output +as detailed in this document. Usually this means spending it with +another *resolving* transaction. Sometimes it simply means noting it for later wallet spending, in which case the transaction containing the output is considered to be its own *resolving* transaction. -Outputs that are *resolved* are considered *irrevocably resolved* + +Outputs which are *resolved* are considered *irrevocably resolved* once their *resolving* transaction is included in a block at least 100 -deep on the most-work blockchain. 100 blocks is far greater than the +deep on the most-work blockchain. 100 blocks is far greater than the longest known Bitcoin fork, and the same value used to wait for confirmations of miner's rewards (see [Reference Implementation](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223)). + ## Requirements + Once a node has broadcast a funding transaction or sent a commitment -signature for a commitment transaction that contains an HTLC output, -it MUST monitor the blockchain for transactions that spend any output -that is not *irrevocably resolved*, until all outputs are *irrevocably +signature for a commitment transaction which contains an HTLC output, +it MUST monitor the blockchain for transactions which spend any output +which is not *irrevocably resolved* until all outputs are *irrevocably resolved*. -A node MUST *resolve* all outputs as specified below and MUST be + +A node MUST *resolve* all outputs as specified below, and MUST be prepared to resolve them multiple times in case of blockchain reorganizations. + A node SHOULD fail the channel if it is not already closed when it -sees the funding transaction spent. A node MAY send a descriptive +sees the funding transaction spent. A node MAY send a descriptive error packet in this case. + Invalid transactions SHOULD be ignored. + ## Rationale + Once a node has had some money at stake, monitoring is required to ensure the other side does not close unilaterally. + Invalid transactions (eg. bad signatures) can be generated by anyone, (and will be ignored by the blockchain anyway), so they should not trigger any action. + # Commitment Transaction -Nodes A and B each hold a *commitment transaction*, each of which has four types of outputs: -1. _A's main output_: Zero or one outputs that pay to A's commitment key. -2. _B's main output_: Zero or one outputs that pay to B's commitment key. +A and B each hold a *commitment transaction*, which has 4 types of outputs: + + +1. _A's main output_: Zero or one outputs which pay to A's commitment key. +2. _B's main output_: Zero or one outputs which pay to B's commitment key. 3. _A's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay B in return for a payment preimage. 4. _B's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay A in return for a payment preimage. -As an incentive for nodes A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers node A's outputs in A's *commitment transaction*, and node B's outputs in B's *commitment transaction*. If node A publishes its commitment transaction, it won't be able to get its funds immediately but node B will. As a consequence, node A and B's *commitment transactions* are not identical, but they are (usually) symmetrical. + +As an incentive for A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers A's outputs in A's *commitment transaction*, and B's outputs in B's *commitment transaction*. If A publishes its commitment transaction, she won't be able to get her funds immediately but B will. As a consequence, A and B's *commitment transactions* are not identical, they are (usually) symmetrical. + See [BOLT #3: Commitment Transaction](03-transactions.md#commitment-transaction) for more details. + # Failing A Channel -Various error cases involve closing a channel. This can be done in -several ways; the most efficient is preferred. Note that there are +Various error cases involve closing a channel, and this can be done in +several ways; the most efficient is preferred. Note that there are requirements around sending the error message to the peer in [BOLT #1: The `error` message](01-messaging.md#the-error-message). @@ -114,34 +128,43 @@ In the early stages of a channel, it's common for one side to have little or no money in the channel; with nothing to lose, there's no reason to consume resources monitoring the channel state. -There's a bias towards using mutual close over unilateral, because -outputs are unencumbered by a delay and are directly spendable by wallets, and +There's a bias towards using mutual close over unilateral because +outputs are unencumbered by delay, directly spendable by wallets, and because fees tend to be less exaggerated than commitment transactions: thus the only reason not to use the signature from `closing_signed` would be if the fee offered was too small for it to be processed. + # Mutual Close Handling + A mutual close transaction *resolves* the funding transaction output. + A node doesn't need to do anything else as it has already agreed to the output, which is sent to its specified `scriptpubkey` (see [BOLT #2: Closing initiation: `shutdown`](02-peer-protocol.md#closing-initiation-shutdown)). + # Unilateral Close Handling + There are two cases to consider here: in the first case, node A sees -its own *commitment transaction*; in the second, it sees the node B's unrevoked +its own *commitment transaction*, in the second, it sees the node B's unrevoked *commitment transaction*. + Either transaction *resolves* the funding transaction output. + ## Requirements + When node A sees its own *commitment transaction*: + 1. _A's main output_: A node SHOULD spend this output to a convenient address. A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other - node's `to_self_delay` field) before spending the output. If the + node's `to_self_delay` field) before spending the output. If the output is spent (as recommended), the output is *resolved* by the spending transaction, otherwise it is considered *resolved* by the *commitment transaction* itself. 2. _B's main output_: No action required, this output is considered *resolved* @@ -152,6 +175,7 @@ When node A sees its own *commitment transaction*: Similarly, when node A sees a *commitment transaction* from B: + 1. _A's main output_: No action is required; this is a simple P2WPKH output. This output is considered *resolved* by the *commitment transaction* itself. 2. _B's main output_: No action required, this output is considered *resolved* @@ -161,189 +185,231 @@ Similarly, when node A sees a *commitment transaction* from B: A node MUST handle the broadcast of any valid *commitment transaction* -from node B in this way; if it is unable to do so it MUST warn about lost funds. +from B in this way; if it is unable to do so it MUST warn about lost funds. + ## Rationale + Spending the `to_local` output avoids having to remember the complicated witness script associated with that particular channel for later spending. + Note that there can be more than one valid, unrevoked *commitment transaction* after a signature has been received via `commitment_signed` and -before the corresponding `revoke_and_ack`. Either commitment can serve as -a node's *commitment transaction*, hence the requirement to handle both. +before the corresponding `revoke_and_ack`. Either commitment can serve as +B's *commitment transaction*, hence the requirement to handle both. -In the case of data loss, a node can reach a state where it doesn't -recognize all of the other node's commitment transaction HTLC outputs. It can tell + +In the case of data loss, a node can reach a state where we don't +recognize all of B's commitment transaction HTLC outputs. It can tell this has happened because the commitment number will be greater than -expected, and because it has signed the transaction. -If both nodes support `option-data-loss-protect` the node will -know B's `per_commitment_point` and thus be able to derive its own -`remotekey` for the transaction and salvage its own funds (but not the +expected, and the fact that the transaction has been signed by this +node. If both nodes support `option-data-loss-protect` the node will +know the B's `per_commitment_point` and thus be able to derive its own +`remotekey` for the transaction and salvage its own funds (but not HTLCs). + # On-chain HTLC Output Handling: Our Offers -Each HTLC output can only be spent by us, the offerer, after it's timed out, -or by them, the recipient, if they have the payment preimage. -The HTLC output has *timed out* once the depth of the latest block is equal -or greater than the HTLC `cltv_expiry`. -The method by which the HTLC times out differs depending -on which party the commitment transaction belongs to. +Each HTLC output can only be spent by us after it's timed out, +or them if they have the payment preimage. -There can be HTLCs that are not represented by an output: either -because they were trimmed as dust, or because the receipient has two +There can be HTLCs which are not represented by an output: either +because they were trimmed as dust, or in the case where B has two valid commitment transactions, and the HTLCs differ in each. +The HTLC has *timed out* once the depth of the latest block is equal +or greater than the HTLC `cltv_expiry`. + +The method by which we time out the HTLC output differs depending +on whether it's our own commitment transaction, or theirs. + ## Requirements + If the HTLC output is spent using the payment preimage, the HTLC output is considered *irrevocably resolved*, and the node MUST extract the payment preimage from the transaction input witness. + If the HTLC output has *timed out* and not been *resolved*, the node MUST *resolve* the output and MUST fail the corresponding incoming HTLC (if any) once the resolving transaction has reached reasonable -depth. If the transaction is the node's own +depth. If the transaction is the node's own commitment transaction, it MUST *resolve* the output by spending it using the HTLC-timeout transaction, and the HTLC-timeout transaction output MUST be *resolved* as described in "On-chain HTLC -Transaction Handling". Otherwise it MUST resolve the +Transaction Handling". Otherwise it MUST resolve the output by spending it to a convenient address. -For any committed HTLC that does not have an output in this + +For any committed HTLC which does not have an output in this commitment transaction, the node MUST fail the corresponding incoming HTLC (if any) once the commitment transaction has reached reasonable depth, and MAY fail it sooner if no valid commitment transaction contains an output corresponding to the HTLC. + ## Rationale -If the commitment transaction is the recipient's, the only way to spend the + +If the commitment transaction is theirs, the only way to spend the HTLC output using a payment preimage is for them to use the -HTLC-success transaction. If the commitment transaction is the offerer's, the recipient +HTLC-success transaction. If the commitment transaction is ours, they could create any transaction using the preimage. -The payment preimage either serves to prove payment (when the offering node originated the payment) or -to redeem the corresponding incoming HTLC from another peer (when the offering node is forwarding the payment). Once a node has extracted the payment, it no longer cares about the fate of the HTLC-spending transaction itself. -In cases where both resolutions are possible (e.g., when a node receives payment success after timeout), either interpretation is -acceptable; it is the responsibility of the recipient to spend it +The payment preimage either serves to prove payment (if this node +originated the payment), or to redeem the corresponding incoming HTLC +from another peer. Note that we don't care about the fate of the +HTLC-spending transaction itself once we've extracted the payment +preimage; the knowledge is not revocable. + + +Note that in cases where both resolutions are possible (payment +success seen after timeout, for example), either interpretation is +acceptable; it is the responsibility of the other node spend it before this occurs. -If the commitment transaction is the recipient's, the offerer's signature alone is enough + +If the commitment transaction is theirs, our signature alone is enough to spend the HTLC output (see -[BOLT #3](03-transactions.md#received-htlc-outputs)), but the offerer needs to -do so, otherwise the recipient could fulfill the HTLC after the timeout. If -the commitment transaction is the offerer's, the offerer must use the HTLC-timeout +[BOLT #3](03-transactions.md#received-htlc-outputs)), but we need to +do so, otherwise they could fulfill the HTLC after the timeout. If +the commitment transaction is ours, we need to use the HTLC-timeout transaction. + The fulfillment of an on-chain HTLC delivers the `payment_preimage` -required to fulfill the incoming HTLC (if it, too, is on-chain) or to use +required to fulfill the incoming HTLC (if it, too, is on-chain) or use in the `update_fulfill_htlc` message for the incoming HTLC. -Otherwise, the node needs to send the `update_fail_htlc` (presumably with +Otherwise, it needs to send the `update_fail_htlc` (presumably with reason `permanent_channel_failure`) as detailed in [BOLT 02](https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#forwarding-htlcs). + If an HTLC is too small to appear in *any* commitment transaction, it can be safely failed immediately and `update_fail_htlc` returned to -the incoming HTLC (if any: it might be locally-generated). - -If a HTLC isn't in the commitment transaction a node needs to make sure +the incoming HTLC (if any: it might be locally-generated). Otherwise, +if a HTLC isn't in the commitment transaction we need to make sure that a blockchain reorganization or race does not switch to a -commitment transaction that does contain it before the node fails it, hence -the wait. The requirement that the incoming HTLC be failed before its +commitment transaction which does contain it, before we fail it, hence +the wait. The requirement that we fail the incoming HTLC before its own timeout still applies as an upper bound. + # On-chain HTLC Output Handling: Their Offers -Each HTLC output can only be spent by us, the recipient (if we have the payment -preimage), or them, the offerer (if it has timed out). + +Each HTLC output can only be spent by us if we have the payment +preimage, or them if it has timed out. There are actually several possible cases for an offered HTLC: -1. The offerer is not irrevocably committed to the offered HTLC; this can only - happen if the recipient has not received `revoke_and_ack` so that the offerer - holds two valid commitment transactions, one with the HTLC and - one without. The recipient won't normally know the preimage here, unless it's - a payment to itself, and revealing that would be an information leak, +1. The other node is not irrevocably committed to it; this can only + happen if we have not received `revoke_and_ack` so that the other + node holds two valid commitment transactions, one with the HTLC and + one without. We won't normally know the preimage here, unless it's + a payment to ourselves, and revealing that would be an information leak, so it's best to allow the HTLC to time out in this case. -2. The offerer is irrevocably committed to the offered HTLC, but the recipient hasn't yet - committed to an outgoing HTLC. In this case the recipient can either forward +2. The other node is irrevocably committed to it, but we haven't yet + committed to an outgoing HTLC. In this case we can either forward or timeout. -3. The recipient has committed to an outgoing HTLC for the offered one. In - this case the recipient has to use the preimage if it receives it from the - outgoing HTLC, otherwise it will lose funds by making an outgoing +3. We have committed to an outgoing HTLC for this incoming one. In + this case we have to use the preimage if we receive it from the + outgoing HTLC, otherwise we will lose funds by making an outgoing payment without redeeming the incoming one. ## Requirements + If the node receives (or already knows) a payment preimage for an unresolved HTLC output it was offered for which it has committed to an outgoing HTLC, it MUST *resolve* the output by spending it. Otherwise, if the other node is not irrevocably committed to the HTLC, it MUST NOT *resolve* the output by spending it. + To spend an offered HTLC output: if the transaction is the node's own commitment transaction, then it MUST use the HTLC-success transaction, and the HTLC-success transaction output MUST be *resolved* as described in "On-chain HTLC Transaction Handling", otherwise, it MUST spend the output to a convenient address. + If not otherwise resolved, once the HTLC output has expired, it is considered *irrevocably resolved*. + ## Rationale -If this is the recipient's commitment transaction, it can only use a payment + +If this is our commitment transaction, we can only use a payment preimage with the HTLC-success transaction (which preserves the -`to_self_delay` requirement). Otherwise the recipient can create any transaction it wants to +`to_self_delay` requirement). Otherwise we can create any transaction we want to resolve it. -The recipient doesn't care about expired offers: it's the sender's responsibility to ensure that the + +We don't care about expired offers: we should have ensured that the HTLC can only expire long it is needed. + # On-chain HTLC Transaction Handling + Because to-self payments have to be delayed (to allow time for a -penalty transaction), HTLC outputs can only be spent by the node that +penalty transaction), HTLC outputs can only be spent by the node which broadcast the *commitment transaction* using the HTLC-timeout or the HTLC-success transaction, which include that delay. + ## Requirements + A node SHOULD resolve its own HTLC transaction output by spending it -to a convenient address. A node MUST wait until the +to a convenient address. A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other node's `open_channel` `to_self_delay` field) before spending the output. + If the output is spent (as recommended), the output is *resolved* by the spending transaction, otherwise it is considered *resolved* by the *commitment transaction* itself. + ## Rationale + Spending the `to_local` output avoids having to remember the complicated witness script associated with that particular channel for later spending. + # Revoked Transaction Close Handling -If a node tries to broadcast old state, the other node can use the revocation key + +If a node tries to broadcast old state, we can use the revocation key to claim all the funds. + ## Requirements + A node MUST NOT broadcast a *commitment transaction* for which it has exposed the revocation key. + If a node sees a *commitment transaction* for which it has a revocation key, that *resolves* the funding transaction output. + A node MUST resolve all unresolved outputs as follows: + 1. _A's main output_: No action is required; this is a simple P2WPKH output. This output is considered *resolved* by the *commitment transaction*. 2. _B's main output_: The node MUST *resolve* this by spending using the @@ -358,48 +424,52 @@ A node MUST resolve all unresolved outputs as follows: 5. _B's HTLC-timeout transaction_: The node MUST *resolve* this by spending using the revocation key. 6. _B's HTLC-success transaction_: The node MUST *resolve* this by - spending using the revocation key. The node SHOULD extract + spending using the revocation key. The node SHOULD extract the payment preimage from the transaction input witness if not already known. + The node MAY use a single transaction to *resolve* all the outputs, but MUST handle its transactions being invalidated by HTLC transactions. + ## Rationale -A single transaction that resolves all the outputs will be under the + +A single transaction which resolves all the outputs will be under the standard size limit thanks to the 483 HTLC-per-party limit (see [BOLT #2](02-peer-protocol.md#the-open_channel-message)). -Note that if a single transaction is used it may be invalidated as node B +Note that if a single transaction is used, it may be invalidated as B broadcasts HTLC-timeout and HTLC-success transactions, but the -requirement of persistence, until all outputs are irrevocably resolved, +requirement that we persist until all outputs are irrevocably resolved should cover this. [FIXME: May have to divide and conquer here, since they may be able to delay us long enough to avoid successful penalty spend? ] ## Penalty Transactions Weight Calculation -There are three different scripts for penalty transactions, with the following witnesses weight (details of the computation are in [Appendix A](#appendix-a-expected-weights)): +There are three different scripts for penalty transactions, with the following witnesses weight (details of the computation in [Appendix A](#appendix-a-expected-weights)): to_local_penalty_witness: 160 bytes offered_htlc_penalty_witness: 243 bytes accepted_htlc_penalty_witness: 249 bytes -The penalty txinput itself takes 41 bytes, which has a weight of 164, making the weight of each input: +The penalty txinput itself takes 41 bytes, thus has a weight of 164, making the weight of each input: to_local_penalty_input_weight: 324 bytes offered_htlc_penalty_input_weight: 407 bytes accepted_htlc_penalty_input_weight: 413 bytes + The rest of the penalty transaction takes 4+1+1+8+1+34+4=53 bytes of non-witness -data, assuming that it has a pay-to-witness-script-hash (the largest standard output -script), in addition to a 2-byte witness header. +data, assuming it has a pay-to-witness-script-hash (the largest standard output +script), in addition to a 2 byte witness header. In addition to outputs being swept under as penalty, the node MAY also sweep the -`to_remote` output of the commitment transaction (e.g. to reduce the total -amount paid in fees). Doing so requires the inclusion of a p2wpkh witness and +`to_remote` output of the commitment transaction, e.g. to reduce the total +amount paid in fees. Doing so requires the inclusion of a p2wpkh witness and additional txinput, resulting in an additional 108 + 164 = 272 bytes. -In a worst case scenario, a node holds only incoming HTLCs, and the HTLC-timeout -transactions are not published, which forces the node to spend from the commitment +In a worst case scenario, we have only incoming HTLCs and the HTLC-timeout +transactions are not published, forcing us to spend from the commitment transaction. With a maximum standard weight of 400000, the maximum number of HTLCs that can @@ -407,19 +477,21 @@ be swept in a single transaction: max_num_htlcs = (400000 - 324 - 272 - 4*53 - 2) / 413 = 966 -This allows 483 HTLCs in each direction (with both `to_local` and -`to_remote` outputs) to still be resolved in a single penalty transaction. +Thus we could allow 483 HTLCs in each direction (with both `to_local` and +`to_remote` outputs) and still resolve it with a single penalty transaction. Note that even if the `to_remote` output is not swept, the resulting `max_num_htlcs` is 967, which yields the same unidirectional limit of 483 HTLCs. # General Requirements + A node SHOULD report an error to the operator if it sees a transaction spend the funding transaction output which does not fall into one of these categories (mutual close, unilateral close, or revoked transaction close). Such a transaction implies its private key has leaked, and funds may be lost. + A node MAY simply watch the contents of the most-work chain for transactions, or MAY watch for (valid) broadcast transactions a.k.a mempool. Considering mempool transactions should cause lower latency @@ -428,7 +500,7 @@ that speed cannot be considered critical. # Appendix A: Expected weights -## Expected Weight of the `to_local` Penalty Transaction Witness +## Expected weight of the `to_local` penalty transaction witness As described in [BOLT #3](03-transactions.md), the witness for this transaction is: @@ -460,7 +532,7 @@ The *expected weight* is calculated as follows: - witness_script (to_local_script) -## Expected Weight of the `offered_htlc` Penalty Transaction Witness +## Expected weight of the offered-htlc penalty transaction witness The *expected weight* is calculated as follows (some calculations have already been made in [BOLT #3](03-transactions.md)): @@ -476,7 +548,7 @@ The *expected weight* is calculated as follows (some calculations have already b - witness_script (offered_htlc_script) -## Expected Weight of the `accepted_htlc` Penalty Transaction Witness +## Expected weight of the received-htlc penalty transaction witness The *expected weight* is calculated as follows (some calculations have already been made in [BOLT #3](03-transactions.md)):