Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

NUT-17: clarify ProofStates subscription example #213

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

NUT-17: clarify ProofStates subscription example #213

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 70 additions & 15 deletions 17.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
}
```

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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:

Expand All @@ -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"
}
Expand All @@ -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:

Expand All @@ -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.
Expand Down Expand Up @@ -261,7 +316,7 @@ Example:
"commands": [
"bolt11_mint_quote",
"bolt11_melt_quote",
"proof_state"
"proof_states"
]
},
]
Expand Down