mirror of
https://github.com/lightning/bolts.git
synced 2025-03-10 17:18:44 +01:00
Merge pull request #267 from toadlyBroodle/master
Copy Edit and Requirements Restructuring
This commit is contained in:
Rusty Russell
GitHub
commit
fd560bb671
5 changed files with 776 additions and 697 deletions
|
|
@ -1,4 +1,4 @@
|
|||
personal_ws-1.1 en 264
|
||||
personal_ws-1.1 en 264
|
||||
secp
|
||||
sig
|
||||
unguessable
|
||||
|
|
@ -214,6 +214,7 @@ num
|
|||
numStreamBytes
|
||||
txout
|
||||
HTLCs
|
||||
HTLC's
|
||||
retransmission
|
||||
decrypted
|
||||
sessionKey
|
||||
|
|
|
|||
52
.copy-edit-stylesheet-checklist.md
Normal file
52
.copy-edit-stylesheet-checklist.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
Basic checklist/stylesheet used for copy editing BOLTs —
|
||||
temporarily included here for reference purposes.
|
||||
|
||||
- spelling
|
||||
- typos
|
||||
- sentence structure
|
||||
- sentence fragments
|
||||
- run-on sentences
|
||||
- dangling, misplaced modifiers
|
||||
- consistent paragraph tense (e.g. past, present, future)
|
||||
- passive voice (e.g. avoid 'we')
|
||||
- exception: `Introduction` section
|
||||
- capitalization
|
||||
- table of contents
|
||||
- headers
|
||||
- commonly forgotten: 'Bitcoin', 'Lightning', 'ID'
|
||||
- punctuation
|
||||
- correct comma, colon, semi-colon, em-dash placement
|
||||
- appropriate use of parenthesis
|
||||
- formatting
|
||||
- single spaces between sentences
|
||||
- consistent use of _emphasis_, **strong**, `code`, CAPS, 'quotes'
|
||||
- single line separators between paragraphs and page elements
|
||||
- number values and quantities
|
||||
- type digits and enumerations, spell out small (<10) amounts
|
||||
- e.g. 'two 2-byte instances set to 0s', 'one 4-byte instance set to 1s', 'the old one is equal to 1 greater than value'
|
||||
- exceptions e.g. 'non-zero (digits)'
|
||||
- list structure
|
||||
- 2 spaces before item
|
||||
- indent 2 spaces
|
||||
- `Requirements` sections
|
||||
- colon after conditions
|
||||
- comma before sub-items
|
||||
- period at branch ends
|
||||
- example:
|
||||
```
|
||||
A sending node:
|
||||
- MAY do this.
|
||||
- if this, AND this:
|
||||
- SHOULD do this.
|
||||
- otherwise:
|
||||
- MUST do this,
|
||||
- but MUST NOT...in this case.
|
||||
```
|
||||
- links
|
||||
- broken links
|
||||
- link text
|
||||
- correct anchors/urls
|
||||
- references
|
||||
- format e.g. <sup>[1](#reference-1)</sup>
|
||||
- tags
|
||||
- consistent usage, e.g. [TODO:], [FIXME:]
|
||||
|
|
@ -1,12 +1,12 @@
|
|||
# BOLT #0: Introduction and Index
|
||||
|
||||
Welcome, friend! These Basis of Lightning Technology (BOLT) documents
|
||||
describe a layer-2 protocol for off-chain bitcoin transfer by mutual
|
||||
Welcome, friend! These Basis of Lightning Technology (BOLT) documents
|
||||
describe a layer-2 protocol for off-chain Bitcoin transfer by mutual
|
||||
cooperation, relying on on-chain transactions for enforcement if
|
||||
necessary.
|
||||
|
||||
Some requirements are subtle; we have tried to highlight motivations
|
||||
and reasoning behind the results you see here. I'm sure we've fallen
|
||||
and reasoning behind the results you see here. I'm sure we've fallen
|
||||
short: if you find any part confusing, or wrong, please contact us and
|
||||
help us improve.
|
||||
|
||||
|
|
@ -25,45 +25,44 @@ This is version 0.
|
|||
|
||||
## Glossary and Terminology Guide
|
||||
|
||||
* *Funding Transaction*:
|
||||
* The on-chain, irreversible transaction which pays to both peers
|
||||
on a channel. Thus it can only be spent by mutual consent.
|
||||
* *Funding transaction*:
|
||||
* The on-chain, irreversible transaction that pays to both peers on a channel.
|
||||
It can only be spent by mutual consent.
|
||||
|
||||
|
||||
* *Channel*:
|
||||
* A fast, off-chain method of mutual exchange between two *peers*.
|
||||
To move funds, they exchange signatures for an updated *commitment
|
||||
transaction*.
|
||||
To move funds, peers exchange signatures for an updated *commitment transaction*.
|
||||
|
||||
|
||||
* *Commitment Transaction*:
|
||||
* A transaction which spends the funding transaction; each peer
|
||||
holds a signature from the other peer for this transaction, so it
|
||||
always has a commitment transaction it can spend. After a new
|
||||
commitment transaction is negotiated, the old one is *revoked*.
|
||||
* *Commitment transaction*:
|
||||
* A transaction which spends the funding transaction.
|
||||
Each peer holds the other peer's signature for this transaction, so that it
|
||||
always has a commitment transaction it can spend. After a new
|
||||
commitment transaction is negotiated, the old one is *revoked*.
|
||||
|
||||
|
||||
* *HTLC*: Hashed Time Locked Contract.
|
||||
* A conditional payment between two peers: the recipient can spend
|
||||
the payment by presenting its signature and a *payment preimage*,
|
||||
otherwise the payer can cancel the contract by spending it after
|
||||
a given time. These are implemented as outputs from the
|
||||
*commitment transaction*.
|
||||
the payment by presenting its signature and a *payment preimage*,
|
||||
otherwise the payer can cancel the contract by spending it after
|
||||
a given time. These are implemented as outputs from the
|
||||
*commitment transaction*.
|
||||
|
||||
|
||||
* *Payment hash, payment preimage*:
|
||||
* The HTLC contains the payment hash, which is the hash of the
|
||||
payment preimage. Only the final recipient knows the payment
|
||||
preimage; thus when it reveals the preimage to collect funds is
|
||||
considered proof that it received the payment.
|
||||
payment preimage. Only the final recipient knows the payment
|
||||
preimage. In order to release funds, the final recipient releases
|
||||
the preimage as proof it has received payment.
|
||||
|
||||
|
||||
* *Commitment revocation key*:
|
||||
* Every *commitment transaction* has a unique *commitment revocation key*
|
||||
value which allows the other peer to spend all outputs
|
||||
immediately: revealing this key is how old commitment
|
||||
transactions are revoked. To do this, each output refers to the
|
||||
commitment revocation pubkey.
|
||||
value which allows the other peer to spend all outputs
|
||||
immediately: revealing this key is how old commitment
|
||||
transactions are revoked. To do this, each output refers to the
|
||||
commitment revocation pubkey.
|
||||
|
||||
|
||||
* *Per-commitment secret*:
|
||||
|
|
@ -72,36 +71,36 @@ This is version 0.
|
|||
for all previous commitments can be stored compactly.
|
||||
|
||||
|
||||
* *Mutual Close*:
|
||||
* *Mutual close*:
|
||||
* A cooperative close of a channel, by broadcasting an unconditional
|
||||
spend of the *funding transaction* with an output to each peer
|
||||
(unless one output is too small, and thus is not included).
|
||||
spend of the *funding transaction* with an output to each peer
|
||||
(unless one output is too small, and thus is not included).
|
||||
|
||||
|
||||
* *Unilateral Close*:
|
||||
* An uncooperative close of a channel, by broadcasting a
|
||||
*commitment transaction*. This transaction is larger (ie. less
|
||||
efficient) than a mutual close transaction, and the peer whose
|
||||
commitment is broadcast cannot access its own outputs for some
|
||||
previously-negotiated duration.
|
||||
* *Unilateral close*:
|
||||
* An uncooperative close of a channel, through broadcasting of a
|
||||
*commitment transaction*. This transaction is larger (i.e. less
|
||||
efficient) than a mutual close transaction, and the peer whose
|
||||
commitment is broadcast cannot access its own outputs for some
|
||||
previously-negotiated duration.
|
||||
|
||||
|
||||
* *Revoked Transaction Close*:
|
||||
* An invalid close of the channel, by broadcasting a revoked
|
||||
*commitment transaction*. Since the other peer knows the
|
||||
*commitment revocation secret key*, it can create a *penalty transaction*.
|
||||
* *Revoked transaction close*:
|
||||
* An invalid close of the channel, through broadcasting of a revoked
|
||||
*commitment transaction*. Since the other peer knows the
|
||||
*commitment revocation secret key*, it can create a *penalty transaction*.
|
||||
|
||||
|
||||
* *Penalty Transaction*:
|
||||
* *Penalty transaction*:
|
||||
* A transaction which spends all outputs of a revoked commitment
|
||||
transaction, using the *commitment revocation secret key*. A peer uses this
|
||||
if the other peer tries to "cheat" by broadcasting a revoked
|
||||
*commitment transaction*.
|
||||
transaction, using the *commitment revocation secret key*. A peer uses this
|
||||
if the other peer tries to "cheat" by broadcasting a revoked
|
||||
*commitment transaction*.
|
||||
|
||||
|
||||
* *Commitment Number*:
|
||||
* A 48-bit incrementing counter for each *commitment transaction*; they
|
||||
are independent for each peer in the channel, and start at 0.
|
||||
* *Commitment number*:
|
||||
* A 48-bit incrementing counter for each *commitment transaction*; counters
|
||||
are independent for each peer in the channel and start at 0.
|
||||
|
||||
|
||||
* *It's ok to be odd*:
|
||||
|
|
@ -112,11 +111,11 @@ This is version 0.
|
|||
|
||||
|
||||
* `chain_hash`:
|
||||
* Used in several of the BOLT documents, and denotes the genesis hash of a
|
||||
* Used in several of the BOLT documents to denote the genesis hash of a
|
||||
target blockchain. This allows nodes to create and reference channels on
|
||||
several blockchains. Nodes are to ignore any messages which reference a
|
||||
`chain_hash` that are unknown to them. Unlike `bitcoin-cli` the hash is
|
||||
not being reversed, and the hash is used directly.
|
||||
`chain_hash` that are unknown to them. Unlike `bitcoin-cli`, the hash is
|
||||
not reversed but is used directly.
|
||||
|
||||
For the main chain Bitcoin blockchain, the `chain_hash` value MUST be
|
||||
(encoded in hex):
|
||||
|
|
@ -124,7 +123,6 @@ This is version 0.
|
|||
|
||||
## Theme Song
|
||||
|
||||
|
||||
Why this network could be democratic...
|
||||
Numismatic...
|
||||
Cryptographic!
|
||||
|
|
@ -172,13 +170,10 @@ This is version 0.
|
|||
|
||||
-- Anthony Towns <aj@erisian.com.au>
|
||||
|
||||
|
||||
## Authors
|
||||
|
||||
|
||||
[ FIXME: Insert Author List ]
|
||||
|
||||
|
||||
|
||||
<br>
|
||||
This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).
|
||||
|
|
|
|||
239
01-messaging.md
239
01-messaging.md
|
|
@ -4,53 +4,62 @@
|
|||
This protocol assumes an underlying authenticated and ordered transport mechanism that takes care of framing individual messages.
|
||||
[BOLT #8](08-transport.md) 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.<sup>[1](#reference-1)</sup>
|
||||
The default TCP port is 9735. This corresponds to hexadecimal `0x2607`: the Unicode code point for LIGHTNING.<sup>[1](#reference-1)</sup>
|
||||
|
||||
All data fields are big-endian unless otherwise specified.
|
||||
|
||||
## Table of Contents
|
||||
* [Connection handling and multiplexing](#connection-handling-and-multiplexing)
|
||||
* [Connection Handling and Multiplexing](#connection-handling-and-multiplexing)
|
||||
* [Lightning Message Format](#lightning-message-format)
|
||||
* [Setup Messages](#setup-messages)
|
||||
* [The `init` message](#the-init-message)
|
||||
* [The `error` message](#the-error-message)
|
||||
* [The `init` Message](#the-init-message)
|
||||
* [The `error` Message](#the-error-message)
|
||||
* [Control Messages](#control-messages)
|
||||
* [The `ping` and `pong` messages](#the-ping-and-pong-messages)
|
||||
* [The `ping` and `pong` Messages](#the-ping-and-pong-messages)
|
||||
* [Acknowledgments](#acknowledgments)
|
||||
* [References](#references)
|
||||
* [Authors](#authors)
|
||||
|
||||
## Connection handling and multiplexing
|
||||
|
||||
Implementations MUST use one connection per peer, channel messages (which include a channel id) being multiplexed over this single connection.
|
||||
## Connection Handling and Multiplexing
|
||||
|
||||
Implementations MUST use a single 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:
|
||||
After decryption, all Lightning messages are of the form:
|
||||
|
||||
1. `type`: 2 byte big-endian field indicating the type of the message.
|
||||
2. `payload`: variable length payload. It comprises the remainder of
|
||||
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 type follows the _it's ok to be odd_ rule, so nodes MAY send _odd_-numbered types without ascertaining that the recipient understands it.
|
||||
|
||||
The messages are grouped logically into 4 groups by their most significant set bit:
|
||||
A sending node:
|
||||
- MUST NOT send an evenly-typed message not listed here, without prior negotiation.
|
||||
|
||||
- Setup & Control (types `0`-`31`): messages related to connection setup, control, supported features, and error reporting. These are described below.
|
||||
- Channel (types `32`-`127`): comprises messages used to setup and tear down micropayment channels. These are described in [BOLT #2](02-peer-protocol.md).
|
||||
- Commitment (types `128`-`255`): comprises 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](02-peer-protocol.md).
|
||||
- Routing (types `256`-`511`): node and channel announcements, as well as any active route exploration. These are described in [BOLT #7](07-routing-gossip.md).
|
||||
A receiving node:
|
||||
- upon receiving a message of _odd_, unknown type:
|
||||
- MUST ignore the received message.
|
||||
- upon receiving a message of _even_, unknown type:
|
||||
- MUST fail the channels.
|
||||
|
||||
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.
|
||||
A node which understands an option (each is numbered) MUST include all the fields annotated with that option.
|
||||
The messages are grouped logically into four 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](02-peer-protocol.md).
|
||||
- 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](02-peer-protocol.md).
|
||||
- Routing (types `256`-`511`): node and channel announcements, as well as any active route exploration. These are described in [BOLT #7](07-routing-gossip.md).
|
||||
|
||||
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.
|
||||
- upon receiving a known message with insufficient length for the contents:
|
||||
- MUST fail the channels.
|
||||
- that understands an option (each is numbered):
|
||||
- MUST include all the fields annotated with that option.
|
||||
|
||||
### Rationale
|
||||
|
||||
|
|
@ -61,24 +70,24 @@ 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
|
||||
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
|
||||
Implementations may prefer to have message data aligned on an 8-byte
|
||||
boundary (the largest natural alignment requirement of any type here);
|
||||
however, 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.
|
||||
a buffer with 6-bytes of pre-padding.
|
||||
|
||||
## Setup Messages
|
||||
|
||||
### The `init` message
|
||||
### 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](09-features.md) 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.
|
||||
[BOLT #9](09-features.md) 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.
|
||||
Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with 0s.
|
||||
|
||||
1. type: 16 (`init`)
|
||||
2. data:
|
||||
|
|
@ -87,41 +96,38 @@ Both fields `globalfeatures` and `localfeatures` MUST be padded to bytes with ze
|
|||
* [`2`:`lflen`]
|
||||
* [`lflen`:`localfeatures`]
|
||||
|
||||
The 2 byte `gflen` and `lflen` fields indicate the number of bytes in the immediately following field.
|
||||
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 sending node:
|
||||
- MUST send `init` as the first Lightning message for any connection.
|
||||
- MUST set feature bits as defined in [BOLT #9](09-features.md).
|
||||
- MUST set any undefined feature bits to 0.
|
||||
- SHOULD use the minimum lengths required to represent the feature fields.
|
||||
|
||||
The sender MUST set feature bits as defined in [BOLT #9](09-features.md),
|
||||
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](09-features.md). 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.
|
||||
The receiving node:
|
||||
- MUST wait to receive `init` before sending any other messages.
|
||||
- MUST respond to known feature bits as specified in [BOLT #9](09-features.md).
|
||||
- upon receiving _odd_ feature bits which are non-zero:
|
||||
- MUST ignore the bit.
|
||||
- upon receiving _even_ feature bits which are non-zero:
|
||||
- MUST fail the connection.
|
||||
|
||||
#### Rationale
|
||||
|
||||
This semantic allows future incompatible changes, or backward
|
||||
compatible changes. Bits should generally be assigned in pairs, so
|
||||
that optional features can later become compulsory.
|
||||
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 where features are incompatible.
|
||||
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 feature masks are split into local features (which only affect the
|
||||
protocol between these two nodes) and global features (which can affect
|
||||
HTLCs) and are thus also advertised to other nodes.
|
||||
|
||||
### The `error` message
|
||||
### The `error` Message
|
||||
|
||||
For simplicity of diagnosis, it is often useful to tell the peer that something is incorrect.
|
||||
For simplicity of diagnosis, it's often useful to tell a peer that something is incorrect.
|
||||
|
||||
1. type: 17 (`error`)
|
||||
2. data:
|
||||
|
|
@ -133,53 +139,66 @@ The 2-byte `len` field indicates the number of bytes in the immediately followin
|
|||
|
||||
#### Requirements
|
||||
|
||||
The channel is referred to by `channel_id` unless `channel_id` is zero (ie. all bytes zero), in which case it refers to all channels.
|
||||
The channel is referred to by `channel_id`, unless `channel_id` is 0 (i.e. all bytes are 0), 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.
|
||||
The funding node:
|
||||
- for all error messages sent before (and including) the `funding_created` message:
|
||||
- MUST use `temporary_channel_id` in lieu of `channel_id`.
|
||||
|
||||
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.
|
||||
The fundee node:
|
||||
- for all error messages sent before (and not including) the `funding_signed` message:
|
||||
- MUST use `temporary_channel_id` in lieu of `channel_id`.
|
||||
|
||||
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 sending node:
|
||||
- when sending `error`:
|
||||
- MUST fail the channel referred to by the error message.
|
||||
- SHOULD send `error` for protocol violations or internal errors which make channels unusable or further communication unusable.
|
||||
- MAY send an empty `data` field.
|
||||
- when failure was caused by an invalid signature check:
|
||||
- SHOULD include the raw, hex-encoded transaction in reply to a `funding_created`, `funding_signed`, `closing_signed`, or `commitment_signed` message.
|
||||
- when `channel_id` is 0:
|
||||
- MUST fail all channels.
|
||||
- MUST close the connection.
|
||||
- MUST set `len` equal to the length of `data`.
|
||||
|
||||
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.
|
||||
The receiving node:
|
||||
- upon receiving `error`:
|
||||
- MUST fail the channel referred to by the error message.
|
||||
- if no existing channel is referred to by the message:
|
||||
- MUST ignore the message.
|
||||
- MUST truncate `len` to the remainder of the packet (if it's larger).
|
||||
- if `data` is not composed solely of printable ASCII characters (For reference: the printable character set includes byte values 32 through 127, inclusive):
|
||||
- SHOULD NOT print out `data` verbatim.
|
||||
|
||||
#### 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.
|
||||
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.
|
||||
|
||||
It may be wise not to distinguish errors in production settings, lest
|
||||
it leak information, thus the optional `data` field.
|
||||
it leak information — hence, the optional `data` field.
|
||||
|
||||
## Control Messages
|
||||
|
||||
### The `ping` and `pong` 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.
|
||||
application level. Such messages also allow obfuscation of traffic patterns.
|
||||
|
||||
1. type: 18 (`ping`)
|
||||
2. data:
|
||||
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
|
||||
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
|
||||
included within the data payload of the `pong` message.
|
||||
|
||||
1. type: 19 (`pong`)
|
||||
2. data:
|
||||
|
|
@ -188,43 +207,51 @@ included within the data payload of the `pong` message
|
|||
|
||||
#### 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
|
||||
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 terminate the network connection,
|
||||
- and MUST NOT fail the channels in this case.
|
||||
- SHOULD NOT send `ping` messages more often than once every 30 seconds.
|
||||
|
||||
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 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 `ping` message SHOULD fail the channels if it has received
|
||||
significantly in excess of one `ping` per 30 seconds, otherwise 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 `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:
|
||||
- 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 receiving a `pong` message MAY fail the channels if `byteslen` does not
|
||||
correspond to any `ping` `num_pong_bytes` value it has sent.
|
||||
A node receiving a `pong` message:
|
||||
- if `byteslen` does not correspond to any `ping`'s `num_pong_bytes` value it has sent:
|
||||
- MAY fail the channels.
|
||||
|
||||
### Rationale
|
||||
|
||||
The largest possible message is 65535 bytes, thus maximum sensible `byteslen`
|
||||
is 65531 to account for the type field (`pong`) and `byteslen` itself. This
|
||||
gives us a convenient cutoff for `num_pong_bytes` to indicate that no reply
|
||||
should be sent.
|
||||
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
|
||||
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, and also to keep the established connection active.
|
||||
significant portion of the lifetime of a connection, no new data will be
|
||||
exchanged. 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
|
||||
against packet and timing analysis — as nodes can fake the traffic patterns of
|
||||
typical exchanges, without applying any true updates to their respective
|
||||
channels.
|
||||
channels.
|
||||
|
||||
When combined with the onion routing protocol defined in
|
||||
[BOLT #4](https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md),
|
||||
|
|
@ -232,25 +259,23 @@ 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
|
||||
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/lightningnetwork/lightning-rfc/blob/master/08-transport.md).
|
||||
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
TODO(roasbeef); fin
|
||||
|
||||
[ TODO: (roasbeef); fin ]
|
||||
|
||||
## References
|
||||
1. <a id="reference-2">http://www.unicode.org/charts/PDF/U2600.pdf</a>
|
||||
|
||||
## Authors
|
||||
|
||||
FIXME
|
||||
[ FIXME: Insert Author List ]
|
||||
|
||||
|
||||
<br>
|
||||
|
|
|
|||
1082
02-peer-protocol.md
1082
02-peer-protocol.md
File diff suppressed because it is too large
Load diff
Loading…
Add table
Reference in a new issue