Merge 89fe83d5eb into 7dec812f99

nip22: fix example type for external URL (#2011 )
NIP-24: Fix heading levels (#2009 )
2025-08-12 22:27:19 +00:00 · 2025-08-11 17:26:05 -04:00 · 2025-08-11 19:37:53 +09:00 · 2025-08-11 19:35:36 +09:00 · 2025-07-31 20:58:39 +07:00 · 2025-03-03 23:15:33 +07:00
4 changed files with 104 additions and 14 deletions
--- a/21.md
+++ b/21.md
@ -21,7 +21,7 @@ The identifiers that come after are expected to be the same as those defined in

 ### Linking HTML pages to Nostr entities

-`<link>` tags with `rel="alternate"` can be used to associate webpages to Nostr events, in cases where the same content is served via the two mediums (for example, a web server that exposes Markdown articles both as HTML pages and as `kind:30023' events served under itself as a relay or through some other relay). For example:
+`<link>` tags with `rel="alternate"` can be used to associate webpages to Nostr events, in cases where the same content is served via the two mediums (for example, a web server that exposes Markdown articles both as HTML pages and as `kind:30023` events served under itself as a relay or through some other relay). For example:

 ```
 <head>
--- a/22.md
+++ b/22.md
@ -143,13 +143,13 @@ A comment on a website's url looks like this:
  "tags": [
    // referencing the root url
    ["I", "https://abc.com/articles/1"],
-    // the root "kind": for an url, the kind is its domain
-    ["K", "https://abc.com"],
+    // the root "kind": for an url
+    ["K", "web"],

    // the parent reference (same as root for top-level comments)
    ["i", "https://abc.com/articles/1"],
-    // the parent "kind": for an url, the kind is its domain
-    ["k", "https://abc.com"]
+    // the parent "kind": for an url
+    ["k", "web"]
  ]
  // other fields
 }
--- a/24.md
+++ b/24.md
@ -8,8 +8,7 @@ Extra metadata fields and tags

 This NIP keeps track of extra optional fields that can added to events which are not defined anywhere else but have become _de facto_ standards and other minor implementation possibilities that do not deserve their own NIP and do not have a place in other NIPs.

-kind 0
-======
+### kind 0

 These are extra fields not specified in NIP-01 that may be present in the stringified JSON of metadata events:

@ -19,24 +18,22 @@ These are extra fields not specified in NIP-01 that may be present in the string
  - `bot`: a boolean to clarify that the content is entirely or partially the result of automation, such as with chatbots or newsfeeds.
  - `birthday`: an object representing the author's birth date. The format is { "year": number, "month": number, "day": number }. Each field MAY be omitted.

-### Deprecated fields
+#### Deprecated fields

 These are fields that should be ignored or removed when found in the wild:

  - `displayName`: use `display_name` instead.
  - `username`: use `name` instead.

-kind 3
-======
+### kind 3

 These are extra fields not specified in NIP-02 that may be present in the stringified JSON of follow events:

-### Deprecated fields
+#### Deprecated fields

  - `{<relay-url>: {"read": <true|false>, "write": <true|false>}, ...}`: an object of relays used by a user to read/write. [NIP-65](65.md) should be used instead.

-tags
-====
+### tags

 These tags may be present in multiple event kinds. Whenever a different meaning is not specified by some more specific NIP, they have the following meanings:

--- a/47.md
+++ b/47.md
@ -151,6 +151,8 @@ _Note on backwards-compatibility:_ If a **wallet service** supports both nip44 a

 Communication between the **client** and **wallet service** requires two keys in order to encrypt and decrypt messages. The connection URI includes the secret key of the **client** and only the public key of the **wallet service**.

+> This is the original flow for initiating a NWC connection, however is less secure and prone to user error as the secret must be copy-pasted into the **client** to initiate the connection. Please see the client-created secret flows below as an alternative.
+
 The **client** discovers **wallet service** by scanning a QR code, handling a deeplink or pasting in a URI.

 The **wallet service** generates this connection URI with protocol `nostr+walletconnect://` and base path its 32-byte hex-encoded `pubkey`, which SHOULD be unique per client connection.
@ -175,6 +177,95 @@ The **client** should then store this connection and use it when the user wants
 nostr+walletconnect://b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558e9d4?relay=wss%3A%2F%2Frelay.damus.io&secret=71a8c14c1407c113601079c4302dab36460f0ccd0ad506f1f2dc73b5100e4f3c
 ```

+## Client-Created Secret
+
+The client MAY generate its own secret and co-ordinate only public keys with the wallet service so that secrets are never exposed.
+
+### HTTP Confirmation Page
+
+A **wallet service** MAY host a publicly accessible confirmation page that the **client** may open (e.g. in a webview or popup window) and allow the **user** to confirm the creation of a new connection, with the following parameters:
+
+- `pubkey` Required. The corresponding pubkey of the secret generated by the **client**.
+
+The **wallet service** MAY ignore all the below optional parameters.
+
+- `name`: Optional. The name of the client app.
+- `icon`: Optional. The URL of an icon of the client app to display on the confirmation page.
+- `return_to` Optional. URI to open after the connection is created. The **wallet service** SHOULD add the `relay_url`, `wallet_pubkey` and `lud16` parameters to the URI.
+- `expires_at` Optional. The connection cannot be used after this date. Unix timestamp in seconds.
+- `max_amount` Optional. The maximum amount in millisats that can be sent per renewal period
+- `budget_renewal` Optional. The reset the budget at the end of the given budget renewal. Can be `never` (default), `daily`, `weekly`, `monthly`, `yearly`
+- `request_methods` Optional. The url encoded, space separated list of request types that you need permission for. For example: `..&request_methods=pay_invoice%20get_balance`
+- `notification_types` Optional. The url encoded, space separated list of notification types that you need permission for. For example: `..&notification_types=payment_received%20payment_sent`
+- `isolated` Optional. The makes an isolated app connection / sub-wallet with its own balance and only access to its own transaction list. e.g. `&isolated=true`.
+- `metadata` Optional. Url encoded, JSON-serialized metadata that describes the app connection.
+
+The **user** MUST be presented with a confirmation page to be able to review and approve or decline the connection.
+
+If the **user** approves the request, a new connection should be created for **client**'s public key (specified in the `pubkey` parameter).
+
+#### Communicating the wallet pubkey and relay to the client via popup/webview
+
+The confirmation page MAY dispatch an event and post a message to the window and window opener (if present) so that the **client** can discover the pubkey and preferred relay url of the **wallet service**.
+
+```javascript
+window.dispatchEvent(new CustomEvent("nwc:success", {
+    detail: {
+        relayUrl,
+        walletPubkey,
+        lud16, // optional
+    },
+}));
+
+window.opener?.postMessage({
+    type: "nwc:success",
+    relayUrl,
+    walletPubkey,
+    lud16, // optional
+}, "*");
+```
+
+At this point, both the **client** and **wallet service** have all information required to communicate over NWC.
+
+#### Example HTTP confirmation URL
+
+`https://example.com/connections/new?pubkey=b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558e9d4`
+
+### Nostr Flow
+
+The **client** MAY generate an authorization URI with protocol `nostr+walletauth://` and base path its hex-encoded `pubkey` with the following query string parameters:
+
+- `relay` Required. URL of the relay where the **client** intends to communicate with the **wallet service**. May be more than one.
+
+The **wallet service** MAY ignore all the below optional parameters.
+
+- `name`: Optional. The name of the client app.
+- `icon`: Optional. The URL of an icon of the client app to display on the confirmation page.
+- `return_to` Optional. URI to open after the connection is created.
+- `expires_at` Optional. The connection cannot be used after this date. Unix timestamp in seconds.
+- `max_amount` Optional. The maximum amount in millisats that can be sent per renewal period
+- `budget_renewal` Optional. The reset the budget at the end of the given budget renewal. Can be `never` (default), `daily`, `weekly`, `monthly`, `yearly`
+- `request_methods` Optional. The url encoded, space separated list of request types that you need permission for. For example: `..&request_methods=pay_invoice%20get_balance`
+- `notification_types` Optional. The url encoded, space separated list of notification types that you need permission for. For example: `..&notification_types=payment_received%20payment_sent`
+- `isolated` Optional. The makes an isolated app connection / sub-wallet with its own balance and only access to its own transaction list. e.g. `&isolated=true`.
+- `metadata` Optional. Url encoded, JSON-serialized metadata that describes the app connection.
+
+The **user** opens the URL in the **wallet service** by scanning a QR code, handling a deeplink or pasting in a URI, and MUST be presented with a confirmation page.
+
+If the **user** approves the request, a new connection should be created for the **client**'s public key (specified in the base path of the authorization URI). Once the connection is created, the NIP-47 info event MUST be broadcasted to the relays specified in the authorization URI, and the info event MUST include a `p` tag containing the public key of the **client** this info is for, so that the **client** can discover the public key of the **wallet service**. The `p` tag MAY contain the recommended relay url of the **wallet service**. If provided, the recommended relay url MUST be used.
+
+The **client** is then able to subscribe to the NIP-47 info event (kind 13194) filtered by setting the `p` tag to the pubkey of the **client**. The **client** will then know the public key of the **wallet service** (as the publisher of the info event).
+
+At this point, both the **client** and **wallet service** have all information required to communicate over NWC.
+
+The `lud16` field cannot be immediately communicated via the NIP-47 event to avoid metadata leaks. To discover the lightning address, the **client** MAY look for the presence of the  `lud16` parameter in the `get_info` response.
+
+#### Example Authorization URI
+
+`nostr+walletauth://b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558e9d4?relay=wss%3A%2F%2Frelay.example.com%2Fv1`
+
+To target a specific wallet, a `nostr+walletauth+walletname` scheme may be used.
+
 ## Commands

 ### `pay_invoice`
@ -479,6 +570,7 @@ Response:
            "block_hash": "hex string",
            "methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "get_info"], // list of supported methods for this connection
            "notifications": ["payment_received", "payment_sent"], // list of supported notifications for this connection, optional.
+            "lud16": "string" // lightning address for this connection, optional
    }
 }
 ```
@ -627,7 +719,8 @@ This NIP does not specify any requirements on the type of relays used. However,
    [
      "notifications",
      "payment_received payment_sent"
-    ]
+    ],
+    ["p", "3ba6db4896124383fdaa5f7d42c25f9df1b128a280928baeb3f3fa36d25506f9"]
  ],
  "content": "pay_invoice pay_keysend get_balance get_info make_invoice lookup_invoice list_transactions multi_pay_invoice multi_pay_keysend sign_message notifications",
  "sig": "31f57b369459b5306a5353aa9e03be7fbde169bc881c3233625605dd12f53548179def16b9fe1137e6465d7e4d5bb27ce81fd6e75908c46b06269f4233c845d8"
Author	SHA1	Message	Date
Roland	2c4d6ca247	Merge `89fe83d5eb` into `7dec812f99`	2025-08-12 22:27:19 +00:00
Awiteb	7dec812f99	nip22: fix example type for external URL (#2011 )	2025-08-11 17:26:05 -04:00
Yoji Shidara	739f3c5263	NIP-24: Fix heading levels (#2009 )	2025-08-11 19:37:53 +09:00
Yoji Shidara	8830525250	NIP-21: Fix markup issue by closing backtick (#2008 )	2025-08-11 19:35:36 +09:00
Roland Bewick	89fe83d5eb	docs: clarify usage of recommended relay url	2025-07-31 20:58:39 +07:00
Roland Bewick	62c18d5bbe	docs: NIP-47 client-created secret	2025-03-03 23:15:33 +07:00