((("wire protocol messages", id="ix_appendix_protocol_messages-asciidoc0", range="startofrange")))This appendix lists all the currently defined message types used in the Lightning P2P protocol. Additionally, we show the structure of each message, grouping the messages into logical groupings based on the protocol flows.
[NOTE]
====
Lightning Protocol messages are extensible and their structure may change during network-wide upgrades. For the authoritative information, consult the latest version of the BOLTs found in the https://github.com/lightningnetwork/lightning-rfc[GitHub Lightning-RFC repository].
====
=== Message Types
((("wire protocol messages","message types", id="ix_appendix_protocol_messages-asciidoc1", range="startofrange")))Currently defined message types are listed in <<apdx_message_types>>.
In <<message_types>>, the `Category` field allows us to quickly categorize a
message based on its functionality within the protocol itself. At a high level,
we place a message into one of eight (nonexhaustive) buckets including:
Connection Establishment:: Sent when a peer-to-peer connection is first
established. Also used to negotiate the set of features supported
by a new connection.
Error Communication:: Used by peers to communicate the occurrence of
protocol level errors to each other.
Connection Liveness:: Used by peers to check that a given transport
connection is still live.
Channel Funding:: Used by peers to create a new payment channel. This
process is also known as the channel funding process.
Channel Operation:: The act of updating a given channel off-chain. This
includes sending and receiving payments, as well as forwarding payments
within the network.
Channel Announcement:: The process of announcing a new public channel to
the wider network so it can be used for routing purposes.
Channel Graph Syncing:: The process of downloading and verifying the channel
graph.
Notice how messages that belong to the same category typically share an
adjacent _message type_ as well. This is done on purpose to group
semantically similar messages together within the specification itself.(((range="endofrange", startref="ix_appendix_protocol_messages-asciidoc1")))
=== Message Structure
((("wire protocol messages","message structure", id="ix_appendix_protocol_messages-asciidoc2", range="startofrange")))We now detail each message category in order to define
the precise structure and semantics of all defined messages within the LN
protocol.
==== Connection Establishment Messages
((("wire protocol messages","connection establishment messages")))Messages in this category are the very first message sent between peers once
they establish a transport connection. At the time of writing this chapter,
there exists only a single message within this category, the `init` message.
The `init` message is sent by _both_ sides of the connection once it has been
first established. No other messages are to be sent before the `init` message
Structurally, the `init` message is composed of two variable size bytes slices
that each store a set of _feature bits_. ((("feature bits","defined")))As we see in <<feature_bits>>, feature bits are a
primitive used within the protocol to advertise the set of protocol
features a node either understands (optional features) or demands (required
features).
Note that modern node implementations will only use the `features` field, with
items residing within the `global_features` vector for primarily _historical_
purposes (backward compatibility).
What follows after the core message is a series of Type-Length-Value (TLV) records that can be used to extend the message in a forward- and backward-compatible manner in the future. We'll cover what TLV records are and how
they're used later in this appendix.
An `init` message is then examined by a peer to determine if the
An `error` message can be sent within the scope of a particular channel by
setting the `channel_id` to the `channel_id` of the channel undergoing this
new error state. Alternatively, if the error applies to the connection in
general, then the `channel_id` field should be set to all zeroes. This all zero
`channel_id` is also known as the connection level identifier for an error.
Depending on the nature of the error, sending an `error` message to a peer you
have a channel with may indicate that the channel cannot continue without
manual intervention, so the only option at that point is to force close the
channel by broadcasting the latest commitment state of the channel.
==== Connection Liveness
((("wire protocol messages","connection liveness messages")))Messages in this section are used to probe to determine if a connection is
still live or not. Because the LN protocol somewhat abstracts over the underlying
transport being used to transmit the messages, a set of protocol level ((("wire protocol messages","ping message")))((("wire protocol messages","pong message")))`ping`
resembles other messages based on the packet sizes sent across. Remember that by
default the Lightning Network uses an _encrypted_ transport, so a passive network monitor
cannot read the plain-text bytes and thus only has timing and packet sizes to go
off of.
==== Channel Funding
((("wire protocol messages","channel funding", id="ix_appendix_protocol_messages-asciidoc3", range="startofrange")))As we go on, we enter into the territory of the core messages that govern the
functionality and semantics of the Lightning Protocol. In this section, we
explore the messages sent during the process of creating a new channel. We'll
((("open_channel message")))((("wire protocol messages","open_channel message")))This is the first message sent when a node wishes to execute a new funding flow
with another node. This message contains all the necessary information required
for both peers to construct both the funding transaction as well as the
commitment transaction.
At the time of writing this chapter, a single TLV record is defined within
the set of optional TLV records that may be appended to the end of a defined
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
((("accept_channel message")))((("wire protocol messages","accept_channel message")))The `accept_channel` message is the response to the `open_channel` message.
((("funding_created message")))((("wire protocol messages","funding_created message")))In response, the initiator will send the `funding_created` message.
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.
((("funding_locked message")))((("wire protocol messages","funding_locked message")))Once the funding transaction has received enough confirmations, the
((("wire protocol messages","channel closing")))Channel closing is a multistep process. ((("wire protocol messages","shutdown message")))One node initiates by sending the `shutdown` message. The two channel partners then exchange a series of `closing_signed` messages to negotiate mutually acceptable fees for the closing transaction. ((("closing_signed message")))((("wire protocol messages","closing_signed message")))The channel funder sends the first `closing_signed` message, and the other side can accept by sending a `closing_signed` message with the same fee values.
((("wire protocol messages","channel operation", id="ix_appendix_protocol_messages-asciidoc4", range="startofrange")))In this section, we briefly describe the set of messages used to allow
nodes to operate a channel. By operation, we mean being able to send, receive,
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
((("channel operation","update_fulfill_hltc message")))((("update_fulfill_hltc message")))The `update_fulfill_hltc` message allows redemption (receipt) of an active HTLC.
((("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.
((("channel operation","commitment_signed message")))((("commitment_signed message")))The `commitment_signed` message is used to stamp the creation of a new commitment transaction.
((("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.
This message is similar to the `update_fail_htlc` message, but it's rarely used in
practice. As mentioned previously, each HTLC carries an onion encrypted routing
packet that also covers the integrity of portions of the HTLC itself. If a
party receives an onion packet that has somehow been corrupted along the way,
then it won't be able to decrypt the packet. As a result, it also can't properly
forward the HTLC; therefore, it'll send this message to signify that the HTLC
has been corrupted somewhere along the route back to the sender.(((range="endofrange", startref="ix_appendix_protocol_messages-asciidoc4")))
==== Channel Announcement
((("channel_announcement message", id="ix_appendix_protocol_messages-asciidoc5", range="startofrange")))((("wire protocol messages","channel announcement", id="ix_appendix_protocol_messages-asciidoc6", range="startofrange")))Messages in this category are used to announce components of the channel graph
authenticated data structure to the wider network. The channel graph has a
series of unique properties due to the condition that all data added to the
channel graph must also be anchored in the base Bitcoin blockchain. As a
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
((("channel_announcement message","node_announcement message")))((("node_announcement message")))The `node_announcement` message allows a node to announce/update its vertex within the
((("channel_announcement message","channel_update message")))((("channel_update message")))The `channel_update` message is sent to update the properties and policies of
((("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`
After the `funding_locked` message has been sent, if both sides wish to
advertise their channel to the network, then they'll each send the
`announce_signatures` message which allows both sides to emplace the four
signatures required to generate an `announce_signatures` message.(((range="endofrange", startref="ix_appendix_protocol_messages-asciidoc6")))(((range="endofrange", startref="ix_appendix_protocol_messages-asciidoc5")))
Nodes create a local perspective of the channel graph using five messages: +query_short_chan_ids+, +reply_short_chan_ids_end+, +query_channel_range+, +reply_channel_range+, and +gossip_timestamp_range+.
((("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
((("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
((("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.
((("channel graph syncing messages","gossip_timestamp_range message")))((("gossip_timestamp_range message")))The `gossip_timestamp_range` message allows a peer to start receiving new
Once a peer has synced the channel graph, they can send this message if they
wish to receive real-time updates on changes in the channel graph. They can
also set the `first_timestamp` and `timestamp_range` fields if they wish to
receive a backlog of updates they may have missed while they were(((range="endofrange", startref="ix_appendix_protocol_messages-asciidoc8")))(((range="endofrange", startref="ix_appendix_protocol_messages-asciidoc7"))) down(((range="endofrange", startref="ix_appendix_protocol_messages-asciidoc2"))).(((range="endofrange", startref="ix_appendix_protocol_messages-asciidoc0")))