mirror of
https://github.com/lightning/bolts.git
synced 2025-03-13 11:35:41 +01:00
Merge 76859f5246 into d8f5b4a680
This commit is contained in:
Jiří Jakeš
GitHub
commit
cce99d757f
12 changed files with 336 additions and 306 deletions
|
|
@ -1,7 +1,11 @@
|
|||
# Basic checklist/stylesheet used for copy editing BOLTs
|
||||
|
||||
Contributions should comply with this checklist/stylesheet to maintain correct, clear, consistent, and concise BOLTS.
|
||||
Items marked as 'lint' can be automatically checked by running `tools/lint.sh`.
|
||||
|
||||
- headings
|
||||
- first line is top-level heading (lint)
|
||||
- there is only one top-level heading in the document (lint)
|
||||
- spelling
|
||||
- run `tools/spellcheck.sh --check [0-9][0-9]-*.md`
|
||||
- update `.aspell.en.pws` with any missing words
|
||||
|
|
|
|||
12
.github/workflows/checks.yml
vendored
Normal file
12
.github/workflows/checks.yml
vendored
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: DavidAnson/markdownlint-cli2-action@v15
|
||||
with:
|
||||
globs: |
|
||||
??-*.md
|
||||
proposals/*.md
|
||||
9
.markdownlint.jsonc
Normal file
9
.markdownlint.jsonc
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
{
|
||||
"default": false,
|
||||
|
||||
// There should be only one top-level heading.
|
||||
"MD025": true,
|
||||
|
||||
// The first line should be top-level heading.
|
||||
"MD041": true
|
||||
}
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
The peer channel protocol has three phases: establishment, normal
|
||||
operation, and closing.
|
||||
|
||||
# Table of Contents
|
||||
## Table of Contents
|
||||
|
||||
* [Channel](#channel)
|
||||
* [Definition of `channel_id`](#definition-of-channel_id)
|
||||
|
|
@ -47,9 +47,9 @@ operation, and closing.
|
|||
* [Message Retransmission: `channel_reestablish` message](#message-retransmission)
|
||||
* [Authors](#authors)
|
||||
|
||||
# Channel
|
||||
## Channel
|
||||
|
||||
## Definition of `channel_id`
|
||||
### Definition of `channel_id`
|
||||
|
||||
Some messages use a `channel_id` to identify the channel. It's
|
||||
derived from the funding transaction by combining the `funding_txid`
|
||||
|
|
@ -69,7 +69,7 @@ transaction is confirmed are also not persistent - until you know the script
|
|||
pubkey corresponding to the funding output nothing prevents duplicative channel
|
||||
ids.
|
||||
|
||||
### `channel_id`, v2
|
||||
#### `channel_id`, v2
|
||||
|
||||
For channels established using the v2 protocol, the `channel_id` is the
|
||||
`SHA256(lesser-revocation-basepoint || greater-revocation-basepoint)`,
|
||||
|
|
@ -82,7 +82,7 @@ for the non-initiator.
|
|||
When sending `accept_channel2`, the `temporary_channel_id` from `open_channel2`
|
||||
must be used, to allow the initiator to match the response to its request.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
The revocation basepoints must be remembered by both peers for correct
|
||||
operation anyway. They're known after the first exchange of messages,
|
||||
|
|
@ -90,13 +90,13 @@ obviating the need for a `temporary_channel_id` in subsequent messages.
|
|||
By mixing information from both sides, they avoid `channel_id` collisions,
|
||||
and they remove the dependency on the funding txid.
|
||||
|
||||
## Interactive Transaction Construction
|
||||
### Interactive Transaction Construction
|
||||
|
||||
Interactive transaction construction allows two peers to collaboratively
|
||||
build a transaction for broadcast. This protocol is the foundation
|
||||
for dual-funded channels establishment (v2).
|
||||
|
||||
### Set-Up and Vocabulary
|
||||
#### Set-Up and Vocabulary
|
||||
|
||||
There are two parties to a transaction construction: an *initiator*
|
||||
and a *non-initiator*.
|
||||
|
|
@ -111,7 +111,7 @@ The protocol makes the following assumptions:
|
|||
- The `nLocktime` for the transaction is known.
|
||||
- The `nVersion` for the transaction is known.
|
||||
|
||||
### Fee Responsibility
|
||||
#### Fee Responsibility
|
||||
|
||||
The *initiator* is responsible for paying the fees for the following fields,
|
||||
to be referred to as the `common fields`.
|
||||
|
|
@ -126,7 +126,7 @@ The rest of the transaction bytes' fees are the responsibility of
|
|||
the peer who contributed that input or output via `tx_add_input` or
|
||||
`tx_add_output`, at the agreed upon `feerate`.
|
||||
|
||||
### Overview
|
||||
#### Overview
|
||||
|
||||
The *initiator* initiates the interactive transaction construction
|
||||
protocol with `tx_add_input`. The *non-initiator* responds with any
|
||||
|
|
@ -150,7 +150,7 @@ necessary to satisfy the parity requirement.
|
|||
|
||||
Here are a few example exchanges.
|
||||
|
||||
#### *initiator* only
|
||||
##### *initiator* only
|
||||
|
||||
A, the *initiator*, has two inputs and an output (the funding output).
|
||||
B, the *non-initiator* has nothing to contribute.
|
||||
|
|
@ -165,7 +165,7 @@ B, the *non-initiator* has nothing to contribute.
|
|||
| |--(7)- tx_complete --->| |
|
||||
+-------+ +-------+
|
||||
|
||||
#### *initiator* and *non-initiator*
|
||||
##### *initiator* and *non-initiator*
|
||||
|
||||
A, the *initiator*, contributes 2 inputs and an output that they
|
||||
then remove. B, the *non-initiator*, contributes 1 input and an output,
|
||||
|
|
@ -187,7 +187,7 @@ B's contributions.
|
|||
| |<-(10) tx_complete ------| |
|
||||
+-------+ +-------+
|
||||
|
||||
### The `tx_add_input` Message
|
||||
#### The `tx_add_input` Message
|
||||
|
||||
This message contains a transaction input.
|
||||
|
||||
|
|
@ -200,7 +200,7 @@ This message contains a transaction input.
|
|||
* [`u32`:`prevtx_vout`]
|
||||
* [`u32`:`sequence`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sending node:
|
||||
- MUST add all sent inputs to the transaction
|
||||
|
|
@ -226,7 +226,7 @@ The receiving node:
|
|||
- the `serial_id` has the wrong parity
|
||||
- if has received 4096 `tx_add_input` messages during this negotiation
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
Each node must know the set of the transaction inputs. The *non-initiator*
|
||||
MAY omit this message.
|
||||
|
|
@ -243,7 +243,7 @@ this input spends. Used to verify that the input is non-malleable.
|
|||
replaceability, and the same value should be used across implementations
|
||||
to avoid on-chain fingerprinting.
|
||||
|
||||
#### Liquidity griefing
|
||||
##### Liquidity griefing
|
||||
|
||||
When sending `tx_add_input`, senders have no guarantee that the remote node
|
||||
will complete the protocol in a timely manner. Malicious remote nodes could
|
||||
|
|
@ -265,7 +265,7 @@ with honest nodes. This is a reasonable trade-off though because:
|
|||
conflicts
|
||||
* failed attempts can simply be retried at no cost
|
||||
|
||||
### The `tx_add_output` Message
|
||||
#### The `tx_add_output` Message
|
||||
|
||||
This message adds a transaction output.
|
||||
|
||||
|
|
@ -277,7 +277,7 @@ This message adds a transaction output.
|
|||
* [`u16`:`scriptlen`]
|
||||
* [`scriptlen*byte`:`script`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
Either node:
|
||||
- MAY omit this message
|
||||
|
|
@ -300,7 +300,7 @@ The receiving node:
|
|||
- the `sats` amount is less than the `dust_limit`
|
||||
- the `sats` amount is greater than 2,100,000,000,000,000 (`MAX_MONEY`)
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
Each node must know the set of the transaction outputs.
|
||||
|
||||
|
|
@ -314,7 +314,7 @@ Outputs in the constructed transaction MUST be sorted by `serial_id`.
|
|||
scripts such as `OP_RETURN` may be accepted, but the corresponding
|
||||
transaction may fail to relay across the network.
|
||||
|
||||
### The `tx_remove_input` and `tx_remove_output` Messages
|
||||
#### The `tx_remove_input` and `tx_remove_output` Messages
|
||||
|
||||
This message removes an input from the transaction.
|
||||
|
||||
|
|
@ -330,7 +330,7 @@ This message removes an output from the transaction.
|
|||
* [`channel_id`:`channel_id`]
|
||||
* [`u64`:`serial_id`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sending node:
|
||||
- MUST NOT send a `tx_remove` with a `serial_id` it did not add
|
||||
|
|
@ -352,7 +352,7 @@ contributions.
|
|||
2. data:
|
||||
* [`channel_id`:`channel_id`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The nodes:
|
||||
- MUST send this message in succession to conclude this protocol
|
||||
|
|
@ -371,7 +371,7 @@ The receiving node:
|
|||
- there are more than 252 outputs
|
||||
- the estimated weight of the tx is greater than 400,000 (`MAX_STANDARD_TX_WEIGHT`)
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
To signal the conclusion of exchange of transaction inputs and outputs.
|
||||
|
||||
|
|
@ -384,7 +384,7 @@ For the `minimum fee` calculation see [BOLT #3](03-transactions.md#calculating-f
|
|||
The maximum inputs and outputs are capped at 252. This effectively fixes
|
||||
the byte size of the input and output counts on the transaction to one (1).
|
||||
|
||||
### The `tx_signatures` Message
|
||||
#### The `tx_signatures` Message
|
||||
|
||||
1. type: 71 (`tx_signatures`)
|
||||
2. data:
|
||||
|
|
@ -398,7 +398,7 @@ the byte size of the input and output counts on the transaction to one (1).
|
|||
* [`u16`:`len`]
|
||||
* [`len*byte`:`witness_data`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sending node:
|
||||
- if it has the lowest total satoshis contributed, as defined by total
|
||||
|
|
@ -421,7 +421,7 @@ The receiving node:
|
|||
- SHOULD apply the `witnesses` to the transaction and broadcast it
|
||||
- MUST reply with their `tx_signatures` if not already transmitted
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
A strict ordering is used to decide which peer sends `tx_signatures` first.
|
||||
This prevents deadlocks where each peer is waiting for the other peer to
|
||||
|
|
@ -435,7 +435,7 @@ it is possible for the fee for the exchanged witness data to be underpaid.
|
|||
It is the responsibility of the sending peer to correctly account for the
|
||||
required fee.
|
||||
|
||||
### The `tx_init_rbf` Message
|
||||
#### The `tx_init_rbf` Message
|
||||
|
||||
This message initiates a replacement of the transaction after it's been
|
||||
completed.
|
||||
|
|
@ -454,7 +454,7 @@ completed.
|
|||
* [`s64`:`satoshis`]
|
||||
1. type: 2 (`require_confirmed_inputs`)
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sender:
|
||||
- MUST set `feerate` greater than or equal to 25/24 times the `feerate`
|
||||
|
|
@ -473,7 +473,7 @@ The recipient:
|
|||
- MUST fail the negotiation if:
|
||||
- `require_confirmed_inputs` is set but it cannot provide confirmed inputs
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
`feerate` is the feerate this transaction will pay. It must be at least
|
||||
1/24 greater than the last used `feerate`, rounded down to the nearest
|
||||
|
|
@ -491,7 +491,7 @@ such an output. Note that it may be different from the contribution
|
|||
made in the previously completed transaction. If omitted, the sender is
|
||||
not contributing to the funding output.
|
||||
|
||||
### The `tx_ack_rbf` Message
|
||||
#### The `tx_ack_rbf` Message
|
||||
|
||||
1. type: 73 (`tx_ack_rbf`)
|
||||
2. data:
|
||||
|
|
@ -506,7 +506,7 @@ not contributing to the funding output.
|
|||
* [`s64`:`satoshis`]
|
||||
1. type: 2 (`require_confirmed_inputs`)
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sender:
|
||||
- If it contributes to the transaction's funding output:
|
||||
|
|
@ -520,7 +520,7 @@ The recipient:
|
|||
- MUST fail the negotiation if:
|
||||
- `require_confirmed_inputs` is set but it cannot provide confirmed inputs
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
`funding_output_contribution` is the amount of satoshis that this peer
|
||||
will contribute to the funding output of the transaction, when there is
|
||||
|
|
@ -533,7 +533,7 @@ a large feerate change, instead stop contributing to the funding output,
|
|||
and decline to participate further in the transaction (by not contributing,
|
||||
they may obtain incoming liquidity at no cost).
|
||||
|
||||
### The `tx_abort` Message
|
||||
#### The `tx_abort` Message
|
||||
|
||||
1. type: 74 (`tx_abort`)
|
||||
2. data:
|
||||
|
|
@ -541,7 +541,7 @@ they may obtain incoming liquidity at no cost).
|
|||
* [`u16`:`len`]
|
||||
* [`len*byte`:`data`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
A sending node:
|
||||
- MUST NOT have already transmitted `tx_signatures`
|
||||
|
|
@ -564,7 +564,7 @@ A receiving node:
|
|||
126, inclusive):
|
||||
- SHOULD NOT print out `data` verbatim.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
A receiving node, if they've already sent their `tx_signatures` has no guarantee
|
||||
that the transaction won't be signed and published by their peer. They must remember
|
||||
|
|
@ -579,7 +579,7 @@ Echoing back `tx_abort` allows the peer to ack that they've seen the abort messa
|
|||
permitting the originating peer to terminate the in-flight process without
|
||||
worrying about stale messages.
|
||||
|
||||
## Channel Establishment v1
|
||||
### Channel Establishment v1
|
||||
|
||||
After authenticating and initializing a connection ([BOLT #8](08-transport.md)
|
||||
and [BOLT #1](01-messaging.md#the-init-message), respectively), channel establishment may begin.
|
||||
|
|
@ -631,7 +631,7 @@ messages are identified by either a `temporary_channel_id` (before the
|
|||
funding transaction is created) or a `channel_id` (derived from the
|
||||
funding transaction).
|
||||
|
||||
### The `open_channel` Message
|
||||
#### The `open_channel` Message
|
||||
|
||||
This message contains information about a node and indicates its
|
||||
desire to set up a new channel. This is the first step toward creating
|
||||
|
|
@ -734,7 +734,7 @@ know this node will accept `funding_satoshis` greater than or equal to 2^24.
|
|||
Since it's broadcast in the `node_announcement` message other nodes can use it to identify peers
|
||||
willing to accept large channel even before exchanging the `init` message with them.
|
||||
|
||||
#### Defined Channel Types
|
||||
##### Defined Channel Types
|
||||
|
||||
Channel types are an explicit enumeration: for convenience of future
|
||||
definitions they reuse even feature bits, but they are not an
|
||||
|
|
@ -749,7 +749,7 @@ Each basic type has the following variations allowed:
|
|||
- `option_scid_alias` (bit 46)
|
||||
- `option_zeroconf` (bit 50)
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sending node:
|
||||
- MUST ensure the `chain_hash` value identifies the chain it wishes to open the channel within.
|
||||
|
|
@ -823,7 +823,7 @@ are not valid secp256k1 pubkeys in compressed format.
|
|||
The receiving node MUST NOT:
|
||||
- consider funds received, using `push_msat`, to be received until the funding transaction has reached sufficient depth.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
The requirement for `funding_satoshis` to be less than 2^24 satoshi was a temporary self-imposed limit while implementations were not yet considered stable, it can be lifted by advertising `option_support_large_channel`.
|
||||
|
||||
|
|
@ -847,7 +847,7 @@ of dust htlcs, which effectively become miner fees.
|
|||
|
||||
Details for how to handle a channel failure can be found in [BOLT 5:Failing a Channel](05-onchain.md#failing-a-channel).
|
||||
|
||||
### The `accept_channel` Message
|
||||
#### The `accept_channel` Message
|
||||
|
||||
This message contains information about a node and indicates its
|
||||
acceptance of the new channel. This is the second step toward creating the
|
||||
|
|
@ -880,7 +880,7 @@ funding transaction and both versions of the commitment transaction.
|
|||
2. data:
|
||||
* [`...*byte`:`type`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The `temporary_channel_id` MUST be the same as the `temporary_channel_id` in
|
||||
the `open_channel` message.
|
||||
|
|
@ -909,7 +909,7 @@ The receiver:
|
|||
|
||||
Other fields have the same requirements as their counterparts in `open_channel`.
|
||||
|
||||
### The `funding_created` Message
|
||||
#### The `funding_created` Message
|
||||
|
||||
This message describes the outpoint which the funder has created for
|
||||
the initial commitment transactions. After receiving the peer's
|
||||
|
|
@ -922,7 +922,7 @@ signature, via `funding_signed`, it will broadcast the funding transaction.
|
|||
* [`u16`:`funding_output_index`]
|
||||
* [`signature`:`signature`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sender MUST set:
|
||||
- `temporary_channel_id` the same as the `temporary_channel_id` in the `open_channel` message.
|
||||
|
|
@ -941,7 +941,7 @@ The recipient:
|
|||
- MUST send a `warning` and close the connection, or send an
|
||||
`error` and fail the channel.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
The `funding_output_index` can only be 2 bytes, since that's how it's packed into the `channel_id` and used throughout the gossip protocol. The limit of 65535 outputs should not be overly burdensome.
|
||||
|
||||
|
|
@ -950,7 +950,7 @@ A transaction with all Segregated Witness inputs is not malleable, hence the fun
|
|||
The funder may use CPFP on a change output to ensure that the funding transaction confirms before 2016 blocks,
|
||||
otherwise the fundee may forget that channel.
|
||||
|
||||
### The `funding_signed` Message
|
||||
#### The `funding_signed` Message
|
||||
|
||||
This message gives the funder the signature it needs for the first
|
||||
commitment transaction, so it can broadcast the transaction knowing that funds
|
||||
|
|
@ -963,7 +963,7 @@ This message introduces the `channel_id` to identify the channel. It's derived f
|
|||
* [`channel_id`:`channel_id`]
|
||||
* [`signature`:`signature`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
Both peers:
|
||||
- if `channel_type` was present in both `open_channel` and `accept_channel`:
|
||||
|
|
@ -987,7 +987,7 @@ The recipient:
|
|||
- on receipt of a valid `funding_signed`:
|
||||
- SHOULD broadcast the funding transaction.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
We decide on `option_static_remotekey` or `option_anchors` at this point
|
||||
when we first have to generate the commitment transaction. The feature
|
||||
|
|
@ -1000,7 +1000,7 @@ parameter, this channel will continue to use `option_static_remotekey` or
|
|||
`option_anchors` is considered superior to `option_static_remotekey`,
|
||||
and the superior one is favored if more than one is negotiated.
|
||||
|
||||
### The `channel_ready` Message
|
||||
#### The `channel_ready` Message
|
||||
|
||||
This message (which used to be called `funding_locked`) indicates that the funding transaction has sufficient confirms for channel use. Once both nodes have sent this, the channel enters normal operating mode.
|
||||
|
||||
|
|
@ -1019,7 +1019,7 @@ accepter would usually wait until the funding has reached the `minimum_depth` as
|
|||
2. data:
|
||||
* [`short_channel_id`:`alias`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sender:
|
||||
- MUST NOT send `channel_ready` unless outpoint of given by `funding_txid` and
|
||||
|
|
@ -1064,7 +1064,7 @@ From the point of waiting for `channel_ready` onward, either node MAY
|
|||
send an `error` and fail the channel if it does not receive a required response from the
|
||||
other node after a reasonable timeout.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
The non-funder can simply forget the channel ever existed, since no
|
||||
funds are at risk. If the fundee were to remember the channel forever, this
|
||||
|
|
@ -1090,7 +1090,7 @@ incoming HTLCs. The recipient only need remember one, for use in
|
|||
If an RBF negotiation is in progress when a `channel_ready` message is
|
||||
exchanged, the negotiation must be abandoned.
|
||||
|
||||
## Channel Establishment v2
|
||||
### Channel Establishment v2
|
||||
|
||||
This is a revision of the channel establishment protocol.
|
||||
It changes the previous protocol to allow the `accept_channel2` peer
|
||||
|
|
@ -1127,7 +1127,7 @@ transaction, via the interactive transaction construction protocol.
|
|||
- where node A is *opener*/*initiator* and node B is
|
||||
*accepter*/*non-initiator*
|
||||
|
||||
### The `open_channel2` Message
|
||||
#### The `open_channel2` Message
|
||||
|
||||
This message initiates the v2 channel establishment workflow.
|
||||
|
||||
|
|
@ -1167,7 +1167,7 @@ This message initiates the v2 channel establishment workflow.
|
|||
Rationale and Requirements are the same as for [`open_channel`](#the-open_channel-message),
|
||||
with the following additions.
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
If nodes have negotiated `option_dual_fund`:
|
||||
- the opening node:
|
||||
|
|
@ -1185,7 +1185,7 @@ The receiving node:
|
|||
- MUST fail the negotiation if:
|
||||
- `require_confirmed_inputs` is set but it cannot provide confirmed inputs
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
`temporary_channel_id` MUST be derived using a zeroed out basepoint for the
|
||||
peer's revocation basepoint. This allows the peer to return channel-assignable
|
||||
|
|
@ -1217,7 +1217,7 @@ The sending node may require the other participant to only use confirmed inputs.
|
|||
This ensures that the sending node doesn't end up paying the fees of a low
|
||||
feerate unconfirmed ancestor of one of the other participant's inputs.
|
||||
|
||||
### The `accept_channel2` Message
|
||||
#### The `accept_channel2` Message
|
||||
|
||||
This message contains information about a node and indicates its
|
||||
acceptance of the new channel.
|
||||
|
|
@ -1255,7 +1255,7 @@ Rationale and Requirements are the same as listed above,
|
|||
for [`accept_channel`](#the-accept_channel-message) with the following
|
||||
additions.
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The accepting node:
|
||||
- MUST use the `temporary_channel_id` of the `open_channel2` message
|
||||
|
|
@ -1267,7 +1267,7 @@ The receiving node:
|
|||
- MUST fail the negotiation if:
|
||||
- `require_confirmed_inputs` is set but it cannot provide confirmed inputs
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
The `funding_satoshis` is the amount of bitcoin in satoshis
|
||||
the *accepter* will be contributing to the channel's funding transaction.
|
||||
|
|
@ -1278,35 +1278,35 @@ Instead, the channel reserve is fixed at 1% of the total channel balance
|
|||
rounded down to the nearest whole satoshi or the `dust_limit_satoshis`,
|
||||
whichever is greater.
|
||||
|
||||
### Funding Composition
|
||||
#### Funding Composition
|
||||
|
||||
Funding composition for channel establishment v2 makes use of the
|
||||
[Interactive Transaction Construction](#interactive-transaction-construction)
|
||||
protocol, with the following additional caveats.
|
||||
|
||||
#### The `tx_add_input` Message
|
||||
##### The `tx_add_input` Message
|
||||
|
||||
##### Requirements
|
||||
###### Requirements
|
||||
|
||||
The sending node:
|
||||
- if the receiver set `require_confirmed_inputs` in `open_channel2`,
|
||||
`accept_channel2`, `tx_init_rbf` or `tx_ack_rbf`:
|
||||
- MUST NOT send a `tx_add_input` that contains an unconfirmed input
|
||||
|
||||
#### The `tx_add_output` Message
|
||||
##### The `tx_add_output` Message
|
||||
|
||||
##### Requirements
|
||||
###### Requirements
|
||||
|
||||
The sending node:
|
||||
- if is the *opener*:
|
||||
- MUST send at least one `tx_add_output`, which contains the
|
||||
channel's funding output
|
||||
|
||||
##### Rationale
|
||||
###### Rationale
|
||||
|
||||
The channel funding output must be added by the *opener*, who pays its fees.
|
||||
|
||||
#### The `tx_complete` Message
|
||||
##### The `tx_complete` Message
|
||||
|
||||
Upon receipt of consecutive `tx_complete`s, the receiving node:
|
||||
- if is the *accepter*:
|
||||
|
|
@ -1327,7 +1327,7 @@ Upon receipt of consecutive `tx_complete`s, the receiving node:
|
|||
- MUST fail the negotiation if:
|
||||
- one of the inputs added by the other peer is unconfirmed
|
||||
|
||||
### The `commitment_signed` Message
|
||||
#### The `commitment_signed` Message
|
||||
|
||||
This message is exchanged by both peers. It contains the signatures for
|
||||
the first commitment transaction.
|
||||
|
|
@ -1335,7 +1335,7 @@ the first commitment transaction.
|
|||
Rationale and Requirements are the same as listed below,
|
||||
for [`commitment_signed`](#committing-updates-so-far-commitment_signed) with the following additions.
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sending node:
|
||||
- MUST send zero HTLCs.
|
||||
|
|
@ -1350,7 +1350,7 @@ The receiving node:
|
|||
- MUST send `tx_signatures` if it should sign first, as specified
|
||||
in the [`tx_signatures` requirements](#the-tx_signatures-message)
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
The first commitment transaction has no HTLCs.
|
||||
|
||||
|
|
@ -1358,7 +1358,7 @@ Once peers are ready to exchange commitment signatures, they must remember
|
|||
the details of the funding transaction to allow resuming the signatures
|
||||
exchange if a disconnection happens.
|
||||
|
||||
### Sharing funding signatures: `tx_signatures`
|
||||
#### Sharing funding signatures: `tx_signatures`
|
||||
|
||||
After a valid `commitment_signed` has been received
|
||||
from the peer and a `commitment_signed` has been sent, a peer:
|
||||
|
|
@ -1366,7 +1366,7 @@ from the peer and a `commitment_signed` has been sent, a peer:
|
|||
transaction, following the order specified in the
|
||||
[`tx_signatures` requirements](#the-tx_signatures-message)
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sending node:
|
||||
- MUST verify it has received a valid commitment signature from its peer
|
||||
|
|
@ -1387,7 +1387,7 @@ The receiving node:
|
|||
opportunity to do so; effectively canceling this channel open
|
||||
- SHOULD apply `witnesses` to the funding transaction and broadcast it
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
A peer sends their `tx_signatures` after receiving a valid `commitment_signed`
|
||||
message, following the order specified in the [`tx_signatures` section](#the-tx_signatures-message).
|
||||
|
|
@ -1398,12 +1398,12 @@ should be considered failed and the channel should be double-spent when
|
|||
there is a productive opportunity to do so. This should disincentivize
|
||||
peers from underpaying fees.
|
||||
|
||||
### Fee bumping: `tx_init_rbf` and `tx_ack_rbf`
|
||||
#### Fee bumping: `tx_init_rbf` and `tx_ack_rbf`
|
||||
|
||||
After the funding transaction has been broadcast, it can be replaced by
|
||||
a transaction paying more fees to make the channel confirm faster.
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The sender of `tx_init_rbf`:
|
||||
- MUST be the *initiator*
|
||||
|
|
@ -1414,7 +1414,7 @@ The recipient:
|
|||
`channel_ready`
|
||||
- MAY fail the negotiation for any reason
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
If a valid `channel_ready` message is received in the middle of an
|
||||
RBF attempt, the attempt MUST be abandoned.
|
||||
|
|
@ -1429,7 +1429,7 @@ a large feerate change, instead sets their `sats` to zero, and decline to
|
|||
participate further in the channel funding: by not contributing, they
|
||||
may obtain incoming liquidity at no cost.
|
||||
|
||||
## Channel Quiescence
|
||||
### Channel Quiescence
|
||||
|
||||
Various fundamental changes, in particular protocol upgrades, are
|
||||
easiest on channels where both commitment transactions match, and no
|
||||
|
|
@ -1497,7 +1497,7 @@ channel state significantly more complex to maintain. This introduces the
|
|||
derivative property that it is impossible to batch multiple downstream protocols
|
||||
in the same quiescence session.
|
||||
|
||||
## Channel Close
|
||||
### Channel Close
|
||||
|
||||
Nodes can negotiate a mutual close of the connection, which unlike a
|
||||
unilateral close, allows them to access their funds immediately and
|
||||
|
|
@ -1521,7 +1521,7 @@ Closing happens in two stages:
|
|||
| |<-(?)-- closing_signed Fn----| |
|
||||
+-------+ +-------+
|
||||
|
||||
### Closing Initiation: `shutdown`
|
||||
#### Closing Initiation: `shutdown`
|
||||
|
||||
Either node (or both) can send a `shutdown` message to initiate closing,
|
||||
along with the `scriptpubkey` it wants to be paid to.
|
||||
|
|
@ -1532,7 +1532,7 @@ along with the `scriptpubkey` it wants to be paid to.
|
|||
* [`u16`:`len`]
|
||||
* [`len*byte`:`scriptpubkey`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
A sending node:
|
||||
- if it hasn't sent a `funding_created` (if it is a funder) or a `funding_signed` (if it is a fundee):
|
||||
|
|
@ -1569,7 +1569,7 @@ A receiving node:
|
|||
- MAY send a `warning`.
|
||||
- MUST fail the connection.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
If channel state is always "clean" (no pending changes) when a
|
||||
shutdown starts, the question of how to behave if it wasn't is avoided:
|
||||
|
|
@ -1599,7 +1599,7 @@ of the receiving node to change the `scriptpubkey`.
|
|||
|
||||
The `shutdown` response requirement implies that the node sends `commitment_signed` to commit any outstanding changes before replying; however, it could theoretically reconnect instead, which would simply erase all outstanding uncommitted changes.
|
||||
|
||||
### Closing Negotiation: `closing_signed`
|
||||
#### Closing Negotiation: `closing_signed`
|
||||
|
||||
Once shutdown is complete, the channel is empty of HTLCs, there are no commitments
|
||||
for which a revocation is owed, and all updates are included on both commitments,
|
||||
|
|
@ -1630,7 +1630,7 @@ reply with the same value (completing after three messages).
|
|||
* [`u64`:`min_fee_satoshis`]
|
||||
* [`u64`:`max_fee_satoshis`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The funding node:
|
||||
- after `shutdown` has been received, AND no HTLCs remain in either commitment transaction:
|
||||
|
|
@ -1691,7 +1691,7 @@ The receiving node:
|
|||
- if one of the outputs in the closing transaction is below the dust limit for its `scriptpubkey` (see [BOLT 3](03-transactions.md#dust-limits)):
|
||||
- MUST fail the channel
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
When `fee_range` is not provided, the "strictly between" requirement ensures
|
||||
that forward progress is made, even if only by a single satoshi at a time.
|
||||
|
|
@ -1713,7 +1713,7 @@ satoshis, which is possible if `dust_limit_satoshis` is below 546 satoshis).
|
|||
No funds are at risk when that happens, but the channel must be force-closed as
|
||||
the closing transaction will likely never reach miners.
|
||||
|
||||
## Normal Operation
|
||||
### Normal Operation
|
||||
|
||||
Once both nodes have exchanged `channel_ready` (and optionally [`announcement_signatures`](07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hashed Time Locked Contracts.
|
||||
|
||||
|
|
@ -1755,7 +1755,7 @@ transactions may be out of sync indefinitely. This is not concerning:
|
|||
what matters is whether both sides have irrevocably committed to a
|
||||
particular update or not (the final state, above).
|
||||
|
||||
### Forwarding HTLCs
|
||||
#### Forwarding HTLCs
|
||||
|
||||
In general, a node offers HTLCs for two reasons: to initiate a payment of its own,
|
||||
or to forward another node's payment. In the forwarding case, care must
|
||||
|
|
@ -1769,7 +1769,7 @@ previous commitment transaction **without/with** it has been revoked, OR
|
|||
2. The commitment transaction **with/without** it has been irreversibly committed to
|
||||
the blockchain.
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
A node:
|
||||
- until an incoming HTLC has been irrevocably committed:
|
||||
|
|
@ -1784,7 +1784,7 @@ to that outgoing HTLC.
|
|||
- upon receiving an `update_fulfill_htlc` for an outgoing HTLC, OR upon discovering the `payment_preimage` from an on-chain HTLC spend:
|
||||
- MUST fulfill the incoming HTLC that corresponds to that outgoing HTLC.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
In general, one side of the exchange needs to be dealt with before the other.
|
||||
Fulfilling an HTLC is different: knowledge of the preimage is, by definition,
|
||||
|
|
@ -1795,7 +1795,7 @@ An HTLC with an unreasonably long expiry is a denial-of-service vector and
|
|||
therefore is not allowed. Note that the exact value of "unreasonable" is currently unclear
|
||||
and may depend on network topology.
|
||||
|
||||
### `cltv_expiry_delta` Selection
|
||||
#### `cltv_expiry_delta` Selection
|
||||
|
||||
Once an HTLC has timed out, it can either be fulfilled or timed-out;
|
||||
care must be taken around this transition, both for offered and received HTLCs.
|
||||
|
|
@ -1888,7 +1888,7 @@ There are four values that need be derived:
|
|||
1-3 above don't apply). The default in [BOLT #11](11-payment-encoding.md) is
|
||||
18, which matches this calculation.
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
An offering node:
|
||||
- MUST estimate a timeout deadline for each HTLC it offers.
|
||||
|
|
@ -1907,7 +1907,7 @@ A fulfilling node:
|
|||
- SHOULD send an `error` to the offering peer (if connected).
|
||||
- MUST fail the channel.
|
||||
|
||||
### Bounding exposure to trimmed in-flight HTLCs: `max_dust_htlc_exposure_msat`
|
||||
#### Bounding exposure to trimmed in-flight HTLCs: `max_dust_htlc_exposure_msat`
|
||||
|
||||
When an HTLC in a channel is below the "trimmed" threshold in [BOLT3 #3](03-transactions.md),
|
||||
the HTLC cannot be claimed on-chain, instead being turned into additional miner
|
||||
|
|
@ -1953,7 +1953,7 @@ For channels that don't use `option_anchors`, an increase of
|
|||
the `feerate_per_kw` may trim multiple htlcs from commitment transactions,
|
||||
which could create a large increase in dust exposure.
|
||||
|
||||
### Adding an HTLC: `update_add_htlc`
|
||||
#### Adding an HTLC: `update_add_htlc`
|
||||
|
||||
Either node can send `update_add_htlc` to offer an HTLC to the other,
|
||||
which is redeemable in return for a payment preimage. Amounts are in
|
||||
|
|
@ -1979,7 +1979,7 @@ is destined, is described in [BOLT #4](04-onion-routing.md).
|
|||
2. data:
|
||||
* [`point`:`path_key`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
A sending node:
|
||||
- if it is _responsible_ for paying the Bitcoin fee:
|
||||
|
|
@ -2052,7 +2052,7 @@ The `onion_routing_packet` contains an obfuscated list of hops and instructions
|
|||
It commits to the HTLC by setting the `payment_hash` as associated data, i.e. includes the `payment_hash` in the computation of HMACs.
|
||||
This prevents replay attacks that would reuse a previous `onion_routing_packet` with a different `payment_hash`.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
Invalid amounts are a clear protocol violation and indicate a breakdown.
|
||||
|
||||
|
|
@ -2082,7 +2082,7 @@ maintaining its channel reserve (because of the increased weight of the
|
|||
commitment transaction), resulting in a degraded channel. See [#728](https://github.com/lightningnetwork/lightning-rfc/issues/728)
|
||||
for more details.
|
||||
|
||||
### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc`
|
||||
#### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc`
|
||||
|
||||
For simplicity, a node can only remove HTLCs added by the other node.
|
||||
There are four reasons for removing an HTLC: the payment preimage is supplied,
|
||||
|
|
@ -2120,7 +2120,7 @@ For an unparsable HTLC:
|
|||
* [`sha256`:`sha256_of_onion`]
|
||||
* [`u16`:`failure_code`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
A node:
|
||||
- SHOULD remove an HTLC as soon as it can.
|
||||
|
|
@ -2163,7 +2163,7 @@ A receiving node:
|
|||
originally sent the HTLC, using the `failure_code` given and setting the
|
||||
data to `sha256_of_onion`.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
A node that doesn't time out HTLCs risks channel failure (see
|
||||
[`cltv_expiry_delta` Selection](#cltv_expiry_delta-selection)).
|
||||
|
|
@ -2184,7 +2184,7 @@ such detection is left as an option.
|
|||
Nodes inside a blinded route must use `invalid_onion_blinding` to avoid
|
||||
leaking information to senders trying to probe the blinded route.
|
||||
|
||||
### Committing Updates So Far: `commitment_signed`
|
||||
#### Committing Updates So Far: `commitment_signed`
|
||||
|
||||
When a node has changes for the remote commitment, it can apply them,
|
||||
sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), and send a
|
||||
|
|
@ -2197,7 +2197,7 @@ sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), an
|
|||
* [`u16`:`num_htlcs`]
|
||||
* [`num_htlcs*signature`:`htlc_signature`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
A sending node:
|
||||
- MUST NOT send a `commitment_signed` message that does not include any
|
||||
|
|
@ -2227,7 +2227,7 @@ A receiving node:
|
|||
`error` and fail the channel.
|
||||
- MUST respond with a `revoke_and_ack` message.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
There's little point offering spam updates: it implies a bug.
|
||||
|
||||
|
|
@ -2248,7 +2248,7 @@ stating time-locks on HTLC outputs.
|
|||
The `option_anchors` allows HTLC transactions to "bring their own fees" by
|
||||
attaching other inputs and outputs, hence the modified signature flags.
|
||||
|
||||
### Completing the Transition to the Updated State: `revoke_and_ack`
|
||||
#### Completing the Transition to the Updated State: `revoke_and_ack`
|
||||
|
||||
Once the recipient of `commitment_signed` checks the signature and knows
|
||||
it has a valid new commitment transaction, it replies with the commitment
|
||||
|
|
@ -2268,7 +2268,7 @@ The description of key derivation is in [BOLT #3](03-transactions.md#key-derivat
|
|||
* [`32*byte`:`per_commitment_secret`]
|
||||
* [`point`:`next_per_commitment_point`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
A sending node:
|
||||
- MUST set `per_commitment_secret` to the secret used to generate keys for
|
||||
|
|
@ -2290,7 +2290,7 @@ A node:
|
|||
them (due to a failed connection),
|
||||
- Note: this is to reduce the above risk.
|
||||
|
||||
### Updating Fees: `update_fee`
|
||||
#### Updating Fees: `update_fee`
|
||||
|
||||
An `update_fee` message is sent by the node which is paying the
|
||||
Bitcoin fee. Like any update, it's first committed to the receiver's
|
||||
|
|
@ -2312,7 +2312,7 @@ given in [BOLT #3](03-transactions.md#fee-calculation).
|
|||
* [`channel_id`:`channel_id`]
|
||||
* [`u32`:`feerate_per_kw`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The node _responsible_ for paying the Bitcoin fee:
|
||||
- SHOULD send `update_fee` to ensure the current fee rate is sufficient (by a
|
||||
|
|
@ -2350,7 +2350,7 @@ A receiving node:
|
|||
- if the dust balance of the local transaction at the updated `feerate_per_kw` is greater than `max_dust_htlc_exposure_msat`:
|
||||
- MAY fail the channel
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
Bitcoin fees are required for unilateral closes to be effective.
|
||||
With `option_anchors`, `feerate_per_kw` is not as critical anymore to guarantee
|
||||
|
|
@ -2377,7 +2377,7 @@ be trimmed at the updated feerate, this could overflow the configured
|
|||
`max_dust_htlc_exposure_msat`. Whether to close the channel preemptively
|
||||
or not is left as a matter of node policy.
|
||||
|
||||
## Message Retransmission
|
||||
### Message Retransmission
|
||||
|
||||
Because communication transports are unreliable, and may need to be
|
||||
re-established from time to time, the design of the transport has been
|
||||
|
|
@ -2419,7 +2419,7 @@ are independent for each peer in the channel and start at 0.
|
|||
They're only explicitly relayed to the other node in the case of
|
||||
re-establishment, otherwise they are implicit.
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
A funding node:
|
||||
- upon disconnection:
|
||||
|
|
@ -2541,7 +2541,7 @@ A node:
|
|||
- if it has sent a previous `shutdown`:
|
||||
- MUST retransmit `shutdown`.
|
||||
|
||||
### Rationale
|
||||
#### Rationale
|
||||
|
||||
The requirements above ensure that the opening phase is nearly
|
||||
atomic: if it doesn't complete, it starts again. The only exception
|
||||
|
|
@ -2614,7 +2614,7 @@ interactive transaction construction, or safely abort that transaction
|
|||
if it was not signed by one of the peers, who has thus already removed
|
||||
it from its state.
|
||||
|
||||
# Authors
|
||||
## Authors
|
||||
|
||||
[ FIXME: Insert Author List ]
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
This details the exact format of on-chain transactions, which both sides need to agree on to ensure signatures are valid. This consists of the funding transaction output script, the commitment transactions, and the HTLC transactions.
|
||||
|
||||
# Table of Contents
|
||||
## Table of Contents
|
||||
|
||||
* [Transactions](#transactions)
|
||||
* [Transaction Output Ordering](#transaction-output-ordering)
|
||||
|
|
@ -45,16 +45,16 @@ This details the exact format of on-chain transactions, which both sides need to
|
|||
* [References](#references)
|
||||
* [Authors](#authors)
|
||||
|
||||
# Transactions
|
||||
## Transactions
|
||||
|
||||
## Transaction Output Ordering
|
||||
### Transaction Output Ordering
|
||||
|
||||
Outputs in transactions are always sorted according to:
|
||||
* first according to their value, smallest first (in whole satoshis, note that for HTLC outputs, the millisatoshi part must be ignored)
|
||||
* followed by `scriptpubkey`, comparing the common-length prefix lexicographically as if by `memcmp`, then selecting the shorter script (if they differ in length),
|
||||
* finally, for HTLC outputs, in increasing `cltv_expiry` order.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
Two offered HTLCs which have the same `amount` (rounded from `amount_msat`) and
|
||||
`payment_hash` will have identical outputs, even if their `cltv_expiry`
|
||||
|
|
@ -62,13 +62,13 @@ differs. This only matters because the same ordering is used to send
|
|||
`htlc_signatures` and the HTLC transactions themselves are different, thus the
|
||||
two peers must agree on the canonical ordering for this case.
|
||||
|
||||
## Use of Segwit
|
||||
### Use of Segwit
|
||||
|
||||
Most transaction outputs used here are pay-to-witness-script-hash<sup>[BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#witness-program)</sup> (P2WSH) outputs: the Segwit version of P2SH. To spend such outputs, the last item on the witness stack must be the actual script that was used to generate the P2WSH output that is being spent. This last item has been omitted for brevity in the rest of this document.
|
||||
|
||||
A `<>` designates an empty vector as required for compliance with MINIMALIF-standard rule.<sup>[MINIMALIF](https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2016-August/013014.html)</sup>
|
||||
|
||||
## Funding Transaction Output
|
||||
### Funding Transaction Output
|
||||
|
||||
* The funding output script is a P2WSH to:
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ A `<>` designates an empty vector as required for compliance with MINIMALIF-stan
|
|||
|
||||
* Where `pubkey1` is the lexicographically lesser of the two `funding_pubkey` in compressed format, and where `pubkey2` is the lexicographically greater of the two.
|
||||
|
||||
## Commitment Transaction
|
||||
### Commitment Transaction
|
||||
|
||||
* version: 2
|
||||
* locktime: upper 8 bits are 0x20, lower 24 bits are the lower 24 bits of the obscured commitment number
|
||||
|
|
@ -95,7 +95,7 @@ case of unilateral close, yet still provides a useful index for both
|
|||
nodes (who know the `payment_basepoint`s) to quickly find a revoked
|
||||
commitment transaction.
|
||||
|
||||
### Commitment Transaction Outputs
|
||||
#### Commitment Transaction Outputs
|
||||
|
||||
To allow an opportunity for penalty transactions, in case of a revoked commitment transaction, all outputs that return funds to the owner of the commitment transaction (a.k.a. the "local node") must be delayed for `to_self_delay` blocks. For HTLCs this delay is done in a second-stage HTLC transaction (HTLC-success for HTLCs accepted by the local node, HTLC-timeout for HTLCs offered by the local node).
|
||||
|
||||
|
|
@ -104,7 +104,7 @@ Otherwise, the required minimum timeout on HTLCs is lengthened by this delay, ca
|
|||
|
||||
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
|
||||
##### `to_local` Output
|
||||
|
||||
This output sends funds back to the owner of this commitment transaction and thus must be timelocked using `OP_CHECKSEQUENCEVERIFY`. It can be claimed, without delay, by the other party if they know the revocation private key. The output is a version-0 P2WSH, with a witness script:
|
||||
|
||||
|
|
@ -127,7 +127,7 @@ If a revoked commitment transaction is published, the other party can spend this
|
|||
|
||||
<revocation_sig> 1
|
||||
|
||||
#### `to_remote` Output
|
||||
##### `to_remote` Output
|
||||
|
||||
If `option_anchors` applies to the commitment transaction, the `to_remote` output is encumbered by a one block csv lock.
|
||||
|
||||
|
|
@ -140,7 +140,7 @@ The output is spent by an input with `nSequence` field set to `1` and witness:
|
|||
Otherwise, this output is a simple P2WPKH to `remotepubkey`. Note: the remote's commitment transaction uses your `localpubkey` for their
|
||||
`to_remote` output to yourself.
|
||||
|
||||
#### `to_local_anchor` and `to_remote_anchor` Output (option_anchors)
|
||||
##### `to_local_anchor` and `to_remote_anchor` Output (option_anchors)
|
||||
|
||||
This output can be spent by the local and remote nodes respectively to provide incentive to mine the transaction, using child-pays-for-parent. Both
|
||||
anchor outputs are always added, except for the case where there are no htlcs and one of the parties has a commitment output that is below the dust limit.
|
||||
|
|
@ -170,7 +170,7 @@ After 16 blocks, anyone can sweep the anchor with witness:
|
|||
|
||||
<>
|
||||
|
||||
#### Offered HTLC Outputs
|
||||
##### Offered HTLC Outputs
|
||||
|
||||
This output sends funds to either an HTLC-timeout transaction after the HTLC-timeout or to the remote node using the payment preimage or the revocation key. The output is a P2WSH, with a witness script (no option_anchors):
|
||||
|
||||
|
|
@ -222,7 +222,7 @@ If a revoked commitment transaction is published, the remote node can spend this
|
|||
|
||||
The sending node can use the HTLC-timeout transaction to timeout the HTLC once the HTLC is expired, as shown below. This is the only way that the local node can timeout the HTLC, and this branch requires `<remotehtlcsig>`, which ensures that the local node cannot prematurely timeout the HTLC since the HTLC-timeout transaction has `cltv_expiry` as its specified `locktime`. The local node must also wait `to_self_delay` before accessing these funds, allowing for the remote node to claim these funds if the transaction has been revoked.
|
||||
|
||||
#### Received HTLC Outputs
|
||||
##### Received HTLC Outputs
|
||||
|
||||
This output sends funds to either the remote node after the HTLC-timeout or using the revocation key, or to an HTLC-success transaction with a successful payment preimage. The output is a P2WSH, with a witness script (no `option_anchors`):
|
||||
|
||||
|
|
@ -276,7 +276,7 @@ If a revoked commitment transaction is published, the remote node can spend this
|
|||
|
||||
To redeem the HTLC, the HTLC-success transaction is used as detailed below. This is the only way that the local node can spend the HTLC, since this branch requires `<remotehtlcsig>`, which ensures that the local node must wait `to_self_delay` before accessing these funds allowing for the remote node to claim these funds if the transaction has been revoked.
|
||||
|
||||
### Trimmed Outputs
|
||||
#### Trimmed Outputs
|
||||
|
||||
Each peer specifies a `dust_limit_satoshis` below which outputs should
|
||||
not be produced; these outputs that are not produced are termed "trimmed". A trimmed output is
|
||||
|
|
@ -285,7 +285,7 @@ to the commitment transaction fee. For HTLCs, it needs to be taken into
|
|||
account that the second-stage HTLC transaction may also be below the
|
||||
limit.
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The base fee and anchor output values:
|
||||
- before the commitment transaction outputs are determined:
|
||||
|
|
@ -318,7 +318,7 @@ less than `dust_limit_satoshis` set by the transaction owner:
|
|||
- MUST be generated as specified in
|
||||
[Received HTLC Outputs](#received-htlc-outputs).
|
||||
|
||||
## HTLC-Timeout and HTLC-Success Transactions
|
||||
### HTLC-Timeout and HTLC-Success Transactions
|
||||
|
||||
These HTLC transactions are almost identical, except the HTLC-timeout transaction is timelocked. Both HTLC-timeout/HTLC-success transactions can be spent by a valid penalty transaction.
|
||||
|
||||
|
|
@ -349,7 +349,7 @@ The witness script for the output is:
|
|||
|
||||
To spend this via penalty, the remote node uses a witness stack `<revocationsig> 1`, and to collect the output, the local node uses an input with nSequence `to_self_delay` and a witness stack `<local_delayedsig> 0`.
|
||||
|
||||
## Closing Transaction
|
||||
### Closing Transaction
|
||||
|
||||
Note that there are two possible variants for each node.
|
||||
|
||||
|
|
@ -364,7 +364,7 @@ Note that there are two possible variants for each node.
|
|||
* `txout` amount: final balance to be paid to one node (minus `fee_satoshis` from `closing_signed`, if this peer funded the channel)
|
||||
* `txout` script: as specified in that node's `scriptpubkey` in its `shutdown` message
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
Each node offering a signature:
|
||||
- MUST round each output down to whole satoshis.
|
||||
|
|
@ -372,7 +372,7 @@ Each node offering a signature:
|
|||
- MUST remove any output below its own `dust_limit_satoshis`.
|
||||
- MAY eliminate its own output.
|
||||
|
||||
### Rationale
|
||||
#### Rationale
|
||||
|
||||
There is a possibility of irreparable differences on closing if one
|
||||
node considers the other's output too small to allow propagation on
|
||||
|
|
@ -390,9 +390,9 @@ has been used.
|
|||
There will be at least one output, if the funding amount is greater
|
||||
than twice `dust_limit_satoshis`.
|
||||
|
||||
## Fees
|
||||
### Fees
|
||||
|
||||
### Fee Calculation
|
||||
#### Fee Calculation
|
||||
|
||||
The fee calculation for both commitment transactions and HTLC
|
||||
transactions is based on the current `feerate_per_kw` and the
|
||||
|
|
@ -423,7 +423,7 @@ This yields the following *expected weights* (details of the computation in [App
|
|||
|
||||
Note the reference 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
|
||||
##### Requirements
|
||||
|
||||
The fee for an HTLC-timeout transaction:
|
||||
- If `option_anchors` applies:
|
||||
|
|
@ -444,7 +444,7 @@ The base fee for a commitment transaction:
|
|||
[Trimmed Outputs](#trimmed-outputs), add 172 to `weight`.
|
||||
3. Multiply `feerate_per_kw` by `weight`, divide by 1000 (rounding down).
|
||||
|
||||
#### Example
|
||||
##### Example
|
||||
|
||||
For example, suppose there is a `feerate_per_kw` of 5000, a `dust_limit_satoshis` of 546 satoshis, and a commitment transaction with:
|
||||
* two offered HTLCs of 5000000 and 1000000 millisatoshis (5000 and 1000 satoshis)
|
||||
|
|
@ -476,7 +476,7 @@ fee (which adds the 1000 and 800 satoshi HTLCs that would make dust
|
|||
outputs) is 7140 satoshi. The final fee may be even higher if the
|
||||
`to_local` or `to_remote` outputs fall below `dust_limit_satoshis`.
|
||||
|
||||
### Fee Payment
|
||||
#### Fee Payment
|
||||
|
||||
Base commitment transaction fees and amounts for `to_local_anchor` and `to_remote_anchor` outputs are extracted from the funder's amount;
|
||||
Restrictions to the commitment tx output for the funder in relation to the
|
||||
|
|
@ -491,13 +491,13 @@ A node:
|
|||
- MAY send a `warning` and close the connection, or send an
|
||||
`error` and fail the channel.
|
||||
|
||||
### Calculating Fees for Collaborative Transactions
|
||||
#### Calculating Fees for Collaborative Transactions
|
||||
|
||||
For transactions constructed using the [interactive protocol](02-peer-protocol.md#interactive-transaction-construction),
|
||||
fees are paid by each party to the transaction, at a `feerate` determined during the
|
||||
initiation, with the initiator covering the fees for the common transaction fields.
|
||||
|
||||
## Dust Limits
|
||||
### Dust Limits
|
||||
|
||||
The `dust_limit_satoshis` parameter is used to configure the threshold below
|
||||
which nodes will not produce on-chain transaction outputs.
|
||||
|
|
@ -520,7 +520,7 @@ is explained in the following sections.
|
|||
In all these sections, the calculations are done with a feerate of 3000 sat/kB
|
||||
as per Bitcoin Core's implementation.
|
||||
|
||||
### Pay to pubkey hash (p2pkh)
|
||||
#### Pay to pubkey hash (p2pkh)
|
||||
|
||||
A p2pkh output is 34 bytes:
|
||||
|
||||
|
|
@ -542,7 +542,7 @@ A p2pkh input is at least 148 bytes:
|
|||
|
||||
The p2pkh dust threshold is then `(34 + 148) * 3000 / 1000 = 546 satoshis`
|
||||
|
||||
### Pay to script hash (p2sh)
|
||||
#### Pay to script hash (p2sh)
|
||||
|
||||
A p2sh output is 32 bytes:
|
||||
|
||||
|
|
@ -555,7 +555,7 @@ script, so we use 148 bytes as a lower bound.
|
|||
|
||||
The p2sh dust threshold is then `(32 + 148) * 3000 / 1000 = 540 satoshis`
|
||||
|
||||
### Pay to witness pubkey hash (p2wpkh)
|
||||
#### Pay to witness pubkey hash (p2wpkh)
|
||||
|
||||
A p2wpkh output is 31 bytes:
|
||||
|
||||
|
|
@ -577,7 +577,7 @@ A p2wpkh input is at least 67 bytes (depending on the signature length):
|
|||
|
||||
The p2wpkh dust threshold is then `(31 + 67) * 3000 / 1000 = 294 satoshis`
|
||||
|
||||
### Pay to witness script hash (p2wsh)
|
||||
#### Pay to witness script hash (p2wsh)
|
||||
|
||||
A p2wsh output is 43 bytes:
|
||||
|
||||
|
|
@ -590,7 +590,7 @@ script, so we use 67 bytes as a lower bound.
|
|||
|
||||
The p2wsh dust threshold is then `(43 + 67) * 3000 / 1000 = 330 satoshis`
|
||||
|
||||
### Unknown segwit versions
|
||||
#### Unknown segwit versions
|
||||
|
||||
Unknown segwit outputs are at most 51 bytes:
|
||||
|
||||
|
|
@ -603,7 +603,7 @@ script, so we use 67 bytes as a lower bound.
|
|||
|
||||
The unknown segwit version dust threshold is then `(51 + 67) * 3000 / 1000 = 354 satoshis`
|
||||
|
||||
## Commitment Transaction Construction
|
||||
### Commitment Transaction Construction
|
||||
|
||||
This section ties the previous sections together to detail the
|
||||
algorithm for constructing the commitment transaction for one peer:
|
||||
|
|
@ -632,9 +632,9 @@ also subtract two times the fixed anchor size of 330 sats from the funder
|
|||
* if `to_remote` exists or there are untrimmed HTLCs, add a [`to_remote_anchor` output](#to_local_anchor-and-to_remote_anchor-output-option_anchors)
|
||||
9. Sort the outputs into [BIP 69+CLTV order](#transaction-output-ordering).
|
||||
|
||||
# Keys
|
||||
## Keys
|
||||
|
||||
## Key Derivation
|
||||
### Key Derivation
|
||||
|
||||
Each commitment transaction uses a unique `localpubkey`.
|
||||
The HTLC-success and HTLC-timeout transactions use `local_delayedpubkey` and `revocationpubkey`.
|
||||
|
|
@ -667,7 +667,7 @@ For efficiency, keys are generated from a series of per-commitment secrets
|
|||
that are generated from a single seed, which allows the receiver to compactly
|
||||
store them (see [below](#efficient-per-commitment-secret-storage)).
|
||||
|
||||
### `localpubkey`, `local_htlcpubkey`, `remote_htlcpubkey`, `local_delayedpubkey`, and `remote_delayedpubkey` Derivation
|
||||
#### `localpubkey`, `local_htlcpubkey`, `remote_htlcpubkey`, `local_delayedpubkey`, and `remote_delayedpubkey` Derivation
|
||||
|
||||
These pubkeys are simply generated by addition from their base points:
|
||||
|
||||
|
|
@ -684,7 +684,7 @@ secrets are known (i.e. the private keys corresponding to `localpubkey`, `local_
|
|||
|
||||
privkey = basepoint_secret + SHA256(per_commitment_point || basepoint)
|
||||
|
||||
### `remotepubkey` Derivation
|
||||
#### `remotepubkey` Derivation
|
||||
|
||||
The `remotepubkey` is simply the remote node's `payment_basepoint`.
|
||||
|
||||
|
|
@ -695,7 +695,7 @@ transactions given to it which only have a `to_remote` output if it
|
|||
sees one of them onchain, but such transactions do not need any
|
||||
enforcement and should not be handed to a watchtower.
|
||||
|
||||
### `revocationpubkey` Derivation
|
||||
#### `revocationpubkey` Derivation
|
||||
|
||||
The `revocationpubkey` is a blinded key: when the local node wishes to create a new
|
||||
commitment for the remote node, it uses its own `revocation_basepoint` and the remote
|
||||
|
|
@ -724,7 +724,7 @@ is known:
|
|||
|
||||
revocationprivkey = revocation_basepoint_secret * SHA256(revocation_basepoint || per_commitment_point) + per_commitment_secret * SHA256(per_commitment_point || revocation_basepoint)
|
||||
|
||||
### Per-commitment Secret Requirements
|
||||
#### Per-commitment Secret Requirements
|
||||
|
||||
A node:
|
||||
- MUST select an unguessable 256-bit seed for each connection,
|
||||
|
|
@ -756,7 +756,7 @@ The receiving node:
|
|||
- MAY store all previous per-commitment secrets.
|
||||
- MAY calculate them from a compact representation, as described below.
|
||||
|
||||
## Efficient Per-commitment Secret Storage
|
||||
### Efficient Per-commitment Secret Storage
|
||||
|
||||
The receiver of a series of secrets can store them compactly in an
|
||||
array of 49 (value,index) pairs. Because, for a given secret on a
|
||||
|
|
@ -829,9 +829,9 @@ This looks complicated, but remember that the index in entry `b` has
|
|||
`b` trailing 0s; the mask and compare simply checks if the index
|
||||
at each bucket is a prefix of the desired index.
|
||||
|
||||
# Appendix A: Expected Weights
|
||||
## Appendix A: Expected Weights
|
||||
|
||||
## Expected Weight of the Funding Transaction (v2 Channel Establishment)
|
||||
### Expected Weight of the Funding Transaction (v2 Channel Establishment)
|
||||
|
||||
The *expected weight* of a funding transaction is calculated as follows:
|
||||
|
||||
|
|
@ -868,7 +868,7 @@ Multiplying non-witness data by 4 results in a weight of:
|
|||
overall_weight = funding_transaction_weight + witness_weight
|
||||
|
||||
|
||||
## Expected Weight of the Commitment Transaction
|
||||
### Expected Weight of the Commitment Transaction
|
||||
|
||||
The *expected weight* of a commitment transaction is calculated as follows:
|
||||
|
||||
|
|
@ -983,7 +983,7 @@ Multiplying non-witness data by 4 results in a weight of:
|
|||
overall_weight (no option_anchors) = 500 + 172 * num-htlc-outputs + 224 weight
|
||||
overall_weight (option_anchors) = 900 + 172 * num-htlc-outputs + 224 weight
|
||||
|
||||
## Expected Weight of HTLC-timeout and HTLC-success Transactions
|
||||
### Expected Weight of HTLC-timeout and HTLC-success Transactions
|
||||
|
||||
The *expected weight* of an HTLC transaction is calculated as follows:
|
||||
|
||||
|
|
@ -1119,7 +1119,7 @@ HTLC-success) results in weights of:
|
|||
703 (HTLC-success) (706 with option_anchors))
|
||||
- (really 702 and 705, but we use these numbers for historical reasons)
|
||||
|
||||
# Appendix B: Funding Transaction Test Vectors
|
||||
## Appendix B: Funding Transaction Test Vectors
|
||||
|
||||
In the following:
|
||||
- It's assumed that *local* is the funder.
|
||||
|
|
@ -1160,7 +1160,7 @@ The resulting funding transaction is:
|
|||
funding tx: 0200000001adbb20ea41a8423ea937e76e8151636bf6093b70eaff942930d20576600521fd000000006b48304502210090587b6201e166ad6af0227d3036a9454223d49a1f11839c1a362184340ef0240220577f7cd5cca78719405cbf1de7414ac027f0239ef6e214c90fcaab0454d84b3b012103535b32d5eb0a6ed0982a0479bbadc9868d9836f6ba94dd5a63be16d875069184ffffffff028096980000000000220020c015c4a6be010e21657068fc2e6a9d02b27ebe4d490a25846f7237f104d1a3cd20256d29010000001600143ca33c2e4446f4a305f23c80df8ad1afdcf652f900000000
|
||||
# txid: 8984484a580b825b9972d7adb15050b3ab624ccd731946b3eeddb92f4e7ef6be
|
||||
|
||||
# Appendix C: Commitment and HTLC Transaction Test Vectors
|
||||
## Appendix C: Commitment and HTLC Transaction Test Vectors
|
||||
|
||||
In the following:
|
||||
- *local* transactions are considered, which implies that all payments to *local* are delayed.
|
||||
|
|
@ -1620,11 +1620,11 @@ And, here are the test vectors themselves:
|
|||
# local_htlc_signature = 304402207157f452f2506d73c315192311893800cfb3cc235cc1185b1cfcc136b55230db022014be242dbc6c5da141fec4034e7f387f74d6ff1899453d72ba957467540e1ecb
|
||||
htlc_timeout_tx (htlc #5): 020000000001014bdccf28653066a2c554cafeffdfe1e678e64a69b056684deb0c4fba909423ec02000000000000000001e1120000000000002200204adb4e2f00643db396dd120d4e7dc17625f5f2c11a40d857accc862d6b7dd80e05004730440220471c9f3ad92e49b13b7b8059f43ecf8f7887b0dccbb9fdb54bfe23d62a8ae332022024bd22fae0740e86a44228c35330da9526fd7306dffb2b9dc362d5e78abef7cc0147304402207157f452f2506d73c315192311893800cfb3cc235cc1185b1cfcc136b55230db022014be242dbc6c5da141fec4034e7f387f74d6ff1899453d72ba957467540e1ecb01008576a91414011f7254d96b819c76986c277d115efce6f7b58763ac67210394854aa6eab5b2a8122cc726e9dded053a2184d88256816826d6231c068d4a5b7c820120876475527c21030d417a46946384f88d5f3337267c5e579765875dc4daca813e21734b140639e752ae67a9142002cc93ebefbb1b73f0af055dcc27a0b504ad7688ac6868fa010000
|
||||
|
||||
# Appendix D: Per-commitment Secret Generation Test Vectors
|
||||
## Appendix D: Per-commitment Secret Generation Test Vectors
|
||||
|
||||
These test the generation algorithm that all nodes use.
|
||||
|
||||
## Generation Tests
|
||||
### Generation Tests
|
||||
|
||||
name: generate_from_seed 0 final node
|
||||
seed: 0x0000000000000000000000000000000000000000000000000000000000000000
|
||||
|
|
@ -1651,7 +1651,7 @@ These test the generation algorithm that all nodes use.
|
|||
I: 1
|
||||
output: 0x915c75942a26bb3a433a8ce2cb0427c29ec6c1775cfc78328b57f6ba7bfeaa9c
|
||||
|
||||
## Storage Tests
|
||||
### Storage Tests
|
||||
|
||||
These test the optional compact storage system. In many cases, an
|
||||
incorrect entry cannot be determined until its parent is revealed: an entry is
|
||||
|
|
@ -1847,7 +1847,7 @@ seeded with `0x000...00`.
|
|||
secret: 0xa7efbc61aac46d34f77778bac22c8a20c6a46ca460addc49009bda875ec88fa4
|
||||
output: ERROR
|
||||
|
||||
# Appendix E: Key Derivation Test Vectors
|
||||
## Appendix E: Key Derivation Test Vectors
|
||||
|
||||
These test the derivation for `localpubkey`, `remotepubkey`, `local_htlcpubkey`, `remote_htlcpubkey`, `local_delayedpubkey`, and
|
||||
`remote_delayedpubkey` (which use the same formula), as well as the `revocationpubkey`.
|
||||
|
|
@ -1899,7 +1899,7 @@ All of them use the following secrets (and thus the derived points):
|
|||
# => 0xd09ffff62ddb2297ab000cc85bcb4283fdeb6aa052affbc9dddcf33b61078110
|
||||
revocationprivkey: 0xd09ffff62ddb2297ab000cc85bcb4283fdeb6aa052affbc9dddcf33b61078110
|
||||
|
||||
# Appendix F: Commitment and HTLC Transaction Test Vectors (anchors)
|
||||
## Appendix F: Commitment and HTLC Transaction Test Vectors (anchors)
|
||||
|
||||
The anchor test vectors are based on the test cases as defined in appendix C.
|
||||
Note that in appendix C, `to_local_msat` and `to_remote_msat` are balances
|
||||
|
|
@ -2077,10 +2077,10 @@ before subtraction of:
|
|||
]
|
||||
```
|
||||
|
||||
# Appendix G: Dual Funded Transaction Test Vectors
|
||||
## Appendix G: Dual Funded Transaction Test Vectors
|
||||
|
||||
## Funding Transaction Construction
|
||||
### Preliminaries:
|
||||
### Funding Transaction Construction
|
||||
#### Preliminaries:
|
||||
|
||||
```
|
||||
Genesis block 0:
|
||||
|
|
@ -2094,7 +2094,7 @@ Parent transaction (spends coinbase of block 1):
|
|||
02000000000101f86fd1d0db3ac5a72df968622f31e6b5e6566a09e29206d7c7a55df90e181de800000000171600141fb9623ffd0d422eacc450fd1e967efc477b83ccffffffff0580b2e60e00000000220020fd89acf65485df89797d9ba7ba7a33624ac4452f00db08107f34257d33e5b94680b2e60e0000000017a9146a235d064786b49e7043e4a042d4cc429f7eb6948780b2e60e00000000160014fbb4db9d85fba5e301f4399e3038928e44e37d3280b2e60e0000000017a9147ecd1b519326bc13b0ec716e469b58ed02b112a087f0006bee0000000017a914f856a70093da3a5b5c4302ade033d4c2171705d387024730440220696f6cee2929f1feb3fd6adf024ca0f9aa2f4920ed6d35fb9ec5b78c8408475302201641afae11242160101c6f9932aeb4fcd1f13a9c6df5d1386def000ea259a35001210381d7d5b1bc0d7600565d827242576d9cb793bfe0754334af82289ee8b65d137600000000
|
||||
```
|
||||
|
||||
### Funding transaction (spends parent's outputs):
|
||||
#### Funding transaction (spends parent's outputs):
|
||||
|
||||
Locktime: 120
|
||||
Feerate: 253 sat/kiloweight
|
||||
|
|
@ -2119,7 +2119,7 @@ Inputs:
|
|||
|
||||
```
|
||||
|
||||
### Expected Opener's `tx_add_input` (input 0 above):
|
||||
#### Expected Opener's `tx_add_input` (input 0 above):
|
||||
```
|
||||
num_inputs: 1
|
||||
tx_add_input:[
|
||||
|
|
@ -2134,7 +2134,7 @@ Inputs:
|
|||
]
|
||||
```
|
||||
|
||||
### Expected Accepter's `tx_add_input` (input 2 above):
|
||||
#### Expected Accepter's `tx_add_input` (input 2 above):
|
||||
```
|
||||
num_inputs: 1
|
||||
tx_add_input:[
|
||||
|
|
@ -2149,7 +2149,7 @@ Inputs:
|
|||
]
|
||||
```
|
||||
|
||||
### Outputs: (scriptPubKeys)
|
||||
#### Outputs: (scriptPubKeys)
|
||||
```
|
||||
# opener's change address
|
||||
pubkey: 0206e626a4c6d4392d4030bc78bd93f728d1ba61214a77c63adc17d71e32ded3df
|
||||
|
|
@ -2172,7 +2172,7 @@ scriptPubKey: 0020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98e
|
|||
address: bcrt1q99ae9s3czclgyzuzfpsggc6tfprts63uvkxc0wfcgxfwd04f3mzs3asq6l
|
||||
```
|
||||
|
||||
### Expected Opener's `tx_add_output`:
|
||||
#### Expected Opener's `tx_add_output`:
|
||||
|
||||
```
|
||||
num_outputs: 2
|
||||
|
|
@ -2193,7 +2193,7 @@ address: bcrt1q99ae9s3czclgyzuzfpsggc6tfprts63uvkxc0wfcgxfwd04f3mzs3asq6l
|
|||
]
|
||||
```
|
||||
|
||||
### Expected Accepter's `tx_add_output`:
|
||||
#### Expected Accepter's `tx_add_output`:
|
||||
|
||||
```
|
||||
num_outputs: 1
|
||||
|
|
@ -2208,7 +2208,7 @@ address: bcrt1q99ae9s3czclgyzuzfpsggc6tfprts63uvkxc0wfcgxfwd04f3mzs3asq6l
|
|||
]
|
||||
```
|
||||
|
||||
### Expected Fee Calculation:
|
||||
#### Expected Fee Calculation:
|
||||
|
||||
Opener's fees and change:
|
||||
```
|
||||
|
|
@ -2247,7 +2247,7 @@ Opener's fees and change:
|
|||
as hex: e5effa0200000000
|
||||
```
|
||||
|
||||
### Accepter's fees and change:
|
||||
#### Accepter's fees and change:
|
||||
```
|
||||
contributor_weight = inputs(txid, vout, scriptSig, sequence)
|
||||
* number contributor inputs * 4
|
||||
|
|
@ -2279,13 +2279,13 @@ Opener's fees and change:
|
|||
as hex: 1cf0fa0200000000
|
||||
```
|
||||
|
||||
### Unsigned Funding Transaction:
|
||||
#### Unsigned Funding Transaction:
|
||||
|
||||
```
|
||||
0200000002b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000fdffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000fdffffff03e5effa02000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b1cf0fa020000000016001444cb0c39f93ecc372b5851725bd29d865d333b100084d71700000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec578000000
|
||||
```
|
||||
|
||||
### Expected Opener's `tx_signatures`:
|
||||
#### Expected Opener's `tx_signatures`:
|
||||
|
||||
```
|
||||
tx_signatures{
|
||||
|
|
@ -2299,7 +2299,7 @@ Opener's fees and change:
|
|||
}
|
||||
```
|
||||
|
||||
### Expected Accepter's `tx_signatures`:
|
||||
#### Expected Accepter's `tx_signatures`:
|
||||
|
||||
```
|
||||
tx_signatures{
|
||||
|
|
@ -2313,7 +2313,7 @@ Opener's fees and change:
|
|||
}
|
||||
```
|
||||
|
||||
#### Signed Funding Transaction:
|
||||
##### Signed Funding Transaction:
|
||||
|
||||
Note locktime is set to 120.
|
||||
|
||||
|
|
@ -2321,9 +2321,9 @@ Note locktime is set to 120.
|
|||
02000000000102b932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430200000000fdffffffb932b0669cd0394d0d5bcc27e01ab8c511f1662a6799925b346c0cf18fca03430000000000fdffffff03e5effa02000000001600141ca1cca8855bad6bc1ea5436edd8cff10b7e448b1cf0fa020000000016001444cb0c39f93ecc372b5851725bd29d865d333b100084d71700000000220020297b92c238163e820b82486084634b4846b86a3c658d87b9384192e6bea98ec50247304402207de9ba56bb9f641372e805782575ee840a899e61021c8b1572b3ec1d5b5950e9022069e9ba998915dae193d3c25cb89b5e64370e6a3a7755e7f31cf6d7cbc2a49f6d0121034695f5b7864c580bf11f9f8cb1a94eb336f2ce9ef872d2ae1a90ee276c772484022068656c6c6f2074686572652c2074686973206973206120626974636f6e2121212782012088a820add57dfe5277079d069ca4ad4893c96de91f88ffb981fdc6a2a34d5336c66aff8778000000
|
||||
```
|
||||
|
||||
# References
|
||||
## References
|
||||
|
||||
# Authors
|
||||
## Authors
|
||||
|
||||
[ FIXME: ]
|
||||
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ A node:
|
|||
- MUST report a route failure to the origin node.
|
||||
- MUST discard the packet.
|
||||
|
||||
# Table of Contents
|
||||
## Table of Contents
|
||||
|
||||
* [Conventions](#conventions)
|
||||
* [Key Generation](#key-generation)
|
||||
|
|
@ -70,7 +70,7 @@ A node:
|
|||
* [References](#references)
|
||||
* [Authors](#authors)
|
||||
|
||||
# Conventions
|
||||
## Conventions
|
||||
|
||||
There are a number of conventions adhered to throughout this document:
|
||||
|
||||
|
|
@ -99,7 +99,7 @@ There are a number of conventions adhered to throughout this document:
|
|||
- The variable length `hop_payload` is prefixed with a `bigsize` encoding
|
||||
the length in bytes, excluding the prefix and the trailing HMAC.
|
||||
|
||||
# Key Generation
|
||||
## Key Generation
|
||||
|
||||
A number of encryption and verification keys are derived from the shared secret:
|
||||
|
||||
|
|
@ -122,7 +122,7 @@ returned as the key.
|
|||
Notice that the key-type does not include a C-style `0x00`-termination-byte,
|
||||
e.g. the length of the _rho_ key-type is 3 bytes, not 4.
|
||||
|
||||
# Pseudo Random Byte Stream
|
||||
## Pseudo Random Byte Stream
|
||||
|
||||
The pseudo-random byte stream is used to obfuscate the packet at each hop of the
|
||||
path, so that each hop may only recover the address and HMAC of the next hop.
|
||||
|
|
@ -132,7 +132,7 @@ derived from the shared secret and a 96-bit zero-nonce (`0x000000000000000000000
|
|||
|
||||
The use of a fixed nonce is safe, since the keys are never reused.
|
||||
|
||||
# Packet Structure
|
||||
## Packet Structure
|
||||
|
||||
The packet consists of four sections:
|
||||
|
||||
|
|
@ -183,7 +183,7 @@ sending peer hasn't forwarded an ill-crafted HTLC.
|
|||
|
||||
Since no `payload` TLV value can ever be shorter than 2 bytes, `length` values of 0 and 1 are reserved. (`0` indicated a legacy format no longer supported, and `1` is reserved for future use).
|
||||
|
||||
### `payload` format
|
||||
#### `payload` format
|
||||
|
||||
This is formatted according to the Type-Length-Value format defined in [BOLT #1](01-messaging.md#type-length-value-format).
|
||||
|
||||
|
|
@ -240,7 +240,7 @@ The requirements ensure consistency in responding to an unexpected
|
|||
`outgoing_cltv_value`, whether it is the final node or not, to avoid
|
||||
leaking its position in the route.
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
The creator of `encrypted_recipient_data` (usually, the recipient of payment):
|
||||
|
||||
|
|
@ -343,7 +343,7 @@ The reader:
|
|||
Additional requirements are specified [here](#basic-multi-part-payments) for
|
||||
multi-part payments, and [here](#route-blinding) for blinded payments.
|
||||
|
||||
### Basic Multi-Part Payments
|
||||
#### Basic Multi-Part Payments
|
||||
|
||||
An HTLC may be part of a larger "multi-part" payment: such
|
||||
"base" atomic multipath payments will use the same `payment_hash` for
|
||||
|
|
@ -362,7 +362,7 @@ blinded paths for which the `payment_secret` doesn't make sense.
|
|||
`payment_metadata` is to be included in every payment part, so that
|
||||
invalid payment details can be detected as early as possible.
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The writer:
|
||||
- if the invoice offers the `basic_mpp` feature:
|
||||
|
|
@ -406,7 +406,7 @@ The final node:
|
|||
- if it fulfills any HTLCs in the HTLC set:
|
||||
- MUST fulfill the entire HTLC set.
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
If `basic_mpp` is present it causes a delay to allow other partial
|
||||
payments to combine. The total amount must be sufficient for the
|
||||
|
|
@ -634,12 +634,11 @@ Encrypted recipient data is created by the final recipient to give to the
|
|||
sender, containing instructions for the node on how to handle the message (it can also be created by the sender themselves: the node forwarding cannot tell). It's used
|
||||
in both payment onions and onion messages onions. See [Route Blinding](#route-blinding).
|
||||
|
||||
|
||||
# Accepting and Forwarding a Payment
|
||||
## Accepting and Forwarding a Payment
|
||||
|
||||
Once a node has decoded the payload it either accepts the payment locally, or forwards it to the peer indicated as the next hop in the payload.
|
||||
|
||||
## Non-strict Forwarding
|
||||
### Non-strict Forwarding
|
||||
|
||||
A node MAY forward an HTLC along an outgoing channel other than the one
|
||||
specified by `short_channel_id`, so long as the receiver has the same node
|
||||
|
|
@ -648,7 +647,7 @@ nodes A and B, the HTLC can be forwarded across any channel connecting A and B.
|
|||
Failure to adhere will result in the receiver being unable to decrypt the next
|
||||
hop in the onion packet.
|
||||
|
||||
### Rationale
|
||||
#### Rationale
|
||||
|
||||
In the event that two peers have multiple channels, the downstream node will be
|
||||
able to decrypt the next hop payload regardless of which channel the packet is
|
||||
|
|
@ -669,7 +668,7 @@ Non-strict forwarding allows nodes to make use of private channels connecting
|
|||
them to the receiving node, even if the channel is not known in the public
|
||||
channel graph.
|
||||
|
||||
### Recommendation
|
||||
#### Recommendation
|
||||
|
||||
Implementations using non-strict forwarding should consider applying the same
|
||||
fee schedule to all channels with the same peer, as senders are likely to select
|
||||
|
|
@ -682,7 +681,7 @@ Alternatively, implementations may choose to apply non-strict forwarding only to
|
|||
like-policy channels to ensure their expected fee revenue does not deviate by
|
||||
using an alternate channel.
|
||||
|
||||
## Payload for the Last Node
|
||||
### Payload for the Last Node
|
||||
|
||||
When building the route, the origin node MUST use a payload for
|
||||
the final node with the following values:
|
||||
|
|
@ -705,7 +704,7 @@ compare its values against those of the HTLC. See the
|
|||
If not for the above, since it need not forward payments, the final node could
|
||||
simply discard its payload.
|
||||
|
||||
# Shared Secret
|
||||
## Shared Secret
|
||||
|
||||
The origin node establishes a shared secret with each hop along the route using
|
||||
Elliptic-curve Diffie-Hellman between the sender's ephemeral key at that hop and
|
||||
|
|
@ -722,7 +721,7 @@ during packet forwarding, the hop uses the ephemeral public key and its own
|
|||
node ID private key. Because of the properties of ECDH, they will both derive
|
||||
the same value.
|
||||
|
||||
# Blinding Ephemeral Onion Keys
|
||||
## Blinding Ephemeral Onion Keys
|
||||
|
||||
In order to ensure multiple hops along the route cannot be linked by the
|
||||
ephemeral public keys they see, the key is blinded at each hop. The blinding is
|
||||
|
|
@ -740,7 +739,7 @@ and the 32-byte shared secret. Concretely, it is the `SHA256` hash value of the
|
|||
concatenation of the public key serialized in its compressed format and the
|
||||
shared secret.
|
||||
|
||||
# Packet Construction
|
||||
## Packet Construction
|
||||
|
||||
In the following example, it's assumed that a _sending node_ (origin node),
|
||||
`n_0`, wants to route a packet to a _receiving node_ (final node), `n_r`.
|
||||
|
|
@ -894,7 +893,7 @@ func NewOnionPacket(paymentPath []*btcec.PublicKey, sessionKey *btcec.PrivateKey
|
|||
}
|
||||
```
|
||||
|
||||
# Onion Decryption
|
||||
## Onion Decryption
|
||||
|
||||
There are two kinds of `onion_packet` we use:
|
||||
|
||||
|
|
@ -903,7 +902,7 @@ There are two kinds of `onion_packet` we use:
|
|||
|
||||
Those sections specify the `associated_data` to use, the `path_key` (if any), the extracted payload format and handling (including how to determine the next peer, if any), and how to handle errors. The processing itself is identical.
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A reader:
|
||||
- if `version` is not 0:
|
||||
|
|
@ -959,7 +958,7 @@ A reader:
|
|||
|
||||
In the case where blinded paths are used, the sender did not actually encrypt this onion for our `node_id`, but for a tweaked version: we can derive the tweak used from `path_key` which is given alongside the onion. Then we either tweak our node private key the same way to decrypt the onion, or tweak to the onion ephemeral key which is mathematically equivalent.
|
||||
|
||||
# Filler Generation
|
||||
## Filler Generation
|
||||
|
||||
Upon receiving a packet, the processing node extracts the information destined
|
||||
for it from the route information and the per-hop payload.
|
||||
|
|
@ -1019,7 +1018,7 @@ Note that this example implementation is for demonstration purposes only; the
|
|||
The last hop need not obfuscate the `filler`, since it won't forward the packet
|
||||
any further and thus need not extract an HMAC either.
|
||||
|
||||
# Returning Errors
|
||||
## Returning Errors
|
||||
|
||||
The onion routing protocol includes a simple mechanism for returning encrypted
|
||||
error messages to the origin node.
|
||||
|
|
@ -1078,7 +1077,7 @@ de-anonymize elements of the blinded path. Thus the decision turn every
|
|||
error into `invalid_onion_blinding` which will be converted to a normal
|
||||
onion error by the introduction point.
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
The _erring node_:
|
||||
- MUST set `pad` such that the `failure_len` plus `pad_len` is at least 256.
|
||||
|
|
@ -1093,14 +1092,14 @@ The _origin node_:
|
|||
(maximum route length of tlv payload type).
|
||||
- SHOULD use constant `ammag` and `um` keys to obfuscate the route length.
|
||||
|
||||
### Rationale
|
||||
#### Rationale
|
||||
|
||||
The requirements for the _origin node_ should help hide the payment sender.
|
||||
By continuing decrypting 27 times (dummy decryption cycles after the error is found)
|
||||
the erroring node cannot learn its relative position in the route by performing
|
||||
a timing analysis if the sender were to retry the same route multiple times.
|
||||
|
||||
## Failure Messages
|
||||
### Failure Messages
|
||||
|
||||
The failure message encapsulated in `failuremsg` has an identical format as
|
||||
a normal message: a 2-byte type `failure_code` followed by data applicable
|
||||
|
|
@ -1295,7 +1294,7 @@ reasonable time.
|
|||
|
||||
An error occurred within the blinded path.
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
An _erring node_:
|
||||
- if `path_key` is set in the incoming `update_add_htlc`:
|
||||
|
|
@ -1400,7 +1399,7 @@ An _intermediate hop_ MUST NOT, but the _final node_:
|
|||
- if it returns a `channel_update`:
|
||||
- MUST set `short_channel_id` to the `short_channel_id` used by the incoming onion.
|
||||
|
||||
### Rationale
|
||||
#### Rationale
|
||||
|
||||
In the case of multiple short_channel_id aliases, the `channel_update`
|
||||
`short_channel_id` should refer to the one the original sender is
|
||||
|
|
@ -1417,9 +1416,9 @@ transition away from including it. Nodes which do not provide a
|
|||
Some nodes may still use the `channel_update` for retries of the same payment,
|
||||
however.
|
||||
|
||||
## Receiving Failure Codes
|
||||
### Receiving Failure Codes
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
The _origin node_:
|
||||
- MUST ignore any extra bytes in `failuremsg`.
|
||||
|
|
@ -1450,7 +1449,7 @@ The _origin node_:
|
|||
- MAY use the data specified in the various failure types for debugging
|
||||
purposes.
|
||||
|
||||
# Onion Messages
|
||||
## Onion Messages
|
||||
|
||||
Onion messages allow peers to use existing connections to query for
|
||||
invoices (see [BOLT 12](12-offer-encoding.md)). Like gossip messages,
|
||||
|
|
@ -1471,7 +1470,7 @@ there is no error returned from intermediary nodes.
|
|||
|
||||
For consistency, all onion messages use [Route Blinding](#route-blinding).
|
||||
|
||||
## The `onion_message` Message
|
||||
### The `onion_message` Message
|
||||
|
||||
1. type: 513 (`onion_message`) (`option_onion_messages`)
|
||||
2. data:
|
||||
|
|
@ -1520,7 +1519,7 @@ even, of course!).
|
|||
2. data:
|
||||
* [`tlv_invoice_error`:`inverr`]
|
||||
|
||||
#### Requirements
|
||||
##### Requirements
|
||||
|
||||
The creator of `encrypted_recipient_data` (usually, the recipient of the onion):
|
||||
|
||||
|
|
@ -1591,7 +1590,7 @@ The reader:
|
|||
along `reply_path` `path`.
|
||||
|
||||
|
||||
#### Rationale
|
||||
##### Rationale
|
||||
|
||||
Care must be taken that replies are only accepted using the exact
|
||||
reply_path given, otherwise probing is possible. That means checking
|
||||
|
|
@ -1620,14 +1619,14 @@ Onion messages don't explicitly require a channel, but for
|
|||
spam-reduction a node may choose to ratelimit such peers, especially
|
||||
messages it is asked to forward.
|
||||
|
||||
## `max_htlc_cltv` Selection
|
||||
### `max_htlc_cltv` Selection
|
||||
|
||||
This `max_htlc_cltv` value is defined as 2016 blocks, based on historical value
|
||||
deployed by Lightning implementations.
|
||||
|
||||
# Test Vector
|
||||
## Test Vector
|
||||
|
||||
## Returning Errors
|
||||
### Returning Errors
|
||||
|
||||
The test vectors use the following parameters:
|
||||
|
||||
|
|
@ -1682,7 +1681,7 @@ The following is an in-depth trace of an example of error message creation:
|
|||
stream = 3699fd352a948a05f604763c0bca2968d5eaca2b0118602e52e59121f050936c8dd90c24df7dc8cf8f1665e39a6c75e9e2c0900ea245c9ed3b0008148e0ae18bbfaea0c711d67eade980c6f5452e91a06b070bbde68b5494a92575c114660fb53cf04bf686e67ffa4a0f5ae41a59a39a8515cb686db553d25e71e7a97cc2febcac55df2711b6209c502b2f8827b13d3ad2f491c45a0cafe7b4d8d8810e805dee25d676ce92e0619b9c206f922132d806138713a8f69589c18c3fdc5acee41c1234b17ecab96b8c56a46787bba2c062468a13919afc18513835b472a79b2c35f9a91f38eb3b9e998b1000cc4a0dbd62ac1a5cc8102e373526d7e8f3c3a1b4bfb2f8a3947fe350cb89f73aa1bb054edfa9895c0fc971c2b5056dc8665902b51fced6dff80c4d247db977c15a710ce280fbd0ae3ca2a245b1c967aeb5a1a4a441c50bc9ceb33ca64b5ca93bd8b50060520f35a54a148a4112e8762f9d0b0f78a7f46a5f06c7a4b0845d020eb505c9e527aabab71009289a6919520d32af1f9f51ce4b3655c6f1aae1e26a16dc9aae55e9d4a6f91d4ba76e96fcb851161da3fc39d0d97ce30a5855c75ac2f613ff36a24801bcbd33f0ce4a3572b9a2fca21efb3b07897fc07ee71e8b1c0c6f8dbb7d2c4ed13f11249414fc94047d1a4a0be94d45db56af4c1a3bf39c9c5aa18209eaebb9e025f670d4c8cc1ee598c912db154eaa3d0c93cb3957e126c50486bf98c852ad326b5f80a19df6b2791f3d65b8586474f4c5dcb2aca0911d2257d1bb6a1e9fc1435be879e75d23290f9feb93ed40baaeca1c399fc91fb1da3e5f0f5d63e543a8d12fe6f7e654026d3a118ab58cb14bef9328d4af254215eb1f639828cc6405a3ab02d90bb70a798787a52c29b3a28fc67b0908563a65f08112abd4e9115cb01db09460c602aba3ddc375569dc3abe42c61c5ea7feb39ad8b05d8e2718e68806c0e1c34b0bc85492f985f8b3e76197a50d63982b780187078f5c59ebd814afaeffc7b2c6ee39d4f9c8c45fb5f685756c563f4b9d028fe7981b70752f5a31e44ba051ab40f3604c8596f1e95dc9b0911e7ede63d69b5eecd245fbecbcf233cf6eba842c0fec795a5adeab2100b1a1bc62c15046d48ec5709da4af64f59a2e552ddbbdcda1f543bb4b687e79f2253ff0cd9ba4e6bfae8e510e5147273d288fd4336dbd0b6617bf0ef71c0b4f1f9c1dc999c17ad32fe196b1e2b27baf4d59bba8e5193a9595bd786be00c32bae89c5dbed1e994fddffbec49d0e2d270bcc1068850e5d7e7652e274909b3cf5e3bc6bf64def0bbeac974a76d835e9a10bdd7896f27833232d907b7405260e3c986569bb8fdd65a55b020b91149f27bda9e63b4c2cc5370bcc81ef044a68c40c1b178e4265440334cc40f59ab5f82a022532805bfa659257c8d8ab9b4aef6abbd05de284c2eb165ef35737e3d387988c566f7b1ca0b1fc3e7b4ed991b77f23775e1c36a09a991384a33b78
|
||||
error packet for node 0: 2dd2f49c1f5af0fcad371d96e8cddbdcd5096dc309c1d4e110f955926506b3c03b44c192896f45610741c85ed4074212537e0c118d472ff3a559ae244acd9d783c65977765c5d4e00b723d00f12475aafaafff7b31c1be5a589e6e25f8da2959107206dd42bbcb43438129ce6cce2b6b4ae63edc76b876136ca5ea6cd1c6a04ca86eca143d15e53ccdc9e23953e49dc2f87bb11e5238cd6536e57387225b8fff3bf5f3e686fd08458ffe0211b87d64770db9353500af9b122828a006da754cf979738b4374e146ea79dd93656170b89c98c5f2299d6e9c0410c826c721950c780486cd6d5b7130380d7eaff994a8503a8fef3270ce94889fe996da66ed121741987010f785494415ca991b2e8b39ef2df6bde98efd2aec7d251b2772485194c8368451ad49c2354f9d30d95367bde316fec6cbdddc7dc0d25e99d3075e13d3de0822669861dafcd29de74eac48b64411987285491f98d78584d0c2a163b7221ea796f9e8671b2bb91e38ef5e18aaf32c6c02f2fb690358872a1ed28166172631a82c2568d23238017188ebbd48944a147f6cdb3690d5f88e51371cb70adf1fa02afe4ed8b581afc8bcc5104922843a55d52acde09bc9d2b71a663e178788280f3c3eae127d21b0b95777976b3eb17be40a702c244d0e5f833ff49dae6403ff44b131e66df8b88e33ab0a58e379f2c34bf5113c66b9ea8241fc7aa2b1fa53cf4ed3cdd91d407730c66fb039ef3a36d4050dde37d34e80bcfe02a48a6b14ae28227b1627b5ad07608a7763a531f2ffc96dff850e8c583461831b19feffc783bc1beab6301f647e9617d14c92c4b1d63f5147ccda56a35df8ca4806b8884c4aa3c3cc6a174fdc2232404822569c01aba686c1df5eecc059ba97e9688c8b16b70f0d24eacfdba15db1c71f72af1b2af85bd168f0b0800483f115eeccd9b02adf03bdd4a88eab03e43ce342877af2b61f9d3d85497cd1c6b96674f3d4f07f635bb26add1e36835e321d70263b1c04234e222124dad30ffb9f2a138e3ef453442df1af7e566890aedee568093aa922dd62db188aa8361c55503f8e2c2e6ba93de744b55c15260f15ec8e69bb01048ca1fa7bbbd26975bde80930a5b95054688a0ea73af0353cc84b997626a987cc06a517e18f91e02908829d4f4efc011b9867bd9bfe04c5f94e4b9261d30cc39982eb7b250f12aee2a4cce0484ff34eebba89bc6e35bd48d3968e4ca2d77527212017e202141900152f2fd8af0ac3aa456aae13276a13b9b9492a9a636e18244654b3245f07b20eb76b8e1cea8c55e5427f08a63a16b0a633af67c8e48ef8e53519041c9138176eb14b8782c6c2ee76146b8490b97978ee73cd0104e12f483be5a4af414404618e9f6633c55dda6f22252cb793d3d16fae4f0e1431434e7acc8fa2c009d4f6e345ade172313d558a4e61b4377e31b8ed4e28f7cd13a7fe3f72a409bc3bdabfe0ba47a6d861e21f64d2fac706dab18b3e546df4
|
||||
|
||||
# References
|
||||
## References
|
||||
|
||||
[sphinx]: http://www.cypherpunks.ca/~iang/pubs/Sphinx_Oakland09.pdf
|
||||
[RFC2104]: https://tools.ietf.org/html/rfc2104
|
||||
|
|
@ -1690,7 +1689,7 @@ The following is an in-depth trace of an example of error message creation:
|
|||
[sec2]: http://www.secg.org/sec2-v2.pdf
|
||||
[rfc8439]: https://tools.ietf.org/html/rfc8439
|
||||
|
||||
# Authors
|
||||
## Authors
|
||||
|
||||
[ FIXME: ]
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ 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
|
||||
## Table of Contents
|
||||
* [General Nomenclature](#general-nomenclature)
|
||||
* [Commitment Transaction](#commitment-transaction)
|
||||
* [Failing a Channel](#failing-a-channel)
|
||||
|
|
@ -47,7 +47,7 @@ encounters any of the above situations, on-chain.
|
|||
* [Expected Weight of the `accepted_htlc` Penalty Transaction Witness](#expected-weight-of-the-accepted-htlc-penalty-transaction-witness)
|
||||
* [Authors](#authors)
|
||||
|
||||
# General Nomenclature
|
||||
## 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
|
||||
|
|
@ -61,7 +61,7 @@ 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](https://github.com/bitcoin/bitcoin/blob/4db82b7aab4ad64717f742a7318e3dc6811b41be/src/consensus/tx_verify.cpp#L223)).
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A node:
|
||||
- once it has broadcast a funding transaction OR sent a commitment signature
|
||||
|
|
@ -78,7 +78,7 @@ A node:
|
|||
- SHOULD fail the channel.
|
||||
- SHOULD ignore invalid transactions.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
Once a local node has some funds at stake, monitoring the blockchain is required
|
||||
to ensure the remote node does not close unilaterally.
|
||||
|
|
@ -87,7 +87,7 @@ 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
|
||||
## Commitment Transaction
|
||||
|
||||
The local and remote nodes each hold a *commitment transaction*. Each of these
|
||||
commitment transactions has up to six types of outputs:
|
||||
|
|
@ -117,7 +117,7 @@ consequence, the two commitment transactions are not identical, but they are
|
|||
See [BOLT #3: Commitment Transaction](03-transactions.md#commitment-transaction)
|
||||
for more details.
|
||||
|
||||
# Failing a Channel
|
||||
## Failing a Channel
|
||||
|
||||
Although closing a channel can be accomplished in several ways, the most
|
||||
efficient is preferred.
|
||||
|
|
@ -126,7 +126,7 @@ Various error cases involve closing a channel. The requirements for sending
|
|||
error messages to peers are specified in
|
||||
[BOLT #1: The `error` Message](01-messaging.md#the-error-message).
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A node:
|
||||
- if a *local commitment transaction* has NOT ever contained a `to_local`
|
||||
|
|
@ -153,7 +153,7 @@ A node:
|
|||
addressed by adding the CSV delay to the non-anchor outputs.
|
||||
- SHOULD use [replace-by-fee](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki) or other mechanism on the spending transaction if it proves insufficient for timely inclusion in a block.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
Since `dust_limit_satoshis` is supposed to prevent creation of uneconomic
|
||||
outputs (which would otherwise remain forever, unspent on the blockchain), all
|
||||
|
|
@ -171,7 +171,7 @@ the commitment transaction may require a child transaction to cause it to be min
|
|||
signature from `closing_signed` would be if the fee offered was too small for
|
||||
it to be processed.
|
||||
|
||||
# Mutual Close Handling
|
||||
## Mutual Close Handling
|
||||
|
||||
A closing transaction *resolves* the funding transaction output.
|
||||
|
||||
|
|
@ -179,7 +179,7 @@ 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`](02-peer-protocol.md#closing-initiation-shutdown)).
|
||||
|
||||
# Unilateral Close Handling: Local Commitment Transaction
|
||||
## 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
|
||||
|
|
@ -190,7 +190,7 @@ 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
|
||||
### Requirements
|
||||
|
||||
A node:
|
||||
- upon discovering its *local commitment transaction*:
|
||||
|
|
@ -209,7 +209,7 @@ A node:
|
|||
- MUST handle HTLCs offered by the remote node as
|
||||
specified in [HTLC Output Handling: Local Commitment, Remote Offers](#htlc-output-handling-local-commitment-remote-offers).
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
Spending the `to_local` output avoids having to remember the complicated
|
||||
witness script, associated with that particular channel, for later
|
||||
|
|
@ -218,7 +218,7 @@ spending.
|
|||
The `to_remote` output is entirely the business of the remote node, and
|
||||
can be ignored.
|
||||
|
||||
## HTLC Output Handling: Local Commitment, Local Offers
|
||||
### 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
|
||||
|
|
@ -231,7 +231,7 @@ 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
|
||||
#### Requirements
|
||||
|
||||
A node:
|
||||
- if the commitment transaction HTLC output is spent using the payment
|
||||
|
|
@ -260,7 +260,7 @@ A node:
|
|||
the HTLC.
|
||||
- MAY fail the corresponding incoming HTLC sooner.
|
||||
|
||||
### Rationale
|
||||
#### Rationale
|
||||
|
||||
The payment preimage either serves to prove payment (when the offering node
|
||||
originated the payment) or to redeem the corresponding incoming HTLC from
|
||||
|
|
@ -288,7 +288,7 @@ race, does not switch to a commitment transaction that does contain the HTLC
|
|||
before the node fails it (hence the wait). The requirement that the incoming
|
||||
HTLC be failed before its own timeout still applies as an upper bound.
|
||||
|
||||
## HTLC Output Handling: Local Commitment, Remote Offers
|
||||
### HTLC Output Handling: Local Commitment, Remote Offers
|
||||
|
||||
Each HTLC output can only be spent by the recipient, using the HTLC-success
|
||||
transaction, which it can only populate if it has the payment
|
||||
|
|
@ -309,7 +309,7 @@ There are several possible cases for an offered HTLC:
|
|||
from the outgoing HTLC; otherwise, it will lose funds by sending an outgoing
|
||||
payment without redeeming the incoming payment.
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
A local node:
|
||||
- if it receives (or already possesses) a payment preimage for an unresolved
|
||||
|
|
@ -335,7 +335,7 @@ transaction itself.
|
|||
If it's NOT otherwise resolved, once the HTLC output has expired, it is
|
||||
considered *irrevocably resolved*.
|
||||
|
||||
# Unilateral Close Handling: Remote Commitment Transaction
|
||||
## Unilateral Close Handling: Remote Commitment Transaction
|
||||
|
||||
The *remote node's* commitment transaction *resolves* the funding
|
||||
transaction output.
|
||||
|
|
@ -344,7 +344,7 @@ There are no delays constraining node behavior in this case, so it's simpler for
|
|||
a node to handle than the case in which it discovers its local commitment
|
||||
transaction (see [Unilateral Close Handling: Local Commitment Transaction](#unilateral-close-handling-local-commitment-transaction)).
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A local node:
|
||||
- upon discovering a *valid* commitment transaction broadcast by a
|
||||
|
|
@ -366,7 +366,7 @@ A local node:
|
|||
- otherwise (it is NOT able to handle the broadcast for some reason):
|
||||
- MUST inform the user of potentially lost funds.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
There may be more than one valid, *unrevoked* commitment transaction after a
|
||||
signature has been received via `commitment_signed` and before the corresponding
|
||||
|
|
@ -380,7 +380,7 @@ commitment number is greater than expected. It can derive its own `remotepubkey`
|
|||
transaction, in order to salvage its own funds. Note: in this scenario, the node
|
||||
will be unable to salvage the HTLCs.
|
||||
|
||||
## HTLC Output Handling: Remote Commitment, Local Offers
|
||||
### HTLC Output Handling: Remote Commitment, Local Offers
|
||||
|
||||
Each HTLC output can only be spent by either the *local offerer*, after it's
|
||||
timed out, or by the *remote recipient*, by using the HTLC-success transaction
|
||||
|
|
@ -393,7 +393,7 @@ because the outputs were trimmed as dust, or because the remote node has two
|
|||
The HTLC output has *timed out* once the depth of the latest block is equal to
|
||||
or greater than the HTLC `cltv_expiry`.
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
A local node:
|
||||
- if the commitment transaction HTLC output is spent using the payment
|
||||
|
|
@ -413,7 +413,7 @@ A local node:
|
|||
the HTLC:
|
||||
- MAY fail it sooner.
|
||||
|
||||
### Rationale
|
||||
#### Rationale
|
||||
|
||||
If the commitment transaction belongs to the *remote* node, the only way for it
|
||||
to spend the HTLC output (using a payment preimage) is for it to use the
|
||||
|
|
@ -445,7 +445,7 @@ commitment transaction that does contain it before the node fails it: hence
|
|||
the wait. The requirement that the incoming HTLC be failed before its
|
||||
own timeout still applies as an upper bound.
|
||||
|
||||
## HTLC Output Handling: Remote Commitment, Remote Offers
|
||||
### HTLC Output Handling: Remote Commitment, Remote Offers
|
||||
|
||||
The remote HTLC outputs can only be spent by the local node if it has the
|
||||
payment preimage. If the local node does not have the preimage (and doesn't
|
||||
|
|
@ -466,7 +466,7 @@ There are actually several possible cases for an offered HTLC:
|
|||
from the outgoing HTLC; otherwise, it will lose funds by sending an outgoing
|
||||
payment without redeeming the incoming one.
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
A local node:
|
||||
- if it receives (or already possesses) a payment preimage for an unresolved
|
||||
|
|
@ -480,14 +480,14 @@ outgoing HTLC:
|
|||
If not otherwise resolved, once the HTLC output has expired, it is considered
|
||||
*irrevocably resolved*.
|
||||
|
||||
# Revoked Transaction Close Handling
|
||||
## Revoked Transaction Close Handling
|
||||
|
||||
If any node tries to cheat by broadcasting an outdated commitment transaction
|
||||
(any previous commitment transaction besides the most current one), the other
|
||||
node in the channel can use its revocation private key to claim all the funds from the
|
||||
channel's original funding transaction.
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
Once a node discovers a commitment transaction for which *it* has a
|
||||
revocation private key, the funding transaction output is *resolved*.
|
||||
|
|
@ -526,7 +526,7 @@ A local node:
|
|||
- MAY use a single transaction to *resolve* all the outputs.
|
||||
- MUST handle its transactions being invalidated by HTLC transactions.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
A single transaction that resolves all the outputs will be under the
|
||||
standard size limit because of the 483 HTLC-per-party limit (see
|
||||
|
|
@ -546,7 +546,7 @@ transaction for the revoked output and actively fee-bump it until its confirmati
|
|||
The exact value of `security_delay` is left as a matter of node policy, though we
|
||||
recommend 18 blocks (similar to incoming HTLC deadline).
|
||||
|
||||
## Penalty Transactions Weight Calculation
|
||||
### Penalty Transactions Weight Calculation
|
||||
|
||||
There are three different scripts for penalty transactions, with the following
|
||||
witness weights (details of weight computation are in
|
||||
|
|
@ -586,7 +586,7 @@ Thus, 483 bidirectional HTLCs (containing both `to_local` and
|
|||
Note: even if the `to_remote` output is not swept, the resulting
|
||||
`max_num_htlcs` is 967; which yields the same unidirectional limit of 483 HTLCs.
|
||||
|
||||
# Generation of HTLC Transactions
|
||||
## Generation of HTLC Transactions
|
||||
|
||||
If `option_anchors` does not apply to the commitment transaction, then
|
||||
HTLC-timeout and HTLC-success transactions are complete transactions with
|
||||
|
|
@ -602,7 +602,7 @@ HTLC-success transactions are signed with the input and output having the same
|
|||
value. This means they have a zero fee and MUST be combined with other inputs
|
||||
to arrive at a reasonable fee.
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A node which broadcasts an HTLC-success or HTLC-timeout transaction for a
|
||||
commitment transaction:
|
||||
|
|
@ -611,7 +611,7 @@ commitment transaction:
|
|||
inclusion in a block.
|
||||
- MAY combine it with other transactions.
|
||||
|
||||
# General Requirements
|
||||
## General Requirements
|
||||
|
||||
A node:
|
||||
- upon discovering a transaction that spends a funding transaction output
|
||||
|
|
@ -627,9 +627,9 @@ A node:
|
|||
- Note: watching for mempool transactions should result in lower latency
|
||||
HTLC redemptions.
|
||||
|
||||
# Appendix A: Expected Weights
|
||||
## Appendix A: Expected Weights
|
||||
|
||||
## Expected Weight of the `to_local` Penalty Transaction Witness
|
||||
### Expected Weight of the `to_local` Penalty Transaction Witness
|
||||
|
||||
As described in [BOLT #3](03-transactions.md), the witness for this transaction
|
||||
is:
|
||||
|
|
@ -661,7 +661,7 @@ calculated as follows:
|
|||
- witness_script_length: 1 byte
|
||||
- witness_script (to_local_script)
|
||||
|
||||
## Expected Weight of the `offered_htlc` Penalty Transaction Witness
|
||||
### Expected Weight of the `offered_htlc` Penalty Transaction Witness
|
||||
|
||||
The *expected weight* of the `offered_htlc` penalty transaction witness is
|
||||
calculated as follows (some calculations have already been made in
|
||||
|
|
@ -678,7 +678,7 @@ calculated as follows (some calculations have already been made in
|
|||
- witness_script_length: 1 byte
|
||||
- witness_script (offered_htlc_script)
|
||||
|
||||
## Expected Weight of the `accepted_htlc` Penalty Transaction Witness
|
||||
### Expected Weight of the `accepted_htlc` Penalty Transaction Witness
|
||||
|
||||
The *expected weight* of the `accepted_htlc` penalty transaction witness is
|
||||
calculated as follows (some calculations have already been made in
|
||||
|
|
@ -695,7 +695,7 @@ calculated as follows (some calculations have already been made in
|
|||
- witness_script_length: 1 byte
|
||||
- witness_script (accepted_htlc_script)
|
||||
|
||||
# Authors
|
||||
## Authors
|
||||
|
||||
[FIXME:]
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ To support channel and node discovery, three *gossip messages* are supported:
|
|||
one valid `channel_announcement` for any channel, but at least two
|
||||
`channel_update` messages are expected.
|
||||
|
||||
# Table of Contents
|
||||
## Table of Contents
|
||||
|
||||
* [Definition of `short_channel_id`](#definition-of-short_channel_id)
|
||||
* [The `announcement_signatures` Message](#the-announcement_signatures-message)
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ used within the protocol to establish an encrypted and authenticated connection
|
|||
with peers, and also to authenticate any information advertised on behalf
|
||||
of a node.
|
||||
|
||||
# Table of Contents
|
||||
## Table of Contents
|
||||
|
||||
* [Cryptographic Messaging Overview](#cryptographic-messaging-overview)
|
||||
* [Authenticated Key Agreement Handshake](#authenticated-key-agreement-handshake)
|
||||
|
|
@ -506,19 +506,19 @@ Key rotation for a key `k` is performed according to the following steps:
|
|||
4. `k = k'`
|
||||
5. `ck = ck'`
|
||||
|
||||
# Security Considerations
|
||||
## Security Considerations
|
||||
|
||||
It is strongly recommended that existing, commonly-used, validated
|
||||
libraries be used for encryption and decryption, to avoid the many possible
|
||||
implementation pitfalls.
|
||||
|
||||
# Appendix A: Transport Test Vectors
|
||||
## Appendix A: Transport Test Vectors
|
||||
|
||||
To make a repeatable test handshake, the following specifies what `generateKey()` will
|
||||
return (i.e. the value for `e.priv`) for each side. Note that this
|
||||
is a violation of the spec, which requires randomness.
|
||||
|
||||
## Initiator Tests
|
||||
### Initiator Tests
|
||||
|
||||
The initiator SHOULD produce the given output when fed this input.
|
||||
The comments reflect internal states, for debugging purposes.
|
||||
|
|
@ -606,7 +606,7 @@ The comments reflect internal states, for debugging purposes.
|
|||
output: ERROR (ACT2_BAD_TAG)
|
||||
```
|
||||
|
||||
## Responder Tests
|
||||
### Responder Tests
|
||||
|
||||
The responder SHOULD produce the given output when fed this input.
|
||||
|
||||
|
|
@ -751,7 +751,7 @@ The responder SHOULD produce the given output when fed this input.
|
|||
output: ERROR (ACT3_BAD_TAG)
|
||||
```
|
||||
|
||||
## Message Encryption Tests
|
||||
### Message Encryption Tests
|
||||
|
||||
In this test, the initiator sends length 5 messages containing "hello"
|
||||
1001 times. Only six example outputs are shown, for brevity and to test
|
||||
|
|
@ -776,16 +776,16 @@ two key rotations:
|
|||
output 1000: 0x4a2f3cc3b5e78ddb83dcb426d9863d9d9a723b0337c89dd0b005d89f8d3c05c52b76b29b740f09
|
||||
output 1001: 0x2ecd8c8a5629d0d02ab457a0fdd0f7b90a192cd46be5ecb6ca570bfc5e268338b1a16cf4ef2d36
|
||||
|
||||
# Acknowledgments
|
||||
## Acknowledgments
|
||||
|
||||
TODO(roasbeef); fin
|
||||
|
||||
# References
|
||||
## References
|
||||
1. <a id="reference-1">https://tools.ietf.org/html/rfc8439</a>
|
||||
2. <a id="reference-2">http://noiseprotocol.org/noise.html</a>
|
||||
3. <a id="reference-3">https://tools.ietf.org/html/rfc5869</a>
|
||||
|
||||
# Authors
|
||||
## Authors
|
||||
|
||||
FIXME
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
A simple, extendable, QR-code-ready protocol for requesting payments
|
||||
over Lightning.
|
||||
|
||||
# Table of Contents
|
||||
## Table of Contents
|
||||
|
||||
* [Encoding Overview](#encoding-overview)
|
||||
* [Human-Readable Part](#human-readable-part)
|
||||
|
|
@ -16,7 +16,7 @@ over Lightning.
|
|||
* [Examples](#examples)
|
||||
* [Authors](#authors)
|
||||
|
||||
# Encoding Overview
|
||||
## Encoding Overview
|
||||
|
||||
The format for a Lightning invoice uses
|
||||
[bech32 encoding](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki),
|
||||
|
|
@ -31,7 +31,7 @@ use 'lightning:' as a prefix before the BOLT-11 encoding (note: not
|
|||
as per BIP-21, with the key 'lightning' and the value equal to the BOLT-11
|
||||
encoding.
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A writer:
|
||||
- MUST encode the payment request in Bech32 (see BIP-0173)
|
||||
|
|
@ -44,7 +44,7 @@ A reader:
|
|||
- if the checksum is incorrect:
|
||||
- MUST fail the payment.
|
||||
|
||||
# Human-Readable Part
|
||||
## Human-Readable Part
|
||||
|
||||
The human-readable part of a Lightning invoice consists of two sections:
|
||||
1. `prefix`: `ln` + BIP-0173 currency prefix (e.g. `lnbc` for Bitcoin mainnet,
|
||||
|
|
@ -60,7 +60,7 @@ The following `multiplier` letters are defined:
|
|||
* `n` (nano): multiply by 0.000000001
|
||||
* `p` (pico): multiply by 0.000000000001
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A writer:
|
||||
- MUST encode `prefix` using the currency required for successful payment.
|
||||
|
|
@ -86,7 +86,7 @@ A reader:
|
|||
- if multiplier is `p` and the last decimal of `amount` is not 0:
|
||||
- MUST fail the payment.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
The `amount` is encoded into the human readable part, as it's fairly
|
||||
readable and a useful indicator of how much is being requested.
|
||||
|
|
@ -98,7 +98,7 @@ whatever is being offered in return.
|
|||
The `p` multiplier would allow to specify sub-millisatoshi amounts, which cannot be transferred on the network, since HTLCs are denominated in millisatoshis.
|
||||
Requiring a trailing `0` decimal ensures that the `amount` represents an integer number of millisatoshis.
|
||||
|
||||
# Data Part
|
||||
## Data Part
|
||||
|
||||
The data part of a Lightning invoice consists of multiple sections:
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ The data part of a Lightning invoice consists of multiple sections:
|
|||
1. zero or more tagged parts
|
||||
1. `signature`: Bitcoin-style signature of above (520 bits)
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A writer:
|
||||
- MUST set `timestamp` to the number of seconds since Midnight 1 January 1970, UTC in
|
||||
|
|
@ -120,14 +120,14 @@ A writer:
|
|||
A reader:
|
||||
- MUST check that the `signature` is valid (see the `n` tagged field specified below).
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
`signature` covers an exact number of bytes even though the SHA2
|
||||
standard actually supports hashing in bit boundaries, because it's not widely
|
||||
implemented. The recovery ID allows public-key recovery, so the
|
||||
identity of the payee node can be implied.
|
||||
|
||||
## Tagged Fields
|
||||
### Tagged Fields
|
||||
|
||||
Each Tagged Field is of the form:
|
||||
|
||||
|
|
@ -159,7 +159,7 @@ Currently defined tagged fields are:
|
|||
supported or required for receiving this payment.
|
||||
See [Feature Bits](#feature-bits).
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
A writer:
|
||||
- MUST include exactly one `p` field.
|
||||
|
|
@ -222,7 +222,8 @@ A reader:
|
|||
- MUST use an expiry delta of at least 18 when making the payment
|
||||
- if an `m` field is provided:
|
||||
- MUST use that as [`payment_metadata`](04-onion-routing.md#tlv_payload-payload-format)
|
||||
### Rationale
|
||||
|
||||
#### Rationale
|
||||
|
||||
The type-and-length format allows future extensions to be backward
|
||||
compatible. `data_length` is always a multiple of 5 bits, for easy
|
||||
|
|
@ -268,7 +269,7 @@ The `r` field allows limited routing assistance: as specified, it only
|
|||
allows minimum information to use private channels, however, it could also
|
||||
assist in future partial-knowledge routing.
|
||||
|
||||
### Security Considerations for Payment Descriptions
|
||||
#### Security Considerations for Payment Descriptions
|
||||
|
||||
Payment descriptions are user-defined and provide a potential avenue for
|
||||
injection attacks: during the processes of both rendering and persistence.
|
||||
|
|
@ -291,7 +292,7 @@ engines that support SQL or other dynamically interpreted querying languages.
|
|||
|
||||
Don't be like the school of [Little Bobby Tables](https://xkcd.com/327/).
|
||||
|
||||
## Feature Bits
|
||||
### Feature Bits
|
||||
|
||||
Feature bits allow forward and backward compatibility, and follow the
|
||||
_it's ok to be odd_ rule. Features appropriate for use in the `9` field
|
||||
|
|
@ -301,7 +302,7 @@ The field is big-endian. The least-significant bit is numbered 0,
|
|||
which is _even_, and the next most significant bit is numbered 1,
|
||||
which is _odd_.
|
||||
|
||||
### Requirements
|
||||
#### Requirements
|
||||
|
||||
A writer:
|
||||
- MUST set the `9` field to a feature vector compliant with the
|
||||
|
|
@ -316,7 +317,7 @@ A reader:
|
|||
- MUST NOT use [Basic multi-part payments](04-onion-routing.md#basic-multi-part-payments).
|
||||
|
||||
|
||||
# Payer / Payee Interactions
|
||||
## Payer / Payee Interactions
|
||||
|
||||
These are generally defined by the rest of the Lightning BOLT series,
|
||||
but it's worth noting that [BOLT #4](04-onion-routing.md#requirements-2) specifies that the payee SHOULD
|
||||
|
|
@ -332,7 +333,7 @@ If the payment succeeds but there is a later dispute, the payer can
|
|||
prove both the signed offer from the payee and the successful
|
||||
payment.
|
||||
|
||||
## Payer / Payee Requirements
|
||||
### Payer / Payee Requirements
|
||||
|
||||
A payer:
|
||||
- after the `timestamp` plus `expiry` has passed:
|
||||
|
|
@ -349,11 +350,11 @@ A payee:
|
|||
- after the `timestamp` plus `expiry` has passed:
|
||||
- SHOULD NOT accept a payment.
|
||||
|
||||
# Implementation
|
||||
## Implementation
|
||||
|
||||
https://github.com/rustyrussell/lightning-payencode
|
||||
|
||||
# Examples
|
||||
## Examples
|
||||
|
||||
NB: all the following examples are signed with `priv_key`=`e126f68f7eafcc8b74f54d269fe206be715000f94dac067d1c04a8ca3b2db734`.
|
||||
All invoices contain a `payment_secret`=`1111111111111111111111111111111111111111111111111111111111111111` unless otherwise noted.
|
||||
|
|
@ -739,9 +740,9 @@ Breakdown:
|
|||
* `7hf8he7ecf7n4ffphs6awl9t6676rrclv9ckg3d3ncn7fct63p6s365duk5wrk202cfy3aj5xnnp5gs3vrdvruverwwq7yzhkf5a3xqp`: signature
|
||||
* `d05wjc`: Bech32 checksum
|
||||
|
||||
# Examples of Invalid Invoices
|
||||
## Examples of Invalid Invoices
|
||||
|
||||
> # Same, but adding invalid unknown feature 100
|
||||
> ### Same, but adding invalid unknown feature 100
|
||||
> lnbc25m1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5vdhkven9v5sxyetpdeessp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9q4psqqqqqqqqqqqqqqqqsgqtqyx5vggfcsll4wu246hz02kp85x4katwsk9639we5n5yngc3yhqkm35jnjw4len8vrnqnf5ejh0mzj9n3vz2px97evektfm2l6wqccp3y7372
|
||||
|
||||
Breakdown:
|
||||
|
|
@ -784,7 +785,7 @@ Breakdown:
|
|||
> ### Invalid sub-millisatoshi precision.
|
||||
> lnbc2500000001p1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpusp5zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zygs9qrsgq0lzc236j96a95uv0m3umg28gclm5lqxtqqwk32uuk4k6673k6n5kfvx3d2h8s295fad45fdhmusm8sjudfhlf6dcsxmfvkeywmjdkxcp99202x
|
||||
|
||||
# Authors
|
||||
## Authors
|
||||
|
||||
[ FIXME: ]
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# BOLT #12: Negotiation Protocol for Lightning Payments
|
||||
|
||||
# Table of Contents
|
||||
## Table of Contents
|
||||
|
||||
* [Limitations of BOLT 11](#limitations-of-bolt-11)
|
||||
* [Payment Flow Scenarios](#payment-flow-scenarios)
|
||||
|
|
@ -11,7 +11,7 @@
|
|||
* [Invoices](#invoices)
|
||||
* [Invoice Errors](#invoice-errors)
|
||||
|
||||
# Limitations of BOLT 11
|
||||
## Limitations of BOLT 11
|
||||
|
||||
The BOLT 11 invoice format has proven popular but has several
|
||||
limitations:
|
||||
|
|
@ -36,7 +36,7 @@ limitations:
|
|||
payment attempts are made for the same user.
|
||||
|
||||
|
||||
# Payment Flow Scenarios
|
||||
## Payment Flow Scenarios
|
||||
|
||||
Here we use "user" as shorthand for the individual user's lightning
|
||||
node and "merchant" as the shorthand for the node of someone who is
|
||||
|
|
@ -58,7 +58,7 @@ The merchant-pays-user flow (e.g. ATM or refund):
|
|||
3. The merchant confirms the *invoice_node_id* to ensure it's about to pay the correct
|
||||
person, and makes a payment to the invoice.
|
||||
|
||||
## Payment Proofs and Payer Proofs
|
||||
### Payment Proofs and Payer Proofs
|
||||
|
||||
Note that the normal lightning "proof of payment" can only demonstrate that an
|
||||
invoice was paid (by showing the preimage of the `payment_hash`), not who paid
|
||||
|
|
@ -70,7 +70,7 @@ to request the invoice. In addition, the Merkle construction of the BOLT 12
|
|||
invoice signature allows the user to reveal invoice fields in case
|
||||
of a dispute selectively.
|
||||
|
||||
# Encoding
|
||||
## Encoding
|
||||
|
||||
Each of the forms documented here are in
|
||||
[TLV](01-messaging.md#type-length-value-format) format.
|
||||
|
|
@ -80,7 +80,7 @@ The supported ASCII encoding is the human-readable prefix, followed by a
|
|||
optionally interspersed with `+` (for indicating additional data is to
|
||||
come). There is no checksum, unlike bech32m.
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
Writers of a bolt12 string:
|
||||
- MUST either use all lowercase or all UPPERCASE.
|
||||
|
|
@ -94,7 +94,7 @@ Readers of a bolt12 string:
|
|||
two bech32 characters:
|
||||
- MUST remove the `+` and whitespace.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
The use of bech32 is arbitrary but already exists in the bitcoin
|
||||
world. We currently omit the six-character trailing checksum: QR
|
||||
|
|
@ -114,7 +114,7 @@ zzzzz
|
|||
|
||||
See [format-string-test.json](bolt12/format-string-test.json).
|
||||
|
||||
# Signature Calculation
|
||||
## Signature Calculation
|
||||
|
||||
All signatures are created as per
|
||||
[BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)
|
||||
|
|
@ -179,7 +179,7 @@ Assume L1A2A > L3A:
|
|||
Signature = SIG("lightninginvoicesignature", Root, nodekey)
|
||||
```
|
||||
|
||||
# Offers
|
||||
## Offers
|
||||
|
||||
Offers are a precursor to an invoice_request: readers will request an invoice
|
||||
(or multiple) based on the offer. An offer can be much longer-lived than a
|
||||
|
|
@ -192,7 +192,7 @@ distinct TLV ranges.
|
|||
|
||||
The human-readable prefix for offers is `lno`.
|
||||
|
||||
## TLV Fields for Offers
|
||||
### TLV Fields for Offers
|
||||
|
||||
1. `tlv_stream`: `offer`
|
||||
2. types:
|
||||
|
|
@ -230,7 +230,7 @@ The human-readable prefix for offers is `lno`.
|
|||
2. data:
|
||||
* [`point`:`id`]
|
||||
|
||||
## Requirements For Offers
|
||||
### Requirements For Offers
|
||||
|
||||
A writer of an offer:
|
||||
- MUST NOT set any TLV fields outside the inclusive ranges: 1 to 79 and 1000000000 to 1999999999.
|
||||
|
|
@ -321,7 +321,7 @@ A reader of an offer:
|
|||
- MUST send the onion message to `offer_issuer_id`
|
||||
- MAY send more than one invoice request onion message at once.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
The entire offer is reflected in the invoice_request, both for
|
||||
completeness (so all information will be returned in the invoice), and
|
||||
|
|
@ -348,7 +348,7 @@ painful to have to special-case the "only one left" offer generation.
|
|||
|
||||
Offers can be used to simply send money without expecting anything in return (tips, kudos, donations, etc), which means the description field is optional (the `offer_issuer` field is very useful for this case!); if you are charging for something specific, the description is vital for the user to know what it was they paid for.
|
||||
|
||||
# Invoice Requests
|
||||
## Invoice Requests
|
||||
|
||||
Invoice Requests are a request for an invoice; the human-readable prefix for
|
||||
invoice requests is `lnr`.
|
||||
|
|
@ -376,7 +376,7 @@ leaves are unguessable, allowing a future compact representation to hide fields
|
|||
while still allowing signature validation.
|
||||
|
||||
|
||||
## TLV Fields for `invoice_request`
|
||||
### TLV Fields for `invoice_request`
|
||||
|
||||
1. `tlv_stream`: `invoice_request`
|
||||
2. types:
|
||||
|
|
@ -447,7 +447,7 @@ while still allowing signature validation.
|
|||
2. data:
|
||||
* [`bip340sig`:`sig`]
|
||||
|
||||
## Requirements for Invoice Requests
|
||||
### Requirements for Invoice Requests
|
||||
|
||||
The writer:
|
||||
- if it is responding to an offer:
|
||||
|
|
@ -544,7 +544,7 @@ The reader:
|
|||
- MUST reject the invoice request if `name` or `domain` contain any bytes which are not
|
||||
`0`-`9`, `a`-`z`, `A`-`Z`, `-`, `_` or `.`.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
`invreq_metadata` might typically contain information about the derivation of the
|
||||
`invreq_payer_id`. This should not leak any information (such as using a simple
|
||||
|
|
@ -571,7 +571,7 @@ informative for the payer to know how the sender claims
|
|||
|
||||
The requirement to use `offer_paths` if present, ensures a node does not reveal it is the source of an offer if it is asked directly. Similarly, the requirement that the correct path is used for the offer ensures that cannot be made to reveal that it is the same node that created some other offer.
|
||||
|
||||
# Invoices
|
||||
## Invoices
|
||||
|
||||
Invoices are a payment request, and when the payment is made,
|
||||
the payment preimage can be combined with the invoice to form a cryptographic receipt.
|
||||
|
|
@ -691,7 +691,7 @@ the `onion_message` `invoice` field.
|
|||
* [`u16`:`len`]
|
||||
* [`len*byte`:`address`]
|
||||
|
||||
## Invoice Features
|
||||
### Invoice Features
|
||||
|
||||
| Bits | Description | Name |
|
||||
|------|----------------------------------|----------------|
|
||||
|
|
@ -704,7 +704,7 @@ MAY (17) use multiple part payments to pay the invoice.
|
|||
Some implementations may not support MPP (e.g. for small payments), or
|
||||
may (due to capacity limits on a single channel) require it.
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A writer of an invoice:
|
||||
- MUST set `invoice_created_at` to the number of seconds since Midnight 1
|
||||
|
|
@ -801,7 +801,7 @@ A reader of an invoice:
|
|||
- otherwise (derived from an offer):
|
||||
- MUST reject the invoice if it did not arrive via invoice request `onionmsg_tlv` `reply_path`.
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
Because the messaging layer is unreliable, it's quite possible to
|
||||
receive multiple requests for the same offer. As it's the caller's
|
||||
|
|
@ -848,13 +848,13 @@ to the invoice request requirements, and we also require it to be mirrored
|
|||
here.
|
||||
|
||||
|
||||
# Invoice Errors
|
||||
## Invoice Errors
|
||||
|
||||
Informative errors can be returned in an onion message `invoice_error`
|
||||
field (via the onion `reply_path`) for either `invoice_request` or
|
||||
`invoice`.
|
||||
|
||||
## TLV Fields for `invoice_error`
|
||||
### TLV Fields for `invoice_error`
|
||||
|
||||
1. `tlv_stream`: `invoice_error`
|
||||
2. types:
|
||||
|
|
@ -868,7 +868,7 @@ field (via the onion `reply_path`) for either `invoice_request` or
|
|||
2. data:
|
||||
* [`...*utf8`:`msg`]
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
A writer of an invoice_error:
|
||||
- MUST set `error` to an explanatory string.
|
||||
|
|
@ -884,7 +884,7 @@ A writer of an invoice_error:
|
|||
A reader of an invoice_error:
|
||||
FIXME!
|
||||
|
||||
## Rationale
|
||||
### Rationale
|
||||
|
||||
Usually an error message is sufficient for diagnostics, however future
|
||||
enhancements may make automated handling useful.
|
||||
|
|
@ -896,7 +896,7 @@ sender of the invoice would have to guess how many msat that was,
|
|||
and could use the `invoice_error` to indicate if the recipient disagreed
|
||||
with the conversion so the sender can send a new invoice.
|
||||
|
||||
# FIXME: Possible future extensions:
|
||||
## FIXME: Possible future extensions:
|
||||
|
||||
1. The offer can require delivery info in the `invoice_request`.
|
||||
2. An offer can be updated: the response to an `invoice_request` is another offer,
|
||||
|
|
|
|||
5
tools/lint.sh
Executable file
5
tools/lint.sh
Executable file
|
|
@ -0,0 +1,5 @@
|
|||
#!/bin/sh
|
||||
|
||||
# https://github.com/DavidAnson/markdownlint-cli2
|
||||
|
||||
markdownlint-cli2 ??-*.md proposals/*.md
|
||||
Loading…
Add table
Reference in a new issue