From a59746d1efe67b46818d7d7ed23552ec5501b89e Mon Sep 17 00:00:00 2001 From: Jiri Jakes Date: Fri, 12 May 2023 15:45:32 +0800 Subject: [PATCH] Make all heading levels consistent Previously, levels of headings were used inconsistently across the documents, which made automated export to other formats complicated. With this change, all documents have single level 1 heading (title of the document) and all other headings are at least level 2. --- 02-peer-protocol.md | 100 ++++++++++++++++++++-------------------- 03-transactions.md | 102 ++++++++++++++++++++--------------------- 04-onion-routing.md | 70 ++++++++++++++-------------- 05-onchain.md | 74 +++++++++++++++--------------- 07-routing-gossip.md | 2 +- 08-transport.md | 18 ++++---- 11-payment-encoding.md | 45 +++++++++--------- 7 files changed, 206 insertions(+), 205 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index f43c68611..970f762a0 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -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) @@ -27,9 +27,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` @@ -50,7 +50,7 @@ pubkey corresponding to the funding output nothing prevents duplicative channel ids. -## Channel Establishment +### Channel Establishment 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. @@ -97,7 +97,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 @@ -200,7 +200,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 @@ -217,7 +217,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. @@ -289,7 +289,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`. @@ -313,7 +313,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 @@ -346,7 +346,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. @@ -375,7 +375,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 @@ -388,7 +388,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. @@ -407,7 +407,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. @@ -416,7 +416,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 @@ -429,7 +429,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`: @@ -457,7 +457,7 @@ The recipient: - on receipt of a valid `funding_signed`: - SHOULD broadcast the funding transaction. -#### Rationale +##### Rationale We decide on `option_static_remotekey`, `option_anchor_outputs` or `option_anchors_zero_fee_htlc_tx` at this point when we first have to generate @@ -473,7 +473,7 @@ use `option_static_remotekey`, `option_anchor_outputs` or `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. @@ -492,7 +492,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 @@ -537,7 +537,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 @@ -560,7 +560,7 @@ ones it has sent so it can use them should they be requested by incoming HTLCs. The recipient only need remember one, for use in `r` route hints in BOLT 11 invoices. -## 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 @@ -584,7 +584,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. @@ -595,7 +595,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): @@ -632,7 +632,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: @@ -662,7 +662,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, @@ -693,7 +693,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: @@ -754,7 +754,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. @@ -776,7 +776,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. @@ -818,7 +818,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 @@ -832,7 +832,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: @@ -847,7 +847,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, @@ -858,7 +858,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. @@ -951,7 +951,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. @@ -970,7 +970,7 @@ A fulfilling node: - SHOULD send an `error` to the offering peer (if connected). - MUST fail the channel. -### 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 @@ -996,7 +996,7 @@ is destined, is described in [BOLT #4](04-onion-routing.md). 2. data: * [`point`:`blinding`] -#### Requirements +##### Requirements A sending node: - if it is _responsible_ for paying the Bitcoin fee: @@ -1064,7 +1064,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. @@ -1094,7 +1094,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, @@ -1132,7 +1132,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. @@ -1173,7 +1173,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)). @@ -1194,7 +1194,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 @@ -1207,7 +1207,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 @@ -1237,7 +1237,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. @@ -1258,7 +1258,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 @@ -1278,7 +1278,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 @@ -1300,7 +1300,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 @@ -1322,7 +1322,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 @@ -1344,7 +1344,7 @@ A receiving node: `error` and fail the channel. - but MAY delay this check until the `update_fee` is committed. -#### 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 @@ -1366,7 +1366,7 @@ it's simplest to only allow it to set fee levels; however, as the same fee rate applies to HTLC transactions, the receiving node must also care about the reasonableness of the fee. -## 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 @@ -1402,7 +1402,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: @@ -1522,7 +1522,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 @@ -1602,7 +1602,7 @@ fall-behind detection. An implementation can offer both, however, and fall back to the `option_data_loss_protect` behavior if `option_static_remotekey` is not negotiated. -# Authors +## Authors [ FIXME: Insert Author List ] diff --git a/03-transactions.md b/03-transactions.md index a8e843ff9..1e5245a9d 100644 --- a/03-transactions.md +++ b/03-transactions.md @@ -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) @@ -43,16 +43,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` @@ -60,13 +60,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[BIP141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#witness-program) (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.[MINIMALIF](https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2016-August/013014.html) -## Funding Transaction Output +### Funding Transaction Output * The funding output script is a P2WSH to: @@ -74,7 +74,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 @@ -93,7 +93,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). @@ -102,7 +102,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: @@ -125,7 +125,7 @@ If a revoked commitment transaction is published, the other party can spend this 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. @@ -138,7 +138,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. @@ -168,7 +168,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): @@ -220,7 +220,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 ``, 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`): @@ -274,7 +274,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 ``, 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 @@ -283,7 +283,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: @@ -316,7 +316,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. @@ -347,7 +347,7 @@ The witness script for the output is: To spend this via penalty, the remote node uses a witness stack ` 1`, and to collect the output, the local node uses an input with nSequence `to_self_delay` and a witness stack ` 0`. -## Closing Transaction +### Closing Transaction Note that there are two possible variants for each node. @@ -362,7 +362,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. @@ -370,7 +370,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 @@ -388,9 +388,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 @@ -421,7 +421,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_zero_fee_htlc_tx` applies: @@ -442,7 +442,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) @@ -474,7 +474,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 @@ -489,7 +489,7 @@ A node: - MAY send a `warning` and close the connection, or send an `error` and fail the channel. -## 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. @@ -512,7 +512,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: @@ -534,7 +534,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: @@ -547,7 +547,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: @@ -569,7 +569,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: @@ -582,7 +582,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: @@ -595,7 +595,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: @@ -624,9 +624,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_anchor_outputs) 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`, and a `remotepubkey`. The HTLC-success and HTLC-timeout transactions use `local_delayedpubkey` and `revocationpubkey`. @@ -661,7 +661,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: @@ -679,7 +679,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 If `option_static_remotekey` or `option_anchors` is negotiated, the `remotepubkey` is simply the remote node's `payment_basepoint`, otherwise it is calculated as above using @@ -692,7 +692,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 @@ -721,7 +721,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, @@ -753,7 +753,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 @@ -826,9 +826,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 Commitment Transaction +### Expected Weight of the Commitment Transaction The *expected weight* of a commitment transaction is calculated as follows: @@ -943,7 +943,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: @@ -1079,7 +1079,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. @@ -1120,7 +1120,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. @@ -1946,11 +1946,11 @@ Here are the same test vectors, but when `option_static_remotekey` is used: # 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 @@ -1977,7 +1977,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 @@ -2173,7 +2173,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`. @@ -2225,7 +2225,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 @@ -2501,7 +2501,7 @@ before subtraction of: ] ``` -# Appendix G: Commitment and HTLC Transaction Test Vectors (anchors_zero_fee_htlc_tx) +## Appendix G: Commitment and HTLC Transaction Test Vectors (anchors_zero_fee_htlc_tx) 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 @@ -2679,9 +2679,9 @@ before subtraction of: ] ``` -# References +## References -# Authors +## Authors [ FIXME: ] diff --git a/04-onion-routing.md b/04-onion-routing.md index 1b5146bf4..0cc551cc5 100644 --- a/04-onion-routing.md +++ b/04-onion-routing.md @@ -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) @@ -67,7 +67,7 @@ A node: * [References](#references) * [Authors](#authors) -# Conventions +## Conventions There are a number of conventions adhered to throughout this document: @@ -96,7 +96,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: @@ -119,7 +119,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. @@ -129,7 +129,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: @@ -180,7 +180,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). @@ -237,7 +237,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): @@ -331,7 +331,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 @@ -350,7 +350,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: @@ -394,7 +394,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 @@ -424,7 +424,7 @@ otherwise meets the amount criterion (eg. some other failure, or invoice timeout), however if it were to fulfill only some of them, intermediary nodes could simply claim the remaining ones. -### Route Blinding +#### Route Blinding Nodes receiving onion packets may hide their identity from senders by "blinding" an arbitrary amount of hops at the end of an onion path. @@ -482,7 +482,7 @@ may contain the following TLV fields: 2. data: * [`...*byte`:`features`] -#### Requirements +##### Requirements A recipient N(r) creating a blinded route `N(0) -> N(1) -> ... -> N(r)` to itself: @@ -541,7 +541,7 @@ The final recipient: - MUST ignore the message if the `path_id` does not match the blinded route it created -#### Rationale +##### Rationale Route blinding is a lightweight technique to provide recipient anonymity. It's more flexible than rendezvous routing because it simply replaces the public @@ -588,11 +588,11 @@ set `payment_constraints.max_cltv_expiry` to restrict the lifetime of a blinded route and reduce the risk that an intermediate node updates its fees and rejects payments (which could be used to unblind nodes inside the route). -# 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 @@ -601,7 +601,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 @@ -622,7 +622,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 @@ -635,7 +635,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: @@ -658,7 +658,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 @@ -675,7 +675,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 Keys +## Blinding Ephemeral 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 @@ -693,7 +693,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`. @@ -847,7 +847,7 @@ func NewOnionPacket(paymentPath []*btcec.PublicKey, sessionKey *btcec.PrivateKey } ``` -# Packet Forwarding +## Packet Forwarding This specification is limited to `version` `0` packets; the structure of future versions may change. @@ -895,7 +895,7 @@ by blinding the ephemeral key with the processing node's public key, along with shared secret, and by serializing the `hop_payloads`. The resulting packet is then forwarded to the addressed peer. -## Requirements +### Requirements The processing node: - if the ephemeral public key is NOT on the `secp256k1` curve: @@ -919,7 +919,7 @@ The processing node: - MUST signal a route failure. -# 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. @@ -979,7 +979,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. @@ -1038,7 +1038,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. @@ -1052,7 +1052,7 @@ The _origin node_: - SHOULD continue decrypting, until the loop has been repeated 20 times. - SHOULD use constant `ammag` and `um` keys to obfuscate the route length. -## 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 @@ -1256,7 +1256,7 @@ reasonable time. An error occurred within the blinded path. -### Requirements +#### Requirements An _erring node_: - if `blinding_point` is set in the incoming `update_add_htlc`: @@ -1363,16 +1363,16 @@ 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 expecting, to both avoid confusion and to avoid leaking information about other aliases (or the real location of the channel UTXO). -## Receiving Failure Codes +### Receiving Failure Codes -### Requirements +#### Requirements The _origin node_: - MUST ignore any extra bytes in `failuremsg`. @@ -1407,9 +1407,9 @@ The _origin node_: - MAY use the data specified in the various failure types for debugging purposes. -# Test Vector +## Test Vector -## Returning Errors +### Returning Errors The test vectors use the following parameters: @@ -1464,7 +1464,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 @@ -1472,7 +1472,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: ] diff --git a/05-onchain.md b/05-onchain.md index 934ab4f62..1328141e4 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -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 @@ -382,7 +382,7 @@ commitment number is greater than expected. If both nodes support 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 @@ -395,7 +395,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 @@ -415,7 +415,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 @@ -447,7 +447,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 @@ -468,7 +468,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 @@ -482,14 +482,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*. @@ -528,7 +528,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 @@ -548,7 +548,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 @@ -588,7 +588,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 @@ -604,7 +604,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: @@ -622,7 +622,7 @@ adding inputs to the final transactions than `option_anchor_outputs`, since the HTLC-success and HTLC-timeout transactions won't propagate without additional inputs added. -# General Requirements +## General Requirements A node: - upon discovering a transaction that spends a funding transaction output @@ -638,9 +638,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: @@ -672,7 +672,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 @@ -689,7 +689,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 @@ -706,7 +706,7 @@ calculated as follows (some calculations have already been made in - witness_script_length: 1 byte - witness_script (accepted_htlc_script) -# Authors +## Authors [FIXME:] diff --git a/07-routing-gossip.md b/07-routing-gossip.md index b53d75e8a..5c9944a6f 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -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) diff --git a/08-transport.md b/08-transport.md index 49ca45e05..d3b6ce6fd 100644 --- a/08-transport.md +++ b/08-transport.md @@ -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) @@ -501,19 +501,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. @@ -601,7 +601,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. @@ -746,7 +746,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 @@ -771,16 +771,16 @@ two key rotations: output 1000: 0x4a2f3cc3b5e78ddb83dcb426d9863d9d9a723b0337c89dd0b005d89f8d3c05c52b76b29b740f09 output 1001: 0x2ecd8c8a5629d0d02ab457a0fdd0f7b90a192cd46be5ecb6ca570bfc5e268338b1a16cf4ef2d36 -# Acknowledgments +## Acknowledgments TODO(roasbeef); fin -# References +## References 1. https://tools.ietf.org/html/rfc8439 2. http://noiseprotocol.org/noise.html 3. https://tools.ietf.org/html/rfc5869 -# Authors +## Authors FIXME diff --git a/11-payment-encoding.md b/11-payment-encoding.md index 1b43550b3..07897a301 100644 --- a/11-payment-encoding.md +++ b/11-payment-encoding.md @@ -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: ]