mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-03-10 09:10:07 +01:00
Code Issues Projects Releases Wiki Activity

BOLT 3: Spell out how to construct the commitment transaction.

Browse source 
* I add the term "trimmed outputs" for sub-dust outputs; this matters
  for both fee calculation and transaction construction.

* Introduce the concept of "base fee": this is what needs to be
  extracted from the funder.

* The requirements are spread between the different sections, let's
  tie it together in a new section at the end.

* Spell out all the steps in the example which calculates fees.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2017-01-24 09:27:40 +10:30
parent 1819ff9355
commit de8be3072d
1 changed files with 96 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

123
03-transactions.md
View file

@ -13,6 +13,7 @@ This details the exact format of on-chain transactions, which both sides need to
* [To-Remote Output](#to-remote-output)
* [Offered HTLC Outputs](#offered-htlc-outputs)
* [Received HTLC Outputs](#received-htlc-outputs)
* [Trimmed Outputs](#trimmed-outputs)
* [HTLC-Timeout and HTLC-Success Transactions](#htlc-timeout-and-htlc-success-transactions)
* [Fees](#fees)
* [Fee Calculation](#fee-calculation)
@ -75,7 +76,7 @@ To allow an opportunity for penalty transactions in case of a revoked commitment
The reason for the separate transaction stage for HTLC outputs is so that HTLCs can time out or be fulfilled even though they are within the `to-self-delay` delay.
Otherwise the required minimum timeout on HTLCs is lengthened by this delay, causing longer timeouts for HTLCs traversing the network.
The amounts for each output are rounded down to whole satoshis. If this amount, minus the fees for the HTLC transaction is less than the `dust-limit-satoshis` set by the owner of the commitment transaction, the output is not produced (thus the funds add to fees).
The amounts for each output MUST BE rounded down to whole satoshis. If this amount, minus the fees for the HTLC transaction is less than the `dust-limit-satoshis` set by the owner of the commitment transaction, the output MUST NOT be produced (thus the funds add to fees).
#### To-Local Output
@ -147,6 +148,44 @@ To timeout the htlc, the remote node spends it with the witness:
To redeem the HTLC, the HTLC-success transaction is used as detailed below.
### Trimmed Outputs
Each peer specifies `dust-limit-satoshis` below which outputs should
not be produced; we term these outputs "trimmed". A trimmed output is
considered too small to be worth creating, and thus that amount adds
to the commitment transaction fee. For HTLCs, we need to take into
account that the second-stage HTLC transaction may also be below the
limit.
#### Requirements
The base fee must be subtracted from the `to-local` or `to-remote`
outputs as specified in [Fee Calculation](#fee-calculation) before the
commitment transaction outputs are determined.
If the amount of the commitment transaction `to-local` output would be
less than `dust-limit-satoshis` set by the transaction owner, the
commitment transaction MUST NOT contain that output, otherwise it MUST
be generated as specified in [To-Local Output](#to-local-output).
If the amount of the commitment transaction `to-remote` output would be
less than `dust-limit-satoshis` set by the transaction owner, the
commitment transaction MUST NOT contain that output, otherwise it MUST
be generated as specified in [To-Remote Output](#to-remote-output).
For every offered HTLC, if the HTLC amount plus the HTLC-timeout fee
would be less than `dust-limit-satoshis` set by the transaction owner,
the commitment transaction MUST NOT contain that output, otherwise it
MUST be generated as specified in
[Offered HTLC Outputs](#offered-htlc-outputs).
For every received HTLC, if the HTLC amount plus the HTLC-success fee
would be less than `dust-limit-satoshis` set by the transaction owner,
the commitment transaction MUST NOT contain that output, otherwise it
MUST be generated as specified in
[Received HTLC Outputs](#received-htlc-outputs).
## HTLC-Timeout and HTLC-Success Transactions
These HTLC transactions are almost identical, except the HTLC-Timeout transaction is timelocked. This is also the transaction which can be spent by a valid penalty transaction.
@ -200,10 +239,12 @@ Thus we use a simplified formula for *expected weight*, which assumes:
This gives us the following *expected weights* (details of the computation in [Appendix A](#appendix-a-expected-weights)):
Commitment weight: 724 + 172 * num-htlc-outputs
Commitment weight: 724 + 172 * num-untrimmed-htlc-outputs
HTLC-timeout weight: 634
HTLC-success weight: 671
Note that we refer to the "base fee" for a commitment transaction in the requirements below, which is what the funder pays. The actual fee may be higher than the amount calculated here, due to rounding and trimmed outputs.
#### Requirements
The fee for an HTLC-timeout transaction MUST BE calculated to match:
@ -214,51 +255,79 @@ The fee for an HTLC-success transaction MUST BE calculated to match:
1. Multiply `feerate-per-kw` by 671 and divide by 1000 (rounding down).
The fee for a commitment transaction MUST BE calculated to match:
The base fee for a commitment transaction MUST BE calculated to match:
1. Start with `weight` = 724, and `fee` = 0.
1. Start with `weight` = 724.
2. For every offered HTLC, if the HTLC amount is greater or equal to the local node's
`dust-limit-satoshis` plus the HTLC-timeout
transaction fee, then add 172 to `weight`, otherwise add
the HTLC amount to `fee`.
2. For each committed HTLC, if that output is not trimmed as specified in
[Trimmed Outputs](#trimmed-outputs), add 172 to `weight`.
3. For every accepted HTLC, if the HTLC amount is greater or equal to the local node's
`dust-limit-satoshis` plus the HTLC-success
transaction fee, then add 172 to `weight`, otherwise add
the HTLC amount to `fee`.
3. Multiply `feerate-per-kw` by `weight`, divide by 1000 (rounding down).
4. Multiply `feerate-per-kw` by `weight`, divide by 1000 (rounding down),
and add to `fee`.
#### Example
For example, suppose that we have a `feerate-per-kw` of 5000, a `dust-limit-satoshis` of 546 satoshis, and commitment transaction with:
* 2 offered HTLCs of 5000000 and 1000000 millisatoshis (5000 and 1000 satoshis)
* 2 received HTLCs of 7000000 and 800000 millisatoshis (7000 and 800 satoshis)
The commitment transaction fee would be 7140 satoshis
The HTLC timeout transaction fee would be 3170 satoshis
The HTLC success transaction fee would be 3355 satoshis
The HTLC timeout transaction weight is 634, thus fee would be 3170 satoshis.
The HTLC success transaction weight is 671, thus fee would be 3355 satoshis
The offered HTLC of 5000 satoshis is above 546 + 3170 and would result in:
* an output of 5000 satoshi in the commitment transaction
* a HTLC timeout transaction of 5000 - 3170 satoshis which spends this output
The commitment transaction weight would be calculated as follows:
The offered HTLC of 1000 satoshis is below 546 + 3170, and its amount would be added to the commitment transaction fee
* weight starts at 724.
The received HTLC of 7000 satoshis is above 546 + 3355 and would result in:
* an output of 7000 satoshi in the commitment transaction
* a HTLC success transaction of 7000 - 3355 satoshis which spends this output
* The offered HTLC of 5000 satoshis is above 546 + 3170 and would result in:
* an output of 5000 satoshi in the commitment transaction
* a HTLC timeout transaction of 5000 - 3170 satoshis which spends this output
* weight increases to 896
The received HTLC of 800 satoshis is below 546 + 3355 and its amount would be added to the commitment transaction fee
* The offered HTLC of 1000 satoshis is below 546 + 3710, so would be trimmed.
* The received HTLC of 7000 satoshis is above 546 + 3355 and would result in:
* an output of 7000 satoshi in the commitment transaction
* a HTLC success transaction of 7000 - 3355 satoshis which spends this output
* weight increases to 1068
* The received HTLC of 800 satoshis is below 546 + 3355 so would be trimmed.
The base commitment transaction fee would be 5340 satoshi; the actual
fee (adding the 1000 and 800 satoshi HTLCs which would have made dust
outputs) is 7140 satoshi. The final fee may even be more if the
`to-local` or `to-remote` outputs fall below `dust-limit-satoshis`.
### Fee Payment
Fees will be extracted from the funder's amount, or if that is insufficient, will use the entire amount of the funder's output.
Base commimtment transaction fees will be extracted from the funder's amount, or if that is insufficient, will use the entire amount of the funder's output.
Note that if once fee amount is subtracted from the to-funder output,
that output may be below `dust-limit-satoshis` and thus also
contributes to fees.
A node MAY fail the channel if the resulting fee rate is too low.
## Commitment Transaction Construction
This section ties the previous sections together to spell out the
algorithm for constructing the commitment transaction for one peer,
given that peer's `dust-limit-satoshis`, the current `feerate-per-kw`,
amounts due to each peer (`to-local` and `to-remote`), and all
committed HTLCs:
1. Calculate which committed HTLCs need to be trimmed (see [Trimmed Outputs](#trimmed-outputs)).
2. Calculate the base [commitment transaction fee](#fee-calculation).
3. Subtract this base fee from the funder (either `to-local` or `to-remote`),
with a floor of zero (see [Fee Payment](#fee-payment)).
3. For every offered HTLC, if it is not trimmed, add an
[offered HTLC output](#offered-htlc-outputs).
4. For every received HTLC, if it is not trimmed, add an
[received HTLC output](#received-htlc-outputs).
5. If the `to-local` amount is greater or equal to `dust-limit-satoshis`,
add a [To-Local Output](#to-local-output).
6. If the `to-remote` amount is greater or equal to `dust-limit-satoshis`,
add a [To-Remote Output](#to-remote-output).
7. Sort the outputs into [BIP 69 order](#transaction-input-and-output-ordering)
# Keys
## Key Derivation