BOLT 7: gossip_status (feature 66/67)

07-routing-gossip.md

@@ -898,6 +898,51 @@ generated directly by the node itself, so they should ignore filters.
 A node:
   - MUST NOT relay any gossip messages it did not generate itself, unless explicitly requested.
 
+### The `gossip_status` Message
+
+`gossip_status` is a simple option to detect if nodes are
+significantly out of sync with each other.
+
+1. type: 267 (`gossip_status`)
+2. data:
+    * [`chain_hash`:`chain_hash`]
+    * [`bigsize`:`num_channel_announcements`]
+    * [`bigsize`:`num_channel_updates`]
+    * [`bigsize`:`num_node_announcements`]
+
+#### Requirements
+
+- A sending node:
+  - MUST not send `gossip_status` if it is not storing gossip messages.
+  - MUST set `num_channel_announcements` to the number of live channels it has a valid `channel_announcement` for.
+  - MUST set `num_channel_updates` to the number of valid unique `channel_update`s it has.
+  - MUST set `num_node_announcements` to the number of valid unique `node_announcement`s it has.
+  - SHOULD NOT send `gossip_status` if it knows it is not synced with the latest block.
+  - SHOULD send `gossip_status` after the initial `gossip_timestamp_filter` message.
+
+- A receiving node:
+  - If it does not advertize `option_gossip_status`, SHOULD ignore `gossip_status`.
+  - If it has responded to a `gossip_status` from this peer already without a reconnection:
+    - SHOULD ignore `option_gossip_status`.
+  - If it has responded to a `gossip_status` from this peer recently:
+    - MAY ignore `option_gossip_status`.
+  - If it has more than 100 more `channel_announcement` than `num_channel_announcements`:
+    - SHOULD send all `channel_announcement`, `channel_update` and `node_announcement` to the peer.
+  - Otherwise, if it has 100 more `channel_update` than `num_channel_updates`:
+    - SHOULD send all `channel_update` to the peer.
+	- MAY send additional gossip messages.
+  - Otherwise, if it has 100 more `node_announcement` than `num_node_announcements`:
+    - SHOULD send all `node_announcement` to the peer.
+	- MAY send additional gossip messages.
+
+#### Rationale
+
+Nodes can fall out of sync with the current gossip, either because they are offline for significant periods, or because peers are limiting the gossip they relay.  Various heuristics can be used to detect this, as can randomly asking a peer for all gossip, but this is both more reliable and more network friendly.
+
+The number 100 is chosen fairly arbitrarily as greater than the largest number of channels opened in a single block, so one node being a block behind will not trigger a flood of gossip.
+
+The requirements explicitly allow an implementation to simply "send all gossip" when any count is too far behind.
+
 ## Rebroadcasting
 
 ### Requirements

09-features.md

@@ -51,6 +51,7 @@ The Context column decodes as follows:
 | 46/47 | `option_scid_alias`               | Supply channel aliases for routing                        | IN       |                           | [BOLT #2][bolt02-channel-ready]                                       |
 | 48/49 | `option_payment_metadata`         | Payment metadata in tlv record                            | 9        |                           | [BOLT #11](11-payment-encoding.md#tagged-fields)                      |
 | 50/51 | `option_zeroconf`                 | Understands zeroconf channel types                        | IN       | `option_scid_alias`       | [BOLT #2][bolt02-channel-ready]                                       |
+| 66/67 | `option_gossip_status`            | Understands `gossip_status` messages                      | IN       |                           | [BOLT #7][bolt07-gossip-status]                                      |
 
 
 ## Requirements
@@ -103,6 +104,7 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li
 [bolt04]: 04-onion-routing.md
 [bolt07-sync]: 07-routing-gossip.md#initial-sync
 [bolt07-query]: 07-routing-gossip.md#query-messages
+[bolt07-gossip-status]: 07-routing-gossip.md#query-messages
 [bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
 [bolt04-route-blinding]: 04-onion-routing.md#route-blinding
 [ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html