From b475639f48123acec1b212801d8b6c28f05ad6f2 Mon Sep 17 00:00:00 2001 From: Landon Mutch Date: Fri, 10 Nov 2017 14:05:21 -0800 Subject: [PATCH] BOLT 0, 1, 2: copy edit add stylesheet item: prefer typed, not written numbers; updated BOLT 0, 1 to reflect change; copy edit BOLT 2 up to line 674; --- .copy-edit-stylesheet-checklist.md | 1 + 00-introduction.md | 4 +- 01-messaging.md | 16 +++--- 02-peer-protocol.md | 90 ++++++++++++++++-------------- 4 files changed, 58 insertions(+), 53 deletions(-) diff --git a/.copy-edit-stylesheet-checklist.md b/.copy-edit-stylesheet-checklist.md index 71cd384..6269377 100644 --- a/.copy-edit-stylesheet-checklist.md +++ b/.copy-edit-stylesheet-checklist.md @@ -18,6 +18,7 @@ Temporarily included here for reference purposes. - single spaces between sentences - consistent use of _emphasis_, **strong**, `code`, CAPS, 'quotes' - single line separators between paragraphs and page elements + - type numbers (e.g. '1', '1s') rather than write numbers (e.g. 'one', 'ones') - list structure - 2 spaces before item - indent 2 spaces diff --git a/00-introduction.md b/00-introduction.md index e403ce8..7879ad5 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -31,7 +31,7 @@ This is version 0. * *Channel*: - * A fast, off-chain method of mutual exchange between two *peers*. + * A fast, off-chain method of mutual exchange between 2 *peers*. To move funds, peers exchange signatures for an updated *commitment transaction*. @@ -43,7 +43,7 @@ This is version 0. * *HTLC*: Hashed Time Locked Contract. - * A conditional payment between two peers: the recipient can spend + * A conditional payment between 2 peers: the recipient can spend the payment by presenting its signature and a *payment preimage*, otherwise the payer can cancel the contract by spending it after a given time. These are implemented as outputs from the diff --git a/01-messaging.md b/01-messaging.md index bd20244..179f7de 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -85,7 +85,7 @@ Once authentication is complete, the first message reveals the features supporte [BOLT #9](09-features.md) specifies lists of global and local features. Each feature is generally represented in `globalfeatures` or `localfeatures` by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. -Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with zeros. +Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s. 1. type: 16 (`init`) 2. data: @@ -101,7 +101,7 @@ The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immedi The sending node: - MUST send `init` as the first Lightning message for any connection. - MUST set feature bits as defined in [BOLT #9](09-features.md). - - MUST set to zero any feature bits that are not defined. + - MUST set any undefined feature bits to 0. - SHOULD use the minimum lengths required to represent the feature fields. The receiving node: @@ -120,7 +120,7 @@ Nodes wait for receipt of the other's features to simplify error diagnosis, where features are incompatible. The feature masks are split into local features (which only affect the -protocol between these two nodes) and global features (which can affect +protocol between these 2 nodes) and global features (which can affect HTLCs) and are thus also advertised to other nodes. ### The `error` Message @@ -137,7 +137,7 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin #### Requirements -The channel is referred to by `channel_id`, unless `channel_id` is zero (i.e. all bytes are zero), in which case it refers to all channels. +The channel is referred to by `channel_id`, unless `channel_id` is 0 (i.e. all bytes are 0), in which case it refers to all channels. The funding node: - for all error messages sent before (and including) the `funding_created` message: @@ -154,7 +154,7 @@ A sending node: - MAY send an empty `data` field. - when failure was caused by an invalid signature check: - SHOULD include the raw, hex-encoded transaction in reply to a `funding_created`, `funding_signed`, `closing_signed`, or `commitment_signed` message. - - when `channel_id` is zero: + - when `channel_id` is 0: - MUST fail all channels, - and MUST close the connection. - MUST set `len` equal to the length of `data`. @@ -206,7 +206,7 @@ included within the data payload of the `pong` message. #### Requirements A node sending a `ping` message: - - SHOULD set `ignored` to zeros, + - SHOULD set `ignored` to 0s, - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. - if it doesn't receive a corresponding `pong`: @@ -215,12 +215,12 @@ memory. - SHOULD NOT send `ping` messages more often than once every 30 seconds. A node sending a `pong` message: - - SHOULD set `ignored` to zeros, + - SHOULD set `ignored` to 0s, - but MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. A node receiving a `ping` message: - - SHOULD fail the channels if it has received significantly in excess of one `ping` per 30 seconds. + - SHOULD fail the channels if it has received significantly in excess of 1 `ping` per 30 seconds. - if `num_pong_bytes` is less than 65532: - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. - otherwise (`num_pong_bytes` is **not** less than 65532): diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 04e3d19..dce5eb3 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1,6 +1,6 @@ # BOLT #2: Peer Protocol for Channel Management -The peer channel protocol has three phases: establishment, normal +The peer channel protocol has 3 phases: establishment, normal operation, and closing. # Table of Contents @@ -256,7 +256,7 @@ This message gives the funder the signature it needs for the first commitment transaction, so it can broadcast signature knowing funds can be redeemed, if need be. -This message introduces the `channel_id` to identify the channel. It's derived from the funding transaction by combining the `funding_txid` and the `funding_output_index`, using big-endian exclusive-OR (i.e. `funding_output_index` alters the last two bytes). +This message introduces the `channel_id` to identify the channel. It's derived from the funding transaction by combining the `funding_txid` and the `funding_output_index`, using big-endian exclusive-OR (i.e. `funding_output_index` alters the last 2 bytes). 1. type: 35 (`funding_signed`) 2. data: @@ -321,7 +321,7 @@ Nodes can negotiate a mutual close of the connection, which unlike a unilateral close, allows them to access their funds immediately and can be negotiated with lower fees. -Closing happens in two stages: 1) one side indicates it wants to clear the channel +Closing happens in 2 stages: 1) one side indicates it wants to clear the channel (and thus will accept no new HTLCs) 2) once all HTLCs are resolved, the final channel close negotiation begins. @@ -453,7 +453,7 @@ reason to pay a premium for rapid processing. Once both nodes have exchanged `funding_locked` (and optionally [`announcement_signatures`](https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hash TimeLocked Contracts. -Changes are sent in batches: one or more `update_` messages are sent before a +Changes are sent in batches: 1 or more `update_` messages are sent before a `commitment_signed` message, as in the following diagram: +-------+ +-------+ @@ -485,14 +485,14 @@ Thus each update traverses through the following states: 5. ... and the sender's previous commitment transaction has been revoked -As the two nodes' updates are independent, the two commitment +As the 2 nodes' updates are independent, the 2 commitment transactions may be out of sync indefinitely. This is not concerning: what matters is whether both sides have irrevocably committed to a particular HTLC or not (the final state, above). ### Forwarding HTLCs -In general, a node offers HTLCs for two reasons: to initiate a payment of its own, +In general, a node offers HTLCs for 2 reasons: to initiate a payment of its own, or to forward another node's payment. In the forwarding case, care must be taken to ensure the *outgoing* HTLC cannot be redeemed unless the *incoming* HTLC can be redeemed. The following requirements ensure this is always true: @@ -583,28 +583,28 @@ the longest possible time to redeem it on-chain: fulfills. B only sees transaction at `N+G+S+R`. 4. B now needs to fulfill the incoming A->B HTLC, but A is unresponsive: B waits `G` more blocks before giving up waiting for A. A or B commits to the blockchain. -5. Bad case: B sees A's commitment transaction in block `N+G+S+R+G+1`, and has +5. Bad case: B sees A's commitment transaction in block `N+G+S+R+G+1` and has to spend the HTLC output, which takes `S` blocks to be mined. -6. Worst case: There's another reorganization `R` deep which A uses to +6. Worst case: there's another reorganization `R` deep which A uses to spend the commitment transaction, so B sees A's commitment - transaction in block `N+G+S+R+G+R`, and has to spend the HTLC output, which + transaction in block `N+G+S+R+G+R` and has to spend the HTLC output, which takes `S` blocks to be mined. 7. B's HTLC spend needs to be at least `R` deep before it times out, otherwise another reorganization could allow A to timeout the transaction. -Thus the worst case is `3R+2G+2S` assuming `R` is at least 1. Note that the -chances of three reorganizations in which the other node wins all of them is +Thus, the worst case is `3R+2G+2S` assuming `R` is at least 1. Note that the +chances of 3 reorganizations in which the other node wins all of them is low for `R` of 2 or more. Since high fees are used (and HTLC spends can use -almost arbitrary fees), `S` should be small, though given that block times are +almost arbitrary fees), `S` should be small; although, given that block times are irregular and empty blocks still occur, `S = 2` should be considered a minimum. Similarly, the grace period `G` can be low (1 or 2), as nodes are -required to timeout or fulfill as soon as possible; but too low increases the +required to timeout or fulfill as soon as possible; but if `G` is too low it increases the risk of unnecessary channel closure due to networking delays. -There are four values that need be derived: +There are 4 values that need be derived: -1. The `cltv_expiry_delta` for channels. `3R+2G+2S`; if in doubt, a +1. The `cltv_expiry_delta` for channels, `3R+2G+2S`: if in doubt, a `cltv_expiry_delta` of 12 is reasonable (R=2, G=1, S=2). 2. For sent HTLCs: the timeout deadline after which the channel has to be failed @@ -624,24 +624,29 @@ the channel has to be failed and the HTLC fulfilled on-chain before its #### Requirements -A node MUST estimate a timeout deadline for each HTLC it offers. A node MUST -NOT offer an HTLC with a timeout deadline before its `cltv_expiry`, and MUST -fail the channel if an HTLC which it offered is in either node's current -commitment transaction past this timeout deadline. +An offering node: + - MUST estimate a timeout deadline for each HTLC it offers. + - MUST NOT offer an HTLC with a timeout deadline before its `cltv_expiry`. + - if an HTLC which it offered is in either node's current + commitment transaction is past this timeout deadline: + - MUST fail the channel. -A node MUST estimate a fulfillment deadline for each HTLC it is attempting to -fulfill. A node MUST fail (and not forward) an HTLC whose fulfillment -deadline is already past, and MUST fail the connection if a HTLC it has -fulfilled is in either node's current commitment transaction past this -fulfillment deadline. +A fulfilling node: + - for each HTLC it is attempting to fulfill: + - MUST estimate a fulfillment deadline. + - MUST fail (and not forward) an HTLC whose fulfillment +deadline is already past. + - if a HTLC it has fulfilled is in either node's current commitment transaction and is past this +fulfillment deadline: + - MUST fail the connection. ### Adding an HTLC: `update_add_htlc` Either node can send `update_add_htlc` to offer a HTLC to the other, which is redeemable in return for a payment preimage. Amounts are in millisatoshi, though on-chain enforcement is only possible for whole -satoshi amounts greater than the dust limit: in commitment transactions these are rounded down as -specified in [BOLT #3](03-transactions.md). +satoshi amounts greater than the dust limit (in commitment transactions these are rounded down as +specified in [BOLT #3](03-transactions.md)). The format of the `onion_routing_packet` portion, which indicates where the payment is destined, is described in [BOLT #4](04-onion-routing.md). @@ -657,16 +662,15 @@ is destined, is described in [BOLT #4](04-onion-routing.md). #### Requirements -A sending node MUST NOT offer `amount_msat` it cannot pay for in the +A sending node: + - MUST NOT offer `amount_msat` it cannot pay for in the remote commitment transaction at the current `feerate_per_kw` (see "Updating -Fees") while maintaining its channel reserve, MUST offer -`amount_msat` greater than 0, MUST NOT offer `amount_msat` below -the receiving node's `htlc_minimum_msat`, and MUST set `cltv_expiry` less -than 500000000. - -For channels with `chain_hash` identifying the Bitcoin blockchain, the -sending node MUST set the 4 most significant bytes of `amount_msat` to -zero. +Fees") while maintaining its channel reserve. + - MUST offer `amount_msat` greater than 0. + - MUST NOT offer `amount_msat` below the receiving node's `htlc_minimum_msat` + - MUST set `cltv_expiry` less than 500000000. + - for channels with `chain_hash` identifying the Bitcoin blockchain: + - MUST set the 4 most significant bytes of `amount_msat` to 0. A sending node MUST NOT add an HTLC if it would result in it offering more than the remote's `max_accepted_htlcs` HTLCs in the remote commitment @@ -677,7 +681,7 @@ A sending node MUST set `id` to 0 for the first HTLC it offers, and increase the value by 1 for each successive offer. A receiving node SHOULD fail the channel if it receives an -`amount_msat` equal to zero, below its own `htlc_minimum_msat`, or +`amount_msat` equal to 0, below its own `htlc_minimum_msat`, or which the sending node cannot afford at the current `feerate_per_kw` while maintaining its channel reserve. A receiving node SHOULD fail the channel if a sending node adds more than its `max_accepted_htlcs` HTLCs to @@ -686,7 +690,7 @@ sets `cltv_expiry` to greater or equal to 500000000. For channels with `chain_hash` identifying the Bitcoin blockchain, the receiving node MUST fail the channel if the 4 most significant bytes -of `amount_msat` are not zero. +of `amount_msat` are not 0. A receiving node MUST allow multiple HTLCs with the same payment hash. @@ -729,7 +733,7 @@ bootstrap phase of the network. ### 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 three reasons for removing an HTLC: it has timed out, it has +There are 3 reasons for removing an HTLC: it has timed out, it has failed to route, or the payment preimage is supplied. The `reason` field is an opaque encrypted blob for the benefit of the @@ -830,7 +834,7 @@ updates. Note that a node MAY send a `commitment_signed` message which only alters the fee, and MAY send a `commitment_signed` message which doesn't change the commitment transaction other than the new revocation hash (due to dust, identical HTLC replacement, or insignificant or multiple -fee changes). A node MUST include one `htlc_signature` for every HTLC +fee changes). A node MUST include 1 `htlc_signature` for every HTLC transaction corresponding to BIP69 lexicographic ordering of the commitment transaction. @@ -1004,20 +1008,20 @@ next `revoke_and_ack` message it expects to receive. If `next_local_commitment_number` is 1 in both the `channel_reestablish` it sent and received, then the node MUST retransmit `funding_locked`, otherwise it MUST NOT. On reconnection, a node MUST ignore a redundant `funding_locked` -if it receives one. +if it receives 1. If `next_local_commitment_number` is equal to the commitment number of the last `commitment_signed` message the receiving node has sent, it MUST reuse the same commitment number for its next `commitment_signed`, -otherwise if `next_local_commitment_number` is not one greater than the commitment number of the +otherwise if `next_local_commitment_number` is not 1 greater than the commitment number of the last `commitment_signed` message the receiving node has sent, it SHOULD fail the channel. If `next_remote_revocation_number` is equal to the commitment number of the last `revoke_and_ack` the receiving node has sent and the receiving node has not already received a `closing_signed`, it MUST re-send the `revoke_and_ack`, otherwise if `next_remote_revocation_number` is not -equal to one greater than the commitment number of the last `revoke_and_ack` the -receiving node has sent (or equal to zero if none have been sent), it SHOULD fail the channel. +equal to 1 greater than the commitment number of the last `revoke_and_ack` the +receiving node has sent (or equal to 0 if none have been sent), it SHOULD fail the channel. A node MUST not assume that previously-transmitted messages were lost: in particular, if it has sent a previous `commitment_signed` message,