Skip to content

Commit

Permalink
Consistency: use "reject" everywhere instead of "fail" or "ignore".
Browse files Browse the repository at this point in the history
And use the explicit name of the thing we are rejecting.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
  • Loading branch information
rustyrussell committed Sep 24, 2024
1 parent 376eedf commit 1197302
Showing 1 changed file with 30 additions and 30 deletions.
60 changes: 30 additions & 30 deletions 12-offer-encoding.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,12 +314,12 @@ A reader of an offer:
from that estimate.
- if the current time is after `offer_absolute_expiry`:
- MUST NOT respond to the offer.
- if it chooses to send an `invoice_request`, it sends an onion message:
- if it chooses to send an invoice request, it sends an onion message:
- if `offer_paths` is set:
- MUST send the onion message via any path in `offer_paths` to the final `onion_msg_hop`.`blinded_node_id` in that path
- otherwise:
- MUST send the onion message to `offer_issuer_id`
- MAY send more than one `invoice_request` onion message at once.
- MAY send more than one invoice request onion message at once.

## Rationale

Expand All @@ -340,7 +340,7 @@ fields.

The `offer_issuer_id` can be omitted for brevity, if `offer_paths` is set, as each of the final `blinded_node_id` in the paths can serve as a valid public key for the destination.

Because `offer_amount` can be in a different currency (using the `offer_currency` field) it is merely a guide: the issuer will convert it into a number of millisatoshis for `invoice_amount` at the time they generate an invoice, or the `invoice_request` can specify the exact amount in `invreq_amount`, but the issuer may then reject it if it disagrees.
Because `offer_amount` can be in a different currency (using the `offer_currency` field) it is merely a guide: the issuer will convert it into a number of millisatoshis for `invoice_amount` at the time they generate an invoice, or the invoice request can specify the exact amount in `invreq_amount`, but the issuer may then reject it if it disagrees.

`offer_quantity_max` is allowed to be 1, which seems useless, but
useful in a system which bases it on available stock. It would be
Expand All @@ -363,7 +363,7 @@ message: if it's valid and refers to a known offer, the response is
generally to reply with an `invoice` using the `reply_path` field of
the onion message.

The second case is publishing an `invoice_request` without an offer,
The second case is publishing an invoice request without an offer,
such as via QR code. It contains neither `offer_issuer_id` nor `offer_paths`, setting the
`invreq_payer_id` (and possibly `invreq_paths`) instead, as it in the one paying: the
other offer fields are filled by the creator of the `invoice_request`,
Expand Down Expand Up @@ -483,53 +483,53 @@ The writer:
- MUST set `invreq_features`.`features` to the bitmap of features.

