diff --git a/LSPS2/README.md b/LSPS2/README.md index 08e5651..6e30f71 100644 --- a/LSPS2/README.md +++ b/LSPS2/README.md @@ -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, @@ -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. @@ -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 @@ -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 @@ -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 [][]: @@ -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`.