diff --git a/07.md b/07.md index 4589120e..63860af4 100644 --- a/07.md +++ b/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 diff --git a/17.md b/17.md index a51fd65a..6b737848 100644 --- a/17.md +++ b/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 diff --git a/23.md b/23.md index 3a3a22d2..bbd522b4 100644 --- a/23.md +++ b/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 diff --git a/25.md b/25.md index 7bbd3a60..c1abb047 100644 --- a/25.md +++ b/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