NUT-17: clarify subscription kind example

cashubtc · Jan 28, 2025 · 3ff5ec3 · 3ff5ec3
1 parent f084e0d
commit 3ff5ec3
Showing 1 changed file with 63 additions and 11 deletions.
diff --git a/17.md b/17.md
@@ -133,7 +133,7 @@ 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 that `CheckStateResponse` is an array of `ProofState`s.
 
 ### Errors
 
@@ -150,9 +150,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 +164,8 @@ Wallet:
   "params": {
     "kind": "proof_state",
     "filters": [
-      "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d"
+      "02e208f9a78cd523444aadf854a4e91281d20f67a923d345239c37f14e137c7c3d",
+      "02599b9ea0a1ad4143706c2a5a4a568ce442dd4313e1cf1f7f0b58a317c1a355ee"
     ],
     "subId": "Ua_IYvRHoCoF_wsZFlJ1m4gBDB--O0_6_n0zHg2T"
   }
@@ -186,7 +187,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 +198,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.