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

BOLT 07: first pass copy edit to line 210

Browse Source
This commit is contained in:
toadlybroodle 2018-01-03 16:23:30 -08:00 committed by Rusty Russell
parent dee91424fa
commit 2252449c45
1 changed files with 79 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
07-routing-gossip.md
View File

@ -118,84 +118,93 @@ announcement message: this is accomplished by having a signature from each
### Requirements ### Requirements
The creating node MUST set `chain_hash` to the 32-byte hash that uniquely The creating node:
identifies the chain that the channel was opened within. For the Bitcoin - MUST set `chain_hash` to the 32-byte hash that uniquely identifies the chain
blockchain, the `chain_hash` value MUST be (encoded in hex): that the channel was opened within:
`000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`. - MUST set the _Bitcoin blockchain_ `chain_hash` value (encoded in hex) to: `000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f`.
- MUST set `short_channel_id` to refer to the confirmed funding transaction,
as specified in [BOLT #2](02-peer-protocol.md#the-funding_locked-message).
- Note: the corresponding output MUST be a P2WSH, as described in [BOLT #3](03-transactions.md#funding-transaction-output).
- MUST set `node_id_1` and `node_id_2` to the public keys of the two nodes
operating the channel, such that `node_id_1` is the numerically-lesser of the
two DER-encoded keys sorted in ascending numerical order.
- MUST set `bitcoin_key_1` and `bitcoin_key_2` to `node_id_1` and `node_id_2`'s
respective `funding_pubkey`s.
- MUST compute the double-SHA256 hash `h` of the message, beginning at offset
256, up to the end of the message.
- Note: the hash skips the 4 signatures but hashes the rest of the message,
including any future fields appended to the end.
- MUST verify that `node_signature_1` and `node_signature_2` are valid
signatures of the hash `h`, using `node_id_1` and `node_id_2`'s respective
secrets.
- MUST verify that `bitcoin_signature_1` and `bitcoin_signature_2` are valid
signatures of the hash `h`, using `bitcoin_key_1` and `bitcoin_key_2`'s
respective secrets.
- SHOULD set `len` to the minimum length required to hold the `features` bits
it sets.
The creating node MUST set `short_channel_id` to refer to the confirmed The receiving node:
funding transaction as specified in [BOLT #2](02-peer-protocol.md#the-funding_locked-message). The corresponding output MUST be a - MUST verify the integrity and authenticity of the message by verifying the
P2WSH as described in [BOLT #3](03-transactions.md#funding-transaction-output). signatures.
- if there is an unknown even bit in the `features` field:
The creating node MUST set `node_id_1` and `node_id_2` to the public - MUST NOT parse the remainder of the message.
keys of the two nodes who are operating the channel, such that - MUST NOT add the channel to its local network view.
`node_id_1` is the numerically-lesser of the two DER-encoded keys sorted in - SHOULD NOT forward the announcement.
ascending numerical order, and MUST set `bitcoin_key_1` and - if the `short_channel_id`'s output does NOT correspond to a P2WSH (using
`bitcoin_key_2` to `funding_pubkey`s of `node_id_1` and `node_id_2` `bitcoin_key_1` and `bitcoin_key_2`, as specified in
respectively. [BOLT #3](03-transactions.md#funding-transaction-output)) OR the output is
spent:
The creating node MUST compute the double-SHA256 hash `h` of the message, starting at offset 256, up to the end of the message. - MUST ignore the message.
Thus the hash skips the 4 signatures, but hashes the rest of the message, including any future fields appended to the end. - if the specified `chain_hash` is unknown to the receiver:
`node_signature_1` and `node_signature_2` MUST be valid signatures of the hash `h` using the secret associated with `node_id_1` and `node_id_2` respectively. - MUST ignore the message.
`bitcoin_signature_1` and `bitcoin_signature_2` MUST be valid signatures of the hash `h` using the secret associated with `bitcoin_key_1` and `bitcoin_key_2` respectively. - otherwise:
- if `bitcoin_signature_1`, `bitcoin_signature_2`, `node_signature_1` OR
The creating node SHOULD set `len` to the minimum length required to `node_signature_2` are invalid OR NOT correct:
hold the `features` bits it sets. - SHOULD fail the connection.
- otherwise:
The receiving node MUST verify the integrity and authenticity of the message by verifying the signatures. - if `node_id_1` or `node_id_2` are blacklisted:
If there is an unknown even bit in the `features` field the receiving node MUST NOT parse the remainder of the message and MUST NOT add the channel to its local network view, and SHOULD NOT forward the announcement. - SHOULD ignore the message.
- otherwise:
The receiving node MUST ignore the message if the output specified - if the transaction referred to was NOT previously announced as a
by `short_channel_id` does not channel:
correspond to a P2WSH using `bitcoin_key_1` and `bitcoin_key_2` as - SHOULD queue the message for rebroadcasting.
specified in [BOLT #3](03-transactions.md#funding-transaction-output). - MAY choose NOT to for messages longer than the minimum expected
The receiving node MUST ignore the message if this output is spent. length.
- if it has previously received a valid `channel_announcement`, for the
The receiving node MUST ignore the message if the specified `chain_hash` same transaction, in the same block, but for a different `node_id_1` or
is unknown to the receiver. `node_id_2`:
- SHOULD blacklist the previous message's `node_id_1` and `node_id_2`,
Otherwise, the receiving node SHOULD fail the connection if as well as this `node_id_1` and `node_id_2` AND forget any channels
`bitcoin_signature_1`, `bitcoin_signature_2`, `node_signature_1` or connected to them.
`node_signature_2` are invalid or not correct. - otherwise:
- SHOULD store this `channel_announcement`.
Otherwise, if `node_id_1` or `node_id_2` are blacklisted, it SHOULD - once its funding output has been spent or reorganized out:
ignore the message. - SHOULD forget a channel.
Otherwise, if the transaction referred to was not previously announced
as a channel, the receiving node SHOULD queue the message for
rebroadcasting, but MAY choose not to for messages longer than
the minimum expected length. If it has previously received a valid
`channel_announcement` for the same transaction in the same block, but
for a different `node_id_1` or `node_id_2`, it SHOULD blacklist the
previous message's `node_id_1` and `node_id_2` as well as this
`node_id_1` and `node_id_2` and forget channels connected to them,
otherwise it SHOULD store this `channel_announcement`.
The receiving node SHOULD forget a channel once its funding output has
been spent or reorganized out.
### Rationale ### Rationale
Requiring both nodes to sign indicates they are both willing to route Both nodes are required to sign to indicate they are willing to route other
other payments via this channel (i.e. be part of the public network). payments via this channel (i.e. be part of the public network); requiring their
Requiring the Bitcoin signatures proves that they control the channel. Bitcoin signatures proves that they control the channel.
The blacklisting of conflicting nodes disallows multiple The blacklisting of conflicting nodes disallows multiple different
different announcements: no node should ever do this, as it implies announcements. Such conflicting announcements should never be broadcast by any
that keys have leaked. node, as this implies that keys have leaked.
While channels shouldn't be advertised before they are sufficiently While channels should not be advertised before they are sufficiently deep, the
deep, the requirement against rebroadcasting only applies if the requirement against rebroadcasting only applies if the transaction has not moved
transaction hasn't moved to a different block. to a different block.
To avoid having to store excessive-sized messages, yet allow In order to avoid storing excessively-large messages, yet still allow for
reasonable expansion in future, nodes are allowed to restrict reasonable future expansion, nodes are permitted to restrict rebroadcasting
rebroadcasting (perhaps statistically). (perhaps statistically).
New channel features are possible in future; backwards compatible (or New channel features are possible in the future: backwards compatible (or
optional) ones will have odd feature bits, incompatible ones will have optional) features will have _odd_ feature bits, while incompatible features
even feature bits (["It's OK to be odd!"](00-introduction.md#glossary-and-terminology-guide)). will have _even_ feature bits
Incompatible features will result in the announcement not being forwarded by nodes that don't understand them. (["It's OK to be odd!"](00-introduction.md#glossary-and-terminology-guide)).
Incompatible features will result in the announcement not being forwarded by
nodes that do not understand them.
## The `node_announcement` Message ## The `node_announcement` Message