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:
- 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").
- The bad way (unilateral close): something goes wrong, without necessarily any evil intent on either side (maybe one of the party crashed, for instance). Anyway, one side publishes its latest commitment transaction.
- 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.
TODO
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].
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.
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.
A and B each hold a commitment transaction, which has 4 types of outputs:
- A's main output: Zero or one outputs which pay to A's commitment key.
- B's main output: Zero or one outputs which pay to B's commitment key.
- A's offered HTLCs: Zero or more pending payments (HTLCs) to pay B in return for a payment preimage.
- 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 tx, 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.
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").
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.
When node A sees its own commitment transaction:
- A's main output: A node SHOULD spend this output to a convenient address.
A node MUST wait until the
OP_CHECKSEQUENCEVERIFYdelay has passed (as specified by the other node'sto-self-delayfield) 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. - B's main output: No action required, this output is considered resolved by the commitment transaction utself.
- A's offered HTLCs: See "On-chain HTLC Output Handling: Our Offers" below.
- B's offered HTLCs: See "On-chain HTLC Output Handling: Their Offers" below.
Similarly, when node A sees a commitment transaction from B:
- A's main output: No action is required; this is a simple P2WPKH output. This output is considered resolved by the commitment tx itself.
- B's main output: No action required, this output is considered resolved by the commitment tx.
- A's offered HTLCs: See "On-chain HTLC Output Handling: Our Offers" below.
- 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.
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 commitsig and
before the corresponding revocation. Either commitment can serve as
B's commitment transaction, hence the requirement to handle both.
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 expiry.
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".
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.
Each HTLC output can only be spent by us if we have the payment preimage, or them if it has timed out.
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.
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.
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.
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.
Spending the to-self output avoids having to remember the complicated witness script associated with that particular channel for later spending.
If a node tries to broadcast old state, we can use the revocation key to claim all the funds.
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:
- A's main output: No action is required; this is a simple P2WPKH output. This output is considered resolved by the commitment transaction.
- B's main output: The node MUST resolve this by spending using the revocation key.
- A's offered HTLCs: The node MUST resolve this in one of two ways: either by spending using the payment preimage if known, or spending using B’s HTLC-timeout transaction.
- B's offered HTLCs: The node MUST resolve this by spending once the HTLC timeout has passed.
- B's HTLC-timeout transaction: The node MUST resolve this by spending using the revocation key.
- 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.
A single transaction which resolves all the outputs will be under the standard size limit thanks to the [FIXME] HTLC-per-party limit (See BOLT #2: FIXME).
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? ]
As described in BOLT #3, the witness script for a penalty transaction is:
<sig> 1 { OP_IF <key> OP_ELSE to-self-delay OP_CSV OP_DROP <key> OP_ENDIF OP_CHECKSIG }
Which takes 1 byte to indicate the number of stack elements, plus one
byte for the size of each element (+3), 73 bytes worst-case for
<sig> (+73), one byte for the 1 (+1), nine bytes for the script
instructions (+9), 33 bytes for each of the keys (+66), and two bytes
for to-self-delay (+2).
This gives 1+3+73+1+9+66+2=155 bytes of witness data, weight 155.
The penalty txinput itself takes 41 bytes, thus has a weight of 164, meaning each input adds 319 weight.
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), thus a base weight of 220.
With a maximum standard weight of 400000, this means a standard penalty transaction can have up to 1253 inputs. Thus we could allow 626 HTLCs in each direction (with one output to-self) and still resolve it with a single penalty transaction.
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.