mirror of
https://github.com/lightning/bolts.git
synced 2025-03-10 09:10:07 +01:00
14e199d823
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>
363 lines
13 KiB
Markdown
363 lines
13 KiB
Markdown
# 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 of the 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 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.
|
||
|
||
|
||
# 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 tx* itself.
|
||
2. _B's main output_: No action required, this output is considered *resolved*
|
||
by the *commitment tx*.
|
||
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 `commitsig` 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 `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 two ways: either by spending using the payment preimage if known, or spending using B’s HTLC-timeout transaction.
|
||
4. _B's offered HTLCs_: The node MUST *resolve* this by spending 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 Transaction Weight Calculation
|
||
|
||
As described in [BOLT #3](03-transactions.md), 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.
|
||
|
||
# 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.
|
||
|
||
|
||
<br>
|
||
This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).
|