BOLT #5: Recommendations for On-chain Transaction Handling

Abstract

Lightning allows for two parties (a local node and a remote node) to conduct transactions off-chain by giving each of the parties 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 the local and remote nodes agree to close the channel. They generate a closing transaction (which is similar to a commitment transaction, but without any pending payments) and publish it on the blockchain (see BOLT #2: 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 commitment transaction (presumably, a prior version, which is more in its 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 when it encounters any of the above situations, on-chain.

Table of Contents

• General Nomenclature
• Commitment Transaction
• Failing a Channel
• Mutual Close Handling
• Unilateral Close Handling: Local Commitment Transaction
  • HTLC Output Handling: Local Commitment, Local Offers
  • HTLC Output Handling: Local Commitment, Remote Offers
• Unilateral Close Handling: Remote Commitment Transaction
  • HTLC Output Handling: Remote Commitment, Local Offers
  • HTLC Output Handling: Remote Commitment, Remote Offers
• Revoked Transaction Close Handling
  • Penalty Transactions Weight Calculation
• Generation of HTLC Transactions
• General Requirements
• Appendix A: Expected Weights
  • Expected Weight of the to_local Penalty Transaction Witness
  • Expected Weight of the offered_htlc Penalty Transaction Witness
  • Expected Weight of the accepted_htlc Penalty Transaction Witness
• Authors

General Nomenclature

Any unspent output is considered to be unresolved and can be resolved as detailed in this document. Usually this is accomplished by spending it with another resolving transaction. Although, sometimes simply noting the output for later wallet spending is sufficient, in which case the transaction containing the output is considered to be its own resolving transaction.

Outputs that are resolved are considered irrevocably resolved 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).

Requirements

A node:

• once it has broadcast a funding transaction OR sent a commitment signature for a commitment transaction that contains an HTLC output:
  • until all outputs are irrevocably resolved:
    • MUST monitor the blockchain for transactions that spend any output that is NOT irrevocably resolved.
• MUST resolve all outputs, as specified below.
• MUST be prepared to resolve outputs multiple times, in case of blockchain reorganizations.
• upon the funding transaction being spent, if the channel is NOT already closed:
  • MAY send a descriptive error.
  • SHOULD fail the channel.
• SHOULD ignore invalid transactions.

Rationale

Once a local node has some funds at stake, monitoring the blockchain is required to ensure the remote node 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 trigger any action.

Commitment Transaction

The local and remote nodes each hold a commitment transaction. Each of these commitment transactions has up to six types of outputs:

1. local node's main output: Zero or one output, to pay to the local node's delayed_pubkey.
2. remote node's main output: Zero or one output, to pay to the remote node's delayed_pubkey.
3. local node's anchor output: one output paying to the local node's funding_pubkey.
4. remote node's anchor output: one output paying to the remote node's funding_pubkey.
5. local node's offered HTLCs: Zero or more pending payments (HTLCs), to pay the remote node in return for a payment preimage.
6. remote node's offered HTLCs: Zero or more pending payments (HTLCs), to pay the local node in return for a payment preimage.

To incentivize the local and remote nodes to cooperate, an OP_CHECKSEQUENCEVERIFY relative timeout encumbers the local node's outputs (in the local node's commitment transaction) and the remote node's outputs (in the remote node's commitment transaction). So for example, if the local node publishes its commitment transaction, it will have to wait to claim its own funds, whereas the remote node will have immediate access to its own funds. As a consequence, the two commitment transactions are not identical, but they are (usually) symmetrical.

See BOLT #3: Commitment Transaction for more details.

Failing a Channel

Although closing a channel can be accomplished in several ways, the most efficient is preferred.

Various error cases involve closing a channel. The requirements for sending error messages to peers are specified in BOLT #1: The error Message.

Requirements

A node:

• if a local commitment transaction has NOT ever contained a to_local or HTLC output:
  • MAY simply forget the channel.
• otherwise:
  • if the current commitment transaction does NOT contain to_local or other HTLC outputs:
    • 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 sufficient fee:
      • SHOULD use this fee to perform a mutual close.
    • otherwise:
      • if the node knows or assumes its channel state is outdated:
        • MUST NOT broadcast its last commitment transaction.
      • otherwise:
        • MUST broadcast the last commitment transaction, for which it has a signature, to perform a unilateral close.
        • MUST spend any to_local_anchor output, providing sufficient fees as incentive to include the commitment transaction in a block. Special care must be taken when spending to a third-party, because this re-introduces the vulnerability that was addressed by adding the CSV delay to the non-anchor outputs.
        • SHOULD use replace-by-fee or other mechanism on the spending transaction if it proves insufficient for timely inclusion in a block.

Rationale

Since dust_limit_satoshis is supposed to prevent creation of uneconomic outputs (which would otherwise remain forever, unspent on the blockchain), all commitment transaction outputs MUST be spent.

In the early stages of a channel, it's common for one side to have little or no funds in the channel; in this case, having nothing at stake, a node need not consume resources monitoring the channel state.

There exists a bias towards preferring mutual closes over unilateral closes, because outputs of the former are unencumbered by a delay and are directly spendable by wallets. In addition, mutual close fees tend to be less exaggerated than those of commitment transactions (or in the case of option_anchors, the commitment transaction may require a child transaction to cause it to be mined). So, 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 closing transaction resolves the funding transaction output.

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).

Unilateral Close Handling: Local Commitment Transaction

This is the first of two cases involving unilateral closes. In this case, a node discovers its local commitment transaction, which resolves the funding transaction output.

However, a node cannot claim funds from the outputs of a unilateral close that it initiated, until the OP_CHECKSEQUENCEVERIFY delay has passed (as specified by the remote node's to_self_delay field). Where relevant, this situation is noted below.

Requirements

A node:

• upon discovering its local commitment transaction:
  • SHOULD spend the to_local output to a convenient address.
  • MUST wait until the OP_CHECKSEQUENCEVERIFY delay has passed (as specified by the remote node's to_self_delay field) before spending the output.
    • Note: 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.
  • MAY ignore the to_remote output.
    • Note: No action is required by the local node, as to_remote is considered resolved by the commitment transaction itself.
  • MUST handle HTLCs offered by itself as specified in HTLC Output Handling: Local Commitment, Local Offers.
  • MUST handle HTLCs offered by the remote node as specified in HTLC Output Handling: Local Commitment, Remote Offers.

Rationale

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 remote node, and can be ignored.

HTLC Output Handling: Local Commitment, Local Offers

Each HTLC output can only be spent by either the local offerer, by using the HTLC-timeout transaction after it's timed out, or the remote recipient, if it has the payment preimage.

There can be HTLCs which are not represented by any outputs: either because they were trimmed as dust, or because the transaction has only been partially committed.

The HTLC output has timed out once the height of the latest block is equal to or greater than the HTLC cltv_expiry.

Requirements

A node:

• if the commitment transaction HTLC output is spent using the payment preimage, the output is considered irrevocably resolved:
  • MUST extract the payment preimage from the transaction input witness.
• if the commitment transaction HTLC output has timed out and hasn't been resolved:
  • MUST resolve the output by spending it using the HTLC-timeout transaction.
  • once the resolving transaction has reached reasonable depth:
    • MUST fail the corresponding incoming HTLC (if any).
    • MUST resolve the output of that HTLC-timeout transaction.
    • SHOULD resolve the HTLC-timeout transaction by spending it to a convenient address.
      • Note: if the output is spent (as recommended), the output is resolved by the spending transaction, otherwise it is considered resolved by the HTLC-timeout transaction itself.
    • MUST wait until the OP_CHECKSEQUENCEVERIFY delay has passed (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 commitment transaction:
  • if the payment preimage is known:
    • MUST fulfill the corresponding incoming HTLC (if any).
  • otherwise:
    • once the commitment transaction has reached reasonable depth:
      • MUST fail the corresponding incoming HTLC (if any).
    • if no valid commitment transaction contains an output corresponding to the HTLC:
      • MAY fail the corresponding incoming HTLC sooner.

Rationale

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 before this occurs.

The local HTLC-timeout transaction needs to be used to time out the HTLC (to prevent the remote node fulfilling it and claiming the funds) before the local node can back-fail any corresponding incoming HTLC, using update_fail_htlc (presumably with reason permanent_channel_failure), as detailed in BOLT #2. If the incoming HTLC is also on-chain, a node must simply wait for it to timeout: there is no way to signal early failure.

There are several reasons a committed HTLC may not have an output in the confirmed commitment transaction: the HTLC may be smaller than dust_limit_satoshis, the HTLC may not have been added to the commitment transaction yet, or the HTLC may have already been failed or fulfilled. In any case, if the payment preimage is known for the HTLC, the upstream HTLC needs to be fulfilled to avoid loss of funds.

If the payment preimage is not known for the missing HTLC, the correct action

[Content truncated — view full spec at source]