diff --git a/blip-0052.md b/blip-0052.md index 46f266b..8e4d983 100644 --- a/blip-0052.md +++ b/blip-0052.md @@ -241,7 +241,8 @@ Example `lsps2.get_info` result: "max_payment_size_msat": "1000000", "promise": "abcdefghijklmnopqrstuvwxyz" } - ] + ], + "ongoing_proportional": true, } ``` The `opening_fee_params_menu` is an array of `opening_fee_params` @@ -294,7 +295,7 @@ and MUST NOT have any additional fields: to the client, not including the forwarding fees of nodes along the way. * `promise` is an arbitrary LSP-generated string that proves to the LSP that it has promised a specific `opening_fee_params` with the specific - `min_fee_msat`, `proportional`, `valid_until`, `min_lifetime`, + `min_fee_msat`, `proportional`, `valid_until`, `min_lifetime`, `max_client_to_self_delay`, `min_payment_size_msat`, and `max_payment_size_msat`. @@ -534,6 +535,10 @@ fn compute_opening_fee(payment_size_msat: u64, > overflow-detecting multiplication routine is optimized away > and replaced with a simple overflow-flag check. +The `ongoing_proportional` field is a boolean that indicates whether +the LSP will charge the agreed upon proportional fee on subsequent +payments after the initial channel open. + ### 2. Request JIT Channel The client constructs a request body for a `lsps2.buy` request, @@ -560,7 +565,8 @@ Example `lsps2.buy` request parameters: "max_payment_size_msat": "1000000", "promise": "abcdefghijklmnopqrstuvwxyz" }, - "payment_size_msat": "42000" + "ongoing_proportional": true, + "payment_size_msat": "42000", } ``` @@ -573,6 +579,12 @@ prove that it previously promised the specified `opening_fee_params`. LSPs MUST check that the `opening_fee_params.valid_until` is not a past datetime. +`ongoing_proportional` is the boolean acquired from the previous step. +Clients MUST provide the same value from a result of a `lsps2.get_info` +call. +LSPs MUST check that the `ongoing_proportional` field matches the mode +of operation they intend to use. + `payment_size_msat` is an *optional* amount denominated in millisatoshis that the client wants to receive [][]: @@ -614,6 +626,8 @@ The following errors are specified for `lsps2.buy`: and the LSP hit an overflow error while calculating the `opening_fee`, **OR** the LSP has insufficient incoming liquidity from the public network to receive the `payment_size_msat`. +* `invalid_ongoing_proportional` (204) - the `ongoing_proportional` field + did not match the expected value. * [LSPS0.client_rejected_error][] (1) - The LSP rejected the client. If there were no errors, the LSP then provides a normal @@ -1029,6 +1043,33 @@ selected. LSPs MUST consider this alias not just for forwarded payments, but also for onion messages. +#### Ongoing Proportional Fees + +If `ongoing_proportional` is true then for all payments forwarded through +the channel after the initial channel-opening payment, the LSP MUST charge +an ongoing proportional fee as specified in the `proportional` field from +the `opening_fee_params` used to open the channel. + +The ongoing fee for each payment is computed as: + + ongoing_fee = ((payment_amount_msat * proportional) + 999999) / 1000000 + +Where `payment_amount_msat` is the amount being forwarded to the client, +and `proportional` is the value from the `opening_fee_params`. + +* All numbers MUST be computed using the same overflow detection rules + specified in the "Computing The `opening_fee`" section. +* The LSP MUST deduct this `ongoing_fee` from each forwarded payment. +* The LSP MUST include an `extra_fee` TLV (type 65537) in the + `update_add_htlc` message for each payment that has ongoing fees + deducted, with the value set to the computed `ongoing_fee`. +* The client MUST accept these fee deductions and validate that the + `extra_fee` matches the expected `ongoing_fee` calculation. + +This ongoing fee allows LSPs to distribute the cost of channel opening +across the lifetime of the channel rather than charging the full amount +upfront on the first payment. + []: ./blip-0050.md#link-lsps0msat []: ./blip-0050.md#link-lsps0ppm []: ./blip-0050.md#link-lsps0datetime