abstract NUT-17 subscription kinds

07.md

@@ -99,6 +99,23 @@ curl -X POST https://mint.host:3338/v1/checkstate -H 'Content-Type: application/
 
 Where `Y` belongs to the provided `Proof` to check in the request, `state` indicates its state, and `witness` is the witness data that was potentially provided in a previous spend operation (can be empty).
 
+## WebSocket Subscriptions
+
+`optional`
+
+`depends on: NUT-17`
+
+This section defines websocket subscriptions for proof state changes, extending [NUT-17][17].
+
+### Subscription Kind
+
+#### `proof_state`
+
+Subscribe to proof state changes.
+
+- **`filters`**: Array of `Y` values
+- **`NotificationPayload`**: `ProofState` object from `PostCheckStateResponse`
+
 ## Mint info setting
 
 The [NUT-06][06] `MintMethodSetting` indicates support for this feature:
@@ -125,3 +142,4 @@ The [NUT-06][06] `MintMethodSetting` indicates support for this feature:
 [11]: 11.md
 [12]: 12.md
 [14]: 14.md
+[17]: 17.md

17.md

@@ -2,17 +2,23 @@
 
 `optional`
 
-`depends on: NUT-07`
+`used in: NUT-07, NUT-23, NUT-25`
 
 ---
 
-This NUT defines a websocket protocol that enables bidirectional communication between apps and mints using the JSON-RPC format.
+This NUT defines a websocket protocol that enables bidirectional communication between apps and mints using the JSON-RPC format. It provides the general framework for real-time subscriptions, with specifics for each supported subscription type provided in dedicated NUTs.
 
 ## Subscriptions
 
-The websocket enables real-time subscriptions that wallets can use to receive notifications for a state change of a `MintQuoteResponse` ([NUT-04][04]), `MeltQuoteResponse` ([NUT-05][05]), `CheckStateResponse` ([NUT-07][07]).
+The websocket enables real-time subscriptions that wallets can use to receive notifications for a state change as defined in the corresponding NUT:
 
-A summary of the subscription flow is the following:
+- [NUT-07][07] for proof state subscriptions
+- [NUT-23][23] for bolt11 mint and melt quote subscriptions
+- [NUT-25][25] for bolt12 mint and melt quote subscriptions
+
+## General Flow
+
+The websocket subscription process follows these steps for all subscription types:
 
 1. A wallet connects to the websocket endpoint and sends a `WsRequest` with the `subscribe` command.
 2. The mint responds with a `WsResponse` containing an ok or an error.
@@ -67,21 +73,9 @@ To subscribe to updates, the wallet sends a `"subscribe"` command with the follo
 
 Here, `subId` is a unique uuid generated by the wallet and allows the client to map its requests to the mint's responses.
 
-`SubscriptionKind` is an enum with the following possible values:
-
-```ts
-enum SubscriptionKind {
-  bolt11_melt_quote = "bolt11_melt_quote",
-  bolt11_mint_quote = "bolt11_mint_quote",
+`SubscriptionKind` specifies what type of subscription the wallet wants to create where specific kinds are defined in their corresponding NUT.
 
-  bolt12_melt_quote = "bolt12_melt_quote",
-  bolt12_mint_quote = "bolt12_mint_quote",
-
-  proof_state = "proof_state",
-}
-```
-
-The `filters` are an array of mint quote IDs ([NUT-04][04]), or melt quote IDs ([NUT-05][05]), or `Y`'s ([NUT-07][07]) of the corresponding object to receive updates from.
+The `filters` are an array of identifiers for the specific objects to receive updates from. The format of these identifiers depends on the subscription kind.
 
 As an example, `filters` would be of the following form to subscribe for updates of three different mint quote IDs:
 
@@ -137,7 +131,8 @@ Here, the `id` corresponds to the `id` in the request (as part of the JSON-RPC s
 }
 ```
 
-`subId` is the subscription ID (previously generated by the wallet) this notification corresponds to. `NotificationPayload` carries the subscription data which is a `MintQuoteResponse` ([NUT-04][04]), a `MeltQuoteResponse` ([NUT-05][05]), or a `CheckStateResponse` ([NUT-07][07]), depending on what the corresponding `SubscriptionKind` was.
+- `subId` is the subscription ID (previously generated by the wallet) this notification corresponds to
+- `NotificationPayload` carries the subscription data defined by the `SubscriptionKind`.
 
 ### Errors
 
@@ -251,7 +246,7 @@ Mints signal websocket support via [NUT-06][06] using the following setting:
 }
 ```
 
-Here, `commands` is an array of the commands that the mint supports. A mint that supports all commands would return `["bolt11_mint_quote", "bolt11_melt_quote", "bolt12_mint_quote", "bolt12_melt_quote", "proof_state"]`. Supported commands are given for each method-unit pair.
+Here, `commands` is an array of the commands that the mint supports. Supported commands are given for each method-unit pair.
 
 Example:
 
@@ -273,6 +268,14 @@ Example:
 }
 ```
 
+## Adding New Subscription Types
+
+To add a new subscription type, implement the following in the corresponding NUT:
+
+1. Define the subscription kind identifier (ie `bolt11_melt_quote`)
+2. Specify the format of the `filters` array
+3. Define the `NotificationPayload` structure
+
 [00]: 00.md
 [01]: 01.md
 [02]: 02.md
@@ -286,3 +289,5 @@ Example:
 [10]: 10.md
 [11]: 11.md
 [12]: 12.md
+[23]: 23.md
+[25]: 25.md

23.md

@@ -254,5 +254,32 @@ Successful melt response:
 }
 ```
 
+## WebSocket Subscriptions
+
+`optional`
+
+`depends on: NUT-17`
+
+This section defines websocket subscriptions for the `bolt11` payment method, extending [NUT-17][17].
+
+### Subscription Kinds
+
+For the `bolt11` method, the following subscription kinds are supported:
+
+#### `bolt11_mint_quote`
+
+Subscribe to state changes for NUT-23 mint quotes.
+
+- **`filters`**: Array of NUT-23 mint quote IDs
+- **`NotificationPayload`**: `PostMintQuoteBolt11Response` as defined above
+
+#### `bolt11_melt_quote`
+
+Subscribe to state changes for NUT-23 melt quotes.
+
+- **`filters`**: Array of NUT-23 melt quote IDs
+- **`NotificationPayload`**: `PostMeltQuoteBolt11Response` as defined above
+
 [04]: 04.md
 [05]: 05.md
+[17]: 17.md

25.md

@@ -272,8 +272,35 @@ curl -X POST https://mint.host:3338/v1/melt/bolt12 -d \
 }
 ```
 
+## WebSocket Subscriptions
+
+`optional`
+
+`depends on: NUT-17`
+
+This section defines websocket subscriptions for the `bolt12` payment method, extending [NUT-17][17].
+
+### Subscription Kinds
+
+For the `bolt12` method, the following subscription kinds are supported:
+
+#### `bolt12_mint_quote`
+
+Subscribe to state changes for NUT-25 mint quotes.
+
+- **`filters`**: Array of NUT-25 mint quote IDs
+- **`NotificationPayload`**: `PostMintQuoteBolt12Response` as defined above
+
+#### `bolt12_melt_quote`
+
+Subscribe state changes for NUT-25 melt quotes.
+
+- **`filters`**: Array of NUT-25 melt quote IDs
+- **`NotificationPayload`**: `PostMeltQuoteBolt12Response` as defined above
+
 [02]: 02.md
 [04]: 04.md
 [05]: 05.md
 [08]: 08.md
+[17]: 17.md
 [20]: 20.md