mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2024-11-19 10:00:04 +01:00
Code Issues Projects Releases Wiki Activity

Use "Bitcoin" with capital "B" where it is appropriate

Browse Source 
pseudo random -> pseudo-random
onchain -> on-chain
This commit is contained in:
Christopher Jämthagen 2016-12-08 07:54:35 +01:00 committed by Pierre-Marie Padiou
parent 6e4f7f0cc2
commit d076039df2
5 changed files with 18 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
01-messaging.md
View File

@ -45,7 +45,7 @@ A node MUST fail the channels if it receives a known message with insufficient l
### Rationale ### 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 are big endian, thus it would be unusual to use a different endian for
other fields. other fields.

8
02-peer-protocol.md
View File

@ -94,7 +94,7 @@ desire to set up a new channel.
* [33:first-per-commitment-point] * [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. `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 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 network. It SHOULD set `htlc-minimum-msat` to the minimum
amount HTLC it is willing to accept from this peer. 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. HTLCs will be added or accepted.
The `scriptpubkey` forms include only standard forms accepted by the 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. 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. 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 The sender SHOULD set the initial `fee-satoshis` according to its
estimate of cost of inclusion in a block. 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 transaction with the node responsible for paying the bitcoin fee
paying `fee-satoshis`, without populating any output which is below paying `fee-satoshis`, without populating any output which is below
the receiver's `dust-limit-satoshis`. the receiver's `dust-limit-satoshis`.

20
04-onion-routing.md
View File

@ -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: 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. 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. - _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. 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 ## 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 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 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. The use of a fixed nonce is safe since the keys are never reused.
## Packet Structure ## 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 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 address is copied into the first 20 bytes of the routing info and the HMAC is copied into
the following 20 bytes. 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`. 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 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 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. 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 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. - 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. 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. 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 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 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 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. 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. 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. 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. 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`. 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 This deobfuscates the information destined for it, and simultaneously obfuscates the added
`0x00`-bytes at the end. `0x00`-bytes at the end.
@ -351,7 +351,7 @@ func generateFiller(key string, numHops int, hopSize int, sharedSecrets [][share
// Zero-fill the last hop // Zero-fill the last hop
copy(filler[len(filler)-hopSize:], bytes.Repeat([]byte{0x00}, hopSize)) 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]) streamKey := generateKey(key, sharedSecrets[i])
streamBytes := generateCipherStream(streamKey, fillerSize) streamBytes := generateCipherStream(streamKey, fillerSize)

2
05-onchain.md
View File

@ -28,7 +28,7 @@ the output is considered to be its own *resolving* transaction.
Outputs which are *resolved* are considered *irrevocably resolved* Outputs which are *resolved* are considered *irrevocably resolved*
once their *resolving* transaction is included in a block at least 100 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 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]. confirmations of miner's rewards[FIXME: ref].

4
07-routing-gossip.md
View File

@ -16,7 +16,7 @@ information), and at least two `channel_update` messages are expected.
## The `channel_announcement` message ## The `channel_announcement` message
This message contains ownership information about a channel. It ties each 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 The channel is not really usable until at least one side has announced
its fee levels and expiry using `channel_update`. 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 Requiring both nodes to sign indicates they are both willing to route
other payments via this node (ie. take part of the public network). 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 The blacklisting of conflicting nodes means that we disallow multiple
different announcements: no node should ever do this, as it implies different announcements: no node should ever do this, as it implies