diff --git a/01-messaging.md b/01-messaging.md index 98f765f..500471c 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -45,7 +45,7 @@ A node MUST fail the channels if it receives a known message with insufficient l ### Rationale -The standard endian of `SHA2` and the encoding of bitcoin public keys +The standard endian of `SHA2` and the encoding of Bitcoin public keys are big endian, thus it would be unusual to use a different endian for other fields. diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 837a7f9..7444cb7 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -94,7 +94,7 @@ desire to set up a new channel. * [33:first-per-commitment-point] -The `temporary-channel-id` is used to identify this channel until the funding transaction is established. `funding-satoshis` is the amount the sender is putting into the channel. `dust-limit-satoshis` is the threshold below which output should be generated for this node’s commitment or HTLC transaction; ie. HTLCs below this amount plus HTLC transaction fees are not enforceable onchain. This reflects the reality that tiny outputs are not considered standard transactions and will not propagate through the bitcoin network. +The `temporary-channel-id` is used to identify this channel until the funding transaction is established. `funding-satoshis` is the amount the sender is putting into the channel. `dust-limit-satoshis` is the threshold below which output should be generated for this node’s commitment or HTLC transaction; ie. HTLCs below this amount plus HTLC transaction fees are not enforceable on-chain. This reflects the reality that tiny outputs are not considered standard transactions and will not propagate through the Bitcoin network. `max-htlc-value-in-inflight-msat` is a cap on total value of outstanding HTLCs, which allows a node to limit its exposure to HTLCs; similarly `max-accepted-htlcs` limits the number of outstanding HTLCs the other node can offer. `channel-reserve-satoshis` is the minimum amount that the other node is to keep as a direct payment. `htlc-minimum-msat` indicates the smallest value HTLC this node will accept. @@ -123,7 +123,7 @@ immediately included in a block. The sender SHOULD set `dust-limit-satoshis` to a sufficient value to -allow commitment transactions to propagate through the bitcoin +allow commitment transactions to propagate through the Bitcoin network. It SHOULD set `htlc-minimum-msat` to the minimum amount HTLC it is willing to accept from this peer. @@ -355,7 +355,7 @@ As shutdown implies a desire to terminate, it implies that no new HTLCs will be added or accepted. The `scriptpubkey` forms include only standard forms accepted by the -bitcoin network, ensuring that the resulting transaction will +Bitcoin network, ensuring that the resulting transaction will propagate to miners. The `shutdown` response requirement implies that the node sends `update_commit` to commit any outstanding changes before replying, but it could theoretically reconnect instead, which simply erases all outstanding uncommitted changes. @@ -387,7 +387,7 @@ fee of the final commitment transaction. The sender SHOULD set the initial `fee-satoshis` according to its estimate of cost of inclusion in a block. -The sender MUST set `signature` to the bitcoin signature of the close +The sender MUST set `signature` to the Bitcoin signature of the close transaction with the node responsible for paying the bitcoin fee paying `fee-satoshis`, without populating any output which is below the receiver's `dust-limit-satoshis`. diff --git a/04-onion-routing.md b/04-onion-routing.md index 05dc740..b9e9292 100644 --- a/04-onion-routing.md +++ b/04-onion-routing.md @@ -56,9 +56,9 @@ There are a number of conventions we will adhere to throughout the document: A number of encryption and verification keys are derived from the shared secret: - - _rho_: used as key when generating the pseudo random byte stream + - _rho_: used as key when generating the pseudo-random byte stream used to obfuscate the routing information. - - _gamma_: used as key when generating the pseudo random byte stream used to obfuscate the per-hop payloads. + - _gamma_: used as key when generating the pseudo-random byte stream used to obfuscate the per-hop payloads. - _mu_: used during the HMAC generation. The key generation takes a key-type (_rho_=`0x72686F`, _gamma_=`0x67616d6d61` or _mu_=`0x6d75`) and a 32 byte secret as inputs and returns a 32 byte key. @@ -70,8 +70,8 @@ Notice that the key-type does not include a C-style `0x00` termination-byte, e.g ## 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 of the next hop as well as the HMAC for the next hop. -The pseudo random byte stream is generated by encrypting a `0x00`-byte stream of the required length with `ChaCha20`, initialized with a key derived from the shared secret and a zero-nonce (`0x00000000000000`). +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 of the next hop as well as the HMAC for the next hop. +The pseudo-random byte stream is generated by encrypting a `0x00`-byte stream of the required length with `ChaCha20`, initialized with a key derived from the shared secret and a zero-nonce (`0x00000000000000`). The use of a fixed nonce is safe since the keys are never reused. ## Packet Structure @@ -174,11 +174,11 @@ following operations: - The routing info field is right-shifted by 40 bytes, discarding the last 40 bytes that exceed the 800 bytes. The address is copied into the first 20 bytes of the routing info and the HMAC is copied into the following 20 bytes. - The _rho_-key is used to generate 800 bytes of pseudo random byte stream and applied with `XOR` to the routing info field. + The _rho_-key is used to generate 800 bytes of pseudo-random byte stream and applied with `XOR` to the routing info field. Should this be the last hop, i.e., the first iteration, then the tail of the routing info field is overwritten with the routing info `filler`. - The per-hop payload field is right-shifted by 20 bytes, and the last 20 bytes discarded, resulting in 400 bytes of per-hop payload. The current hop's per-hop payload is copied into the first 20 bytes. - The _gamma_-key is used to generate 400 bytes of pseudo random byte stream which are then applied using `XOR` to the per-hop payloads field. + The _gamma_-key is used to generate 400 bytes of pseudo-random byte stream which are then applied using `XOR` to the per-hop payloads field. Should this be the last hop then the tail of the per-hop payloads field is overwritten with the per-hop payload filler. - The next HMAC is computed over the concatenated routing info, per-hop payload and associated data, with the _mu_-key as HMAC-key. - The next address is computed from the current node's public key using the Bitcoin address hash derivation. @@ -283,13 +283,13 @@ Comparison of the computed HMAC and the HMAC from the packet MUST be time-consta At this point the node can generate a _rho_-key and a _gamma_-key. The routing info is deobfuscated and the information about the next hop is extracted. -In order to do so the node copies the routing info field, appends 40 `0x00` bytes and generates 840 pseudo random bytes using the _rho_-key and applies it using `XOR` to the copy of the routing information. +In order to do so the node copies the routing info field, appends 40 `0x00` bytes and generates 840 pseudo-random bytes using the _rho_-key and applies it using `XOR` to the copy of the routing information. The first 20 bytes of the resulting routing info are the address of the next hop, followed by the 20 byte HMAC. The routing info for the outgoing packet, destined for the next hop, consists of the 800 bytes starting at byte 40. The per-hop payload is deobfuscated in a similar way. The node creates a copy of the per-hop payloads field and appends 20 `0x00` bytes of padding. -It generates 420 bytes of pseudo random bytes using the _gamma_-key and applies it using `XOR` to the padded copy of the per-hop payloads. +It generates 420 bytes of pseudo-random bytes using the _gamma_-key and applies it using `XOR` to the padded copy of the per-hop payloads. The first 20 bytes of the padded copy are the node's per-hop payload, while the remaining 400 bytes are the per-hop payload destined for the next hop. A special HMAC value of 20 `0x00` bytes indicates that the currently processing hop is the intended recipient and that the packet should not be forwarded. @@ -327,7 +327,7 @@ We call the number of bytes extracted from the field _hopsize_. In case of the route info the hopsize is 40 bytes (20 bytes address and 20 bytes HMAC), while in the case of the per-hop payload it is 20 bytes. Before deobfuscating the field, the node pads the field with hopsize `0x00` bytes, such that the total length of the field is `(20 + 1) * hopsize`. -It then generates the pseudo random byte stream of matching length and applies it with `XOR` to the field. +It then generates the pseudo-random byte stream of matching length and applies it with `XOR` to the field. This deobfuscates the information destined for it, and simultaneously obfuscates the added `0x00`-bytes at the end. @@ -351,7 +351,7 @@ func generateFiller(key string, numHops int, hopSize int, sharedSecrets [][share // Zero-fill the last hop copy(filler[len(filler)-hopSize:], bytes.Repeat([]byte{0x00}, hopSize)) - // Generate pseudo random byte stream + // Generate pseudo-random byte stream streamKey := generateKey(key, sharedSecrets[i]) streamBytes := generateCipherStream(streamKey, fillerSize) diff --git a/05-onchain.md b/05-onchain.md index ec47e5f..be57058 100644 --- a/05-onchain.md +++ b/05-onchain.md @@ -28,7 +28,7 @@ the output is considered to be its own *resolving* transaction. Outputs which are *resolved* are considered *irrevocably resolved* once their *resolving* transaction is included in a block at least 100 deep on the most-work blockchain. 100 blocks is far greater than the -longest known bitcoin fork, and the same value used to wait for +longest known Bitcoin fork, and the same value used to wait for confirmations of miner's rewards[FIXME: ref]. diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 784b123..f1173b7 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -16,7 +16,7 @@ information), and at least two `channel_update` messages are expected. ## The `channel_announcement` message This message contains ownership information about a channel. It ties each -on-chain bitcoin key to the lightning node key, and vice-versa. +on-chain Bitcoin key to the lightning node key, and vice-versa. The channel is not really usable until at least one side has announced its fee levels and expiry using `channel_update`. @@ -84,7 +84,7 @@ been spent or reorganized out. Requiring both nodes to sign indicates they are both willing to route other payments via this node (ie. take part of the public network). -Requiring the bitcoin signatures proves they control the channel. +Requiring the Bitcoin signatures proves they control the channel. The blacklisting of conflicting nodes means that we disallow multiple different announcements: no node should ever do this, as it implies