From 45459af12f8b28649b7a8ab5cdf9d5b0a81d8de8 Mon Sep 17 00:00:00 2001 From: shocknet-justin Date: Sun, 23 Aug 2026 23:10:25 -0400 Subject: [PATCH 1/5] offer code 6 for required payer_data Co-authored-by: Cursor --- specs/clink-offers.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/specs/clink-offers.md b/specs/clink-offers.md index 44aaa14..308abbf 100644 --- a/specs/clink-offers.md +++ b/specs/clink-offers.md @@ -177,7 +177,17 @@ Sent by the receiving service back to the payer. "sig": "" } ``` - *Common reasons might include: an invalid offer (code 1), an expired or moved offer (code 3), or an invalid amount (code 5).* + *Common reasons might include: an invalid offer (code 1), an expired or moved offer (code 3), an invalid amount (code 5), or missing payer data (code 6).* + +## Payer Data + +Offers MAY require extra fields at pay time (set on the offer via [CLINK Manage](clink-manage.md) `payer_data` as a list of names). Those names are not encoded in the `noffer1…` string. + +The request `payer_data` field is an object: keys are those names, values are strings, except `quantity` which is an integer (units purchased). This spec does not define email/address formats or other validation — the host accepts or returns `code: 6`. + +If `quantity` is in the required list, the host MUST NOT infer `1`. A request without `quantity` MUST get `code: 6` and MUST NOT return `bolt11` — there is no invoice to pay. + +If any required keys are missing, the host MUST NOT return `bolt11`. It MUST respond with `code: 6` and `payer_data` as the array of required names so the client can render inputs and retry. ## Error Handling @@ -190,6 +200,7 @@ To ensure consistent error handling across implementations, this NIP defines the - `3`: **Expired or Moved Offer**: The offer has expired, been replaced, or permanently moved. - `4`: **Unsupported Feature**: The receiver doesn't support a feature requested by the payer. - `5`: **Invalid Amount**: The amount specified is too big or too small. +- `6`: **Payer Data**: Required `payer_data` keys are missing or rejected. ### Error Response Payloads @@ -248,6 +259,18 @@ The response SHOULD include the acceptable `range` for the amount in sats. } ``` +#### Code 6: Payer Data +The offer requires `payer_data` keys that were omitted or rejected. The payload MUST include `payer_data` as an array of required field names. Clients SHOULD collect those keys (text inputs; `quantity` as an integer) and retry the request. This spec does not define other value types or formats — the host accepts or rejects. + +- **Payload**: +```json +{ + "error": "Payer data required", + "code": 6, + "payer_data": ["quantity", "email", "address"] +} +``` + ### Protocol Versioning CLINK events utilize a mandatory `["clink_version", "1"]` tag. This ensures: @@ -268,6 +291,7 @@ Implementations MUST include this tag in both request and response events and SH 4. **Service Processing**: Receiving service listens for Kind `21001` events. * Decrypts payload. * Validates the `offer` ID and `amount_sats` against offer parameters. + * If the offer requires `payer_data` keys and they are missing or rejected, responds with `code: 6` and the required key names (no invoice). * (If variable price) Calculates the current price in sats. * (If zap) Processes the `zap` event. * Generates a BOLT11 Lightning invoice. From aff7c9a71ce21d0d680e8b1c0c5d08670da7db98 Mon Sep 17 00:00:00 2001 From: shocknet-justin Date: Fri, 6 Nov 2026 12:59:37 -0500 Subject: [PATCH 2/5] Define quantity pricing across offer price categories --- specs/clink-offers.md | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/specs/clink-offers.md b/specs/clink-offers.md index 308abbf..c31fc50 100644 --- a/specs/clink-offers.md +++ b/specs/clink-offers.md @@ -132,8 +132,8 @@ Sent by the payer's wallet to the receiving service. ```json { "offer": "", // From noffer TLV 2 - "amount_sats": , // Required for spontaneous/variable, optional otherwise - "payer_data": { ... }, // Optional: Arbitrary JSON object with payer info (e.g., NIP-05, name, pubkey) + "amount_sats": , // Required for spontaneous pricing; optional otherwise (see Quantity and Pricing) + "payer_data": { ... }, // Optional unless required by the offer; string values except numeric quantity "zap": "{...}", // Optional: Stringified JSON of kind 9734 zap request event for NIP-57 flow "expires_in_seconds": , // Optional: Requested invoice expiry time "description": "" // Optional: A description to be included in the invoice, max 100 chars @@ -181,13 +181,27 @@ Sent by the receiving service back to the payer. ## Payer Data -Offers MAY require extra fields at pay time (set on the offer via [CLINK Manage](clink-manage.md) `payer_data` as a list of names). Those names are not encoded in the `noffer1…` string. +Offers MAY require extra fields at pay time (set on the offer via [CLINK Manage](clink-manage.md) `payer_data` as a list of names). Those names are not encoded in the `noffer1...` string. -The request `payer_data` field is an object: keys are those names, values are strings, except `quantity` which is an integer (units purchased). This spec does not define email/address formats or other validation — the host accepts or returns `code: 6`. +The request `payer_data` field is an object: keys are those names, values are strings, except `quantity` which MUST be a JSON number representing a positive integer no greater than `9007199254740991` (units purchased). Numeric strings such as `"2"` are not valid quantities. This spec does not define email/address formats or other field-specific validation. -If `quantity` is in the required list, the host MUST NOT infer `1`. A request without `quantity` MUST get `code: 6` and MUST NOT return `bolt11` — there is no invoice to pay. +For an otherwise valid request identifying a known offer with required payer fields, an omitted `payer_data` object, a non-object value (including an array), a missing required key, or a rejected required value MUST produce `code: 6` with `payer_data` as the full array of required names. The host MUST NOT return `bolt11`. Clients SHOULD collect or correct those fields and retry; clients MUST NOT rely on the human-readable `error` text to identify this response. -If any required keys are missing, the host MUST NOT return `bolt11`. It MUST respond with `code: 6` and `payer_data` as the array of required names so the client can render inputs and retry. +If `quantity` is in the required list, the host MUST NOT infer `1` when it is omitted or invalid. Fields not in the required list MUST NOT affect pricing or seller fulfillment data. In particular, an unsolicited `quantity` MUST NOT multiply the amount. + +### Quantity and Pricing + +Quantity does not introduce a new price category or require a price in the encoded offer. The host MUST first determine the unit price in whole satoshis according to the existing pricing type: + +- **Fixed (`0`):** The host's configured fixed price is the unit price. TLV `4`, when present, advertises that unit price. +- **Variable (`1`):** The host determines the current unit price at request time, for example by converting its reference-currency price to satoshis. TLV `4` is not required; when TLV `5` is present, TLV `4` MUST be omitted. A payer-supplied `amount_sats` MUST NOT override the host's resolved price. +- **Spontaneous (`2`, including the default):** The request's `amount_sats` supplies the unit price when `quantity` is required; otherwise it supplies the invoice amount as before. + +When the offer requires `quantity`, the invoice amount MUST be the resolved unit price multiplied by the validated quantity. The host MUST validate the final total against its amount limits and MUST NOT issue an invoice if the total is out of range or cannot be represented exactly as a whole-satoshi integer no greater than `9007199254740991`. Such a total is an amount failure (`code: 5`), not a payer-data failure. For these requests, the code-5 `range` describes acceptable invoice totals, not unit prices. + +For example, a variable-price offer may contain no satoshi price. If the host resolves its current unit price to 1,000 sats and the request supplies `quantity: 3`, the invoice is for 3,000 sats. The same multiplication applies to a fixed unit price or a spontaneous unit amount of 1,000 sats. + +The host MUST retain the accepted quantity with the other required payer fields on the invoice record and make it available through any seller fulfillment callback it supports. The wallet MUST verify the returned invoice amount before payment and obtain payer approval for the total; it MUST NOT assume an encoded price is present or sufficient to price a variable offer. ## Error Handling @@ -195,13 +209,15 @@ To ensure consistent error handling across implementations, this NIP defines the ### Error Codes -- `1`: **Invalid Offer**: The requested offer ID is invalid or no longer available. +- `1`: **Invalid Offer**: The requested offer ID is invalid or no longer available, or the request is malformed apart from the recoverable payer-data cases below. - `2`: **Temporary Failure**: The receiver is temporarily unable to process the request. - `3`: **Expired or Moved Offer**: The offer has expired, been replaced, or permanently moved. - `4`: **Unsupported Feature**: The receiver doesn't support a feature requested by the payer. - `5`: **Invalid Amount**: The amount specified is too big or too small. - `6`: **Payer Data**: Required `payer_data` keys are missing or rejected. +These codes are scoped to CLINK Offers (kind `21001`); code `6` here is not the invalid-request code used by other CLINK operations. + ### Error Response Payloads Error responses are sent as kind `21001` events with an encrypted `content` field containing a JSON object. The base structure is: @@ -215,6 +231,7 @@ Error responses are sent as kind `21001` events with an encrypted `content` fiel ``` #### Code 1: Invalid Offer +Malformed requests (for example, a missing offer identifier or an invalid top-level field type) also use code `1`. This response MUST NOT include the payer-data discovery array; recoverable required payer-field failures use code `6` instead. - **Payload**: `{"error": "Invalid Offer", "code": 1}` #### Code 2: Temporary Failure @@ -260,7 +277,7 @@ The response SHOULD include the acceptable `range` for the amount in sats. ``` #### Code 6: Payer Data -The offer requires `payer_data` keys that were omitted or rejected. The payload MUST include `payer_data` as an array of required field names. Clients SHOULD collect those keys (text inputs; `quantity` as an integer) and retry the request. This spec does not define other value types or formats — the host accepts or rejects. +The offer requires `payer_data` keys that were omitted or rejected. The payload MUST include `payer_data` as the full array of required field names and MUST NOT include `bolt11`. Clients SHOULD collect or correct those fields (text inputs; `quantity` as a positive integer) and retry the request. A repeated rejection SHOULD be shown to the payer rather than retried indefinitely without changes. - **Payload**: ```json @@ -285,7 +302,7 @@ Implementations MUST include this tag in both request and response events and SH 2. **Decoding**: Payer's wallet decodes the `noffer` to get service pubkey, relay hint, offer ID, and pricing info. 3. **Request**: Payer's wallet constructs and sends a Kind `21001` request event to the relay, addressed to the service pubkey. * Includes `offer` ID. - * Includes `amount_sats` if offer type is spontaneous (`2`) or variable (`1`). + * Includes `amount_sats` if offer type is spontaneous (`2`); variable pricing (`1`) is resolved by the host. * Optionally includes `payer_data`. * Optionally includes `zap` payload if performing a NIP-57 zap. 4. **Service Processing**: Receiving service listens for Kind `21001` events. @@ -293,6 +310,7 @@ Implementations MUST include this tag in both request and response events and SH * Validates the `offer` ID and `amount_sats` against offer parameters. * If the offer requires `payer_data` keys and they are missing or rejected, responds with `code: 6` and the required key names (no invoice). * (If variable price) Calculates the current price in sats. + * If `quantity` is required, multiplies the unit price by the validated quantity and checks the invoice total against amount limits. * (If zap) Processes the `zap` event. * Generates a BOLT11 Lightning invoice. 5. **Response**: Service sends a Kind `21001` response event back to the payer's pubkey. From 59311891aba1b09dad9d922ec88b88a2a06a4ef5 Mon Sep 17 00:00:00 2001 From: shocknet-justin Date: Mon, 9 Nov 2026 00:00:35 -0500 Subject: [PATCH 3/5] Define offer price integer encoding and bounds --- specs/clink-offers.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specs/clink-offers.md b/specs/clink-offers.md index c31fc50..d134e73 100644 --- a/specs/clink-offers.md +++ b/specs/clink-offers.md @@ -23,13 +23,15 @@ The static payment code is a single bech32 encoded string (per [NIP-19](https:// - `0`: Fixed price (Price stated in TLV `4`) - `1`: Variable price (Price determined by the service upon request, e.g., based on fiat conversion) - `2`: Spontaneous payment (Payer specifies the amount in the request) -- `4`: (Optional) The price in satoshis (integer), primarily for display purposes or fixed price offers. +- `4`: (Optional) The price in satoshis, encoded as a nonempty unsigned big-endian integer from `0` through `9007199254740991`, primarily for display purposes or fixed price offers. - `5`: (Optional) A currency code (e.g., "USD", "EUR") identifying the reference currency a service uses to determine a variable price. If present, pricing type `1` (Variable) MUST be used and TLV `4` MUST be omitted. **Default Behavior:** If neither price (TLV `4`) nor pricing type (TLV `3`) is present, the offer SHOULD be treated as type `2` (Spontaneous payment). **Amount Unit:** Amounts in TLV `4` and request/response payloads are specified in **whole satoshis**. +**Price Encoding (TLV `4`):** The value is 1 to 255 bytes, subject to the numerical bound above. Decoders MUST accept leading zero bytes and MUST reject empty or out-of-range values rather than rounding or truncating. To preserve existing offer encodings, encoders SHOULD use four bytes for values from `0` through `4294967295` and the shortest sufficient byte width for larger values. An explicitly supplied zero price is encoded as zero, not treated as an absent TLV. TLV `5` excludes TLV `4` even when the price is zero. + **Example Structure:** ``` noffer1... From a2081b7a8c4855ee5a0dfd9e59661aab5d89ee28 Mon Sep 17 00:00:00 2001 From: shocknet-justin Date: Mon, 9 Nov 2026 00:58:31 -0500 Subject: [PATCH 4/5] Fix Manage create example and simplify price encoding text --- specs/clink-manage.md | 10 ++++++---- specs/clink-offers.md | 4 ++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/specs/clink-manage.md b/specs/clink-manage.md index edc098d..cefc0fe 100644 --- a/specs/clink-manage.md +++ b/specs/clink-manage.md @@ -38,10 +38,12 @@ Allows an app to create, update, and delete offers on the user's wallet server. "pointer": "", // Optional "action": "create", "offer": { - "label": "Product X", - "price_sats": 12345, - "callback_url": "https://example-marketplace.app/callback/123", - "payer_data": ["email", "shipping_address"] + "fields": { + "label": "Product X", + "price_sats": 12345, + "callback_url": "https://example-marketplace.app/callback/123", + "payer_data": ["email", "shipping_address"] + } } } ``` diff --git a/specs/clink-offers.md b/specs/clink-offers.md index d134e73..131c6f0 100644 --- a/specs/clink-offers.md +++ b/specs/clink-offers.md @@ -23,14 +23,14 @@ The static payment code is a single bech32 encoded string (per [NIP-19](https:// - `0`: Fixed price (Price stated in TLV `4`) - `1`: Variable price (Price determined by the service upon request, e.g., based on fiat conversion) - `2`: Spontaneous payment (Payer specifies the amount in the request) -- `4`: (Optional) The price in satoshis, encoded as a nonempty unsigned big-endian integer from `0` through `9007199254740991`, primarily for display purposes or fixed price offers. +- `4`: (Optional) The price in whole satoshis, primarily for display or fixed-price offers. - `5`: (Optional) A currency code (e.g., "USD", "EUR") identifying the reference currency a service uses to determine a variable price. If present, pricing type `1` (Variable) MUST be used and TLV `4` MUST be omitted. **Default Behavior:** If neither price (TLV `4`) nor pricing type (TLV `3`) is present, the offer SHOULD be treated as type `2` (Spontaneous payment). **Amount Unit:** Amounts in TLV `4` and request/response payloads are specified in **whole satoshis**. -**Price Encoding (TLV `4`):** The value is 1 to 255 bytes, subject to the numerical bound above. Decoders MUST accept leading zero bytes and MUST reject empty or out-of-range values rather than rounding or truncating. To preserve existing offer encodings, encoders SHOULD use four bytes for values from `0` through `4294967295` and the shortest sufficient byte width for larger values. An explicitly supplied zero price is encoded as zero, not treated as an absent TLV. TLV `5` excludes TLV `4` even when the price is zero. +**Price Encoding:** TLV `4` MUST contain a nonempty unsigned big-endian integer. Encoders SHOULD use four bytes when the value fits, otherwise the minimum required width. Decoders MUST accept leading zero bytes and MUST NOT round or truncate the value. **Example Structure:** ``` From b9efa0b0aeb6c3821996a2678ad62dec05ddfdf5 Mon Sep 17 00:00:00 2001 From: shocknet-justin Date: Mon, 9 Nov 2026 14:02:14 -0500 Subject: [PATCH 5/5] Define required Manage fields and optional callback updates --- specs/clink-manage.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/specs/clink-manage.md b/specs/clink-manage.md index cefc0fe..4661cf8 100644 --- a/specs/clink-manage.md +++ b/specs/clink-manage.md @@ -93,7 +93,13 @@ Allows an app to create, update, and delete offers on the user's wallet server. } ``` -The offer object is managed by the wallet server. It includes a unique `id` (generated by the server on creation) and may include the following fields: a human-readable `label` for display purposes (this is the standardized, optional field for this purpose), a `price_sats`, a `callback_url`, and a `payer_data` array listing required payer-supplied data fields. +Create and update requests use `offer.fields`: +- `label`: Required, nonempty display name. The server MUST NOT invent a missing label. +- `price_sats`: Required. Use `0` for spontaneous pricing. +- `payer_data`: Required array of payer-field names. Use `[]` when none are required. +- `callback_url`: Optional string or `null`. Omission on create means no callback (`null`). Omission on update preserves the existing callback; `null` or `""` clears it. + +The server assigns the offer's `id` on creation. Updates MUST include `offer.id`; an account `pointer` alone does not identify an offer. #### Response Payloads - **Success (`create`, `update`, `get`)**