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 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.
## The `channel_announcement` message
This message contains ownership information about a channel. It ties each
on-chain bitcoin key to the lightning node key, and vice-versa.
The channel is not really usable until at least one side has announced
The `timestamp` allows ordering in the case of multiple announcements;
the `ipv6` and `port` allow the node to announce its willingness to
accept incoming network connections, the `rgb-color` and `alias` allow
intelligence services to give their nodes cool monikers like IRATEMONK
and WISTFULTOLL and use the color black.
### Requirements
The creating node MUST set `timestamp` to be greater than any previous
`node_announcement` it has created. It MAY base it on a UNIX
timestamp. It MUST set the `ipv6` and `port` fields to all zeroes, or
a non-zero `port` and `ipv6` set to a valid IPv6 address or an IPv4-Mapped IPv6 Address format as defined in [RFC 4291 section 2.5.5.2](https://tools.ietf.org/html/rfc4291#section-2.5.5.2). It MUST set `signature` to the signature of
the double-SHA256 of the entire remaining packet after `signature` using the
key given by `node-id`. It MUST set `pad` to zero. 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 of up to 21 bytes in length, with all `alias` bytes following equal to zero.
The creating node MUST set `blockheight`, `blockindex` and `outputindex` to
match those in the already-sent `channel_announcement` message, and MUST set `side` to 0 if the creating node is `node-id-1` in that message, otherwise 1.
The creating node MUST set `timestamp` to greater than zero, and MUST set it to greater than any previously-sent `channel_update` for this channel, and MUST set `pad` to zero.
It MUST set `expiry` to the number of blocks it will subtract from an incoming HTLC's `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 node SHOULD fail the connection if `side` is not 0 or 1.
It MUST ignore the contents of `pad`. The receiving node SHOULD fail
the connection if `signature` is invalid or incorrect for the entire
message including unknown fields following `signature`, and MUST NOT
further process the message. The receiving node SHOULD ignore `ipv6`
if `port` is zero. It SHOULD ignore the message if `blockheight`,
`blockindex` and `outputindex` do not correspond to a previously
known, unspent channel from `channel_announcement` or if `timestamp`
is not greater than than the last-received `channel_announcement` for
this channel and `side`. Otherwise, if the `timestamp` is equal to
the last-received `channel_announcement` and the fields other than
`signature` differ, the node MAY blacklist this node-id and forget all
channels associated with it. Otherwise the receiving node SHOULD
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
