BOLT 12: re-add recurrence support.#1240
Conversation
This is taken from the old draft, and updated with modern field numbers and names. I've made some minor changes: 1. The `proportional_amount` field comes before `seconds_before` which seems more logical to me. 2. The `offer_absolute_expiry` is clarified to only apply to the *initial* invoice request: once you're recurring the other fields take over. The complexities mainly come from two sources: 1. A requirement to be precise about when recurrence happens. This is because we want a push system, not a pull, since only the former allows for real authorization by the user, and there are many different reasonable ways to do recurrence. 2. This is the first wallet feature which isn't just "fire and forget", but requires them to keep state and do unprompted actions. One proposal I would like to add is a courtesy onion message when a user cancels a periodic payment. This is generally useful to tell the difference between a deliberate cancellation and a user-related failure. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
| - add the offset days to get the day of the period start. | ||
| - if the day is not within the month, use the last day within the month. | ||
| - add the offset seconds to get the period start in seconds. |
There was a problem hiding this comment.
If the day is not within the month, we should use the last day of the month and the last second of that day.
We want a one month period starting on January 30th at 2AM to end before a one month period starting on January 31th at 1AM as it starts almost a full day later. However with your proposal, the former would end an hour after the latter.
There was a problem hiding this comment.
If you're having monthly recurrences, you don't care about +/- a day, BUT we have to define it somehow. I think you'll find this easier to implement as written, so I think that's better.
1. Remove start_any_period. If you want them not to start in a random period (only appliciable if you set `offer_recurrence_base`) then use offer_absolute_expiry. 2. Remove years, use months. 3. Clarify leap seconds. 4. Put `proportional_amount` inside `offer_recurrence_base` where it belongs, not inside paywindow. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Only offer_recurrence_base is compulsory, really. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
|
OK, updated. I will need to rework the test vectors, however! |
This allows the writer of the offer to decide how pre-recurrence-supporting wallets should behave. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
rustyrussell
force-pushed
the
guilt/offers-recurrence
branch
from
0ddbe23 to
147e86c
Compare
vincenzopalazzo
left a comment
vincenzopalazzo
left a comment
There was a problem hiding this comment.
LGTM overall, I want to take another look later in the month, but probably in this PR we can also remove the FIXME N 7 in the https://github.com/lightning/bolts/blob/master/12-offer-encoding.md#fixme-possible-future-extensions
Subscriptions likely require more communication. From the initial sharing of the offer, to price changes, to notifying a user about a missed payment, providing a receipt, etc. Maybe best to leave this type of communication up to the participants to handle in their medium of choice? |
@GBKS I agree that from a UX perspective there is always going to be more communication required between the subscriber and the recipient. However, if there is a protocol-native way to create a subscription, I think there also needs to be a protocol-native way to cancel the subscription. |
Maybe. You're creating a subscription proposal, but it's not active until the payee accepts it and acts on it. It's more like a subscription request, like we have payment requests. So if you want a "subscription cancelled" message, you may also want a "subscription accepted" message. But TBH, I don't have a super strong opinion. Just doesn't seem 100% right to exclusively have the cancel message. |
|
Note: @TheBlueMatt pointed out that the correct behavior is to send the courtesy "cancel" message in place of the next request. Slightly more complex to implement (your wallet now needs to remember cancelled subscriptions), but it's a nice balance between letting the vendor know, and not letting them cut you off early. Apparently Apple Pay does something similar, and I can see the logic. From an implementation POV, this may simply look like a stub invoice_request? |
That, however, has proven to be a centralized disaster, and severely limits interoperation. You cannot automate this unspecified stuff... Eventually we will probably want offer replacement (where we reject an invoice_request and optionally refers to an updated offer), but one step at a time! |
Thanks https://github.com/a-mpch! Also replace some errant tabs. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This is a best-effort message, but helps differentiate a deliberate cancellation by a user from wallet issues. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
|
Added the "cancel" flag. You basically send an invreq like normal, but it says "cancel" instead of "send me the next invoice". Also added the requirement to fetch the next invoice explicitly to the requirements for recurring payments! |
Recurrence has the same fields in offer, invoice_request and invoice, and bip_353_name has the same fields in invoice_request and invoice. This is slightly clearer, and it makes code generation cleaner (since they are clearly the same type, they are easier to use). Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Ramin078
left a comment
Ramin078
left a comment
There was a problem hiding this comment.
rustyrussell:guilt/offers-recurrence
Ramin078
left a comment
Ramin078
left a comment
There was a problem hiding this comment.
rustyrussell:guilt/offers-recurrence 69099
There was a problem hiding this comment.
Looks great on the first pass! 🚀
I’ve got a few questions and points I’d like to discuss. If some (or all 😄) have already been covered in earlier conversations I may have missed, please excuse the repetition. And in case I’ve misunderstood anything, please feel free to correct me. Thanks!
Feedback from https://github.com/shaavan 1. rename max_period to max_period_index for a little more clarity. 2. clarify `offer_absolute_expiry` example.
shaavan
left a comment
shaavan
left a comment
There was a problem hiding this comment.
Thanks for all the clarifications, Rusty and Thomas!
1. Remove reference to years (it's now seconds, days or months). 2. Make 0 illegal. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
rustyrussell
force-pushed
the
guilt/offers-recurrence
branch
from
cb79233 to
941b20d
Compare
| - MUST set `invreq_recurrence_counter` `counter` to 0. | ||
| - MUST NOT set `invreq_recurrence_cancel`. | ||
| - for any successive requests: | ||
| - MUST use the same `invreq_payer_id` as the initial request. |
There was a problem hiding this comment.
Why does the payer need to maintain a stable invreq_payer_id across recurrence invoice requests? This appears to introduce public linkability for the payer across the lifetime of a recurrence session.
If the goal is to allow the payee to associate invoice requests with a particular recurrence session, could the recently added invoice_recurrence_prev_state and invoice_recurrence_next_state fields serve that purpose instead, avoiding the need for a stable payer identifier?
| `payment_preimage` that will be given in return for payment. | ||
| - if `offer_issuer_id` is present: | ||
| - MUST set `invoice_node_id` to the `offer_issuer_id` | ||
| - otherwise, if `offer_paths` is present: |
There was a problem hiding this comment.
Recurrence sessions may be very long-lived, potentially lasting months or years.
When offer_paths is present, subsequent recurrence invoice requests are required to use the same blinded paths from the original offer. This appears to require those paths to remain usable for the entire lifetime of the recurrence session, potentially long after the original offer itself has expired.
If those paths become invalid over time, how is the payer expected to continue the recurrence session?
More generally, should long-lived recurrence sessions depend on communication paths established at offer creation time, or is some mechanism for path refresh expected?
| 1. A `time_unit` defining 0 (seconds), 1 (days), 2 (months). | ||
| 2. A `period`, defining how often (in `time_unit`) it has to be paid. | ||
| 3. An optional `offer_recurrence_limit` of total payments to be paid. | ||
| 4. An optional `offer_recurrence_base`: |
There was a problem hiding this comment.
The current design allows a recurrence to be anchored either via offer_recurrence_base in the offer or via invoice_recurrence_basetime in the first invoice.
What advantages does allowing recurrence anchoring to originate from either the offer or the first invoice provide compared to requiring period #0 to always be defined at offer creation time and making the offer the sole source of truth for recurrence anchoring?
Additional Thoughts
I can see the value of payer-driven recurrence basetimes. However, I am curious whether that flexibility could be moved to the application layer while keeping recurrence anchoring entirely offer-defined.
For example:
- A merchant could support generating recurrence-on-demand offers, with the basetime chosen when the payer decides to begin the recurrence.
- For a long-lived static offer, a payer could begin participating after several recurrence periods have already elapsed, with the recurrence offset indicating the period at which participation began.
Would an approach like this preserve the same flexibility while keeping a single source of truth for recurrence anchoring?
|
|
||
| Note: you can create an recurring offer with a fixed start which can only be used from the first period, using `offer_absolute_expiry`. For example, my weekly book club starts January 1st 2026, for $5 a week: by setting `offer_absolute_expiry` to January 8th 2026, I ensure nobody can join after the first week. Now, if only I could require them to actually read this week's book! | ||
|
|
||
| For wallets which don't (yet) support recurrence, the basic recurrence field comes in two variants: `offer_recurrence_compulsory` if they should not attempt a payment, and `offer_recurrence_optional` if it still makes sense for them to attempt a single payment. |
There was a problem hiding this comment.
The current design distinguishes between recurrence being optional or compulsory at the protocol level.
What advantages are gained by encoding this distinction in the recurrence specification itself?
Could recurrence instead be treated as a protocol extension where recurrence is always optional at the spec level, with applications advertising and deciding whether one-time payments are accepted or rejected?
10 participants
This is taken from the old draft, and updated with modern field numbers and names.
I've made some minor changes:
proportional_amountfield comes beforeseconds_beforewhich seems more logical to me.offer_absolute_expiryis clarified to only apply to the initial invoice request: once you're recurring the other fields take over.The complexities mainly come from two sources:
One proposal I would like to add is a courtesy onion message when a user cancels a periodic payment. This is generally useful to tell the difference between a deliberate cancellation and a user-related failure.