lightning-bolts/01-messaging.md

BOLT #1: Base Protocol

Overview

This protocol assumes an underlying authenticated and ordered transport mechanism that takes care of framing individual messages. BOLT #8 specifies the canonical transport layer used in Lightning, though it can be replaced by any transport that fulfills the above guarantees.

The default TCP port is 9735. This corresponds to hexadecimal 0x2607, the Unicode code point for LIGHTNING.¹

All data fields are big-endian unless otherwise specified.

Table of Contents

• Connection Handling and Multiplexing
• Lightning Message Format
• Setup Messages
  • The init Message
  • The error Message
• Control Messages
  • The ping and pong Messages
• Acknowledgments
• References
• Authors

Connection Handling and Multiplexing

Implementations MUST use one connection per peer, channel messages (which include a channel id) are multiplexed over this single connection.

Lightning Message Format

After decryption, all lightning messages are of the form:

1. type: 2 byte big-endian field indicating the type of message.
2. payload: variable length payload which comprises the remainder of the message and conforms to the format matching the type.

The type field indicates how to interpret the payload field. The format for each individual type is specified in a specification in this repository. The type follows the it's ok to be odd rule, so nodes MAY send odd-numbered types without ascertaining that the recipient understands it. A node MUST NOT send an evenly-typed message not listed here without prior negotiation. A node MUST ignore a received message of unknown type, if that type is odd. A node MUST fail the channels if it receives a message of unknown type, if that type is even.

The messages are grouped logically into 4 groups, ordered by their most significant set bit:

• Setup & Control (types 0-31): messages related to connection setup, control, supported features, and error reporting. These are described below.
• Channel (types 32-127): messages used to setup and tear down micropayment channels. These are described in BOLT #2.
• Commitment (types 128-255): messages related to updating the current commitment transaction, which includes adding, revoking, and settling HTLCs, as well as updating fees and exchanging signatures. These are described in BOLT #2.
• Routing (types 256-511): node and channel announcements, as well as any active route exploration. These are described in BOLT #7.

The size of the message is required to fit into a 2 byte unsigned int by the transport layer, therefore the maximum possible size is 65535 bytes. A node MUST ignore any additional data within a message, beyond the length it expects for that type. A node MUST fail the channels if it receives a known message with insufficient length for the contents.

Rationale

The standard endian of SHA2 and the encoding of Bitcoin public keys are big endian, thus it would be unusual to use a different endian for other fields.

Length is limited to 65535 bytes by the cryptographic wrapping, and messages in the protocol are never more than that length anyway.

The "it's OK to be odd" rule allows for future optional extensions without negotiation or special coding in clients. The "ignore additional data" rule similarly allows for future expansion.

Implementations may prefer to have message data aligned on an 8 byte boundary (the largest natural alignment requirement of any type here), but adding a 6 byte padding after the type field was considered wasteful: alignment may be achieved by decrypting the message into a buffer with 6 bytes of pre-padding.

Setup Messages

The init Message

Once authentication is complete, the first message reveals the features supported or required by this node, even if this is a reconnection.

BOLT #9 specifies lists of global and local features. Each feature is generally represented in globalfeatures or localfeatures by 2 bits. The least-significant bit is numbered 0, which is even, and the next most significant bit is numbered 1, which is odd.

Both fields globalfeatures and localfeatures MUST be padded to bytes with zeros.

1. type: 16 (init)
2. data:
   • [2:gflen]
   • [gflen:globalfeatures]
   • [2:lflen]
   • [lflen:localfeatures]

The 2 byte gflen and lflen fields indicate the number of bytes in the immediately following field.

Requirements

Each node MUST send init as the first lightning message for any connection. The sending node SHOULD use the minimum lengths required to represent the feature fields.

The sender MUST set feature bits as defined in BOLT #9 and MUST set to zero any feature bits that are not defined.

The receiver MUST respond to known feature bits as specified in BOLT #9. For unknown feature bits which are non-zero, the receiver MUST ignore the bit if the bit number is odd and MUST fail the connection if the bit number is even.

Each node MUST wait to receive init before sending any other messages.

Rationale

This semantic allows future incompatible changes and/or backward compatible changes. Bits should generally be assigned in pairs, so that optional features can later become compulsory.

Nodes wait for receipt of the other's features to simplify error diagnosis, where features are incompatible.

The feature masks are split into local features, which only affect the protocol between these two nodes, and global features, which can affect HTLCs and thus are also advertised to other nodes.

The error Message

For simplicity of diagnosis, it is often useful to tell the peer that something is incorrect.

