From 9616490619179ec612a9f94d6dae68773e098003 Mon Sep 17 00:00:00 2001 From: elnosh Date: Tue, 28 Jan 2025 12:06:58 -0500 Subject: [PATCH] NUT-17: clarify notification should be an array --- 17.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 70 insertions(+), 15 deletions(-) diff --git a/17.md b/17.md index 5603237e..8b9f7204 100644 --- a/17.md +++ b/17.md @@ -73,7 +73,7 @@ Here, `subId` is a unique uuid generated by the wallet and allows the client to enum SubscriptionKind { bolt11_melt_quote = "bolt11_melt_quote", bolt11_mint_quote = "bolt11_mint_quote", - proof_state = "proof_state", + proof_states = "proof_states", } ``` @@ -89,7 +89,7 @@ Note that `id` and `subId` are unrelated. The `subId` is the ID for each subscri **Important:** If the subscription is accepted by the mint, the mint MUST first respond with the _current_ state of the subscribed object and continue sending any further updates to it. -For example, if the wallet subscribes to a `Proof.Y` of a `Proof` that has not been spent yet, the mint will first respond with a `ProofState` with `state == "UNSPENT"`. If the wallet then spends this `Proof`, the mint would send a `ProofState` with `state == "PENDING"` and then one with `state == "SPENT"`. In total, the mint would send three notifications to the wallet. +For example, if the wallet subscribes to a `MintQuote` that has not been paid yet, the mint will first respond with a `MintQuoteResponse` with `state == "UNPAID"`. If the request for the quote gets paid, the mint would send a `MintQuoteResponse` with `state == "PAID"` and then after issuance, one with `state == "ISSUED"`. In total, the mint would send three notifications to the wallet. #### Command: Unsubscribe @@ -133,7 +133,10 @@ 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 which is a `MintQuoteResponse` ([NUT-04][04]), a `MeltQuoteResponse` ([NUT-05][05]), or a `CheckStateResponse` ([NUT-07](https://github.com/cashubtc/nuts/blob/main/07.md#example)), depending on what the corresponding `SubscriptionKind` was. + +**Note: `CheckStateResponse` is an array of only the `ProofStates` that have been updated. For example, if the wallet subscribes to 10 `Proofs` +and 5 `Proofs` have changed, the notification will consist of an array of the 5 `ProofStates` that changed.** ### Errors @@ -150,9 +153,9 @@ Here, the `id` corresponds to the `id` in the request (as part of the JSON-RPC s } ``` -### Example: `ProofState` subscription +### Example: `ProofStates` subscription -To subscribe to the `ProofState` of a `Proof`, the wallet establishes a websocket connection to `https://mint.com/v1/ws` and sends a `WsRequest` with a `filters` chosen to be the a `Proof.Y` value of the `Proof` (see [NUT-00][00]). Note that `filters` is an array meaning multiple subscriptions of the same `kind` can be made in the same request. +To subscribe to the `ProofStates` of a set `Proofs`, the wallet establishes a websocket connection to `https://mint.com/v1/ws` and sends a `WsRequest` with a `filters` array chosen to be the `Proof.Y` values of the `Proofs` (see [NUT-00][00]). Note that `filters` is an array meaning it can subscribe to updates from multiple objects of the same `kind` in one request. Wallet: @@ -162,9 +165,10 @@ Wallet: "id": 0, "method": "subscribe", "params": { - "kind": "proof_state", + "kind": "proof_states", "filters": [ - "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d" + "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d", + "02599b9ea0a1ad4143706c2a5a4a568ce442dd4313e1cf1f7f0b58a317c1a355ee" ], "subId": "Ua_IYvRHoCoF_wsZFlJ1m4gBDB--O0_6_n0zHg2T" } @@ -186,7 +190,7 @@ Mint: } ``` -The mint immediately sends the current `ProofState` of the subscription as a `WsNotification`. +The mint immediately sends the current `ProofStates` of the subscription as a `WsNotification`. Mint: @@ -197,22 +201,73 @@ Mint: "params": { "subId": "Ua_IYvRHoCoF_wsZFlJ1m4gBDB--O0_6_n0zHg2T", "payload": { - "Y": "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d", - "state": "UNSPENT", - "witness": null + "states": [ + { + "Y": "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d", + "state": "UNSPENT", + "witness": null + }, + { + "Y": "02599b9ea0a1ad4143706c2a5a4a568ce442dd4313e1cf1f7f0b58a317c1a355ee", + "state": "UNSPENT", + "witness": null + } + ] } } } ``` -While leaving the websocket connection open, the wallet then spends the ecash. The mint sends `WsNotification` updating the wallet about state changes of the `ProofState` accordingly: +While leaving the websocket connection open, the wallet then spends the ecash. The mint sends `WsNotification` updating the wallet about state changes of the `ProofStates` accordingly: Mint: ```json -{"jsonrpc": "2.0", "method": "subscribe", "params": {"subId": "Ua_IYvRHoCoF_wsZFlJ1m4gBDB--O0_6_n0zHg2T", "payload": {"Y": "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d", "state": "PENDING"}}} +{ + "jsonrpc": "2.0", + "method": "subscribe", + "params": { + "subId": "Ua_IYvRHoCoF_wsZFlJ1m4gBDB--O0_6_n0zHg2T", + "payload": { + "states": [ + { + "Y": "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d", + "state": "PENDING", + "witness": null + }, + { + "Y": "02599b9ea0a1ad4143706c2a5a4a568ce442dd4313e1cf1f7f0b58a317c1a355ee", + "state": "PENDING", + "witness": null + } + ] + } + } +} +``` -{"jsonrpc": "2.0", "method": "subscribe", "params": {"subId": "Ua_IYvRHoCoF_wsZFlJ1m4gBDB--O0_6_n0zHg2T", "payload": {"Y": "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d", "state": "SPENT"}}} +```json +{ + "jsonrpc": "2.0", + "method": "subscribe", + "params": { + "subId": "Ua_IYvRHoCoF_wsZFlJ1m4gBDB--O0_6_n0zHg2T", + "payload": { + "states": [ + { + "Y": "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d", + "state": "SPENT", + "witness": null + }, + { + "Y": "02599b9ea0a1ad4143706c2a5a4a568ce442dd4313e1cf1f7f0b58a317c1a355ee", + "state": "SPENT", + "witness": null + } + ] + } + } +} ``` The wallet then unsubscribes. @@ -261,7 +316,7 @@ Example: "commands": [ "bolt11_mint_quote", "bolt11_melt_quote", - "proof_state" + "proof_states" ] }, ]