From 4e3ad54a9023d12d2ede0e2afe2e732536e6910f Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Tue, 7 Feb 2017 01:53:39 +0100 Subject: [PATCH] BOLT 2&7: Cleaner separation of concerns wrt announcement signatures (#97) * 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. (It also ended up adding a localfeatures flag to opt-into the channel-announcement, and thus creating BOLT 9) --- 00-introduction.md | 1 + 02-peer-protocol.md | 15 +-------------- 07-routing-gossip.md | 17 +++++++++++++++++ 09-features.md | 16 ++++++++++++++++ 4 files changed, 35 insertions(+), 14 deletions(-) create mode 100644 09-features.md diff --git a/00-introduction.md b/00-introduction.md index 5072f78..f1b2fa0 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/02-peer-protocol.md b/02-peer-protocol.md index ce98dcb..5713eca 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 @@ -289,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 @@ -443,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` (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 452a5f2..8ae3c89 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -13,6 +13,23 @@ 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] + +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 This message contains ownership information about a channel. It ties diff --git a/09-features.md b/09-features.md new file mode 100644 index 0000000..fb0f21d --- /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