doc: clean up offers bolt quotes

As of 2b923a0367c5f9154fcec706e3302cc4658dd889. Recurrence quotes need to be marked separately, since they're no longer in offers main bolt. Signed-off-by: Rusty Russell <[email protected]>
okeygo · Nov 30, 2021 · 163d3a1 · 163d3a1
1 parent 894f184
commit 163d3a1
Show file tree

Hide file tree

Showing 9 changed files with 63 additions and 57 deletions.
diff --git a/common/bolt12.c b/common/bolt12.c
@@ -22,15 +22,10 @@ bool bolt12_chains_match(const struct bitcoin_blkid *chains,
 	/* BOLT-offers #12:
 	 * The reader of an invoice_request:
 	 *...
-	 *  - MUST fail the request if `chains` does not include (or
-	 *    imply) a supported chain.
-	 */
-	/* BOLT-offers #12:
-	 *
-	 * - if the chain for the invoice is not solely bitcoin:
-	 *   - MUST specify `chains` the invoice is valid for.
-	 * - otherwise:
-	 *   - the bitcoin chain is implied as the first and only entry.
+	 *  - if `chain` is not present:
+	 *    - MUST fail the request if bitcoin is not a supported chain.
+	 *  - otherwise:
+	 *    - MUST fail the request if `chain` is not a supported chain.
 	 */
 	num_chains = tal_count(chains);
 	if (num_chains == 0) {
@@ -340,7 +335,7 @@ static u64 time_change(u64 prevstart, u32 number,
 u64 offer_period_start(u64 basetime, size_t n,
 		       const struct tlv_offer_recurrence *recur)
 {
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * 1. A `time_unit` defining 0 (seconds), 1 (days), 2 (months),
 	 *    3 (years).
 	 */
@@ -365,13 +360,13 @@ void offer_period_paywindow(const struct tlv_offer_recurrence *recurrence,
 			    u64 basetime, u64 period_idx,
 			    u64 *start, u64 *end)
 {
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * - if the offer contains `recurrence_paywindow`:
 	 */
 	if (recurrence_paywindow) {
 		u64 pstart = offer_period_start(basetime, period_idx,
 						recurrence);
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - if the offer has a `recurrence_basetime` or the
 		 *    `recurrence_counter` is non-zero:
 		 *   - SHOULD NOT send an `invoice_request` for a period prior to
@@ -389,7 +384,7 @@ void offer_period_paywindow(const struct tlv_offer_recurrence *recurrence,
 		    && recurrence_paywindow->seconds_after < 60)
 			*end = pstart + 60;
 	} else {
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - otherwise:
 		 *   - SHOULD NOT send an `invoice_request` with
 		 *     `recurrence_counter` is non-zero for a period whose
@@ -401,7 +396,7 @@ void offer_period_paywindow(const struct tlv_offer_recurrence *recurrence,
 			*start = offer_period_start(basetime, period_idx-1,
 						    recurrence);
 
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 *     - SHOULD NOT send an `invoice_request` for a period which
 		 *       has already passed.
 		 */

diff --git a/common/bolt12_merkle.c b/common/bolt12_merkle.c
@@ -54,7 +54,7 @@ static void h_simpletag_ctx(struct sha256_ctx *sctx, const char *tag)
 /* BOLT-offers #12:
  * The Merkle tree's leaves are, in TLV-ascending order for each tlv:
  * 1. The H(`LnLeaf`,tlv).
- * 2. The H(`LnAll`|all-tlvs,tlv) where "all-tlvs" consists of all non-signature TLV entries appended in ascending order.
+ * 2. The H(`LnAll`||all-tlvs,tlv) where "all-tlvs" consists of all non-signature TLV entries appended in ascending order.
  */
 
 /* Create a sha256_ctx which has the tag part done. */
@@ -107,7 +107,7 @@ static void calc_lnleaf(const struct tlv_field *field, struct sha256 *hash)
 }
 
 /* BOLT-offers #12:
- * The Merkle tree inner nodes are H(`LnBranch`, lesser-SHA256|greater-SHA256);
+ * The Merkle tree inner nodes are H(`LnBranch`, lesser-SHA256||greater-SHA256)
  */
 static struct sha256 *merkle_pair(const tal_t *ctx,
 				  const struct sha256 *a, const struct sha256 *b)
@@ -200,11 +200,11 @@ void merkle_tlv(const struct tlv_field *fields, struct sha256 *merkle)
  *
  * Each form is signed using one or more TLV signature elements; TLV
  * types 240 through 1000 are considered signature elements.  For these
- * the tag is `lightning` | `messagename` | `fieldname`, and `msg` is the
- * Merkle-root; `lightning` is the literal 9-byte ASCII string,
- * `messagename` is the name of the TLV stream being signed (i.e. `offer`,
- * `invoice_request` or `invoice`) and the `fieldname` is the TLV field
- * containing the signature (e.g. `signature` or `payer_signature`).
+ * the tag is "lightning" || `messagename` || `fieldname`, and `msg` is the
+ * Merkle-root; "lightning" is the literal 9-byte ASCII string,
+ * `messagename` is the name of the TLV stream being signed (i.e. "offer",
+ * "invoice_request" or "invoice") and the `fieldname` is the TLV field
+ * containing the signature (e.g. "signature" or "payer_signature").
  */
 void sighash_from_merkle(const char *messagename,
 			 const char *fieldname,

diff --git a/common/features.h b/common/features.h
@@ -135,7 +135,7 @@ const char *fmt_featurebits(const tal_t *ctx, const u8 *featurebits);
  */
 #define OPT_QUIESCE 				34
 
-/* BOLT-1ede04a1a3225581e265b3ce96984ba88253a4a4 #9:
+/* BOLT-offers #9:
  *
  * | 38/39 | `option_onion_messages` |... IN ...
  */

diff --git a/devtools/bolt12-cli.c b/devtools/bolt12-cli.c
@@ -174,8 +174,8 @@ static bool print_recurrance(const struct tlv_offer_recurrence *recurrence,
 	const char *unit;
 	bool ok = true;
 
-	/* BOLT-offers #12:
-	 * Thus, each payment has:
+	/* BOLT-offers-recurrence #12:
+	 * Thus, each offer containing a recurring payment has:
 	 * 1. A `time_unit` defining 0 (seconds), 1 (days), 2 (months),
 	 *    3 (years).
 	 * 2. A `period`, defining how often (in `time_unit`) it has to be paid.

diff --git a/lightningd/offer.c b/lightningd/offer.c
@@ -310,7 +310,7 @@ static struct command_result *prev_payment(struct command *cmd,
 		if (!inv->recurrence_counter)
 			continue;
 
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - if the offer contained `recurrence_base` with
 		 *   `start_any_period` non-zero:
 		 *   - MUST include `recurrence_start`

diff --git a/plugins/fetchinvoice.c b/plugins/fetchinvoice.c
@@ -238,6 +238,15 @@ static struct command_result *handle_invreq_response(struct command *cmd,
 		goto badinv;
 
 	/* BOLT-offers #12:
+	 * - if the invoice is a reply to an `invoice_request`:
+	 *...
+	 *   - MUST reject the invoice unless the following fields are equal or
+	 *     unset exactly as they are in the `invoice_request:`
+	 *     - `quantity`
+	 *     - `payer_key`
+	 *     - `payer_info`
+	 */
+	/* BOLT-offers-recurrence #12:
 	 * - if the invoice is a reply to an `invoice_request`:
 	 *...
 	 *   - MUST reject the invoice unless the following fields are equal or
@@ -279,7 +288,7 @@ static struct command_result *handle_invreq_response(struct command *cmd,
 	} else
 		expected_amount = NULL;
 
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * - if the offer contained `recurrence`:
 	 *   - MUST reject the invoice if `recurrence_basetime` is not set.
 	 */
@@ -1080,7 +1089,7 @@ static struct command_result *invreq_done(struct command *cmd,
 		if (sent->invreq->recurrence_start)
 			period_idx += *sent->invreq->recurrence_start;
 
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - if the offer contained `recurrence_limit`:
 		 *   - MUST NOT send an `invoice_request` for a period greater
 		 *     than `max_period`
@@ -1093,7 +1102,7 @@ static struct command_result *invreq_done(struct command *cmd,
 					    period_idx,
 					    *sent->offer->recurrence_limit);
 
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - SHOULD NOT send an `invoice_request` for a period which has
 		 *   already passed.
 		 */
@@ -1257,11 +1266,11 @@ static struct command_result *json_fetchinvoice(struct command *cmd,
 	    && time_now().ts.tv_sec > *sent->offer->absolute_expiry)
 		return command_fail(cmd, OFFER_EXPIRED, "Offer expired");
 
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * - if the offer did not specify `amount`:
 	 *   - MUST specify `amount`.`msat` in multiples of the minimum
-	 *     lightning-payable unit (e.g. milli-satoshis for bitcoin) for the
-	 *     first `chains` entry.
+	 *     lightning-payable unit (e.g. milli-satoshis for bitcoin) for
+	 *     `chain` (or for bitcoin, if there is no `chain`).
 	 * - otherwise:
 	 *   - MAY omit `amount`.
 	 *     - if it sets `amount`:
@@ -1309,16 +1318,16 @@ static struct command_result *json_fetchinvoice(struct command *cmd,
 					    "quantity parameter unnecessary");
 	}
 
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * - if the offer contained `recurrence`:
 	 */
 	if (sent->offer->recurrence) {
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 *    - for the initial request:
 		 *...
 		 *      - MUST set `recurrence_counter` `counter` to 0.
 		 */
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 *    - for any successive requests:
 		 *...
 		 *      - MUST set `recurrence_counter` `counter` to one greater
@@ -1328,7 +1337,7 @@ static struct command_result *json_fetchinvoice(struct command *cmd,
 			return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
 					    "needs recurrence_counter");
 
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 *    - if the offer contained `recurrence_base` with
 		 *      `start_any_period` non-zero:
 		 *      - MUST include `recurrence_start`
@@ -1353,7 +1362,7 @@ static struct command_result *json_fetchinvoice(struct command *cmd,
 			return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
 					    "needs recurrence_label");
 	} else {
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - otherwise:
 		 *   - MUST NOT set `recurrence_counter`.
 		 *   - MUST NOT set `recurrence_start`
@@ -1758,9 +1767,7 @@ static struct command_result *json_sendinvoice(struct command *cmd,
 	 */
 	sent->inv->payer_key = sent->offer->node_id;
 
-	/* BOLT-offers #12:
-	 *     - FIXME: recurrence!
-	 */
+	/* FIXME: recurrence? */
 	if (sent->offer->recurrence)
 		return command_fail(cmd, JSONRPC2_INVALID_PARAMS,
 				    "FIXME: handle recurring send_invoice offer!");

diff --git a/plugins/offers.c b/plugins/offers.c
@@ -339,7 +339,7 @@ static bool json_add_blinded_paths(struct json_stream *js,
 
 static const char *recurrence_time_unit_name(u8 time_unit)
 {
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * `time_unit` defining 0 (seconds), 1 (days), 2 (months), 3 (years).
 	 */
 	switch (time_unit) {
@@ -608,7 +608,7 @@ static void json_add_b12_invoice(struct json_stream *js,
 		if (invoice->recurrence_start)
 			json_add_u32(js, "recurrence_start",
 				     *invoice->recurrence_start);
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - if the offer contained `recurrence`:
 		 *   - MUST reject the invoice if `recurrence_basetime` is not
 		 *     set.
@@ -733,7 +733,7 @@ static void json_add_invoice_request(struct json_stream *js,
 
 	/* BOLT-offers #12:
 	 * - MUST fail the request if `payer_key` is not present.
-	 * - MUST fail the request if `chains` does not include (or imply) a supported chain.
+	 *...
 	 * - MUST fail the request if `features` contains unknown even bits.
 	 * - MUST fail the request if `offer_id` is not present.
 	 */

diff --git a/plugins/offers_inv_hook.c b/plugins/offers_inv_hook.c
@@ -354,8 +354,10 @@ struct command_result *handle_invoice(struct command *cmd,
 	 *
 	 * The reader of an invoice_request:
 	 *...
-	 *   - MUST fail the request if `chains` does not include (or imply) a
-	 *     supported chain.
+	 *   - if `chain` is not present:
+	 *     - MUST fail the request if bitcoin is not a supported chain.
+	 *   - otherwise:
+	 *     - MUST fail the request if `chain` is not a supported chain.
 	 */
 	if (!bolt12_chain_matches(inv->inv->chain, chainparams, inv->inv->chains)) {
 		return fail_inv(cmd, inv,

diff --git a/plugins/offers_invreq_hook.c b/plugins/offers_invreq_hook.c
@@ -109,7 +109,7 @@ test_field(struct command *cmd,
 	return NULL;
 }
 
-/* BOLT-offers #12:
+/* BOLT-offers-recurrence #12:
  * - if the invoice corresponds to an offer with `recurrence`:
  * ...
  *   - if it sets `relative_expiry`:
@@ -230,7 +230,7 @@ static struct command_result *check_period(struct command *cmd,
 	if (ir->offer->recurrence_base)
 		basetime = ir->offer->recurrence_base->basetime;
 
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * - if the invoice corresponds to an offer with `recurrence`:
 	 *   - MUST set `recurrence_basetime` to the start of period #0 as
 	 *     calculated by [Period Calculation](#offer-period-calculation).
@@ -239,7 +239,7 @@ static struct command_result *check_period(struct command *cmd,
 
 	period_idx = *ir->invreq->recurrence_counter;
 
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * - if the offer had `recurrence_base` and `start_any_period`
 	 *   was 1:
 	 *   - MUST fail the request if there is no `recurrence_start`
@@ -255,14 +255,14 @@ static struct command_result *check_period(struct command *cmd,
 			return err;
 		period_idx += *ir->invreq->recurrence_start;
 
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - MUST set (or not set) `recurrence_start` exactly as the
 		 *   invoice_request did.
 		 */
 		ir->inv->recurrence_start
 			= tal_dup(ir->inv, u32, ir->invreq->recurrence_start);
 	} else {
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 *
 		 * - otherwise:
 		 *   - MUST fail the request if there is a `recurrence_start`
@@ -275,7 +275,7 @@ static struct command_result *check_period(struct command *cmd,
 			return err;
 	}
 
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * - if the offer has a `recurrence_limit`:
 	 *   - MUST fail the request if the period index is greater than
 	 *     `max_period`.
@@ -309,7 +309,7 @@ static struct command_result *check_period(struct command *cmd,
 
 	set_recurring_inv_expiry(ir->inv, paywindow_end);
 
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 *
 	 * - if `recurrence_counter` is non-zero:
 	 *...
@@ -475,7 +475,7 @@ static struct command_result *invreq_base_amount_simple(struct command *cmd,
 
 		*amt = amount_msat(raw_amount);
 	} else {
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 *
 		 * - otherwise:
 		 * - MUST fail the request if it does not contain `amount`.
@@ -534,7 +534,7 @@ static struct command_result *handle_amount_and_recurrence(struct command *cmd,
 	/* Last of all, we handle recurrence details, which often requires
 	 * further lookups. */
 
-	/* BOLT-offers #12:
+	/* BOLT-offers-recurrence #12:
 	 * - MUST set (or not set) `recurrence_counter` exactly as the
 	 *   invoice_request did.
 	 */
@@ -723,7 +723,7 @@ static struct command_result *listoffers_done(struct command *cmd,
 	}
 
 	if (ir->offer->recurrence) {
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 *
 		 * - if the offer had a `recurrence`:
 		 *   - MUST fail the request if there is no `recurrence_counter`
@@ -733,7 +733,7 @@ static struct command_result *listoffers_done(struct command *cmd,
 		if (err)
 			return err;
 	} else {
-		/* BOLT-offers #12:
+		/* BOLT-offers-recurrence #12:
 		 * - otherwise (the offer had no `recurrence`):
 		 *   - MUST fail the request if there is a `recurrence_counter`
 		 *     field.
@@ -870,8 +870,10 @@ struct command_result *handle_invoice_request(struct command *cmd,
 	 *
 	 * The reader of an invoice_request:
 	 *...
-	 *   - MUST fail the request if `chains` does not include (or imply) a
-	 *     supported chain.
+	 *  - if `chain` is not present:
+	 *    - MUST fail the request if bitcoin is not a supported chain.
+	 *  - otherwise:
+	 *    - MUST fail the request if `chain` is not a supported chain.
 	 */
 	if (!bolt12_chain_matches(ir->invreq->chain, chainparams,
 				  ir->invreq->chains)) {