mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2024-11-19 10:00:04 +01:00
Code Issues Projects Releases Wiki Activity

BOLT 5: first pass copy edit to line 113, change ephasis scheme;

Browse Source
This commit is contained in:
Landon Mutch 2017-12-09 15:42:12 -08:00 committed by Rusty Russell
parent cc7811cea8
commit 11abe4724e
1 changed files with 77 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

150
05-onchain.md
View File

@ -5,26 +5,26 @@
Lightning allows for two parties (nodes A and B) to conduct transactions 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 off-chain by giving each of them a cross-signed *commitment transaction*, which
describes the current state of the channel (basically, the current balance). describes the current state of the channel (basically, the current balance).
This *commitment transaction* is updated every time a new payment is made, and This *commitment transaction* is updated every time a new payment is made and
is spendable at all times. is spendable at all times.
There are three ways a channel can end: 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 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 channel. They generate a *closing transaction* (which is similar to a
*commitment transaction* without any pending payments) and publish it on the commitment transaction, but without any pending payments) and publish it on the
blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)). blockchain (see [BOLT #2: Channel Close](02-peer-protocol.md#channel-close)).
2. The bad way (*unilateral close*): something goes wrong, possibly without evil 2. The bad way (*unilateral close*): something goes wrong, possibly without evil
intent on either side. Perhaps one party crashed, for instance. One side intent on either side. Perhaps one party crashed, for instance. One side
publishes its latest *commitment transaction*. publishes its *latest* commitment transaction.
3. The ugly way (*revoked transaction close*): one of the parties deliberately 3. The ugly way (*revoked transaction close*): one of the parties deliberately
tries to cheat by publishing an outdated version of its *commitment transaction* tries to cheat, by publishing an outdated version of *its* commitment transaction
(presumably one that was more in her favor). (presumably one that is more in its favor).
Because Lightning is designed to be trustless, there is no risk of loss of funds 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. in any of these three cases; provided that the situation is properly handled.
The goal of this document is to explain exactly how a node should react to The goal of this document is to explain exactly how a node should react when it
seeing any of these on-chain. encounters any of the above situations, on-chain.
# Table of Contents # Table of Contents
* [General Nomenclature](#general-nomenclature) * [General Nomenclature](#general-nomenclature)
@ -48,62 +48,66 @@ seeing any of these on-chain.
# General Nomenclature # General Nomenclature
We consider any unspent output to be *unresolved*, and *resolve* them Any unspent output is considered to be *unresolved* and is *resolved*
as detailed in this document. Usually this means spending it with as detailed in this document. Usually this is accomplished by spending it with
another *resolving* transaction. Sometimes it simply means noting the output another *resolving* transaction. Although, sometimes simply noting the output
for later wallet spending, in which case the transaction containing for later wallet spending is sufficient, in which case the transaction containing
the output is considered to be its own *resolving* transaction. the output is considered to be its own *resolving* transaction.
Outputs that 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 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 longest known Bitcoin fork and is the same wait time used for
confirmations of miner's rewards (see [Reference Implementation](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223)). confirmations of miners' rewards (see [Reference Implementation](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223)).
## Requirements ## Requirements
Once a node has broadcast a funding transaction or sent a commitment A node:
signature for a commitment transaction that contains an HTLC output, - once it has broadcast a funding transaction OR sent a commitment signature
it MUST monitor the blockchain for transactions that spend any output for a commitment transaction that contains an HTLC output:
that is not *irrevocably resolved*, until all outputs are *irrevocably - until all outputs are *irrevocably resolved*:
resolved*. - MUST monitor the blockchain for transactions that spend any output that
is NOT *irrevocably resolved*.
A node MUST *resolve* all outputs as specified below and MUST be - MUST *resolve* all outputs, as specified below.
prepared to resolve them multiple times in case of blockchain - MUST be prepared to resolve outputs multiple times, in case of blockchain
reorganizations. reorganizations.
- upon the funding transaction being spent, if the channel is NOT already
A node SHOULD fail the channel if it is not already closed when it closed:
sees the funding transaction spent. A node MAY send a descriptive - SHOULD fail the channel.
error packet in this case. - MAY send a descriptive error packet.
- SHOULD ignore invalid transactions.
Invalid transactions SHOULD be ignored.
## Rationale ## Rationale
Once a node has had some money at stake, monitoring is required to Once a node has had some money at stake, monitoring is required to
ensure the other side does not close unilaterally. ensure the other party does not close unilaterally.
Invalid transactions (eg. bad signatures) can be generated by anyone, Invalid transactions (e.g. bad signatures) can be generated by anyone,
(and will be ignored by the blockchain anyway), so they should not (and will be ignored by the blockchain anyway), so they should not
trigger any action. trigger any action.
# Commitment Transaction # Commitment Transaction
Nodes A and B each hold a *commitment transaction*, each of which has four types of outputs: Nodes A and B each hold a *commitment transaction*. Each of these commitment
transactions has four types of outputs:
1. _A's main output_: Zero or one outputs that pay to A's commitment key. 1. _A's main output_: Zero or one output, to pay to *A's* commitment key.
2. _B's main output_: Zero or one outputs that pay to B's commitment key. 2. _B's main output_: Zero or one output, to 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. 3. _A's offered HTLCs_: Zero or more pending payments (*HTLCs*), to pay *B* in
4. _B's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay A in return for a payment preimage. 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` To incentivize nodes A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative
relative timeout encumbers node A's outputs in A's *commitment transaction*, and 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 node *B's outputs* (in *B's* commitment transaction). So for example, if node A
commitment transaction, it won't be able to get its funds immediately but node B publishes its commitment transaction, it will have to wait to claim its funds,
will. As a consequence, node A and B's *commitment transactions* are not whereas node B will have immediate access to its funds. As a consequence, the
identical, but they are (usually) symmetrical. two commitment transactions are not identical, but they are (usually)
symmetrical.
See [BOLT #3: Commitment Transaction](03-transactions.md#commitment-transaction) for more details. See [BOLT #3: Commitment Transaction](03-transactions.md#commitment-transaction)
for more details.
# Failing a Channel # Failing a Channel
@ -114,15 +118,15 @@ requirements around sending the error message to the peer in
## Requirements ## Requirements
- If no local commitment transaction ever contained a `to_local` - If no *local* commitment transaction ever contained a `to_local`
or HTLC output, the node MAY simply forget the channel. or HTLC output, the node MAY simply forget the channel.
- Otherwise, if the current commitment transaction does not contain - Otherwise, if the *current* commitment transaction does not contain
`to_local` or HTLC outputs, a node MAY simply wait and rely on the `to_local` or HTLC outputs, a node MAY simply wait and rely on the
other node to close, but MUST not forget the channel. other node to close, but MUST not forget the channel.
- Otherwise, if the node has received a valid `closing_signed` message - Otherwise, if the node has received a valid `closing_signed` message
with high enough fee level, it SHOULD use that to perform a mutual with high enough fee level, it SHOULD use that to perform a mutual
close. close.
- Otherwise, it MUST use the last commitment transaction for which it - Otherwise, it MUST use the *last* commitment transaction for which it
has a signature to perform unilateral close. has a signature to perform unilateral close.
## Rationale ## Rationale
@ -151,9 +155,9 @@ output, which is sent to its specified `scriptpubkey` (see [BOLT #2: Closing ini
# Unilateral Close Handling: Our Own Commitment Transaction # Unilateral Close Handling: Our Own Commitment Transaction
There are two unilateral cases to consider: in this case, a node sees There are two unilateral cases to consider: in this case, a node sees
its own *commitment transaction*. *its own* commitment transaction.
Our own commitment transaction *resolves* the funding transaction output. *Our own* commitment transaction *resolves* the funding transaction output.
A node can't claim funds from the outputs of its own unilateral close A node can't claim funds from the outputs of its own unilateral close
until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by
@ -162,15 +166,15 @@ noted below.
## Requirements ## Requirements
When a node sees its own *commitment transaction*: When a node sees *its own* commitment transaction:
1. `to_local` output: A node SHOULD spend this output to a convenient address. 1. `to_local` 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 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 output is spent (as recommended), the output is *resolved* by the spending
transaction, otherwise it is considered *resolved* by the *commitment transaction* itself. transaction, otherwise it is considered *resolved* by the commitment transaction itself.
2. `to_remote` output: No action required, this output is considered *resolved* 2. `to_remote` output: No action required, this output is considered *resolved*
by the *commitment transaction* itself. by the commitment transaction itself.
3. HTLCs offered by this node: See "HTLC Output Handling: Our Commitment, Our Offers" below. 3. HTLCs offered by this node: See "HTLC Output Handling: Our Commitment, Our Offers" below.
4. HTLCs offered by the other node: See "HTLC Output Handling: Our Commitment, Their Offers" below. 4. HTLCs offered by the other node: See "HTLC Output Handling: Our Commitment, Their Offers" below.
@ -213,7 +217,7 @@ transaction.
A node SHOULD resolve that HTLC-timeout transaction by spending it to A node SHOULD resolve that HTLC-timeout transaction by spending it to
a convenient address. If the output is spent (as recommended), the a convenient address. If the output is spent (as recommended), the
output is *resolved* by the spending transaction, otherwise it is output is *resolved* by the spending transaction, otherwise it is
considered *resolved* by the *commitment transaction* itself. considered *resolved* by the commitment transaction itself.
A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed
(as specified by the other node's `open_channel` `to_self_delay` (as specified by the other node's `open_channel` `to_self_delay`
@ -222,7 +226,7 @@ field) before spending that HTLC-timeout output.
For any committed HTLC that 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 commitment transaction, the node MUST fail the corresponding incoming
HTLC (if any) once the commitment transaction has reached reasonable HTLC (if any) once the commitment transaction has reached reasonable
depth, and MAY fail it sooner if no valid commitment transaction depth, and MAY fail it sooner if no *valid* commitment transaction
contains an output corresponding to the HTLC. contains an output corresponding to the HTLC.
### Rationale ### Rationale
@ -247,7 +251,7 @@ no way to signal early failure.
If an HTLC is too small to appear in *any* commitment transaction, it If an HTLC is too small to appear in *any* commitment transaction, it
can be safely failed immediately. Otherwise, can be safely failed immediately. Otherwise,
if a HTLC isn't in our commitment transaction a node needs to make sure if a HTLC isn't in *our* commitment transaction a node needs to make sure
that a blockchain reorganization or race does not switch to a that a blockchain reorganization or race does not switch to a
commitment transaction which does contain it before the node fails it, hence commitment transaction which does contain it before the node fails it, hence
the wait. The requirement that the incoming HTLC be failed before its the wait. The requirement that the incoming HTLC be failed before its
@ -288,7 +292,7 @@ spending it.
A node SHOULD resolve that HTLC-success transaction output by spending A node SHOULD resolve that HTLC-success transaction output by spending
it to a convenient address. If the output is spent (as recommended), it to a convenient address. If the output is spent (as recommended),
the output is *resolved* by the spending transaction, otherwise it is the output is *resolved* by the spending transaction, otherwise it is
considered *resolved* by the *commitment transaction* itself. considered *resolved* by the commitment transaction itself.
A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed
(as specified by the other node's `open_channel` `to_self_delay` (as specified by the other node's `open_channel` `to_self_delay`
@ -299,7 +303,7 @@ If not otherwise resolved, once the HTLC output has expired, it is considered
# Unilateral Close Handling: Their Commitment Transaction # Unilateral Close Handling: Their Commitment Transaction
The other node's commitment transaction *resolves* the funding The *other node's* commitment transaction *resolves* the funding
transaction output. transaction output.
There are no delays constraining behavior here, so it's simpler than There are no delays constraining behavior here, so it's simpler than
@ -307,28 +311,28 @@ when dealing with one's own commitment transaction.
## Requirements ## Requirements
When a node sees a *commitment transaction* from the other node: When a node sees a commitment transaction from the *other node*:
1. `to_remote`: No action is required; this is a simple P2WPKH output to us. 1. `to_remote`: No action is required; this is a simple P2WPKH output to us.
This output is considered *resolved* by the *commitment transaction* itself. This output is considered *resolved* by the commitment transaction itself.
2. `to_local`:: No action required; this is a payment to them. This output is considered *resolved* 2. `to_local`:: No action required; this is a payment to them. This output is considered *resolved*
by the *commitment transaction*. by the commitment transaction.
3. HTLCs offered by this node: See "HTLC Output Handling: Their Commitment, Our Offers" below. 3. HTLCs offered by this node: See "HTLC Output Handling: Their Commitment, Our Offers" below.
4. HTLCs offered by the other node: See "HTLC Output Handling: Their Commitment, Their Offers" below. 4. HTLCs offered by the other node: See "HTLC Output Handling: Their Commitment, Their Offers" below.
A node MUST handle the broadcast of any valid *commitment transaction* A node MUST handle the broadcast of any *valid* commitment transaction
from the other node in this way; if it is unable to do so it MUST warn from the *other node* in this way; if it is unable to do so it MUST warn
about lost funds. about lost funds.
## Rationale ## Rationale
Note that there can be more than one valid, unrevoked *commitment Note that there can be more than one valid, *unrevoked* commitment
transaction* after a signature has been received via `commitment_signed` and transaction after a signature has been received via `commitment_signed` and
before the corresponding `revoke_and_ack`. Either commitment can serve as before the corresponding `revoke_and_ack`. Either commitment can serve as
the other node's *commitment transaction*, hence the requirement to handle both. the *other node'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 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 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 this has happened because the commitment number will be greater than
expected, and because it has signed the transaction. expected, and because it has signed the transaction.
If both nodes support `option-data-loss-protect` the node will If both nodes support `option-data-loss-protect` the node will
@ -346,7 +350,7 @@ or greater than the HTLC `cltv_expiry`.
There can be HTLCs which are not represented by an output: either There can be HTLCs which are not represented by an output: either
because they were trimmed as dust, or in the case where the other node has two because they were trimmed as dust, or in the case where the other node has two
valid commitment transactions, and the HTLCs differ in each. *valid* commitment transactions, and the HTLCs differ in each.
### Requirements ### Requirements
@ -362,12 +366,12 @@ to a convenient address.
For any committed HTLC that 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 commitment transaction, the node MUST fail the corresponding incoming
HTLC (if any) once the commitment transaction has reached reasonable HTLC (if any) once the commitment transaction has reached reasonable
depth, and MAY fail it sooner if no valid commitment transaction depth, and MAY fail it sooner if no *valid* commitment transaction
contains an output corresponding to the HTLC. contains an output corresponding to the HTLC.
### Rationale ### Rationale
If the commitment transaction is theirs, 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 output using a payment preimage is for them to use the
HTLC-success transaction. HTLC-success transaction.
@ -391,7 +395,7 @@ timeout: there's no way to signal early failure.
If an HTLC is too small to appear in *any* commitment transaction, it If an HTLC is too small to appear in *any* commitment transaction, it
can be safely failed immediately. Otherwise, can be safely failed immediately. Otherwise,
if a HTLC isn't in our commitment transaction a node needs to make sure if a HTLC isn't in *our* commitment transaction a node needs to make sure
that a blockchain reorganization or race does not switch to a that a blockchain reorganization or race does not switch to a
commitment transaction which does contain it before the node fails it, hence commitment transaction which does contain it before the node fails it, hence
the wait. The requirement that the incoming HTLC be failed before its the wait. The requirement that the incoming HTLC be failed before its
@ -441,16 +445,16 @@ to claim all the funds.
## Requirements ## Requirements
A node MUST NOT broadcast a *commitment transaction* for which it has A node MUST NOT broadcast a commitment transaction for which *it* has
exposed the revocation key. exposed the revocation key.
If a node sees a *commitment transaction* for which it has a If a node sees a commitment transaction for which *it* has a
revocation key, that *resolves* the funding transaction output. revocation key, that *resolves* the funding transaction output.
A node MUST resolve all unresolved outputs as follows: A node MUST resolve all unresolved outputs as follows:
1. _A's main output_: No action is required; this is a simple P2WPKH output. 1. _A's main output_: No action is required; this is a simple P2WPKH output.
This output is considered *resolved* by the *commitment transaction*. This output is considered *resolved* by the commitment transaction.
2. _B's main output_: The node MUST *resolve* this by spending using the 2. _B's main output_: The node MUST *resolve* this by spending using the
revocation key. revocation key.
3. _A's offered HTLCs_: The node MUST *resolve* these in one of three ways: 3. _A's offered HTLCs_: The node MUST *resolve* these in one of three ways: