@ -8,18 +8,18 @@ This appendix lists all the currently defined message types used in the Lightnin
[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.
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
Currently defined message types are:
Currently defined message types are listed in <<apdx_message_types>>.
[[apdx_message_types]]
.Message Types
.Message types
[options="header"]
|===
| Type Integer | Message Name | Category
| Type integer | Message name | Category
| 16 | `init` | Connection Establishment
| 17 | `error` | Error Communication
| 18 | `ping` | Connection Liveness
@ -52,34 +52,34 @@ Currently defined message types are:
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 8 (non exhaustive) buckets including:
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 in order to negotiate the set of feature supported
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 peer to communicate the occurrence of
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 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
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
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
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 & verifying the channel
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 in order to group
adjacent _message type_ as well. This is done on purpose to group
semantically similar messages together within the specification itself.
=== Message Structure
@ -91,8 +91,8 @@ protocol.
==== 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 of this chapter,
there exists only a single messages within this category, the `init` message.
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
has been sent by both parties.
@ -102,8 +102,8 @@ The structure of the `init` message is defined as follows:
[[apdx_init_message]]
===== The init message
* type: *16*
* fields:
* Type: *16*
* Fields:
** `uint16`: `global_features_len`
** `global_features_len*byte`: `global_features`
** `uint16`: `features_len`
@ -112,20 +112,18 @@ The structure of the `init` message is defined as follows:
Structurally, the `init` message is composed of two variable size bytes slices
that each store a set of _feature bits_. As we see in <<feature_bits>>, feature bits are a
primitive used within the protocol in order to advertise the set of protocol
features a node either understands (optional features), or demands (required
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 (backwards compatibility).
purposes (backward compatibility).
What follows after the core message is a series of T.L.V, or Type Length Value
records which can be used to extend the message in a forwards+backwards
compatible manner in the future. We'll cover what TLV records are and how
they're used later in the chapter.
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 in order to determine if the
An `init` message is then examined by a peer to determine if the
connection is well defined based on the set of optional and required feature
bits advertised by both sides.
@ -134,33 +132,33 @@ consider it critical to the operation of a new connection. An example of one
would be something like the ability to understand the semantics of a newly
added field to an existing message.
On the other hand, required feature indicate that if the other peer doesn't
On the other hand, required features indicate that if the other peer doesn't
know about the feature, then the connection isn't well defined. An example of
such a feature would be a theoretical new channel type within the protocol: if
your peer doesn't know of this feature, they you don't want to keep the
connection as they're unable to open your new preferred channel type.
your peer doesn't know of this feature, then you don't want to keep the
connection because they're unable to open your new preferred channel type.
==== Error Communication Messages
Messages in this category are used to send connection level errors between two
peers. Another type of error exists in the protocol: an
HTLC forwarding level error. Connection level errors may signal things like
feature bit incompatibility, or the intent to force close (unilaterally
broadcast the latest signed commitment)
feature bit incompatibility or the intent to _force close_ (unilaterally
broadcast the latest signed commitment).
The sole message in this category is the `error` message:
[[apdx_error_message]]
===== The error message
* type: *17*
* fields:
* Type: *17*
* Fields:
** `channel_id` : `chan_id`
** `uint16` : `data_len`
** `data_len*byte` : `data`
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
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.
@ -173,26 +171,26 @@ channel by broadcasting the latest commitment state of the channel.
==== Connection Liveness
Messages in this section are used to probe to determine if a connection is
still live or not. As the LN protocol somewhat abstracts over the underlying
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 `ping`
and `pong` messages are defined.
[[apdx_ping_message]]
===== The ping message
* type: *18*
* fields:
* Type: *18*
* Fields:
** `uint16` : `num_pong_bytes`
** `uint16` : `ping_body_len`
** `ping_body_len*bytes` : `ping_body`
Next it's companion, the `pong` message.
Next its companion, the `pong` message.
[[apdx_pong_message]]
===== The pong message
* type: *19*
* fields:
* Type: *19*
* Fields:
** `uint16` : `pong_body_len`
** `ping_body_len*bytes` : `pong_body`
@ -203,16 +201,16 @@ the receiving node with respect to how large the payload it sends in its `pong`
message is. The `ping` message also includes a `ping_body` opaque set of bytes
which can be safely ignored. It only serves to allow a sender to pad out `ping`
messages they send, which can be useful in attempting to thwart certain
de-anonymization techniques based on packet sizes on the wire.
deanonymization techniques based on packet sizes on the wire.
A `pong` message should be sent in response to a received `ping` message. The
receiver should read a set of `num_pong_bytes` random bytes to send back as the
`pong_body` field. Clever use of these fields/messages may allow a privacy
concious routing node to attempt to thwart certain classes of network
de-anonymization attempts, as they can create a "fake" transcript that
resembles other messages based on the packet sizes set across. Remember that by
default the LN uses an _encrypted_ transport, so a passive network monitor
cannot read the plaintext bytes, thus only has timing and packet sizes to go
deanonymization attempts because they can create a "fake" transcript that
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
@ -220,20 +218,20 @@ off of.
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
only describe the fields used as we leave a in in-depth analysis of the
only describe the fields used as we leave an in-depth analysis of the
funding process to <<payment_channels>>.
Messages that are sent during the channel funding flow belong to the following
set of 5 messages: `open_channel`, `accept_channel`, `funding_created`,
`funding_signed`, `funding_locked`.
set of five messages: `open_channel`, `accept_channel`, `funding_created`,
`funding_signed`, and `funding_locked`.
The detailed protocol flow using these messages is described in <<payment_channels>>.
[[apdx_open_channel_message]]
===== The open_channel message
* type: *32*
* fields:
* Type: *32*
* Fields:
** `chain_hash` : `chain_hash`
** `32*byte` : `temp_chan_id`
** `uint64` : `funding_satoshis`
@ -256,36 +254,35 @@ The detailed protocol flow using these messages is described in <<payment_channe
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 constructs both the funding transaction as well as the
for both peers to construct both the funding transaction as well as the
commitment transaction.
At the time of writing of this chapter, a single TLV record is defined within
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
message:
* type: *0*
* data: `upfront_shutdown_script`
* Type: *0*
* Data: `upfront_shutdown_script`
The `upfront_shutdown_script` is a variable sized byte slice that MUST be a
valid public key script as accepted by the Bitcoin networks' consensus
The `upfront_shutdown_script` is a variable sized byte slice that must be a
valid public key script as accepted by the Bitcoin network's consensus
algorithm. By providing such an address, the sending party is able to
effectively create a "closed loop" for their channel, as neither side will sign
off an cooperative closure transaction that pays to any other address. In
practice, this address is usually one derived from a cold storage wallet.
The `channel_flags` field is a bitfield of which at the time of writing, only
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
denotes that this channel is to be advertised to the public network as a route
bal channel. Otherwise, the channel is considered to be unadvertised, also
commonly referred to as a "private" channel.
denotes that 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.
The `accept_channel` message is the response to the `open_channel` message:
[[apdx_accept_channel_message]]
===== The accept_channel message
* type: *33*
* fields:
* Type: *33*
* Fields:
** `32*byte` : `temp_chan_id`
** `uint64` : `dust_limit_satoshis`
** `uint64` : `max_htlc_value_in_flight_msat`
@ -306,7 +303,7 @@ The `accept_channel` message is the second message sent during the funding flow
process. It serves to acknowledge an intent to open a channel with a new remote
peer. The message mostly echoes the set of parameters that the responder wishes
to apply to their version of the commitment transaction. In <<payment_channels>>,
when we go into the funding process in details, we do a deep dive to explore
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.
@ -315,67 +312,67 @@ In response, the initiator will send the `funding_created` message.
[[apdx_funding_created_message]]
===== The funding_created message
* type: *34*
* fields:
* Type: *34*
* Fields:
** `32*byte` : `temp_chan_id`
** `32*byte` : `funding_txid`
** `uint16` : `funding_output_index`
** `sig` : `commit_sig`
Once the initiator of a channel receives the `accept_channel` message from the
responder, they they have all the materials they need in order to construct the
responder, they they have all the materials they need to construct the
commitment transaction, as well as the funding transaction. As channels by
default are single funder (only one side commits funds), only the initiator
needs to construct the funding transaction. As a result, in order to allow the
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.
initiator only needs to send the funding outpoint of the channel.
To conclude the responder sends the `funding_signed` message.
[[apdx_funding_signed_message]]
===== The funding_signed message
* type: *34*
* fields:
* Type: *34*
* Fields:
** `channel_id` : `channel_id`
** `sig` : `signature`
To conclude after the responder receivers the `funding_created` message, they
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 multi-sig funding output, and broadcasting the transaction. This is
referred to as a force close. In order to give the initiator the ability to do
so was well, before the channel can be used, the responder then signs the
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 was well, before the channel can be used, and the responder then signs the
initiator's commitment transaction as well.
Once this message has been received by the initiator, it's safe for them to
broadcast the funding transaction, as they're now able to exit the channel
broadcast the funding transaction because they're now able to exit the channel
agreement unilaterally.
Once the funding transaction has received enough confirmations, the
`funding_locked` is sent.
`funding_locked` message is sent.
[[apdx_funding_locked_message]]
===== The funding_locked message
* type: *36*
* fields:
* Type: *36*
* Fields:
** `channel_id` : `channel_id`
** `pubkey` : `next_per_commitment_point`
Once the funding transaction obtains a `minimum_depth` number of confirmations,
then the `funding_locked` message is to be sent by both sides. Only after this
message has been received, and sent can the channel being to be used.
message has been received and sent can the channel begin to be used.
==== Channel Closing
Channel closing is a multi-step process. One node initiates by sending the `shutdown` message. The two channel partners then exchange a series of `channel_closing` messages to negotiate mutually acceptable fees for the closing transaction. 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.
Channel closing is a multistep process. One node initiates by sending the `shutdown` message. The two channel partners then exchange a series of `channel_closing` messages to negotiate mutually acceptable fees for the closing transaction. 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.
[[apdx_shutdown_message]]
===== The shutdown message
* type: *38*
* fields:
* Type: *38*
* Fields:
** `channel_id` : `channel_id`
** `u16` : `len`
** `len*byte` : `scriptpubkey`
@ -383,8 +380,8 @@ Channel closing is a multi-step process. One node initiates by sending the `shut
[[apdx_closing_signed_message]]
===== The closing_signed message
* type: *39*
* fields:
* Type: *39*
* Fields:
** `channel_id` : `channel_id`
** `u64` : `fee_satoshis`
** `signature` : `signature`
@ -392,11 +389,11 @@ Channel closing is a multi-step process. One node initiates by sending the `shut
==== Channel Operation
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,
nodes to operate a channel. By operation, we mean being able to send, receive,
and forward payments for a given channel.
In order to send, receive or forward a payment over a channel, an HTLC must
first be added to both commitment transactions that comprise of a channel link.
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.
The `update_add_htlc` message allows either side to add a new HTLC to the
kristen@oreilly.com
3 years ago