Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
18 changes: 13 additions & 5 deletions specs/clink-manage.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,12 @@ Allows an app to create, update, and delete offers on the user's wallet server.
"pointer": "<pointer_id>", // 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"]
}
}
}
```
Expand Down Expand Up @@ -91,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`)**
Expand Down
56 changes: 50 additions & 6 deletions specs/clink-offers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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` 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:**
```
noffer1...
Expand Down Expand Up @@ -132,8 +134,8 @@ Sent by the payer's wallet to the receiving service.
```json
{
"offer": "<offer_id_string>", // From noffer TLV 2
"amount_sats": <amount_in_sats_integer>, // Required for spontaneous/variable, optional otherwise
"payer_data": { ... }, // Optional: Arbitrary JSON object with payer info (e.g., NIP-05, name, pubkey)
"amount_sats": <amount_in_sats_integer>, // 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": <number_of_seconds_integer>, // Optional: Requested invoice expiry time
"description": "<string>" // Optional: A description to be included in the invoice, max 100 chars
Expand Down Expand Up @@ -177,19 +179,46 @@ Sent by the receiving service back to the payer.
"sig": "<signature>"
}
```
*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 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.

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 `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

To ensure consistent error handling across implementations, this NIP defines the following error responses, similar to other NIPs. Clients MUST handle these error responses gracefully and display appropriate messages to users.

### 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

Expand All @@ -204,6 +233,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
Expand Down Expand Up @@ -248,6 +278,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 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
{
"error": "Payer data required",
"code": 6,
"payer_data": ["quantity", "email", "address"]
}
```

### Protocol Versioning

CLINK events utilize a mandatory `["clink_version", "1"]` tag. This ensures:
Expand All @@ -262,13 +304,15 @@ 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.
* 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 `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.
Expand Down