lightning-bolts/05-onchain.md

# BOLT #5: Recommendations for On-chain Transaction Handling

## 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 everytime 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").
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 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

TODO

# 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
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*
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
longest known Bitcoin fork, and the same value used to wait for
confirmations of miner's rewards[FIXME: ref].


## 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
resolved*.


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


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 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: Bitcoin Transaction and Script Formats" for more details.


# 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`").


# 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
*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
   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*
   by the *commitment transaction* utself.
3. _A's offered HTLCs_: See "On-chain HTLC Output Handling: Our Offers" below.
4. _B's offered HTLCs_: See "On-chain HTLC Output Handling: Their Offers" below.


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*
   by the *commitment transaction*.
3. _A's offered HTLCs_: See "On-chain HTLC Output Handling: Our Offers" below.
4. _B's offered HTLCs_: See "On-chain HTLC Output Handling: Their Offers" below.


A node MUST handle the broadcast if any valid *commitment transaction*
from B in this way.


## Rationale


Spending the to-self 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 `revocation`.  Either commitment can serve as
B's *commitment transaction*, hence the requirement to handle both.


# On-chain HTLC Output Handling: Our Offers


Each HTLC output can only be spent by us after it's timed out,
or them if they have the payment preimage.


The HTLC has *timed out* once the depth of the latest block is equal
or greater than the HTLC `ctlv-expiry`.


## 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 by spending it using the HTLC-timeout
transaction.  The HTLC-timeout transaction output MUST be *resolved*
as described in "On-chain HTLC Transaction Handling".


## Rationale


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 ours, they
could create any transaction using the primage.


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.


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


## Requirements


If the node receives (or already knows) a payment preimage for an
unresolved HTLC output it was offered, it MUST *resolve* the output by
spending it.  If this is done using the HTLC-success transaction, the
HTLC-success transaction output MUST be *resolved* as described in
"On-chain HTLC Transaction Handling".


Otherwise, if the HTLC output has expired, it is considered
*irrevocably resolved*.


## Rationale


If this is our commitment transaction, we can only use a payment
preimage with the HTLC-success transaction (which preserves the
`to-self` delay).  Otherwise we can create any transaction we want to
resolve it.


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 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
`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-self 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
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.
3. _A's offered HTLCs_: The node MUST *resolve* this in one of three ways by spending: 
  * the *commitment tx* using the payment revocation
  * the *commitment tx* using the payment preimage if known
  * the *HTLC-timeout tx* if B publishes them
4. _B's offered HTLCs_: The node MUST *resolve* this in one of two ways by spending:
  * the *commitment tx* using the payment revocation
  * the *commitment tx* once the HTLC timeout has passed.
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
   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
standard size limit thanks to the 511 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
broadcasts HTLC-timeout and HTLC-success transactions, but the
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 in [Appendix A](#appendix-a-expected-weights)):

    to_local_penalty_witness: 154 bytes
    offered_htlc_penalty_witness: 291 bytes
    accepted_htlc_penalty_witness: 307 bytes

The penalty txinput itself takes 41 bytes, thus has a weight of 164, making the weight of each input:

    to_local_penalty_input_weight: 318 bytes
    offered_htlc_penalty_input_weight: 455 bytes
    accepted_htlc_penalty_input_weight: 471 bytes

The rest of the penalty transaction takes 4+3+1+8+1+34+4=55 bytes
assuming it has a pay-to-witness-script-hash (the largest standard
output script).

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:
 
    max_num_htlcs = (400000 - 318 - 55) / 471  = 848
 
Thus we could allow 424 HTLCs in each direction (with one output to-self) and still resolve it with a single penalty 
transaction.

# 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
for HTLC redemption, but on-chain HTLCs should be such an unusual case
that speed cannot be considered critical.

# Appendix A: Expected weights

## Expected weight of the to-local penalty transaction witness

As described in [BOLT #3](03-transactions.md), the witness for
this transaction is:

    <sig> 1 { OP_IF <key> OP_ELSE to-self-delay OP_CSV OP_DROP <key> OP_ENDIF OP_CHECKSIG }

The *expected weight* is calculated as follows:

    to_local_script: 77 bytes
        - OP_IF: 1 byte
        - OP_DATA: 1 byte (revocationkey length)
		- revocationkey: 33 bytes
		- OP_ELSE: 1 byte
		- OP_DATA: 1 byte (delay length)
		- delay: 2 bytes
		- OP_CSV: 1 byte
		- OP_DROP: 1 byte
		- OP_DATA: 1 byte (localkey length)
		- localkey: 33 bytes
		- OP_ENDIF: 1 byte
		- OP_CHECKSIG: 1 byte
		
    to_local_penalty_witness: 154 bytes
        - 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)
    
    
## 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)):

    offered_htlc_script: 139 bytes
		
    offered_htlc_penalty_witness: 291 bytes
        - number_of_witness_elements: 1 byte
        - nil_length: 1 byte
        - remote_sig_length: 1 byte
        - remote_sig: 73 bytes
        - revocation_sig_length: 1 byte
        - revocation_sig: 73 bytes
        - nil_length: 1 byte
        - witness_script_length: 1 byte
        - witness_script (to_local_script)

      
## 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)):

    accepted_htlc_script: 156 bytes
		
    accepted_htlc_penalty_witness: 307 bytes
        - number_of_witness_elements: 1 byte
        - nil_length: 1 byte
        - remote_sig_length: 1 byte
        - remote_sig: 73 bytes
        - revocation_sig_length: 1 byte
        - revocation_sig: 73 bytes
        - witness_script_length: 1 byte
        - witness_script (to_local_script)
            

![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/).