2016-11-15 02:23:20 +01:00
# BOLT #5: Recommendations for On-chain Transaction Handling
## Abstract
2017-12-09 20:38:37 +01:00
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.
2016-11-15 02:23:20 +01:00
There are three ways a channel can end:
2017-12-09 20:38:37 +01:00
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 three cases, provided that the situation is properly handled.
The goal of this document is to explain exactly how a node should react to
seeing any of these on-chain.
2016-11-15 02:23:20 +01:00
2017-05-11 03:46:05 +02:00
# Table of Contents
* [General Nomenclature ](#general-nomenclature )
* [Commitment Transaction ](#commitment-transaction )
2017-12-09 21:04:58 +01:00
* [Failing a Channel ](#failing-a-channel )
2017-05-11 03:46:05 +02:00
* [Mutual Close Handling ](#mutual-close-handling )
2017-12-06 04:09:47 +01:00
* [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 )
2017-05-11 03:46:05 +02:00
* [Revoked Transaction Close Handling ](#revoked-transaction-close-handling )
* [Penalty Transactions Weight Calculation ](#penalty-transactions-weight-calculation )
* [General Requirements ](#general-requirements )
2017-12-09 21:04:58 +01:00
* [Appendix A: Expected Weights ](#appendix-a-expected-weights )
2017-12-06 07:08:32 +01:00
* [Expected Weight of the `to_local` Penalty Transaction Witness ](#expected-weight-of-the-to-local-penalty-transaction-witness )
2017-12-09 21:04:58 +01:00
* [Expected Weight of the `offered_htlc` Penalty Transaction Witness ](#expected-weight-of-the-offered-htlc-penalty-transaction-witness )
2017-12-06 07:08:32 +01:00
* [Expected Weight of the `accepted_htlc` Penalty Transaction Witness ](#expected-weight-of-the-accepted-htlc-penalty-transaction-witness )
2017-05-11 03:46:05 +02:00
* [Authors ](#authors )
2016-11-15 02:23:20 +01:00
# General Nomenclature
We consider any unspent output to be *unresolved* , and *resolve* them
2017-12-06 07:08:32 +01:00
as detailed in this document. Usually this means spending it with
another *resolving* transaction. Sometimes it simply means noting the output
2016-11-15 02:23:20 +01:00
for later wallet spending, in which case the transaction containing
the output is considered to be its own *resolving* transaction.
2017-12-06 07:08:32 +01:00
Outputs that are *resolved* are considered *irrevocably resolved*
2016-11-15 02:23:20 +01:00
once their *resolving* transaction is included in a block at least 100
2017-12-06 07:08:32 +01:00
deep on the most-work blockchain. 100 blocks is far greater than the
2016-12-08 07:54:35 +01:00
longest known Bitcoin fork, and the same value used to wait for
2017-11-15 13:20:38 +01:00
confirmations of miner's rewards (see [Reference Implementation ](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223 )).
2016-11-15 02:23:20 +01:00
## Requirements
Once a node has broadcast a funding transaction or sent a commitment
2017-12-06 07:08:32 +01:00
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
2016-11-15 02:23:20 +01:00
resolved*.
2017-12-06 07:08:32 +01:00
A node MUST *resolve* all outputs as specified below and MUST be
2016-11-15 02:23:20 +01:00
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
2017-12-06 07:08:32 +01:00
sees the funding transaction spent. A node MAY send a descriptive
2016-11-15 02:23:20 +01:00
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
2017-12-06 07:08:32 +01:00
Nodes A and B each hold a *commitment transaction* , each of which has four types of outputs:
2016-11-15 02:23:20 +01:00
2017-12-06 07:08:32 +01:00
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.
2016-11-15 02:23:20 +01:00
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.
2017-12-09 20:38:37 +01:00
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.
2016-11-15 02:23:20 +01:00
2017-05-11 03:46:05 +02:00
See [BOLT #3: Commitment Transaction ](03-transactions.md#commitment-transaction ) for more details.
2016-11-15 02:23:20 +01:00
2017-12-09 21:04:58 +01:00
# Failing a Channel
2017-05-16 03:21:12 +02:00
2017-12-06 07:08:32 +01:00
Various error cases involve closing a channel. This can be done in
several ways; the most efficient is preferred. Note that there are
2017-05-16 03:21:12 +02:00
requirements around sending the error message to the peer in
[BOLT #1: The `error` message ](01-messaging.md#the-error-message ).
## Requirements
- If no local commitment transaction ever contained a `to_local`
or HTLC output, the node MAY simply forget the channel.
- Otherwise, if the current commitment transaction does not contain
`to_local` or HTLC outputs, a node MAY simply wait and rely on the
other node to close, but MUST not forget the channel.
- Otherwise, if the node has received a valid `closing_signed` message
with high enough fee level, it SHOULD use that to perform a mutual
close.
- Otherwise, it MUST use the last commitment transaction for which it
has a signature to perform unilateral close.
## Rationale
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
little or no money in the channel; with nothing to lose, there's no
reason to consume resources monitoring the channel state.
2017-12-06 07:08:32 +01:00
There's a bias towards using mutual close over unilateral, because
outputs are unencumbered by a delay and are directly spendable by wallets, and
2017-05-16 03:21:12 +02:00
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.
2016-11-15 02:23:20 +01:00
# 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
2017-05-11 03:46:05 +02:00
output, which is sent to its specified `scriptpubkey` (see [BOLT #2: Closing initiation: `shutdown` ](02-peer-protocol.md#closing-initiation-shutdown )).
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
# Unilateral Close Handling: Our Own Commitment Transaction
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
There are two unilateral cases to consider: in this case, a node sees
its own *commitment transaction* .
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
Our own commitment transaction *resolves* the funding transaction output.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
A node can't claim funds from the outputs of its own unilateral close
until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by
2017-12-09 20:38:37 +01:00
the other node's `to_self_delay` field). Where this applies, it's
2017-12-06 04:09:47 +01:00
noted below.
2016-11-15 02:23:20 +01:00
## Requirements
2017-12-06 04:09:47 +01:00
When a node sees its own *commitment transaction* :
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
1. `to_local` output: A node SHOULD spend this output to a convenient address.
2016-11-15 02:23:20 +01:00
A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other
2017-12-06 07:08:32 +01:00
node's `to_self_delay` field) before spending the output. If the
2016-11-15 02:23:20 +01:00
output is spent (as recommended), the output is *resolved* by the spending
transaction, otherwise it is considered *resolved* by the *commitment transaction* itself.
2017-12-06 04:09:47 +01:00
2. `to_remote` output: No action required, this output is considered *resolved*
2017-05-02 09:20:37 +02:00
by the *commitment transaction* itself.
2017-12-06 04:09:47 +01:00
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.
2016-11-15 02:23:20 +01:00
## Rationale
2017-05-14 04:36:13 +02:00
Spending the `to_local` output avoids having to remember the complicated
2016-11-15 02:23:20 +01:00
witness script associated with that particular channel for later
spending.
2017-12-06 04:09:47 +01:00
The `to_remote` output is entirely the business of the other node, and
can be ignored.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
## HTLC Output Handling: Our Commitment, Our Offers
2017-09-06 07:13:50 +02:00
2017-12-06 07:08:32 +01:00
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
2017-12-06 04:09:47 +01:00
preimage.
2016-11-15 02:23:20 +01:00
2017-08-31 03:32:25 +02:00
There can be HTLCs which are not represented by an output: either
2017-12-06 04:09:47 +01:00
because they were trimmed as dust, or because it's only been partially
committed.
2016-11-15 02:23:20 +01:00
The HTLC has *timed out* once the depth of the latest block is equal
2017-05-11 03:46:05 +02:00
or greater than the HTLC `cltv_expiry` .
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
### Requirements
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
If the commitment transaction HTLC output is spent using the payment
preimage, the output is considered *irrevocably resolved* , and the
node MUST extract the payment preimage from the transaction input
witness.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
If the commitment transaction HTLC output has *timed out* and not
been *resolved* , the node MUST *resolve* the output by spending it
using the HTLC-timeout transaction, MUST fail the corresponding
incoming HTLC (if any) once the resolving transaction has reached
reasonable depth, and MUST resolve the output of that HTLC-timeout
transaction.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
A node SHOULD resolve that HTLC-timeout transaction by spending it to
2017-12-06 07:08:32 +01:00
a convenient address. If the output is spent (as recommended), the
2017-12-06 04:09:47 +01:00
output is *resolved* by the spending transaction, otherwise it is
considered *resolved* by the *commitment transaction* itself.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
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 that HTLC-timeout output.
2016-11-15 02:23:20 +01:00
2017-12-06 07:08:32 +01:00
For any committed HTLC that does not have an output in this
2017-08-31 03:32:25 +02:00
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.
2017-12-06 04:09:47 +01:00
### Rationale
2017-08-31 03:32:25 +02:00
2017-12-09 20:38:37 +01:00
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.
2016-11-15 02:23:20 +01:00
2017-12-09 20:38:37 +01:00
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.
2016-11-15 02:23:20 +01:00
2017-12-09 20:38:37 +01:00
We need to use our 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
2017-12-06 04:09:47 +01:00
`permanent_channel_failure` ) as detailed in
2017-12-09 20:38:37 +01:00
[BOLT 02 ](https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#forwarding-htlcs ).
If the incoming HTLC is on-chain too, we simply wait for it to timeout: there's
no way to signal early failure.
2017-08-21 04:47:12 +02:00
2017-08-31 03:32:25 +02:00
If an HTLC is too small to appear in *any* commitment transaction, it
2017-12-06 07:08:32 +01:00
can be safely failed immediately. Otherwise,
if a HTLC isn't in our commitment transaction a node needs to make sure
2017-08-31 03:32:25 +02:00
that a blockchain reorganization or race does not switch to a
2017-12-06 07:08:32 +01:00
commitment transaction which does contain it before the node fails it, hence
2017-12-09 20:38:37 +01:00
the wait. The requirement that the incoming HTLC be failed before its
2017-08-31 03:32:25 +02:00
own timeout still applies as an upper bound.
2017-12-06 04:09:47 +01:00
## HTLC Output Handling: Our Commitment, Their Offers
2017-08-31 03:32:25 +02:00
2017-12-06 07:08:32 +01:00
Each HTLC output can only be spent by us, the recipient, using the HTLC-success
2017-12-06 04:09:47 +01:00
transaction, which we can only populate if we have the payment
2017-12-09 20:38:37 +01:00
preimage. If we don't have the preimage (and don't discover it), it's
2017-12-06 07:08:32 +01:00
the offerer's responsibility to spend the HTLC output once it's timed out.
2016-11-15 02:23:20 +01:00
2017-09-18 02:33:11 +02:00
There are actually several possible cases for an offered HTLC:
2017-12-09 20:38:37 +01:00
1. The offerer is not irrevocably committed to it. The recipient won't
2017-12-06 07:08:32 +01:00
normally know the preimage here, since it won't forward HTLCs until
2017-12-09 20:38:37 +01:00
they're fully committed. So using the preimage would reveal that
2017-12-06 07:08:32 +01:00
this recipient is the final hop, so it's best to allow the HTLC to time out in
2017-12-06 04:09:47 +01:00
this case.
2017-12-06 07:08:32 +01:00
2. The offerer is irrevocably committed to the offered HTLC, but the recipient hasn't yet
2017-12-09 20:38:37 +01:00
committed to an outgoing HTLC. In this case the recipient can either forward
2017-09-18 02:33:11 +02:00
or timeout.
2017-12-09 20:38:37 +01:00
3. The recipient has committed to an outgoing HTLC for the offered one. In
2017-12-06 07:08:32 +01:00
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
2017-09-18 02:33:11 +02:00
payment without redeeming the incoming one.
2017-12-06 04:09:47 +01:00
### Requirements
2016-11-15 02:23:20 +01:00
If the node receives (or already knows) a payment preimage for an
2017-09-18 02:33:11 +02:00
unresolved HTLC output it was offered for which it has committed to an
2017-12-06 04:09:47 +01:00
outgoing HTLC, it MUST *resolve* the output by spending it using the
HTLC-success transaction, and MUST resolve the output of that
2017-12-09 20:38:37 +01:00
HTLC-success transaction. Otherwise, if the other node is not
2017-12-06 04:09:47 +01:00
irrevocably committed to the HTLC, it MUST NOT *resolve* the output by
spending it.
2017-09-18 02:33:11 +02:00
2017-12-06 04:09:47 +01:00
A node SHOULD resolve that HTLC-success transaction output by spending
2017-12-09 20:38:37 +01:00
it to a convenient address. If the output is spent (as recommended),
2017-12-06 04:09:47 +01:00
the output is *resolved* by the spending transaction, otherwise it is
considered *resolved* by the *commitment transaction* itself.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
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 that HTLC-success transaction output.
2016-11-15 02:23:20 +01:00
2017-09-18 02:33:11 +02:00
If not otherwise resolved, once the HTLC output has expired, it is considered
2016-11-15 02:23:20 +01:00
*irrevocably resolved*.
2017-12-09 21:04:58 +01:00
# Unilateral Close Handling: Their Commitment Transaction
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
The other node's commitment transaction *resolves* the funding
transaction output.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
There are no delays constraining behavior here, so it's simpler than
when dealing with one's own commitment transaction.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
## Requirements
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.
This output is considered *resolved* by the *commitment transaction* itself.
2017-12-09 20:38:37 +01:00
2. `to_local` :: No action required; this is a payment to them. This output is considered *resolved*
2017-12-06 04:09:47 +01:00
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.
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
about lost funds.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
## Rationale
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
Note that there can be more than one valid, unrevoked *commitment
transaction* after a signature has been received via `commitment_signed` and
2017-12-06 07:08:32 +01:00
before the corresponding `revoke_and_ack` . Either commitment can serve as
2017-12-06 04:09:47 +01:00
the other node's *commitment transaction* , hence the requirement to handle both.
2016-11-15 02:23:20 +01:00
2017-12-06 07:08:32 +01:00
In the case of data loss, a node can reach a state where it doesn't
2017-12-09 20:38:37 +01:00
recognize all of the other node's commitment transaction HTLC outputs. It can tell
2017-12-06 04:09:47 +01:00
this has happened because the commitment number will be greater than
2017-12-06 07:08:32 +01:00
expected, and because it has signed the transaction.
If both nodes support `option-data-loss-protect` the node will
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
2017-12-06 04:09:47 +01:00
HTLCs).
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
## HTLC Output Handling: Their Commitment, Our Offers
2016-11-15 02:23:20 +01:00
2017-12-06 07:08:32 +01:00
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` .
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
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
valid commitment transactions, and the HTLCs differ in each.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
### Requirements
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
If the commitment transaction HTLC output is spent using the payment
preimage, the output is considered *irrevocably resolved* , and the
node MUST extract the payment preimage from the HTLC-success transaction input
witness.
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
If the commitment transaction HTLC output has *timed out* and not
been *resolved* , the node MUST *resolve* the output by spending it
to a convenient address.
2016-11-15 02:23:20 +01:00
2017-12-06 07:08:32 +01:00
For any committed HTLC that does not have an output in this
2017-12-06 04:09:47 +01:00
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.
2016-11-15 02:23:20 +01:00
2017-12-09 21:04:58 +01:00
### Rationale
2016-11-15 02:23:20 +01:00
2017-12-06 04:09:47 +01:00
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.
2016-11-15 02:23:20 +01:00
2017-12-09 20:38:37 +01:00
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.
2017-12-06 04:09:47 +01:00
2017-12-09 20:38:37 +01:00
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.
2017-12-06 04:09:47 +01:00
We need to spend the HTLC output once it has timed out to prevent
them using the HTLC-success transaction, and before we can
back-fail any corresponding incoming HTLC, using `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 the incoming HTLC is on-chain too, we simply wait for it to
timeout: there's no way to signal early failure.
If an HTLC is too small to appear in *any* commitment transaction, it
2017-12-06 07:08:32 +01:00
can be safely failed immediately. Otherwise,
if a HTLC isn't in our commitment transaction a node needs to make sure
2017-12-06 04:09:47 +01:00
that a blockchain reorganization or race does not switch to a
2017-12-06 07:08:32 +01:00
commitment transaction which does contain it before the node fails it, hence
2017-12-09 20:38:37 +01:00
the wait. The requirement that the incoming HTLC be failed before its
2017-12-06 04:09:47 +01:00
own timeout still applies as an upper bound.
## HTLC Output Handling: Their Commitment, Their Offers
2017-12-06 07:08:32 +01:00
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.
2017-12-06 04:09:47 +01:00
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
responsibility to spend the HTLC output once it's timed out.
There are actually several possible cases for an offered HTLC:
2017-12-09 20:38:37 +01:00
1. The offerer is not irrevocably committed to it. The recipient won't
2017-12-06 07:08:32 +01:00
normally know the preimage here, since it won't forward HTLCs until
2017-12-09 20:38:37 +01:00
they're fully committed. So using the preimage would reveal that
2017-12-06 07:08:32 +01:00
this recipient is the final hop, so it's best to allow the HTLC to time out in
2017-12-06 04:09:47 +01:00
this case.
2017-12-06 07:08:32 +01:00
2. The offerer is irrevocably committed to the offered HTLC, but the recipient hasn't yet
2017-12-09 20:38:37 +01:00
committed to an outgoing HTLC. In this case the recipient can either forward
2017-12-06 04:09:47 +01:00
or timeout.
2017-12-09 20:38:37 +01:00
3. The recipient has committed to an outgoing HTLC for the offered one. In
2017-12-06 07:08:32 +01:00
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
2017-12-06 04:09:47 +01:00
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 to a
2017-12-09 20:38:37 +01:00
convenient address. Otherwise, if the other node is not irrevocably
2017-12-06 04:09:47 +01:00
committed to the HTLC, it MUST NOT *resolve* the output by spending
it.
If not otherwise resolved, once the HTLC output has expired, it is considered
*irrevocably resolved*.
2016-11-15 02:23:20 +01:00
# Revoked Transaction Close Handling
2017-12-06 07:08:32 +01:00
If a node tries to broadcast old state, the other node can use the revocation key
2016-11-15 02:23:20 +01:00
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
revocation key.
2017-11-29 02:50:04 +01:00
3. _A's offered HTLCs_ : The node MUST *resolve* these in one of three ways:
* spending using the payment revocation
* spending using any transaction once the HTLC timeout has passed
* by noting *B's HTLC-success transaction* if B publishes it
4. _B's offered HTLCs_ : The node MUST *resolve* these in one of three ways:
* spending using the payment revocation
* spending using the payment preimage if known
* by noting *B's HTLC-timeout transaction* if B publishes it
2016-11-15 02:23:20 +01:00
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
2017-12-06 07:08:32 +01:00
spending using the revocation key. The node SHOULD extract
2016-11-15 02:23:20 +01:00
the payment preimage from the transaction input witness if not
already known.
2017-12-09 20:38:37 +01:00
The node MAY use a single transaction to *resolve* all the outputs, but MUST
handle its transactions being invalidated by HTLC transactions.
2016-11-15 02:23:20 +01:00
## Rationale
2017-12-06 07:08:32 +01:00
A single transaction that resolves all the outputs will be under the
2017-11-29 01:53:54 +01:00
standard size limit thanks to the 483 HTLC-per-party limit (see
BOLT 1, BOLT 2, BOLT 5: 2-byte lengths everywhere.
Since our cryptopacket limits us to 2 bytes, and since people will
send 1-message-per-crypto-packet and nobody will test the
multiple-messages-in-one-cryptopacket code, let's just restrict to
64k messages.
1. Make cryptopacket length not include the HMAC, so we can actually send
64k messages.
2. Remove len prefix from packet, make type 2 bytes, note alignment properties.
3. Change message internal lengths/counts from 4 to 2 bytes, since more
is nonsensical anyway, and this removes a need to check before allocating:
- init feature bitfield length
- error message length
- shutdown scriptpubkey length
- commit_sig number of HTLC signatures
- revoke_and_ack number of HTLC-timeout signatures
4. Change max-accepted-htlcs to two bytes, and limit it to 511 to ensure
that commit_sig will always be under 64k.
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2016-11-24 05:58:30 +01:00
[BOLT #2 ](02-peer-protocol.md#the-open_channel-message )).
2016-11-15 02:23:20 +01:00
2017-12-06 07:08:32 +01:00
Note that if a single transaction is used it may be invalidated as node B
2016-11-15 02:23:20 +01:00
broadcasts HTLC-timeout and HTLC-success transactions, but the
2017-12-06 07:08:32 +01:00
requirement of persistence, until all outputs are irrevocably resolved,
2017-12-09 20:38:37 +01:00
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? ]
2016-11-15 02:23:20 +01:00
2017-02-10 12:23:32 +01:00
## Penalty Transactions Weight Calculation
2016-11-15 04:21:09 +01:00
2017-12-09 20:38:37 +01:00
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 )):
2016-11-15 04:21:09 +01:00
2017-08-16 09:44:59 +02:00
to_local_penalty_witness: 160 bytes
2017-03-07 00:58:30 +01:00
offered_htlc_penalty_witness: 243 bytes
accepted_htlc_penalty_witness: 249 bytes
2016-11-15 04:21:09 +01:00
2017-12-09 20:38:37 +01:00
The penalty txinput itself takes 41 bytes, which has a weight of 164, making the
weight of each input:
2016-11-15 04:21:09 +01:00
2017-08-16 09:44:59 +02:00
to_local_penalty_input_weight: 324 bytes
2017-03-07 00:58:30 +01:00
offered_htlc_penalty_input_weight: 407 bytes
accepted_htlc_penalty_input_weight: 413 bytes
2016-11-15 04:21:09 +01:00
2017-08-16 09:44:59 +02:00
The rest of the penalty transaction takes 4+1+1+8+1+34+4=53 bytes of non-witness
2017-12-06 07:08:32 +01:00
data, assuming that it has a pay-to-witness-script-hash (the largest standard output
script), in addition to a 2-byte witness header.
2017-02-10 12:23:32 +01:00
2017-08-16 09:44:59 +02:00
In addition to outputs being swept under as penalty, the node MAY also sweep the
2017-12-06 07:08:32 +01:00
`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
2017-08-16 09:44:59 +02:00
additional txinput, resulting in an additional 108 + 164 = 272 bytes.
2017-12-06 07:08:32 +01:00
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
2017-08-16 09:44:59 +02:00
transaction.
With a maximum standard weight of 400000, the maximum number of HTLCs that can
be swept in a single transaction:
2017-12-09 20:38:37 +01:00
2017-12-09 21:04:58 +01:00
max_num_htlcs = [400000 - 324 - 272 - (4 * 53) - 2] / 413 = 966
2017-12-09 20:38:37 +01:00
2017-12-06 07:08:32 +01:00
This allows 483 HTLCs in each direction (with both `to_local` and
`to_remote` outputs) to still be resolved in a single penalty transaction.
2017-08-16 09:44:59 +02:00
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.
2016-11-15 02:23:20 +01:00
# 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
2017-12-09 20:38:37 +01:00
transaction close). Such a transaction implies its private key has
2016-11-15 02:23:20 +01:00
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
2017-12-09 20:38:37 +01:00
mempool. Considering mempool transactions should cause lower latency
2016-11-15 02:23:20 +01:00
for HTLC redemption, but on-chain HTLCs should be such an unusual case
that speed cannot be considered critical.
2016-11-22 20:52:59 +01:00
2017-12-09 21:04:58 +01:00
# Appendix A: Expected Weights
2017-02-10 12:23:32 +01:00
2017-12-06 07:08:32 +01:00
## Expected Weight of the `to_local` Penalty Transaction Witness
2017-02-10 12:23:32 +01:00
As described in [BOLT #3 ](03-transactions.md ), the witness for
this transaction is:
2017-05-14 02:32:22 +02:00
< sig > 1 { OP_IF < key > OP_ELSE to_self_delay OP_CSV OP_DROP < key > OP_ENDIF OP_CHECKSIG }
2017-02-10 12:23:32 +01:00
The *expected weight* is calculated as follows:
2017-08-16 09:44:59 +02:00
to_local_script: 83 bytes
2017-02-10 12:23:32 +01:00
- OP_IF: 1 byte
2017-08-16 09:44:59 +02:00
- OP_DATA: 1 byte (revocationkey length)
- revocationkey: 33 bytes
- OP_CHECKSIG: 1 byte
- OP_ELSE: 1 byte
- OP_DATA: 1 byte (localkey length)
- localkey: 33 bytes
- OP_CHECKSIG_VERIFY: 1 byte
- OP_DATA: 1 byte (delay length)
- delay: 8 bytes
- OP_CHECKSEQUENCEVERIFY: 1 byte
- OP_ENDIF: 1 byte
to_local_penalty_witness: 160 bytes
2017-02-10 12:23:32 +01:00
- number_of_witness_elements: 1 byte
- revocation_sig_length: 1 byte
- revocation_sig: 73 bytes
- one_length: 1 byte
- witness_script_length: 1 byte
- witness_script (to_local_script)
2017-08-16 09:44:59 +02:00
2017-12-06 07:08:32 +01:00
## Expected Weight of the `offered_htlc` Penalty Transaction Witness
2017-02-10 12:23:32 +01:00
2017-12-09 20:38:37 +01:00
The *expected weight* is calculated as follows (some calculations have already
been made in [BOLT #3 ](03-transactions.md )):
2017-02-10 12:23:32 +01:00
2017-03-07 00:58:30 +01:00
offered_htlc_script: 133 bytes
2017-12-09 20:38:37 +01:00
2017-03-07 00:58:30 +01:00
offered_htlc_penalty_witness: 243 bytes
2017-02-10 12:23:32 +01:00
- number_of_witness_elements: 1 byte
- revocation_sig_length: 1 byte
- revocation_sig: 73 bytes
2017-03-07 00:58:30 +01:00
- revocation_key_length: 1 byte
- revocation_key: 33 bytes
2017-02-10 12:23:32 +01:00
- witness_script_length: 1 byte
2017-03-07 00:58:30 +01:00
- witness_script (offered_htlc_script)
2017-02-10 12:23:32 +01:00
2017-12-06 07:08:32 +01:00
## Expected Weight of the `accepted_htlc` Penalty Transaction Witness
2017-02-10 12:23:32 +01:00
2017-12-09 20:38:37 +01:00
The *expected weight* is calculated as follows (some calculations have already
been made in [BOLT #3 ](03-transactions.md )):
2017-02-10 12:23:32 +01:00
2017-03-07 00:58:30 +01:00
accepted_htlc_script: 139 bytes
2017-12-09 20:38:37 +01:00
2017-03-07 00:58:30 +01:00
accepted_htlc_penalty_witness: 249 bytes
2017-02-10 12:23:32 +01:00
- number_of_witness_elements: 1 byte
- revocation_sig_length: 1 byte
- revocation_sig: 73 bytes
2017-03-07 00:58:30 +01:00
- revocation_key_length: 1 byte
- revocation_key: 33 bytes
2017-02-10 12:23:32 +01:00
- witness_script_length: 1 byte
2017-03-07 00:58:30 +01:00
- witness_script (accepted_htlc_script)
2017-12-09 20:38:37 +01:00
2017-05-11 03:46:05 +02:00
# Authors
2017-12-09 20:38:37 +01:00
[FIXME:]
2017-02-10 12:23:32 +01:00
2016-11-22 20:52:59 +01:00
![Creative Commons License ](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY" )
< br >
This work is licensed under a [Creative Commons Attribution 4.0 International License ](http://creativecommons.org/licenses/by/4.0/ ).