This specification describes simple node discovery, channel discovery and channel update mechanisms which do not rely on a third-party to disseminate the information.
Node and channel discovery serve two different purposes:
- Channel discovery allows the creation and maintenance of a local view of the network's topology such that the node can discover routes to the desired destination.
- Node discovery allows nodes to broadcast their ID, host and port, such that other nodes can open connections and establish payment channels.
Peers in the network exchange `channel_announcement` messages that contain information about new channels between two nodes. They can also exchange `node_announcement` messages which supply additional information about nodes, and `channel_update` messages which update information about a channel.
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.
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.
The willingness of the initiating node to announce the channel is signaled during channel opening by setting the `announce_channel` bit in `channel_flags` (see [BOLT #2](02-peer-protocol.md#the-open_channel-message)).
If the `open_channel` message had the `announce_channel` bit set, then both nodes must send the `announcement_signatures` message, otherwise they MUST NOT.
If sent, `announcement_signatures` messages MUST NOT be sent until `funding_locked` has been sent, and the funding transaction is has at least 6 confirmations.
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.
On reconnection, a node SHOULD retransmit the `announcement_signatures` message if it has not received an `announcement_signatures` message, and MUST respond to the first `announcement_signatures` message after reconnection with its own `announcement_signatures` message.
`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.
`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.
key given by `node_id`. It MAY set `alias` and `rgb_color` to customize their node's appearance in maps and graphs, where the first byte of `rgb` is the red value, the second byte is the green value and the last byte is the blue value. It MUST set `alias` to a valid UTF-8 string, with any `alias` bytes following equal to zero.
A node MAY still create a `channel_update` to communicate the channel parameters to the other endpoint, even though the channel has not been announced, e.g., because the `announce_channel` bit was not set.
The `flags` bitfield is used to indicate the direction of the channel this update concerns, i.e., it identifies the node that this update originated from, and signal various options concerning the channel.
The creating node MUST set `short_channel_id` to match those in the already-sent `channel_announcement` message, and MUST set the `direction` bit of `flags` to 0 if the creating node is `node_id_1` in that message, otherwise 1.
Bits which are not assigned a meaning must be set to 0.
A node MAY create and send a `channel_update` with the `disable` bit set to signal the temporary unavailability of a channel, e.g., due to loss of connectivity, or the permanent unavailability, e.g., ahead of an on-chain settlement.
A subsequent `channel_update` with the `disable` bit unset MAY re-enable the channel.
The creating node MUST set `timestamp` to greater than zero, and MUST set it to greater than any previously-sent `channel_update` for this `short_channel_id`.
It MUST set `cltv_expiry_delta` to the number of blocks it will subtract from an incoming HTLCs `cltv_expiry`. It MUST set `htlc_minimum_msat` to the minimum HTLC value it will accept, in millisatoshi. It MUST set `fee_base_msat` to the base fee it will charge for any HTLC, in millisatoshi, and `fee_proportional_millionths` to the amount it will charge per millionth of a satoshi.
The receiving nodes MUST ignore the `channel_update` if it does not correspond to one of its own channels, if the `short_channel_id` does not match a previous `channel_announcement`, or the channel has been closed in the meantime.
It SHOULD accept `channel_update`s for its own channels in order to learn the other end's forwarding parameters, even for non-public channels.
The `node_id` for the signature verification is taken from the corresponding `channel_announcement`: `node_id_1` if least-significant bit of flags is 0 or `node_id_2` otherwise.
Upon establishing a connection, the two endpoints negotiate whether to perform an initial sync by setting the `initial_routing_sync` flags in the `init` message.
The endpoint SHOULD set the `initial_routing_sync` flag if it requires a full copy of the other endpoint's routing state.
Upon receiving an `init` message with the `initial_routing_sync` flag set the node sends `channel_announcement`s, `channel_update`s and `node_announcement`s for all known channels and nodes as if they were just received.
If the `initial_routing_sync` flag is not set, or initial sync was completed, then the node resumes normal operation, see the _Rebroadcasting_ section for details.
Once the announcement has been processed it is added to a list of outgoing announcements (perhaps replacing older updates) to the processing node's peers, which will be flushed at regular intervals.
This store and delayed forward broadcast is called a _staggered broadcast_
If, after applying the changes from the announcement, there are no channels associated with the announcing node, then the receiving node MAY purge the announcing node from the set of known nodes.
Otherwise the receiving node updates the metadata and stores the signature associated with the announcement.
This will later allow the receiving node to rebuild the announcement for its peers.
After processing the announcement the receiving node adds the announcement to a list of outgoing announcements.
### Requirements
Each node SHOULD flush outgoing announcements once every 60 seconds, independently of the arrival times of announcements, resulting in a staggered announcement and deduplication of announcements.
Nodes MAY re-announce their channels regularly, however this is discouraged in order to keep the resource requirements low.
Nodes SHOULD send all `channel_announcement` messages followed by the
latest `node_announcement` and `channel_update` messages upon
connection establishment.
### Rationale
Batching announcements form a natural ratelimit with low overhead.
The sending of all announcements on reconnection is naive, but simple,
and allows bootstrap for new nodes as well as updating for nodes which
Nodes SHOULD monitor the funding transactions in the blockchain to identify channels that are being closed.
If the funding output of a channel is being spent, then the channel is to be considered closed and SHOULD be removed from the local network view.
Nodes MAY prune nodes added through `node_announcement` messages from their local view if the announced node no longer has any open channels associated.
This is a direct result from the dependency of a `node_announcement` being preceded by a `channel_announcement`.
### Recommendation on pruning stale entries
Several scenarios may result in channels becoming unusable and the endpoints unable to send updates for these channels.
This happens for example in case that both endpoints lose access to their private keys, and cannot sign a `channel_update` or close the channel on-chain.
These channels are unlikely to be part of a computed route since they would be partitioned off from the rest of the network, however they would remain in the local network view, and be forwarded to other nodes forever.
For this reason nodes MAY prune channels should the timestamp of the latest `channel_update` be older than 2 weeks (1209600 seconds).
In addition nodes MAY ignore channels with a timestamp older than 2 weeks.
Notice that this is a node policy and MUST NOT be enforced by peers, e.g., by closing channels when receiving outdated gossip messages.
