nips/69.md

NIP-69
======

Nostr Offer STRings
-------------------

`wip` `optional`

This NIP proposes a format for static payment codes in Nostr as a successor to LNURL-Pay, enabling users to initiate Lightning Network payments by scanning or clicking a string.

## Motivation

Reliance on LNURL has led to centralization via custodial solutions due to the legacy baggage of IP4-NAT/Domain/SSL requirements. Nostr's use-cases are already centered around Lightning, whether as a wallet connector, zap receipts, or its overlapping network effects, rendering Nostr as a de facto "3rd layer" for Lightning and a natural successor to LNURL.

When layered over kind 21000, NWC, or other potential Lightning RPCs, this specification enables a seamless user experience similar to legacy LNURL-Pay, without the domain and SSL requirements. Additionally, the signed nature of Nostr communications minimizes the trust requirements inherent in LNURL when a receiving node must outsource the serving of web requests.

## Specification

### Static Payment Code Format

The static payment code is a bech32 (per [NIP-19](19.md)) encoded string prefixed with `noffer`. The encoded string will include the following TLV (Type-Length-Value) items:

- `0`: The 32 bytes of the receiving service's public key, encoded in hex.
- `1`: The relay URL where the receiving service subscribes to payment requests.
- `2`: The offer identifying string.
- `3`: A flag indicating the pricing type:
  - `0`: Fixed price
  - `1`: Variable price
  - `2`: Spontaneous payment (payer specifies the amount)
- `4`: The price in sats (optional for display purposes).

If neither the price nor the pricing type flag is present, the sender may assume it is a spontaneous payment offer.

Example static payment code structure:

```
noffer1...
  0: <receiver_public_key_in_hex>
  1: <relay_url>
  2: <offer_id_string> 
  3: <pricing_type_flag> (optional, 0 for fixed, 1 for variable, 2 for spontaneous)
  4: <price_in_sats> (optional)
```

## Integration with other NIPs

### NIP-01 User Metadata

Example user metadata content with `nip69` field:
```json
{
  "pubkey": "hex_pub",
  "kind": 0,
  "content": "{\"name\": \"bob\", \"nip05\": \"bob@example.com\", \"nip69\": \"noffer1...\"}"
  ...
}
```

### NIP-05 "Lightning Addresses"

To support trust-minimized Lightning Addresses, services can add a `nip69` field in the NIP-05 content to contain an offer for spontaneous payments. This field will provide the offer on name-based lookups.

Example NIP-05 Service Response with Offers


```json
{
  "names": {
    "bob": "hex_pub"
  },
  "nip69": {
    "bob": "noffer1..."
  }
}
```

### NIP-57 Zaps

Instead of using the LNURL-pay callback, the "zap" flow can be initiated as content payload to an Offer:

1. The client creates a kind 9734 zap request event as specified in NIP-57.
2. Instead of sending this to an LNURL-pay endpoint, the client sends it as the `zap` part of the encrypted content in a NIP-69 payment request.
3. The receiver processes the NIP-69 payment request, decrypts the content, extracts the kind 9734 event, and uses it to generate the invoice.
4. The receiver responds with the invoice as specified in NIP-69.
5. Once paid, the receiver generates and publishes the kind 9735 zap receipt as specified in NIP-57.

Example NIP-57 zap request:

```json
{
  "id": "<event_id>",
  "pubkey": "<sender_pubkey>",
  "created_at": 1234567890,
  "kind": 21001,
  "tags": [
    ["p", "<receiver_pubkey>"]
  ],
  "content": "<NIP-44 encrypted {\"offer\":\"<zap1234>\",\"zap\":<kind 9734 zap request event>}>",
  "sig": "<signature>"
}
```

There is no requirement on the service to acknowledge the zap request content, given that spontaneous payments are default behavior. Service implementations and clients should however consider offer identifiers, where `startsWith("zap")`, to indicate that the service will honor zap requests. A service should not error if no zap request is attached to a zap named offer, rather just treat it any other spontaneous payment.

## General Process Flow

1. **Payer Scans or Clicks the Static Payment Code**
2. **Payer's Wallet Decodes the Payment Code**
3. **Payer's Wallet Sends a Nostr Event to the Specified Relay**
   - Addressed to the receiver's public key, containing the offer identifying string.
   - Event Type: Ephemeral Kind 21001 | NIP-44 Encrypted
   - **Conditional**: Include the amount in sats the sender wishes to pay if the payment type is spontaneous.
   - Optional: Include additional payer data.
4. **Receiver Responds with Lightning Invoice**
   - Generates a Lightning invoice and responds with a Nostr event containing the invoice details.
   - Event Type: Ephemeral Kind 21001 | NIP-44 Encrypted
   - **Content**: `{"bolt11":"<BOLT11_invoice_string>"}`
   - Optional: Include additional purchase data.
5. **Payer Pays the Invoice**
   - Completes the payment by settling the Lightning invoice.
