# [BOLT #1: Base Protocol](https://github.com/lightning/bolts/blob/master/01-messaging.md) Links: [[Lightning]], [[BOLT|BOLTs]] (Abridged) ## Overview The default TCP port is 9735. This corresponds to hexadecimal `0x2607`: the Unicode code point for LIGHTNING.[1](https://github.com/lightning/bolts/blob/master/01-messaging.md#reference-1) All data fields are unsigned big-endian unless otherwise specified. ## 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. #### Requirements The sending node: - MUST send `init` as the first Lightning message for any connection. - MUST set feature bits as defined in [BOLT #9](https://github.com/lightning/bolts/blob/master/09-features.md). - MUST set any undefined feature bits to 0. - ... The receiving node: - MUST wait to receive `init` before sending any other messages. - MUST combine (logical OR) the two feature bitmaps into one logical `features` map. - MUST respond to known feature bits as specified in [BOLT #9](https://github.com/lightning/bolts/blob/master/09-features.md). #### Rationale There used to be two feature bitfields here, but for backwards compatibility they're now combined into one. This semantic allows both future incompatible changes and future backward compatible changes. Bits should generally be assigned in pairs, in order that optional features may later become compulsory. Nodes wait for receipt of the other's features to simplify error diagnosis when features are incompatible. Since all networks share the same port, but most implementations only support a single network, the `networks` fields avoids nodes erroneously believing they will receive updates about their preferred network, or that they can open channels. ### The `error` and `warning` Messages For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect. A sending node: - SHOULD send `error` for protocol violations or internal errors that make channels unusable or that make further communication unusable. - SHOULD send `error` with the unknown `channel_id` in reply to messages of type `32`-`255` related to unknown channels. - when sending `error`: - MUST fail the channel(s) referred to by the error message. The receiving node: - upon receiving `error`: - if `channel_id` is all zero: - MUST fail all channels with the sending node. - otherwise: - MUST fail the channel referred to by `channel_id`, if that channel is with the sending node. #### Rationale There are unrecoverable errors that 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 this indicates that one peer has a bug. On the other hand, overuse of error messages has lead to implementations ignoring them (to avoid an otherwise expensive channel break), so the "warning" message was added to allow some degree of retry or recovery for spurious errors. It may be wise not to distinguish errors in production settings, lest it leak information — hence, the optional `data` field. ## Control Messages ### The `ping` and `pong` Messages In order to allow for the existence of 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. 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. #### Requirements A node sending a `ping` message: - SHOULD set `ignored` to 0s. - MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. - if it doesn't receive a corresponding `pong`: - MAY close the network connection, - and MUST NOT fail the channels in this case. A node receiving a `ping` message: - if `num_pong_bytes` is less than 65532: - MUST respond by sending a `pong` message, with `byteslen` equal to `num_pong_bytes`. - otherwise (`num_pong_bytes` is **not** less than 65532): - MUST ignore the `ping`. A node sending a `pong` message: - SHOULD set `ignored` to 0s. - MUST NOT set `ignored` to sensitive data such as secrets or portions of initialized memory. A node receiving a `pong` message: - if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent: - MAY close the connection. ### 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 long lived, as payment channels have an indefinite lifetime. However, it's likely that no new data will be exchanged for a significant portion of a connection's lifetime. Also, on several platforms it's possible that Lightning clients will be put to sleep without prior warning. Hence, a distinct `ping` message is used, 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](https://github.com/lightning/bolts/blob/master/04-onion-routing.md), 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 (e.g. 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](https://github.com/lightning/bolts/blob/master/08-transport.md).