Skip to content
This repository was archived by the owner on Jan 10, 2025. It is now read-only.

Encode fields in opening_fee_params promise #111

Closed
wants to merge 3 commits into from
Closed

Encode fields in opening_fee_params promise #111

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f84c346
lsps2: lsp must encode params fields inside the promise
JssDWt Apr 11, 2024
244d8b6
lsps2: sending the promise to the buy request is enough
JssDWt Apr 11, 2024
409965f
lsps2: allow adding fields to opening_fee_params
JssDWt Apr 11, 2024
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
56 changes: 34 additions & 22 deletions LSPS2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,12 @@ the following rules:

The LSP, when generating the `promise` field:

* MUST encode all fields of the `opening_fee_params` into the `promise` in such
a way that the `opening_fee_params` object can be reconstructed from the
`promise`. This spec does not describe _how_ the fields must be encoded. This
could be through an identifier that allows the LSP to lookup the values
associated to the `promise`. It is recommended to encode the raw values of the
fields inside the `promise` string, so the LSP can be stateless.
* SHOULD use a cryptographically-verifiable method of generating
`promise`, such as a MAC of some deterministic serialization of the
other `opening_fee_params` keys, then encoded in hexadecimal, base64,
Expand Down Expand Up @@ -340,6 +346,15 @@ The LSP, when generating the `promise` field:
> **Rationale** The method to generate `promise` is left vague in order
> to allow LSP implementors the flexibility to structure their code
> as necessary.
>
> The LSP should be able to extract all the information in the
> `opening_fee_params` object from the `promise` to allow a clear upgrade path.
> If this would not be the case, if ever a field is added to the
> `opening_fee_params` object, clients may not know about the new field and they
> may send back an `opening_fee_params` object without the newly added field in
> the `lsps2.buy` call. The LSP would only be able to verify the `promise` if
> the field was encoded in the `promise` itself.
>
> The above specification suggests the use of any MAC, which would cover
> the above requirements, and requires a symmetric key known only by
> the LSP.
Expand Down Expand Up @@ -375,9 +390,7 @@ Clients, when reading the `promise` field:
> A size limit is imposed so that LSPs cannot burden clients with
> unreasonable storage requirements.

LSPs MUST NOT add any other fields to an `opening_fee_params` object.

Clients MUST fail and abort the flow if a `opening_fee_params`
Clients MAY fail and abort the flow if a `opening_fee_params`
object has unrecognized fields.

> **Rationale** Clients that expect this version of LSPS2 will
Expand All @@ -395,6 +408,14 @@ object has unrecognized fields.
> the `promise` can be used to determine whether this information
> exists or not, and the LSP can cut the added information in this
> `promise` from the cryptographic commitment.
>
> It is possible that in the future this spec adds additional backward
> compatible fields to the `opening_fee_params` object. Clients may therefore
> also choose to ignore unrecognized fields in order to allow for backward
> compatible upgrade paths. Since the LSP can commit to any random data in the
> promise that the client may not be able to read, there is no real harm in
> ignoring additional fields. The client has an incentive to understand the
> newly added fields, because they might give a discount.

The client now takes the `opening_fee_params` and the expected
`payment_size_msat`, to compute the `opening_fee`, and determine if the
Expand Down Expand Up @@ -530,28 +551,19 @@ Example `lsps2.buy` request parameters:

```JSON
{
"opening_fee_params": {
"min_fee_msat": "546000",
"proportional": 1200,
"valid_until": "2023-02-23T08:47:30.511Z",
"min_lifetime": 1008,
"max_client_to_self_delay": 2016,
"min_payment_size_msat": "1000",
"max_payment_size_msat": "1000000",
"promise": "abcdefghijklmnopqrstuvwxyz"
},
"promise": "abcdefghijklmnopqrstuvwxyz",
"payment_size_msat": "42000"
}
```

`opening_fee_params` is the object acquired from the previous
step.
`promise` is taken from an `opening_fee_params` object acquired from the
previous step.
Clients MUST copy it verbatim from an entry of `opening_fee_params_menu`
from a result of a `lsps2.get_info` call.
LSPs MUST check that the `opening_fee_params.promise` does in fact
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.
LSPs MUST check that the `promise` does in fact prove that it previously
committed to a specific `opening_fee_params` object.
LSPs MUST check that the `opening_fee_params.valid_until` encoded in the
`promise` is not a past datetime.

`payment_size_msat` is an *optional* amount denominated in millisatoshis
that the client wants to receive [<LSPS0.msat>][]:
Expand Down Expand Up @@ -584,9 +596,9 @@ The LSP MUST validate that the `payment_size_msat` is within the previous

The following errors are specified for `lsps2.buy`:

* `invalid_opening_fee_params` (201) - the `valid_until` field
of the `opening_fee_params` is already past, **OR** the `promise`
did not match the parameters.
* `invalid_promise` (201) - the `promise` could not be decoded, **OR** the
`promise` could not be verified with the LSP's rules, **OR** the `valid_until`
field of the associated `opening_fee_params` has already past.
* `payment_size_too_small` (202) - the `payment_size_msat` was specified,
and the resulting `opening_fee` is equal or greater than the
`payment_size_msat`.
Expand Down