From 03900f805168aeee44ee8d79ccc150a988642239 Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Tue, 31 Jan 2017 14:52:12 +0100 Subject: [PATCH 1/5] BOLT 2&7: Cleaner separation of concerns wrt announcement signatures So far we did not have any indication on what to do if a node does not allow announcing the channel and we had a mix of concerns in the `funding_locked` message, which would also transfer the signatures needed for the announcement. This is a proposal about splitting the signatures into their own message, so that simple omission is an opt-out of announcements, and it does not mix announcement/gossip stuff into the peer-protocol. --- 02-peer-protocol.md | 4 ---- 07-routing-gossip.md | 13 +++++++++++++ 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 445821479..1dbe6e22f 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -248,8 +248,6 @@ This message indicates that the funding transaction has reached the `minimum-dep 2. data: * [8:temporary-channel-id] * [8:channel-id] - * [64:announcement-node-signature] - * [64:announcement-bitcoin-signature] * [33:next-per-commitment-point] The `channel-id` is the unique description of the funding transaction. @@ -261,8 +259,6 @@ index which pays to the channel. This `channel-id` is used in all messages referring to the channel from this point onwards. -`announcement-node-signature` and `announcement-bitcoin-signature` are the optional signature for `channel_announcement` as described in [BOLT #7](07-routing-gossip.md#the-channel_announcement-message). - #### Requirements The sender MUST wait until the funding transaction has reached diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 12fa41008..2d5331dce 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -13,6 +13,19 @@ There can only be one valid `channel_announcement` for any channel, but multiple `node_announcement` messages are possible (to update node information), and at least two `channel_update` messages are expected. +## The `announcement_signatures` message +This is a direct message between two endpoints of a channel and serves as an opt-in mechanism to allow the announcement of the channel to the rest of the network. +It contains the necessary signatures by the sender to construct the `channel_announcement` message. + +1. type: 259 (`announcement_signatures`) +2. data: + * [8:channel-id] + * [64:node-signature] + * [64:bitcoin-signature] + +Assuming both endpoints agree to announce the channel, then they SHOULD create a `channel_announcement` message, and sign it with the secrets matching their `node-id` and `bitcoin-key`, and send them using an `announcement_signatures`. +Should one or both endpoints not want to announce the channel to the rest of the network, then they MUST NOT send an `announcement_signatures` message, and ignore any incoming `announcement_signatures` messages. + ## The `channel_announcement` message This message contains ownership information about a channel. It ties From 96d017d99a5b61e993306f36947c078767ac6420 Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Wed, 1 Feb 2017 12:21:26 +0100 Subject: [PATCH 2/5] BOLT 02 & 07: Moving missed pieces --- 02-peer-protocol.md | 11 +---------- 07-routing-gossip.md | 5 +++++ 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 1dbe6e22f..ef6240ab9 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -285,14 +285,6 @@ re-transmit `funding_locked` if the `channel-id` changes. If the recipient has received previous `funding_locked` message, it MUST ignore it in favor of the new `funding_locked`. -The sender MUST set `announcement-node-signature` and `announcement-bitcoin-signature` to the signatures for the -`channel_announcement` message, or all zeroes if it does not want the -channel announced. - -The recipient SHOULD fail the channel if the `announcement-node-signature` and `announcement-bitcoin-signature`s are incorrect (and not all zeroes). -The recipient SHOULD queue the `channel_announcement` message for its -peers if it has sent and received a non-zero `announcement-node-signature` and `announcement-bitcoin-signature`. - #### Rationale If the `minimum-depth` is very low (such as 1), it's possible that @@ -439,8 +431,7 @@ reason to pay a premium for rapid processing. ## Normal Operation -Once both nodes have exchanged `funding_locked`, the channel can be -used to make payments via Hash TimeLocked Contracts. +Once both nodes have exchanged `funding_locked`, 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 `commit_sig` message, as in the following diagram: diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 2d5331dce..a173f5818 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -23,9 +23,14 @@ It contains the necessary signatures by the sender to construct the `channel_ann * [64:node-signature] * [64:bitcoin-signature] +An `announcement_signatures` message MUST NOT be sent before the channel is fully established, i.e., before both ends have received the corresponding `channel_locked` messages. + Assuming both endpoints agree to announce the channel, then they SHOULD create a `channel_announcement` message, and sign it with the secrets matching their `node-id` and `bitcoin-key`, and send them using an `announcement_signatures`. Should one or both endpoints not want to announce the channel to the rest of the network, then they MUST NOT send an `announcement_signatures` message, and ignore any incoming `announcement_signatures` messages. +The recipient MAY fail the channel if the `node-signature` or `bitcoin-signature` is incorrect. +The recipient SHOULD queue the `channel_announcement` message for its peers if it has sent and received a valid `announcement_signatures` message. + ## The `channel_announcement` message This message contains ownership information about a channel. It ties From 92e066a61ef07d18b43986de4d280e0c8f64a5a6 Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Sat, 4 Feb 2017 15:29:26 +0100 Subject: [PATCH 3/5] fixup! BOLT 02 & 07: Moving missed pieces --- 07-routing-gossip.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/07-routing-gossip.md b/07-routing-gossip.md index a173f5818..7a7507d2b 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -23,7 +23,7 @@ It contains the necessary signatures by the sender to construct the `channel_ann * [64:node-signature] * [64:bitcoin-signature] -An `announcement_signatures` message MUST NOT be sent before the channel is fully established, i.e., before both ends have received the corresponding `channel_locked` messages. +An `announcement_signatures` message MUST NOT be sent before the channel is fully established, i.e., before both ends have received the corresponding `funding_locked` messages. Assuming both endpoints agree to announce the channel, then they SHOULD create a `channel_announcement` message, and sign it with the secrets matching their `node-id` and `bitcoin-key`, and send them using an `announcement_signatures`. Should one or both endpoints not want to announce the channel to the rest of the network, then they MUST NOT send an `announcement_signatures` message, and ignore any incoming `announcement_signatures` messages. From 1bdaa38da8c70f47ec5cda2762bc6fbda978896d Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Mon, 6 Feb 2017 14:34:22 +0100 Subject: [PATCH 4/5] gossip: Added localfeatures flag to opt-into the channel-announcement --- 02-peer-protocol.md | 2 +- 07-routing-gossip.md | 9 ++++----- 09-features.md | 16 ++++++++++++++++ 3 files changed, 21 insertions(+), 6 deletions(-) create mode 100644 09-features.md diff --git a/02-peer-protocol.md b/02-peer-protocol.md index ef6240ab9..31a579e3c 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -431,7 +431,7 @@ reason to pay a premium for rapid processing. ## Normal Operation -Once both nodes have exchanged `funding_locked`, the channel can be used to make payments via Hash TimeLocked Contracts. +Once both nodes have exchanged `funding_locked` (and optionally `announcement_signatures`), 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 `commit_sig` message, as in the following diagram: diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 7a7507d2b..04abe592b 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -23,13 +23,12 @@ It contains the necessary signatures by the sender to construct the `channel_ann * [64:node-signature] * [64:bitcoin-signature] -An `announcement_signatures` message MUST NOT be sent before the channel is fully established, i.e., before both ends have received the corresponding `funding_locked` messages. - -Assuming both endpoints agree to announce the channel, then they SHOULD create a `channel_announcement` message, and sign it with the secrets matching their `node-id` and `bitcoin-key`, and send them using an `announcement_signatures`. -Should one or both endpoints not want to announce the channel to the rest of the network, then they MUST NOT send an `announcement_signatures` message, and ignore any incoming `announcement_signatures` messages. - +The willingness of the endpoints to announce the channel is signaled during the connection setup by setting the first bit (`0x01`) in the `localfeatures` field. +Should both endpoints have signaled that they'd like to publish the channel (`localfeatures & 0x01 == 0x01`) then the `announcement_signatures` message MUST directly sent following the `funding_locked` message that established the corresponding channel. +The `announcement_signatures` message is created by constructing a `channel_announcement` message corresponding to the newly established channel, and sign it with the secrets matching their `node-id` and `bitcoin-key`, and send them using an `announcement_signatures`. The recipient MAY fail the channel if the `node-signature` or `bitcoin-signature` is incorrect. The recipient SHOULD queue the `channel_announcement` message for its peers if it has sent and received a valid `announcement_signatures` message. +If either endpoints does not signal (`localfeatures & 0x01 == 0x00`) then `announcement_signatures` MUST NOT be sent. ## The `channel_announcement` message diff --git a/09-features.md b/09-features.md new file mode 100644 index 000000000..0bf57c8ea --- /dev/null +++ b/09-features.md @@ -0,0 +1,16 @@ +# BOLT #9: Assigned feature flags + +This document tracks the assignment of `localfeatures` and `globalfeatures` flags in the `init` message ([BOLT #1](01-messaging.md)), as well as the `features` field in the `channel_announcement` message and `node_announcement` message ([BOLT #7](07-routing-gossip.md)). +They are tracked separately since new flags will likely be added over time. + +The `features` flags in the routing messages are a subset of the `globalfeatures` flags, since the `localfeatures` are by definition only of interest to direct peers. + +## Assigned `localfeatures` flags + +This flags may only be used in the `init` message. + +| Bits | Description | Link | +|------|-------------------------------------------------|---------------------------------------------------------------------| +| 1 | The sending node wishes to announce the channel | [BOLT #7](07-routing-gossip.md#the-announcement_signatures-message) | + +## Assigned `globalfeatures` flags From 33ef026199367fdc39fa95835f170bb628e6aeda Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Tue, 7 Feb 2017 11:20:33 +1030 Subject: [PATCH 5/5] FIX! Add to index, capitalize heading to match other BOLTs. --- 00-introduction.md | 1 + 09-features.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/00-introduction.md b/00-introduction.md index 5072f78ec..f1b2fa0a2 100644 --- a/00-introduction.md +++ b/00-introduction.md @@ -20,6 +20,7 @@ This is version 0. 6. [BOLT #6](06-irc-announcements.md): Interim Node and Channel Discovery 7. [BOLT #7](07-routing-gossip.md): P2P Node and Channel Discovery 8. [BOLT #8](08-transport.md): Encrypted and Authenticated Transport +9. [BOLT #9](09-features.md): Assigned Feature Flags ## Glossary and Terminology Guide diff --git a/09-features.md b/09-features.md index 0bf57c8ea..fb0f21d7b 100644 --- a/09-features.md +++ b/09-features.md @@ -1,4 +1,4 @@ -# BOLT #9: Assigned feature flags +# BOLT #9: Assigned Feature Flags This document tracks the assignment of `localfeatures` and `globalfeatures` flags in the `init` message ([BOLT #1](01-messaging.md)), as well as the `features` field in the `channel_announcement` message and `node_announcement` message ([BOLT #7](07-routing-gossip.md)). They are tracked separately since new flags will likely be added over time.