BOLT #7: P2P Node and Channel Discovery

This specification describes simple node discovery, channel discovery, and channel update mechanisms that do not rely on a third-party to disseminate the information.

Node and channel discovery serve two different purposes:

• Node discovery allows nodes to broadcast their ID, host, and port, so that other nodes can open connections and establish payment channels with them.
• Channel discovery allows the creation and maintenance of a local view of the network's topology, so that a node can discover routes to desired destinations.

To support channel and node discovery, three gossip messages are supported:

• For node discovery, peers exchange node_announcement messages, which supply additional information about the nodes. There may be multiple node_announcement messages, in order to update the node information.

• For channel discovery, peers in the network exchange channel_announcement messages containing information regarding new channels between the two nodes. They can also exchange channel_update messages, which update information about a channel. There can only be one valid channel_announcement for any channel, but at least two channel_update messages are expected.

Table of Contents

• Definition of short_channel_id
• The announcement_signatures Message
• The channel_announcement Message
• The node_announcement Message
• The channel_update Message
• Query Messages
• Rebroadcasting
• HTLC Fees
• Pruning the Network View
• Recommendations for Routing
• References

Definition of short_channel_id

The short_channel_id is the unique description of the funding transaction. It is constructed as follows:

1. the most significant 3 bytes: indicating the block height
2. the next 3 bytes: indicating the transaction index within the block
3. the least significant 2 bytes: indicating the output index that pays to the channel.

The standard human readable format for short_channel_id is created by printing the above components, in the order: block height, transaction index, and output index. Each component is printed as a decimal number, and separated from each other by the small letter x. For example, a short_channel_id might be written as 539268x845x1, indicating a channel on the output 1 of the transaction at index 845 of the block at height 539268.

Rationale

The short_channel_id human readable format is designed so that double-clicking or double-tapping it will select the entire ID on most systems. Humans prefer decimal when reading numbers, so the ID components are written in decimal. The small letter x is used since on most fonts, the x is visibly smaller than decimal digits, making it easy to visibly group each component of the ID.

The announcement_signatures Message

This is a direct message between the 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:
   • [channel_id:channel_id]
   • [short_channel_id:short_channel_id]
   • [signature:node_signature]
   • [signature:bitcoin_signature]

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).

Requirements

The announcement_signatures message is created by constructing a channel_announcement message, corresponding to the newly confirmed channel funding transaction, and signing it with the secrets matching an endpoint's node_id and bitcoin_key.

A node:

• If the open_channel message has the announce_channel bit set AND a shutdown message has not been sent:
  • After channel_ready has been sent and received AND the funding transaction has enough confirmations to ensure that it won't be reorganized:
    • MUST send announcement_signatures for the funding transaction.
  • After splice_locked has been sent and received AND the splice transaction has enough confirmations to ensure that it won't be reorganized:
    • MUST send announcement_signatures for the matching splice transaction.
• Otherwise:
  • MUST NOT send the announcement_signatures message.
• Upon reconnection (once the above timing requirements have been met):
  • If it has NOT previously received announcement_signatures for the funding transaction:
    • MUST send its own announcement_signatures message.
  • If it receives announcement_signatures for the funding transaction:
    • MUST respond with its own announcement_signatures message.
  • If it has NOT previously received announcement_signatures for a splice transaction:
    • MUST SET the announcement_signatures bit in the retransmit_flags of my_current_funding_locked.
  • If the announcement_signatures bit is set in the remote retransmit_flags:
    • MUST retransmit its announcement_signatures message.

A recipient node:

• If the short_channel_id doesn't match one of its funding transactions:
  • SHOULD send a warning.
• If the node_signature OR the bitcoin_signature is NOT correct:
  • MAY send a warning and close the connection, or send an error and fail the channel.
• If it has sent AND received a valid announcement_signatures message:
  • If the funding transaction has at least 6 confirmations:
    • SHOULD queue the channel_announcement message for its peers.
• If it has not sent channel_ready:
  • SHOULD defer handling the announcement_signatures until after it has sent channel_ready.
• If it has not sent splice_locked for the transaction matching this short_channel_id:
  • SHOULD defer handling the announcement_signatures until after it has sent splice_locked.

Rationale

Channels must not be announced before the funding transaction has enough confirmations, because a blockchain reorganization would otherwise invalidate the short_channel_id.

When splicing is used, a channel_announcement is generated for every splice transaction once both sides have sent splice_locked. This lets the network know that the transaction spending a currently active channel is a splice and not a closing transaction, and this channel can still be used with its updated short_channel_id.

The channel_announcement Message

This gossip message contains ownership information regarding a channel. It ties each on-chain Bitcoin key to the associated Lightning node key, and vice-versa. The channel is not practically usable until at least one side has announced its fee levels and expiry, using channel_update.

Proving the existence of a channel between node_1 and node_2 requires:

1. proving that the funding transaction pays to bitcoin_key_1 and bitcoin_key_2
2. proving that node_1 owns bitcoin_key_1
3. proving that node_2 owns bitcoin_key_2

Assuming that all nodes know the unspent transaction outputs, the first proof is accomplished by a node finding the output given by the short_channel_id and verifying that it is indeed a P2WSH funding transaction output for those keys specified in BOLT #3.

The last two proofs are accomplished through explicit signatures: bitcoin_signature_1 and bitcoin_signature_2 are generated for each bitcoin_key and each of the corresponding node_ids are signed.

It's also necessary to prove that node_1 and node_2 both agree on the announcement message: this is accomplished by having a signature from each node_id (node_signature_1 and node_signature_2) signing the message.

