BOLT12 recurrence spec update

.msggen.json

@@ -3128,11 +3128,14 @@
             "Offer.description": 2,
             "Offer.issuer": 3,
             "Offer.label": 4,
+            "Offer.optional_recurrence": 14,
+            "Offer.proportional_amount": 15,
             "Offer.quantity_max": 5,
             "Offer.recurrence": 7,
             "Offer.recurrence_base": 8,
             "Offer.recurrence_limit": 10,
             "Offer.recurrence_paywindow": 9,
+            "Offer.recurrence_proportional": 13,
             "Offer.recurrence_start_any_period": 12,
             "Offer.single_use": 11
         },
@@ -11268,6 +11271,14 @@
             "added": "pre-v0.10.1",
             "deprecated": null
         },
+        "Offer.optional_recurrence": {
+            "added": "v25.09",
+            "deprecated": null
+        },
+        "Offer.proportional_amount": {
+            "added": "v25.09",
+            "deprecated": null
+        },
         "Offer.quantity_max": {
             "added": "pre-v0.10.1",
             "deprecated": null
@@ -11320,6 +11331,10 @@
             "added": "pre-v0.10.1",
             "deprecated": null
         },
+        "Offer.recurrence_proportional": {
+            "added": "v25.09",
+            "deprecated": null
+        },
         "Offer.recurrence_start_any_period": {
             "added": "v24.02",
             "deprecated": null

common/bolt12.c

@@ -377,11 +377,6 @@ static void add_months(struct tm *tm, u32 number)
 	tm->tm_mon += number;
 }
 
-static void add_years(struct tm *tm, u32 number)
-{
-	tm->tm_year += number;
-}
-
 static u64 time_change(u64 prevstart, u32 number,
 		       void (*add_time)(struct tm *tm, u32 number),
 		       bool day_const)
@@ -412,8 +407,7 @@ u64 offer_period_start(u64 basetime, size_t n,
 		       const struct recurrence *recur)
 {
 	/* BOLT-recurrence #12:
-	 * 1. A `time_unit` defining 0 (seconds), 1 (days), 2 (months),
-	 *    3 (years).
+	 * 1. A `time_unit` defining 0 (seconds), 1 (days), 2 (months).
 	 */
 	switch (recur->time_unit) {
 	case 0:
@@ -422,8 +416,6 @@ u64 offer_period_start(u64 basetime, size_t n,
 		return time_change(basetime, recur->period * n, add_days, false);
 	case 2:
 		return time_change(basetime, recur->period * n, add_months, true);
-	case 3:
-		return time_change(basetime, recur->period * n, add_years, true);
 	default:
 		/* This is our offer, how did we get here? */
 		return 0;
@@ -437,17 +429,17 @@ void offer_period_paywindow(const struct recurrence *recurrence,
 			    u64 *start, u64 *end)
 {
 	/* BOLT-recurrence #12:
-	 * - if the offer contains `recurrence_paywindow`:
+	 * - if `offer_recurrence_paywindow` is present:
 	 */
 	if (recurrence_paywindow) {
 		u64 pstart = offer_period_start(basetime, period_idx,
 						recurrence);
 		/* BOLT-recurrence #12:
-		 * - if the offer has a `recurrence_basetime` or the
+		 * - if `recurrence_basetime` is present or
 		 *    `recurrence_counter` is non-zero:
-		 *   - SHOULD NOT send an `invreq` for a period prior to
+		 *   - SHOULD NOT send an `invoice_request` for a period prior to
 		 *     `seconds_before` seconds before that period start.
-		 *   - SHOULD NOT send an `invreq` for a period later
+		 *   - SHOULD NOT send an `invoice_request` for a period later
 		 *     than `seconds_after` seconds past that period start.
 		 */
 		*start = pstart - recurrence_paywindow->seconds_before;
@@ -462,9 +454,9 @@ void offer_period_paywindow(const struct recurrence *recurrence,
 	} else {
 		/* BOLT-recurrence #12:
 		 * - otherwise:
-		 *   - SHOULD NOT send an `invreq` with
-		 *     `recurrence_counter` is non-zero for a period whose
-		 *     immediate predecessor has not yet begun.
+		 *   - SHOULD NOT send an `invoice_request` with
+		 *     non-zero `recurrence_counter` for a period
+		 *     whose immediate predecessor has not yet begun.
 		 */
 		if (period_idx == 0)
 			*start = 0;
@@ -473,7 +465,7 @@ void offer_period_paywindow(const struct recurrence *recurrence,
 						    recurrence);
 
 		/* BOLT-recurrence #12:
-		 *     - SHOULD NOT send an `invreq` for a period which
+		 *     - SHOULD NOT send an `invoice_request` for a period which
 		 *       has already passed.
 		 */
 		*end = offer_period_start(basetime, period_idx+1,
@@ -815,3 +807,24 @@ bool bolt12_bip353_valid_string(const u8 *str, size_t len)
 	}
 	return true;
 }
+
+const struct recurrence *offer_recurrence(const struct tlv_offer *offer)
+{
+	if (offer->offer_recurrence_compulsory)
+		return offer->offer_recurrence_compulsory;
+	return offer->offer_recurrence_optional;
+}
+
+const struct recurrence *invreq_recurrence(const struct tlv_invoice_request *invreq)
+{
+	if (invreq->offer_recurrence_compulsory)
+		return invreq->offer_recurrence_compulsory;
+	return invreq->offer_recurrence_optional;
+}
+
+const struct recurrence *invoice_recurrence(const struct tlv_invoice *inv)
+{
+	if (inv->offer_recurrence_compulsory)
+		return inv->offer_recurrence_compulsory;
+	return inv->offer_recurrence_optional;
+}

common/bolt12.h

@@ -182,4 +182,9 @@ const struct tlv_field *any_field_outside_range(const struct tlv_field *fields,
  *     `A`-`Z`, `-`, `_` or `.`.
  */
 bool bolt12_bip353_valid_string(const u8 *str, size_t strlen);
+
+/* Extract either offer_recurrence_compulsory or offer_recurrence_optional */
+const struct recurrence *offer_recurrence(const struct tlv_offer *offer);
+const struct recurrence *invreq_recurrence(const struct tlv_invoice_request *invreq);
+const struct recurrence *invoice_recurrence(const struct tlv_invoice *inv);
 #endif /* LIGHTNING_COMMON_BOLT12_H */

common/json_param.h

@@ -51,8 +51,8 @@ bool param(struct command *cmd, const char *buffer,
 
 /*
  * Version which *doesn't* fail if command_check_only(cmd) is true:
- * allows you can do extra checks after, but MUST still fail with
- * command_param_failed(); if command_check_only(cmd) is true! */
+ * allows you can do extra checks after, but MUST terminate
+ * with command_check_done() if command_check_only(cmd) is true! */
 bool param_check(struct command *cmd,
 		 const char *buffer,
 		 const jsmntok_t tokens[], ...) LAST_ARG_NULL;