mirror of
https://github.com/lightning/bolts.git
synced 2024-11-19 01:50:03 +01:00
BOLT 5: change us/them terminology to local/remote;
This commit is contained in:
Landon Mutch
Rusty Russell
parent
9c6ca1b722
commit
6a2b1dd841
@ -31,12 +31,12 @@ encounters any of the above situations, on-chain.
|
||||
* [Commitment Transaction](#commitment-transaction)
|
||||
* [Failing a Channel](#failing-a-channel)
|
||||
* [Mutual Close Handling](#mutual-close-handling)
|
||||
* [Unilateral Close Handling: Our Own Commitment Transaction](#unilateral-close-handling-our-own-commitment-transaction)
|
||||
* [HTLC Output Handling: Our Commitment, Our Offers](#htlc-output-handling-our-commitment-our-offers)
|
||||
* [HTLC Output Handling: Our Commitment, Their Offers](#htlc-output-handling-our-commitment-their-offers)
|
||||
* [Unilateral Close Handling: Their Commitment Transaction](#unilateral-close-handling-their-commitment-transaction)
|
||||
* [HTLC Output Handling: Their Commitment, Our Offers](#htlc-output-handling-their-commitment-our-offers)
|
||||
* [HTLC Output Handling: Their Commitment, Their Offers](#htlc-output-handling-their-commitment-their-offers)
|
||||
* [Unilateral Close Handling: Local Commitment Transaction](#unilateral-close-handling-local-own-commitment-transaction)
|
||||
* [HTLC Output Handling: Local Commitment, Local Offers](#htlc-output-handling-local-commitment-local-offers)
|
||||
* [HTLC Output Handling: Local Commitment, Remote Offers](#htlc-output-handling-local-commitment-remote-offers)
|
||||
* [Unilateral Close Handling: Remote Commitment Transaction](#unilateral-close-handling-remote-commitment-transaction)
|
||||
* [HTLC Output Handling: Remote Commitment, Local Offers](#htlc-output-handling-remote-commitment-local-offers)
|
||||
* [HTLC Output Handling: Remote Commitment, Remote Offers](#htlc-output-handling-remote-commitment-remote-offers)
|
||||
* [Revoked Transaction Close Handling](#revoked-transaction-close-handling)
|
||||
* [Penalty Transactions Weight Calculation](#penalty-transactions-weight-calculation)
|
||||
* [General Requirements](#general-requirements)
|
||||
@ -55,7 +55,7 @@ for later wallet spending is sufficient, in which case the transaction containin
|
||||
the output is considered to be its own *resolving* transaction.
|
||||
|
||||
Outputs that are *resolved* are considered *irrevocably resolved*
|
||||
once their *resolving* transaction is included in a block at least 100
|
||||
once the remote's *resolving* transaction is included in a block at least 100
|
||||
deep, on the most-work blockchain. 100 blocks is far greater than the
|
||||
longest known Bitcoin fork and is the same wait time used for
|
||||
confirmations of miners' rewards (see [Reference Implementation](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223)).
|
||||
@ -79,8 +79,8 @@ A node:
|
||||
|
||||
## Rationale
|
||||
|
||||
Once a node has had some money at stake, monitoring is required to
|
||||
ensure the other party does not close unilaterally.
|
||||
Once a local node has some funds at stake, monitoring the blockchain is required
|
||||
to ensure the remote party does not close unilaterally.
|
||||
|
||||
Invalid transactions (e.g. bad signatures) can be generated by anyone,
|
||||
(and will be ignored by the blockchain anyway), so they should not
|
||||
@ -127,8 +127,8 @@ A node:
|
||||
- otherwise:
|
||||
- if the *current commitment transaction* does NOT contain `to_local` or
|
||||
other HTLC outputs:
|
||||
- MAY simply wait for the other node to close the channel.
|
||||
- until the other node closes:
|
||||
- MAY simply wait for the remote node to close the channel.
|
||||
- until the remote node closes:
|
||||
- MUST NOT forget the channel.
|
||||
- otherwise:
|
||||
- if it has received a valid `closing_signed` message that includes a
|
||||
@ -163,7 +163,7 @@ In the case of a mutual close, a node need not 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: Our Own Commitment Transaction
|
||||
# Unilateral Close Handling: Local Own Commitment Transaction
|
||||
|
||||
This is the first of two cases involving unilateral closes: in this case, a
|
||||
node sees *its own commitment transaction*, which *resolves* the funding
|
||||
@ -178,14 +178,14 @@ the other node's `to_self_delay` field). Where relevant, this is noted below.
|
||||
When a node sees *its own* commitment transaction:
|
||||
|
||||
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 remote
|
||||
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. `to_remote` output: No action required, this output is considered *resolved*
|
||||
by the commitment transaction itself.
|
||||
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.
|
||||
3. HTLCs offered by this node: See "HTLC Output Handling: Local Commitment, Local Offers" below.
|
||||
4. HTLCs offered by the remote node: See "HTLC Output Handling: Local Commitment, Remote Offers" below.
|
||||
|
||||
## Rationale
|
||||
|
||||
@ -193,10 +193,10 @@ Spending the `to_local` output avoids having to remember the complicated
|
||||
witness script associated with that particular channel for later
|
||||
spending.
|
||||
|
||||
The `to_remote` output is entirely the business of the other node, and
|
||||
The `to_remote` output is entirely the business of the remote node, and
|
||||
can be ignored.
|
||||
|
||||
## HTLC Output Handling: Our Commitment, Our Offers
|
||||
## HTLC Output Handling: Local Commitment, Local Offers
|
||||
|
||||
Each HTLC output can only be spent by us, the offerer, using the HTLC-timeout
|
||||
transaction after it's timed out, or by them, the recipient, if they have the payment
|
||||
@ -229,7 +229,7 @@ output is *resolved* by the spending transaction, otherwise it is
|
||||
considered *resolved* by the commitment transaction itself.
|
||||
|
||||
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 remote node's `open_channel` `to_self_delay`
|
||||
field) before spending that HTLC-timeout output.
|
||||
|
||||
For any committed HTLC that does not have an output in this
|
||||
@ -250,7 +250,7 @@ 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.
|
||||
|
||||
We need to use our HTLC-timeout transaction to time out the HTLC to prevent them
|
||||
We need to use local HTLC-timeout transaction to time out the HTLC to prevent them
|
||||
fulfilling it and claiming the funds, and before we can back-fail any
|
||||
corresponding incoming HTLC, using `update_fail_htlc` (presumably with reason
|
||||
`permanent_channel_failure`) as detailed in
|
||||
@ -260,13 +260,13 @@ no way to signal early failure.
|
||||
|
||||
If an HTLC is too small to appear in *any* commitment transaction, it
|
||||
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 *local* 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 the node fails it, hence
|
||||
the wait. The requirement that the incoming HTLC be failed before its
|
||||
own timeout still applies as an upper bound.
|
||||
|
||||
## HTLC Output Handling: Our Commitment, Their Offers
|
||||
## HTLC Output Handling: Local Commitment, Remote Offers
|
||||
|
||||
Each HTLC output can only be spent by us, the recipient, using the HTLC-success
|
||||
transaction, which we can only populate if we have the payment
|
||||
@ -294,7 +294,7 @@ 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 using the
|
||||
HTLC-success transaction, and MUST resolve the output of that
|
||||
HTLC-success transaction. Otherwise, if the other node is not
|
||||
HTLC-success transaction. Otherwise, if the remote node is not
|
||||
irrevocably committed to the HTLC, it MUST NOT *resolve* the output by
|
||||
spending it.
|
||||
|
||||
@ -304,15 +304,15 @@ the output is *resolved* by the spending transaction, otherwise it is
|
||||
considered *resolved* by the commitment transaction itself.
|
||||
|
||||
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 remote node's `open_channel` `to_self_delay`
|
||||
field) before spending that HTLC-success transaction output.
|
||||
|
||||
If not otherwise resolved, once the HTLC output has expired, it is considered
|
||||
*irrevocably resolved*.
|
||||
|
||||
# Unilateral Close Handling: Their Commitment Transaction
|
||||
# Unilateral Close Handling: Remote Commitment Transaction
|
||||
|
||||
The *other node's* commitment transaction *resolves* the funding
|
||||
The *remote node's* commitment transaction *resolves* the funding
|
||||
transaction output.
|
||||
|
||||
There are no delays constraining behavior here, so it's simpler than
|
||||
@ -320,17 +320,17 @@ when dealing with one's own commitment transaction.
|
||||
|
||||
## Requirements
|
||||
|
||||
When a node sees a commitment transaction from the *other node*:
|
||||
When a node sees a commitment transaction from the *remote node*:
|
||||
|
||||
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.
|
||||
2. `to_local`:: No action required; this is a payment to them. This output is considered *resolved*
|
||||
by the commitment transaction.
|
||||
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.
|
||||
3. HTLCs offered by the local node: See "HTLC Output Handling: Remote Commitment, Local Offers" below.
|
||||
4. HTLCs offered by the remote node: See "HTLC Output Handling: Remote Commitment, Remote Offers" below.
|
||||
|
||||
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 *remote node* in this way; if it is unable to do so it MUST warn
|
||||
about lost funds.
|
||||
|
||||
## Rationale
|
||||
@ -338,10 +338,10 @@ about lost funds.
|
||||
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
|
||||
the *other node's* commitment transaction, hence the requirement to handle both.
|
||||
the *remote 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
|
||||
recognize all of the *other node's* commitment transaction HTLC outputs. It can tell
|
||||
recognize all of the *remote node'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
|
||||
@ -349,7 +349,7 @@ know the peer's `per_commitment_point` and thus be able to derive its own
|
||||
`remotekey` for the transaction and salvage its own funds (but not the
|
||||
HTLCs).
|
||||
|
||||
## HTLC Output Handling: Their Commitment, Our Offers
|
||||
## HTLC Output Handling: Remote Commitment, Local 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.
|
||||
@ -358,7 +358,7 @@ The HTLC output has *timed out* once the depth of the latest block is equal
|
||||
or greater than the HTLC `cltv_expiry`.
|
||||
|
||||
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 remote node has two
|
||||
*valid* commitment transactions, and the HTLCs differ in each.
|
||||
|
||||
### Requirements
|
||||
@ -380,7 +380,7 @@ 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 *remotes*, the only way to spend the
|
||||
HTLC output using a payment preimage is for them to use the
|
||||
HTLC-success transaction.
|
||||
|
||||
@ -404,20 +404,20 @@ timeout: there's no way to signal early failure.
|
||||
|
||||
If an HTLC is too small to appear in *any* commitment transaction, it
|
||||
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 the *local* 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 the node fails it, hence
|
||||
the wait. The requirement that the incoming HTLC be failed before its
|
||||
own timeout still applies as an upper bound.
|
||||
|
||||
## HTLC Output Handling: Their Commitment, Their Offers
|
||||
## HTLC Output Handling: Remote Commitment, Remote Offers
|
||||
|
||||
Each HTLC output can only be spent by us, the recipient, using the payment
|
||||
preimage. If we don't have the preimage (and don't discover it), it's
|
||||
the offerer's responsibility to spend the HTLC output once it's timed out.
|
||||
|
||||
We can only spend their HTLC outputs if we have the payment preimage.
|
||||
If we don't have the preimage (and don't discover it), it's their
|
||||
We can only spend remote HTLC outputs if we have the payment preimage.
|
||||
If we don't have the preimage (and don't discover it), it's the remote's
|
||||
responsibility to spend the HTLC output once it's timed out.
|
||||
|
||||
There are actually several possible cases for an offered HTLC:
|
||||
@ -440,7 +440,7 @@ There are actually several possible cases for an offered HTLC:
|
||||
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 to a
|
||||
convenient address. Otherwise, if the other node is not irrevocably
|
||||
convenient address. Otherwise, if the remote node is not irrevocably
|
||||
committed to the HTLC, it MUST NOT *resolve* the output by spending
|
||||
it.
|
||||
|
||||
@ -449,7 +449,7 @@ If not otherwise resolved, once the HTLC output has expired, it is considered
|
||||
|
||||
# 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, the remote node can use the revocation key
|
||||
to claim all the funds.
|
||||
|
||||
## Requirements
|
||||
|
||||
Loading…
Reference in New Issue
Block a user