Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Suggested update for PR#134
commit 108869b8cdfa33c4ae4b842e990047b6b1e805a2
Author: Rusty Russell <>
Date: Fri Mar 31 13:21:35 2017 +1030
1. rename randombytes to ignored, and say they SHOULD BE zero. Simpler.
2. Add explicit padding field to `ping`: that keeps it extensible.
3. Split requirements into sender and receiver; they're kind of intertwined
so let's combine the two sections.
4. Let num_pong_bytes >= 65534 (which would be impossible) mean "no reply",
which ensures they check that case, as well as allowing better synthetic
5. Spell out failure options on flooding, but note other flooding avenues.
Signed-off-by: Rusty Russell <>
diff --git a/ b/
index 12c506c..d8cb852 100644
--- a/
+++ b/
@@ -15,8 +15,7 @@ All data fields are big-endian unless otherwise specified.
* [The `init` message](#the-init-message)
* [The `error` message](#the-error-message)
* [Control Messages](#control-messages)
- * [The `ping` message](#the-ping-message)
- * [The `pong` message](#the-pong-message)
+ * [The `ping` and `pong` messages](#the-ping-and-pong-messages)
* [Acknowledgements](#acknowledgements)
* [References](#references)
* [Authors](#authors)
@@ -158,44 +157,43 @@ it leak information, thus the optional data field.
## Control Messages
-### The `ping` message
+### 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.
+application level. Such messages also allow obsfusation of traffic
1. type: 18 (`ping`)
2. data:
* [2:num_pong_bytes]
-#### Requirements
-A node receiving a `ping` message MUST respond with a `pong` message that
-contains the specified `num_pong_bytes` number of bytes within it's data
-payload. These `ping` messages may be sent any time at the sender's discretion,
-however `ping` messages MUST NOT be sent with a frequency lower than one every
-30 seconds.
-### The `pong` message
-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.
+ * [2:byteslen]
+ * [byteslen:ignored]
1. type: 19 (`pong`)
2. data:
* [2:byteslen]
- * [byteslen:randombytes]
+ * [byteslen:ignored]
#### Requirements
-A `pong` message MUST only be sent in response to receiving a `ping` message.
-Within the received `ping` message, the sender will specify the number of bytes
-to be included within the data payload of the `pong` message. Senders of the
-`pong` message may retrieve the payload bytes from any source as the bytes are
-opaque and convey no meaning. Senders of a `pong` message SHOULD take care to
-ensure that the bytes being sent don't contain sensitive data such as secrets,
-or portions of initialized memory.
+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
+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 65534 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
@@ -219,6 +217,11 @@ When combined with the onion routing protocol defined in
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](
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.