1. type: 256 (channel_announcement)
2. data:
   • [signature:node_signature_1]
   • [signature:node_signature_2]
   • [signature:bitcoin_signature_1]
   • [signature:bitcoin_signature_2]
   • [u16:len]
   • [len*byte:features]
   • [chain_hash:chain_hash]
   • [short_channel_id:short_channel_id]
   • [point:node_id_1]
   • [point:node_id_2]
   • [point:bitcoin_key_1]
   • [point:bitcoin_key_2]

Requirements

The origin node:

• MUST set chain_hash to the 32-byte hash that uniquely identifies the chain that the channel was opened within:
  • for the Bitcoin blockchain:
    • MUST set chain_hash value (encoded in hex) equal to 6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000.
• When announcing a channel creation:
  • MUST set short_channel_id to refer to the confirmed funding transaction, as specified in BOLT #2.
• When announcing a splice transaction:
  • MUST set short_channel_id to refer to the confirmed splice transaction for which splice_locked has been sent and received, as specified in BOLT #2.
  • SHOULD keep relaying payments that use the short_channel_ids of its previous channel_announcements.
  • SHOULD send a new channel_update using the short_channel_id that matches the latest channel_announcement.
• Note: the corresponding output MUST be a P2WSH, as described in BOLT #3.
• MUST set node_id_1 and node_id_2 to the public keys of the two nodes operating the channel, such that node_id_1 is the lexicographically-lesser of the two compressed keys sorted in ascending lexicographic order.
• MUST set bitcoin_key_1 and bitcoin_key_2 to node_id_1 and node_id_2's respective funding_pubkeys.
• MUST compute the double-SHA256 hash h of the message, beginning at offset 256, up to the end of the message.
  • Note: the hash skips the 4 signatures but hashes the rest of the message, including any future fields appended to the end.
• MUST set node_signature_1 and node_signature_2 to valid signatures of the hash h (using node_id_1 and node_id_2's respective secrets).
• MUST set bitcoin_signature_1 and bitcoin_signature_2 to valid signatures of the hash h (using bitcoin_key_1 and bitcoin_key_2's respective secrets).
• MUST set features based on what features were negotiated for this channel, according to BOLT #9
• MUST set len to the minimum length required to hold the features bits it sets.
• If the funding transaction has less than 6 confirmations:
  • MUST NOT send channel_announcement.

The receiving node:

• MUST verify the integrity AND authenticity of the message by verifying the signatures.
• if there is an unknown even bit in the features field:
  • MUST NOT attempt to route messages through the channel.
• if the short_channel_id's output does NOT correspond to a P2WSH (using bitcoin_key_1 and bitcoin_key_2, as specified in BOLT #3) OR the output is spent:
  • MUST ignore the message.
• if the specified chain_hash is unknown to the receiver:
  • MUST ignore the message.
• if the short_channel_id's output does NOT have at least 6 confirmations:
  • MAY accept the message if the output is close to 6 confirmations, in case the receiving node hasn't received the latest block(s) yet.
  • otherwise:
    • SHOULD ignore the message.
• otherwise:
  • if bitcoin_signature_1, bitcoin_signature_2, node_signature_1 OR node_signature_2 are invalid OR NOT correct:
    • SHOULD send a warning.
    • MAY close the connection.
    • MUST ignore the message.
  • otherwise:
    • if node_id_1 OR node_id_2 are blacklisted:
      • SHOULD ignore the message.
    • otherwise:
      • if the transaction referred to was NOT previously announced as a channel:
        • SHOULD queue the message for rebroadcasting.
        • MAY choose NOT to for messages longer than the minimum expected length.
    • if it has previously received a valid channel_announcement, for the same transaction, in the same block, but for a different node_id_1 or node_id_2:
      • SHOULD blacklist the previous message's node_id_1 and node_id_2, as well as this node_id_1 and node_id_2 AND forget any channels connected to them.
    • otherwise:
      • SHOULD store this channel_announcement.
• once its funding output has been spent OR reorganized out:
  • SHOULD forget a channel after a 72-block delay.
  • SHOULD NOT rebroadcast this channel_announcement to its peers.

Rationale

Both nodes are required to sign to indicate they are willing to route other payments via this channel (i.e. be part of the public network); requiring their Bitcoin signatures proves that they control the channel.

The blacklisting of conflicting nodes disallows multiple different announcements. Such conflicting announcements should never be broadcast by any node, as this implies that keys have leaked.

While channels should not be advertised before they are sufficiently deep, the requirement against rebroadcasting only applies if the transaction has not moved to a different block.

In order to avoid storing excessively large messages, yet still allow for reasonable future expansion, nodes are permitted to restrict rebroadcasting (perhaps statistically).

New channel features are possible in the future: backwards compatible (or optional) features will have odd feature bits, while incompatible features will have even feature bits ("It's OK to be odd!").

A delay of 72 blocks is used when forgetting a channel after detecting that it has been spent: this can allow a new channel_announcement to propagate to indicate that this channel was spliced and not closed. Thanks to this delay, payments can still be relayed on the channel while the splice transaction is waiting for enough confirmations.

The node_announcement Message

This gossip message allows a node to indicate extra data associated with it, in addition to its public key. To avoid trivial denial of service attacks, nodes not associated with an already known channel are ignored.

1. type: 257 (node_announcement)
2. data:
   • [signature:signature]
   • [u16:flen]
   • [flen*byte:features]
   • [u32:timestamp]
   • [point:node_id]
   • [3*byte:rgb_color]
   • [32*byte:`alias

[Content truncated — view full spec at source]