1. type: 17 (error)
2. data:
   • [32:channel_id]
   • [2:len]
   • [len:data]

The 2-byte len field indicates the number of bytes in the immediately following field.

Requirements

The channel is referred to by channel_id, unless channel_id is zero (ie. all bytes are zero), in which case it refers to all channels.

The funding node MUST use temporary_channel_id in lieu of channel_id for all error messages sent before (and including) the funding_created message. The fundee node MUST use temporary_channel_id in lieu of channel_id for all error messages sent before (and not including) the funding_signed message.

A node SHOULD send error for protocol violations or internal errors which make channels unusable or further communication unusable. A node MAY send an empty data field. A node sending error MUST fail the channel referred to by the error message; or if channel_id is zero, it MUST fail all channels and MUST close the connection. A node MUST set len equal to the length of data. A node SHOULD include the raw, hex-encoded transaction in reply to a funding_created, funding_signed, closing_signed, or commitment_signed message when failure was caused by an invalid signature check.

A node receiving error MUST fail the channel referred to by the message, or if channel_id is zero, it MUST fail all channels and MUST close the connection. If no existing channel is referred to by the message, the receiver MUST ignore the message. A receiving node MUST truncate len to the remainder of the packet if it is larger.

A receiving node SHOULD only print out data verbatim if the string is composed solely of printable ASCII characters. For reference, the printable character set includes byte values 32 through 127, inclusive.

Rationale

There are unrecoverable errors which require an abort of conversations; if the connection is simply dropped then the peer may retry the connection. It's also useful to describe protocol violations for diagnosis, as it indicates that one peer has a bug.

It may be wise not to distinguish errors in production settings, lest it leak information, thus the optional data field.

Control Messages

The ping and pong Messages

In order to allow for the existence of very long-lived TCP connections, at times it may be required that both ends keep alive the TCP connection at the application level. Such messages also allow obfuscation of traffic patterns.

1. type: 18 (ping)
2. data:
   • [2:num_pong_bytes]
   • [2:byteslen]
   • [byteslen:ignored]

The pong message is to be sent whenever a ping message is received. It serves as a reply and also serves to keep the connection alive while explicitly notifying the other end that the receiver is still active. Within the received ping message, the sender will specify the number of bytes to be included within the data payload of the pong message.

1. type: 19 (pong)
2. data:
   • [2:byteslen]
   • [byteslen:ignored]

Requirements

A node sending pong or ping SHOULD set ignored to zeroes, but MUST NOT set ignored to sensitive data such as secrets or portions of initialized memory.

A node SHOULD NOT send ping messages more often than once every 30 seconds and MAY terminate the network connection if it does not receive a corresponding pong: it MUST NOT fail the channels in this case.

A node receiving a ping message SHOULD fail the channels if it has received significantly in excess of one ping per 30 seconds; if num_pong_bytes is less than 65532, it MUST respond by sending a pong message with byteslen equal to num_pong_bytes; otherwise it MUST ignore the ping.

A node receiving a pong message MAY fail the channels, if byteslen does not correspond to any ping num_pong_bytes value it has sent.

Rationale

The largest possible message is 65535 bytes, thus the maximum sensible byteslen is 65531 in order to account for the type field (pong) and the byteslen itself. This allows a convenient cutoff for num_pong_bytes to indicate that no reply should be sent.

Connections between nodes within the network may be very long lived, as payment channels have an indefinite lifetime. However, it's likely that for a significant portion of the life-time of a connection, no new data will be exchanged. Additionally, on several platforms it's possible that Lightning clients will be put to sleep without prior warning. As a result, we use a distinct ping message in order to probe for the liveness of the connection on the other side as well as to keep the established connection active.

Additionally, the ability for a sender to request that the receiver send a response with a particular number of bytes enables nodes on the network to create synthetic traffic. Such traffic can be used to partially defend against packet and timing analysis, as nodes can fake the traffic patterns of typical exchanges without applying any true updates to their respective channels.

When combined with the onion routing protocol defined in BOLT #4, careful statistically driven synthetic traffic can serve to further bolster the privacy of participants within the network.

Limited precautions are recommended against ping flooding, however some latitude is given because of network delays. Note that there are other methods of incoming traffic flooding (eg. sending odd unknown message types, or padding every message maximally).

Finally, the usage of periodic ping messages serves to promote frequent key rotations as specified within BOLT #8.

Acknowledgments

TODO(roasbeef); fin

References

1. http://www.unicode.org/charts/PDF/U2600.pdf

Authors

FIXME

This work is licensed under a Creative Commons Attribution 4.0 International License.