6. **Optional: Receiver Emits Payment Receipt**
   - This step is out of scope for this NIP, but potential receipt considerations include:
     - Nostr Event as Receipt: Emitting a public Nostr event as a "zap" receipt for verifiable record-keeping.
     - Lightning Pre-Image: The Lightning pre-image is proof of payment.
     - External / WebHook: The receiver may finalize the flow out-of-band.

### Nostr Event

This NIP specifies the use of event kind `21001` with the following structure:

- `content`: NIP-44 encrypted payment details.
- `tags`: 
  - `p`: Receiver's public key (hex).
  - `e`: Used in response to the requesting event.

Example event:

```json
{
  "id": "<event_id>",
  "pubkey": "<sender_pubkey>",
  "created_at": 1234567890,
  "kind": 21001,
  "tags": [
    ["p", "<receiver_pubkey>"],
    ["e", "<event_id>"] // used only in response by the receiver to identify the original payment request
  ],
  "content": "<NIP-44 encrypted offer identifier and conditional payer data>",
  "sig": "<signature>"
}
```

The `content` field, after NIP-44 decryption, should contain an object with the following structure:

```json
{
    "offer": "<offer_string>",
    "amount": "<conditional_amount_in_sats>",
    "payer_data": "<optional_payer_data>"
}
```

Example response event with `bolt11` invoice:

```json
{
  "id": "<response_event_id>",
  "pubkey": "<receiver_pubkey>",
  "created_at": 1234567891,
  "kind": 21001,
  "tags": [
    ["p", "<sender_pubkey>"],
    ["e", "<event_id>"] // original payment request event ID
  ],
  "content": "<NIP-44 encrypted {\"bolt11\":\"<BOLT11_invoice_string>\"}>",
  "sig": "<signature>"
}
```

## Client Behavior

### Mandatory

Clients implementing this NIP must:

1. Decode and validate the structure of the `noffer` bech32-encoded static payment code.
2. Use NIP-44 encryption for all communication between payer and receiver.
3. Generate and send kind 21001 events as specified in this NIP.
4. Parse the `content` field of received events by decrypting and JSON-parsing the stringified content.
5. Handle potential errors gracefully, providing clear feedback to users.
6. Respect the relay URL specified in the static payment code for sending payment request events.

### Optional

Clients implementing this NIP may:

1. Support both this protocol and LNURL for backward compatibility during the transition period.
2. Implement additional features such as multi-recipient payments or integration with other Lightning-related NIPs.
   - Ex: If an offer lists multiple recipient keys, a client might "for each" over them to pay multiple recipients.
3. Use Addressable Events: Nest offers in addressable event for marketplace products where the offer may change more frequently than the product due to price, receiving key, or relay URL associated with the offer.
4. **Attempt Payments by Name**: Use the combination of NIP-05 and NIP-69 to attempt payments by name-based lookups.
5. Prefix and Parse `noffer` strings with existing `lightning:` link handlers, just as they would invoices or legacy LNURL strings.

### Prohibited

Clients implementing this NIP MUST NOT:

1. Send unencrypted sensitive information in event content or tags.
2. Ignore or modify any fields from the encoded static payment code.

## Service Behavior

### Optional

Services implementing this NIP may:

1. Use an account identifier as a default offer string for spontaneous payments without explicit user setup.
2. **NIP-05 Integration**: Add a `nip69` field in the NIP-05 content to provide the offer on name-based lookups for trust-optimized Lightning Addresses.

## Error Handling

To ensure consistent error handling across implementations, this NIP defines the following error responses, similar to other NIPs:

1. **Invalid Offer**: When the offer ID is invalid or no longer available.
2. **Temporary Failure**: When the receiver is temporarily unable to process the request.
3. **Expired Offer**: When the offer has expired and is no longer valid.
4. **Unsupported Feature**: When the receiver doesn't support a feature requested by the payer.
5. **Invalid Amount**: When the amount specified is too big or too small, providing the acceptable range.

Error responses should be sent as kind 21001 events with the following structure in the encrypted content:

```json
{
  "error": "<error_message>",
  "code": "<error_code>",
  "range": {
    "min": "<minimum_amount_in_sats>",
    "max": "<maximum_amount_in_sats>"
  }
}
```

Error codes:

- 1: Invalid Offer
- 2: Temporary Failure
- 3: Expired Offer
- 4: Unsupported Feature
- 5: Invalid Amount

Clients MUST handle these error responses gracefully and display appropriate messages to users.

## Transition from LNURL

LNURL services wishing to migrate to Nostr Offer STRings should consider adding a `noffer` tag to their responses.

## Future Considerations

Future versions of this NIP may consider standardizing additional features such as:

1. Multi-recipient payments with weighting.
2. Integration with other Lightning-related NIPs.
3. Extended metadata for more complex payment scenarios.
4. Best practices for use with Addressable Events.

## Reference Implementation

Lightning.Pub / ShockWallet noffer branches