diff --git a/appendix_protocol_messages.asciidoc b/appendix_protocol_messages.asciidoc index d020a75..5727ab9 100644 --- a/appendix_protocol_messages.asciidoc +++ b/appendix_protocol_messages.asciidoc @@ -276,11 +276,11 @@ The `channel_flags` field is a bitfield of which, at the time of writing, only the _first_ bit has any sort of significance. If this bit is set, then this channel is to be advertised to the public network as a routable channel. Otherwise, the channel is considered to be unadvertised, also commonly referred to as a private channel. -((("accept_channel message")))((("wire protocol messages","accept_channel message")))The `accept_channel` message is the response to the `open_channel` message. - [[apdx_accept_channel_message]] ===== The accept_channel message +((("accept_channel message")))((("wire protocol messages","accept_channel message")))The `accept_channel` message is the response to the `open_channel` message. + * Type: 33 * Fields: ** `32*byte` : `temp_chan_id` @@ -307,11 +307,11 @@ when we go into the funding process in detail, we explore the implications of the various parameters that can be set when opening a new channel. -((("funding_created message")))((("wire protocol messages","funding_created message")))In response, the initiator will send the `funding_created` message. - [[apdx_funding_created_message]] ===== The funding_created message +((("funding_created message")))((("wire protocol messages","funding_created message")))In response, the initiator will send the `funding_created` message. + * Type: 34 * Fields: ** `32*byte` : `temp_chan_id` @@ -327,11 +327,11 @@ needs to construct the funding transaction. As a result, to allow the responder to sign a version of a commitment transaction for the initiator, the initiator only needs to send the funding outpoint of the channel. -((("funding_signed message")))((("wire protocol messages","funding_signed message")))To conclude, the responder sends the `funding_signed` message. - [[apdx_funding_signed_message]] ===== The funding_signed message +((("funding_signed message")))((("wire protocol messages","funding_signed message")))To conclude, the responder sends the `funding_signed` message. + * Type: 34 * Fields: ** `channel_id` : `channel_id` @@ -341,20 +341,18 @@ To conclude after the responder receives the `funding_created` message, they now own a valid signature of the commitment transaction by the initiator. With this signature they're able to exit the channel at any time by signing their half of the multisig funding output and broadcasting the transaction. This is -referred to as a force close. To give the initiator the ability to do -so as well, before the channel can be used, and the responder then signs the -initiator's commitment transaction as well. +referred to as a force close. Conversely, to give the initiator the ability to close the channel, the responder also signs the initiator's commitment transaction. Once this message has been received by the initiator, it's safe for them to broadcast the funding transaction because they're now able to exit the channel agreement unilaterally. -((("funding_locked message")))((("wire protocol messages","funding_locked message")))Once the funding transaction has received enough confirmations, the -`funding_locked` message is sent. - [[apdx_funding_locked_message]] ===== The funding_locked message +((("funding_locked message")))((("wire protocol messages","funding_locked message")))Once the funding transaction has received enough confirmations, the +`funding_locked` message is sent. + * Type: 36 * Fields: ** `channel_id` : `channel_id` @@ -395,12 +393,12 @@ and forward payments for a given channel. To send, receive, or forward a payment over a channel, an HTLC must first be added to both commitment transactions that comprise a channel link. -((("channel operation","update_add_htlc message")))((("update_add_htlc message")))((("wire protocol messages","update_add_htlc message")))The `update_add_htlc` message allows either side to add a new HTLC to the -opposite commitment transaction. - [[apdx_update_add_htlc_message]] ===== The update_add_htlc message +((("channel operation","update_add_htlc message")))((("update_add_htlc message")))((("wire protocol messages","update_add_htlc message")))The `update_add_htlc` message allows either side to add a new HTLC to the +opposite commitment transaction. + * Type: 128 * Fields: ** `channel_id` : `channel_id` @@ -422,11 +420,11 @@ Note that each HTLC sent uses an automatically incrementing ID which is used by message which modifies an HTLC (settle or cancel) to reference the HTLC in a unique manner scoped to the channel. -((("channel operation","update_fulfill_hltc message")))((("update_fulfill_hltc message")))The `update_fulfill_hltc` message allows redemption (receipt) of an active HTLC. - [[apdx_update_fulfill_hltc_message]] ===== The update_fulfill_hltc message +((("channel operation","update_fulfill_hltc message")))((("update_fulfill_hltc message")))The `update_fulfill_hltc` message allows redemption (receipt) of an active HTLC. + * Type: 130 * Fields: ** `channel_id` : `channel_id` @@ -437,11 +435,11 @@ This message is sent by the HTLC receiver to the proposer to redeem an active HTLC. The message references the `id` of the HTLC in question, and also provides the preimage (which unlocks the HLTC). -((("channel operation","update_fail_htlc message")))((("update_fail_htlc message")))The `update_fail_htlc` message is sent to remove an HTLC from a commitment transaction. - [[apdx_update_fail_htlc_message]] ===== The update_fail_htlc message +((("channel operation","update_fail_htlc message")))((("update_fail_htlc message")))The `update_fail_htlc` message is sent to remove an HTLC from a commitment transaction. + * Type: 131 * Fields: ** `channel_id` : `channel_id` @@ -457,11 +455,11 @@ sent back to the sender to unravel the HTLC chain. As we explore in may allow the sender to either adjust their payment route or terminate if the failure itself is a terminal one. -((("channel operation","commitment_signed message")))((("commitment_signed message")))The `commitment_signed` message is used to stamp the creation of a new commitment transaction. - [[apdx_commitment_signed_message]] ===== The commitment_signed message +((("channel operation","commitment_signed message")))((("commitment_signed message")))The `commitment_signed` message is used to stamp the creation of a new commitment transaction. + * Type: 132 * Fields: ** `channel_id` : `channel_id` @@ -473,11 +471,11 @@ In addition to sending a signature for the next commitment transaction, the sender of this message also needs to send a signature for each HTLC that's present on the commitment transaction. -((("channel operation","revoke_and_ack message")))((("revoke_and_ack message")))The `revoke_and_ack` is sent to revoke a dated commitment. - [[apdx_revoke_and_ack_message]] ===== The revoke_and_ack message +((("channel operation","revoke_and_ack message")))((("revoke_and_ack message")))The `revoke_and_ack` is sent to revoke a dated commitment. + * Type: 133 * Fields: ** `channel_id` : `channel_id` @@ -491,12 +489,12 @@ While revoking a commitment transaction, the revoker then also provides the next commitment point that's required to allow the other party to send them a new commitment state. -((("channel operation","update_fee message")))((("update_fee message")))The `update_fee` is sent to update the fee on the current commitment -transactions. - [[apdx_update_fee_message]] ===== The update_fee message +((("channel operation","update_fee message")))((("update_fee message")))The `update_fee` is sent to update the fee on the current commitment +transactions. + * Type: 134 * Fields: ** `channel_id` : `channel_id` @@ -505,12 +503,11 @@ transactions. This message can only be sent by the initiator of the channel; they're the ones that will pay for the commitment fee of the channel as along as it's open. -((("channel operation","update_fail_malformed_htlc message")))((("update_fail_malformed_htlc message")))The `update_fail_malformed_htlc` message is sent to remove a corrupted HTLC. - - [[apdx_update_fail_malformed_htlc_message]] ===== The update_fail_malformed_htlc message +((("channel operation","update_fail_malformed_htlc message")))((("update_fail_malformed_htlc message")))The `update_fail_malformed_htlc` message is sent to remove a corrupted HTLC. + * Type: 135 * Fields: ** `channel_id` : `channel_id` @@ -536,12 +533,13 @@ result, to add a new entry to the channel graph, an agent must be an on-chain transaction fee. This serves as a natural spam deterrent for the Lightning Network. -The `channel_announcement` message is used to announce a new channel to the wider -network. [[apdx_channel_announcement_message]] ===== The channel_announcement message +The `channel_announcement` message is used to announce a new channel to the wider +network. + * Type: 256 * Fields: ** `sig` : `node_signature_1` @@ -563,12 +561,12 @@ we detail in <>, each channel is uniquely identified by a locator that encodes its _location_ within the blockchain. This locator is called this `short_channel_id` and can fit into a 64-bit integer. -((("channel_announcement message","node_announcement message")))((("node_announcement message")))The `node_announcement` message allows a node to announce/update its vertex within the -greater channel graph. - [[apdx_node_announcement_message]] ===== The node_announcement message +((("channel_announcement message","node_announcement message")))((("node_announcement message")))The `node_announcement` message allows a node to announce/update its vertex within the +greater channel graph. + * Type: 257 * Fields: ** `sig` : `signature` @@ -589,12 +587,12 @@ the cost of creating the channel to which this node is connected. In addition to advertising its feature set, this message also allows a node to announce/update the set of network `addresses` where it can be reached. -((("channel_announcement message","channel_update message")))((("channel_update message")))The `channel_update` message is sent to update the properties and policies of -an active channel edge within the channel graph. - [[apdx_channel_update_message]] ===== The channel_update message +((("channel_announcement message","channel_update message")))((("channel_update message")))The `channel_update` message is sent to update the properties and policies of +an active channel edge within the channel graph. + * Type: 258 * Fields: ** `signature` : `signature` @@ -613,13 +611,13 @@ In addition to being able to enable/disable a channel, this message allows a node to update its routing fees as well as other fields that shape the type of payment that is permitted to flow through this channel. +[[apdx_announce_signatures_message]] +===== The announce_signatures message + ((("announce_signatures message")))((("channel_announcement message","announce_signatures message")))The `announce_signatures` message is exchanged by channel peers to assemble the set of signatures required to produce a `channel_announcement` message. -[[apdx_announce_signatures_message]] -===== The announce_signatures message - * Type: 259 * Fields: ** `channel_id` : `channel_id` @@ -651,12 +649,12 @@ As we learn in <>, these channel IDs may be a series of channels that were new to the sender or were out-of-date, which allows the sender to obtain the latest set of information for a set of channels. -((("channel graph syncing messages","reply_short_chan_ids_end message")))((("reply_short_chan_ids_end message")))The `reply_short_chan_ids_end` message is sent after a peer finishes responding -to a prior `query_short_chan_ids` message. - [[apdx_reply_short_chan_ids_end_message]] ===== The reply_short_chan_ids_end message +((("channel graph syncing messages","reply_short_chan_ids_end message")))((("reply_short_chan_ids_end message")))The `reply_short_chan_ids_end` message is sent after a peer finishes responding +to a prior `query_short_chan_ids` message. + * Type: 262 * Fields: ** `chain_hash` : `chain_hash` @@ -665,12 +663,12 @@ to a prior `query_short_chan_ids` message. This message signals to the receiving party that if they wish to send another query message, they can now do so. -((("channel graph syncing messages","query_channel_range message")))((("query_channel_range message")))The `query_channel_range` message allows a node to query for the set of channels -opened within a block range. - [[apdx_query_channel_range_message]] ===== The query_channel_range message +((("channel graph syncing messages","query_channel_range message")))((("query_channel_range message")))The `query_channel_range` message allows a node to query for the set of channels +opened within a block range. + * Type: 263 * Fields: ** `chain_hash` : `chain_hash` @@ -684,12 +682,12 @@ of a channel in the chain, a node on the network can use a block height as a sort of _cursor_ to seek through the chain in order to discover a set of newly opened channels. -((("channel graph syncing messages","reply_channel_range message")))((("reply_channel_range message")))The `reply_channel_range` message is the response to the `query_channel_range` message and -includes the set of short channel IDs for known channels within that range. - [[apdx_reply_channel_range_message]] ===== The reply_channel_range message +((("channel graph syncing messages","reply_channel_range message")))((("reply_channel_range message")))The `reply_channel_range` message is the response to the `query_channel_range` message and +includes the set of short channel IDs for known channels within that range. + * Type: 264 * Fields: ** `chain_hash` : `chain_hash` @@ -705,12 +703,12 @@ channels that were opened within that range. This process can be repeated with the requester advancing their cursor further down the chain to continue syncing the channel graph. -((("channel graph syncing messages","gossip_timestamp_range message")))((("gossip_timestamp_range message")))The `gossip_timestamp_range` message allows a peer to start receiving new -incoming gossip messages on the network. - [[apdx_gossip_timestamp_range_message]] ===== The gossip_timestamp_range message +((("channel graph syncing messages","gossip_timestamp_range message")))((("gossip_timestamp_range message")))The `gossip_timestamp_range` message allows a peer to start receiving new +incoming gossip messages on the network. + * Type: 265 * Fields: ** `chain_hash` : `chain_hash`