The reader:
- MUST fail the request if `invreq_payer_id` or `invreq_metadata` are not present.
- MUST fail the request if any non-signature TLV fields are outside the inclusive ranges: 0 to 159 and 1000000000 to 2999999999
- MUST reject the invoice request if `invreq_payer_id` or `invreq_metadata` are not present.
- MUST reject the invoice request if any non-signature TLV fields are outside the inclusive ranges: 0 to 159 and 1000000000 to 2999999999
- if `invreq_features` contains unknown _odd_ bits that are non-zero:
- MUST ignore the bit.
- if `invreq_features` contains unknown _even_ bits that are non-zero:
- MUST fail the request.
- MUST fail the request if `signature` is not correct as detailed in [Signature Calculation](#signature-calculation) using the `invreq_payer_id`.
- MUST reject the invoice request.
- MUST reject the invoice request if `signature` is not correct as detailed in [Signature Calculation](#signature-calculation) using the `invreq_payer_id`.
- if `num_hops` is 0 in any `blinded_path` in `invreq_paths`:
- MUST fail the request.
- MUST reject the invoice request.
- if `offer_issuer_id` is present, and `invreq_metadata` is identical to a previous `invoice_request`:
- MAY simply reply with the previous invoice.
- otherwise:
- MUST NOT reply with a previous invoice.
- if `offer_issuer_id` or `offer_paths` are present (response to an offer):
- MUST fail the request if the offer fields do not exactly match a valid, unexpired offer.
- MUST reject the invoice request if the offer fields do not exactly match a valid, unexpired offer.
- if `offer_paths` is present:
- MUST ignore the invoice_request if it did not arrive via one of those paths.
- otherwise:
- MUST ignore any invoice_request if it arrived via a blinded path.
- if `offer_quantity_max` is present:
- MUST fail the request if there is no `invreq_quantity` field.
- MUST reject the invoice request if there is no `invreq_quantity` field.
- if `offer_quantity_max` is non-zero:
- MUST fail the request if `invreq_quantity` is zero, OR greater than `offer_quantity_max`.
- MUST reject the invoice request if `invreq_quantity` is zero, OR greater than `offer_quantity_max`.
- otherwise:
- MUST fail the request if there is an `invreq_quantity` field.
- MUST reject the invoice request if there is an `invreq_quantity` field.
- if `offer_amount` is present:
- MUST calculate the *expected amount* using the `offer_amount`:
- if `offer_currency` is not the `invreq_chain` currency, convert to the
`invreq_chain` currency.
- if `invreq_quantity` is present, multiply by `invreq_quantity`.`quantity`.
- if `invreq_amount` is present:
- MUST fail the request if `invreq_amount`.`msat` is less than the *expected amount*.
- MAY fail the request if `invreq_amount`.`msat` greatly exceeds the *expected amount*.
- MUST reject the invoice request if `invreq_amount`.`msat` is less than the *expected amount*.
- MAY reject the invoice request if `invreq_amount`.`msat` greatly exceeds the *expected amount*.
- otherwise (no `offer_amount`):
- MUST fail the request if it does not contain `invreq_amount`.
- MUST reject the invoice request if it does not contain `invreq_amount`.
- SHOULD send an invoice in response using the `onionmsg_tlv` `reply_path`.
- otherwise (no `offer_issuer_id` or `offer_paths`, not a response to our offer):
- MUST fail the request if any of the following are present:
- MUST reject the invoice request if any of the following are present:
- `offer_chains`, `offer_features` or `offer_quantity_max`.
- MUST fail the request if `invreq_amount` is not present.
- MUST reject the invoice request if `invreq_amount` is not present.
- MAY use `offer_amount` (or `offer_currency`) for informational display to user.
- if it sends an invoice in response:
- MUST use `invreq_paths` if present, otherwise MUST use `invreq_payer_id` as the node id to send to.
- if `invreq_chain` is not present:
- MUST fail the request if bitcoin is not a supported chain.
- MUST reject the invoice request if bitcoin is not a supported chain.
- otherwise:
- MUST fail the request if `invreq_chain`.`chain` is not a supported chain.
- MUST reject the invoice request if `invreq_chain`.`chain` is not a supported chain.


## Rationale
Expand All @@ -551,7 +551,7 @@ the invoice request amount exceeds the amount it's expecting (i.e. its
`offer_amount` after any currency conversion, multiplied by `invreq_quantity`, if
any).

Non-offer-response `invoice_request`s are currently required to
Non-offer-response invoice requests are currently required to
explicitly state the `invreq_amount` in the chain currency,
so `offer_amount` and `offer_currency` are redundant (but may be
informative for the payer to know how the sender claims
Expand Down Expand Up @@ -695,7 +695,7 @@ A writer of an invoice:
the minimal lightning-payable unit (e.g. milli-satoshis for bitcoin) for
`invreq_chain`.
- if the invoice is in response to an `invoice_request`:
- MUST copy all non-signature fields from the `invoice_request` (including unknown fields).
- MUST copy all non-signature fields from the invoice request (including unknown fields).
- if `invreq_amount` is present:
- MUST set `invoice_amount` to `invreq_amount`
- otherwise:
Expand All @@ -705,7 +705,7 @@ A writer of an invoice:
- if `offer_issuer_id` is present:
- MUST set `invoice_node_id` to the `offer_issuer_id`
- otherwise, if `offer_paths` is present:
- MUST set `invoice_node_id` to the final `blinded_node_id` on the path it received the `invoice_request`
- MUST set `invoice_node_id` to the final `blinded_node_id` on the path it received the invoice request
- MUST specify exactly one signature TLV element: `signature`.
- MUST set `sig` to the signature using `invoice_node_id` as described in [Signature Calculation](#signature-calculation).
- if it requires multiple parts to pay the invoice:
Expand Down Expand Up @@ -734,9 +734,9 @@ A reader of an invoice:
- MUST reject the invoice if `invoice_payment_hash` is not present.
- MUST reject the invoice if `invoice_node_id` is not present.
- if `invreq_chain` is not present:
- MUST fail the request if bitcoin is not a supported chain.
- MUST reject the invoice if bitcoin is not a supported chain.
- otherwise:
- MUST fail the request if `invreq_chain`.`chain` is not a supported chain.
- MUST reject the invoice if `invreq_chain`.`chain` is not a supported chain.
- if `invoice_features` contains unknown _odd_ bits that are non-zero:
- MUST ignore the bit.
- if `invoice_features` contains unknown _even_ bits that are non-zero:
Expand All @@ -753,11 +753,11 @@ A reader of an invoice:
- MUST NOT use the corresponding `invoice_paths`.`path` if `payinfo`.`features` has any unknown even bits set.
- MUST reject the invoice if this leaves no usable paths.
- if the invoice is a response to an `invoice_request`:
- MUST reject the invoice if all fields in ranges 0 to 159 and 1000000000 to 2999999999 (inclusive) do not exactly match the `invoice_request`.
- MUST reject the invoice if all fields in ranges 0 to 159 and 1000000000 to 2999999999 (inclusive) do not exactly match the invoice request.
- if `offer_issuer_id` is present (invoice_request for an offer):
- MUST reject the invoice if `invoice_node_id` is not equal to `offer_issuer_id`
- otherwise, if `offer_paths` is present (invoice_request for an offer without id):
- MUST reject the invoice if `invoice_node_id` is not equal to the final `blinded_node_id` it sent the `invoice_request` to.
- MUST reject the invoice if `invoice_node_id` is not equal to the final `blinded_node_id` it sent the invoice request to.
- otherwise (invoice_request without an offer):
- MAY reject the invoice if it cannot confirm that `invoice_node_id` is correct, out-of-band.
- MUST reject the invoice if `signature` is not a valid signature using `invoice_node_id` as described in [Signature Calculation](#signature-calculation).
Expand All @@ -777,11 +777,11 @@ A reader of an invoice:
- MUST ignore any `fallback_address` for which `address` is less than 2 or greater than 40 bytes.
- MUST ignore any `fallback_address` for which `address` does not meet known requirements for the given `version`
- if `invreq_paths` is present:
- MUST ignore the invoice if it did not arrive via one of those paths.
- MUST reject the invoice if it did not arrive via one of those paths.
- otherwise, neither `offer_issuer_id` nor `offer_paths` are present (not derived from an offer):
- MUST ignore any invoice if it arrived via a blinded path.
- MUST reject the invoice if it arrived via a blinded path.
- otherwise (derived from an offer):
- MUST ignore the invoice if it did not arrive via invoice request `onionmsg_tlv` `reply_path`.
- MUST reject the invoice if it did not arrive via invoice request `onionmsg_tlv` `reply_path`.

## Rationale

Expand Down

0 comments on commit 1197302

Please sign in to comment.