Skip to content

bLIP-0052: Add ongoing proportional fees #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

bLIP-0052: Add ongoing proportional fees #63

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
10e6d61
bLIP-0052: Add ongoing proportional fees
aylagreystone Jun 9, 2025
6396f08
Use backwards compat. flag instead of new param
aylagreystone Jun 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 44 additions & 3 deletions blip-0052.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -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`.

Expand Down Expand Up @@ -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,
Expand All @@ -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",
}
```

Expand All @@ -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 [<LSPS0.msat>][]:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should repeat the computation here, but rather just refer to the other parts of the spec.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only potential confusion is that in the 'computing the fee' section that is for the opening fee which includes the min_fee portion. The ongoing_fee as defined only includes the proportional component of the fee.


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.

[<LSPS0.msat>]: ./blip-0050.md#link-lsps0msat
[<LSPS0.ppm>]: ./blip-0050.md#link-lsps0ppm
[<LSPS0.datetime>]: ./blip-0050.md#link-lsps0datetime
Expand Down