common: fix up BOLT 4 references.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

common/sphinx.c

@@ -464,7 +464,8 @@ u8 *create_onionreply(const tal_t *ctx, const struct secret *shared_secret,
 
 	/* BOLT #4:
 	 *
-	 * The node returning the message builds a return packet consisting of
+	 * The node generating the error message (_erring node_) builds a return
+	 * packet consisting of
 	 * the following fields:
 	 *
 	 * 1. data:
@@ -481,16 +482,18 @@ u8 *create_onionreply(const tal_t *ctx, const struct secret *shared_secret,
 
 	/* BOLT #4:
 	 *
-	 * The node SHOULD set `pad` such that the `failure_len` plus
-	 * `pad_len` is equal to 256.  This is 118 bytes longer than then the
-	 * longest currently-defined message.
+	 * The _erring node_:
+	 *   - SHOULD set `pad` such that the `failure_len` plus `pad_len` is
+	 *     equal to 256.
+	 *     - Note: this value is 118 bytes longer than the longest
+	 *       currently-defined message.
 	 */
 	assert(tal_len(payload) == ONION_REPLY_SIZE + 4);
 
 	/* BOLT #4:
 	 *
  	 * Where `hmac` is an HMAC authenticating the remainder of the packet,
-	 * with a key using the above key generation with key type `um`
+	 * with a key generated using the above process, with key type `um`
 	 */
 	generate_key(key, "um", 2, shared_secret->data);
 
@@ -513,11 +516,11 @@ u8 *wrap_onionreply(const tal_t *ctx,
 
 	/* BOLT #4:
 	 *
-	 * The node then generates a new key, using the key type `ammag`.
+	 * The erring node then generates a new key, using the key type `ammag`.
 	 * This key is then used to generate a pseudo-random stream, which is
-	 * then applied to the packet using `XOR`.
+	 * in turn applied to the packet using `XOR`.
 	 *
-	 * The obfuscation step is repeated by every node on the return path.
+	 * The obfuscation step is repeated by every hop along the return path.
 	 */
 	generate_key(key, "ammag", 5, shared_secret->data);
 	generate_cipher_stream(stream, key, streamlen);

common/sphinx.h

@@ -35,9 +35,9 @@ enum route_next_case {
 
 /* BOLT #4:
  *
- * The `hops_data` field is a structure that holds obfuscated versions of the
- * next hop's address, transfer information and the associated HMAC. It is
- * 1300 bytes long, and has the following structure:
+ * The `hops_data` field is a structure that holds obfuscations of the
+ * next hop's address, transfer information, and its associated HMAC. It is
+ * 1300 bytes (`20x65`) long and has the following structure:
  *
  * 1. type: `hops_data`
  * 2. data:
@@ -47,14 +47,14 @@ enum route_next_case {
  *    * ...
  *    * `filler`
  *
- * Where the `realm`, `HMAC` and `per_hop` (whose contents depend on `realm`)
- * are repeated for each hop, and `filler` consists of obfuscated
- * deterministically generated padding. For details about how the `filler` is
- * generated please see below. In addition, `hops_data` is incrementally
- * obfuscated at each hop.
+ * Where, the `realm`, `per_hop` (with contents dependent on `realm`), and `HMAC`
+ * are repeated for each hop; and where, `filler` consists of obfuscated,
+ * deterministically-generated padding, as detailed in
+ * [Filler Generation](#filler-generation).  Additionally, `hops_data` is
+ * incrementally obfuscated at each hop.
  *
- * The `realm` byte determines the format of the `per_hop`; so far only
- * `realm` 0 is defined, and for that, the `per_hop` format is:
+ * The `realm` byte determines the format of the `per_hop` field; currently, only
+ * `realm` 0 is defined, for which the `per_hop` format follows:
  *
  * 1. type: `per_hop` (for `realm` 0)
  * 2. data: