NUT-17: clarify notification should be an array

cashubtc · Jan 30, 2025 · 5741865 · 5741865
1 parent f084e0d
commit 5741865
Showing 1 changed file with 70 additions and 13 deletions.
diff --git 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,12 @@ 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 +155,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:
 
@@ -164,7 +169,8 @@ Wallet:
   "params": {
     "kind": "proof_state",
     "filters": [
-      "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d"
+      "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d",
+      "02599b9ea0a1ad4143706c2a5a4a568ce442dd4313e1cf1f7f0b58a317c1a355ee"
     ],
     "subId": "Ua_IYvRHoCoF_wsZFlJ1m4gBDB--O0_6_n0zHg2T"
   }
@@ -186,7 +192,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 +203,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.