From 0cf9f85fb73600b0fa468ff6b7889c289a7c7241 Mon Sep 17 00:00:00 2001
From: Rusty Russell <rusty@rustcorp.com.au>
Date: Sun, 17 Jun 2018 19:43:44 +0930
Subject: [PATCH] common: fix up BOLT 1 references.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
---
 common/ping.c       | 31 +++++++++++++++++++------------
 common/wire_error.c | 14 ++++++++------
 common/wire_error.h |  5 ++---
 common/wireaddr.h   |  2 +-
 4 files changed, 30 insertions(+), 22 deletions(-)

diff --git a/common/ping.c b/common/ping.c
index 992b9da49..977f621c1 100644
--- a/common/ping.c
+++ b/common/ping.c
@@ -15,23 +15,29 @@ bool check_ping_make_pong(const tal_t *ctx, const u8 *ping, u8 **pong)
 	/* FIXME: */
 	/* BOLT #1:
 	 *
-	 * A node receiving a `ping` message SHOULD fail the channels if it
-	 * has received significantly in excess of one `ping` per 30 seconds,
+	 * A node receiving a `ping` message:
+	 *  - SHOULD fail the channels if it has received significantly in
+	 *    excess of one `ping` per 30 seconds.
 	 */
 
 	/* BOLT #1:
 	 *
-	 * ... 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:
+	 *...
+	 *  - 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`.
 	 */
 	if (num_pong_bytes < 65532) {
 		/* BOLT #1:
 		 *
-		 * 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 sending a `pong` message:
+		 *   - SHOULD set `ignored` to 0s.
+		 *   - MUST NOT set `ignored` to sensitive data such as secrets
+		 *     or portions of initialized memory.
+		 */
 		ignored = tal_arrz(ctx, u8, num_pong_bytes);
 #if DEVELOPER
 		/* Embed version */
@@ -49,9 +55,10 @@ u8 *make_ping(const tal_t *ctx, u16 num_pong_bytes, u16 padlen)
 {
 	/* BOLT #1:
 	 *
-	 * 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 sending a `ping` message:
+	 *  - SHOULD set `ignored` to 0s.
+	 *  - MUST NOT set `ignored` to sensitive data such as secrets or
+	 *    portions of initialized memory.
 	 */
 	u8 *ping, *ignored = tal_arrz(ctx, u8, padlen);
 
diff --git a/common/wire_error.c b/common/wire_error.c
index 1b52f3a76..c8664f021 100644
--- a/common/wire_error.c
+++ b/common/wire_error.c
@@ -12,8 +12,8 @@ u8 *towire_errorfmtv(const tal_t *ctx,
 {
 	/* BOLT #1:
 	 *
-	 * The channel is referred to by `channel_id` unless `channel_id` is
-	 * zero (ie. all bytes zero), in which case it refers to all
+	 * 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. */
 	static const struct channel_id all_channels;
 	char *estr;
@@ -63,10 +63,12 @@ char *sanitize_error(const tal_t *ctx, const u8 *errmsg,
 
 	/* BOLT #1:
 	 *
-	 * 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:
+	 *...
+	 *  - if `data` is not composed solely of printable ASCII characters
+	 *   (For reference: the printable character set includes byte values 32
+	 *   through 126, inclusive):
+	 *    - SHOULD NOT print out `data` verbatim.
 	 */
 	for (i = 0; i < tal_len(data); i++) {
 		if (data[i] < 32 || data[i] > 127) {
diff --git a/common/wire_error.h b/common/wire_error.h
index e33533374..bf9ffa09b 100644
--- a/common/wire_error.h
+++ b/common/wire_error.h
@@ -34,9 +34,8 @@ u8 *towire_errorfmtv(const tal_t *ctx,
 
 /* BOLT #1:
  *
- * 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.
+ * 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.
  */
 /**
  * channel_id_is_all - True if channel_id is all zeroes.
diff --git a/common/wireaddr.h b/common/wireaddr.h
index 3ea63531b..9cab8fd9a 100644
--- a/common/wireaddr.h
+++ b/common/wireaddr.h
@@ -18,7 +18,7 @@ struct sockaddr_un;
 /* BOLT #1:
  *
  * The default TCP port is 9735. This corresponds to hexadecimal
- * `0x2607`, the Unicode code point for LIGHTNING.
+ * `0x2607`: the Unicode code point for LIGHTNING.
  */
 #define DEFAULT_PORT 9735