diff --git a/19.md b/19.md new file mode 100644 index 0000000..6f4d78b --- /dev/null +++ b/19.md @@ -0,0 +1,67 @@ +# NUT-19: Cached Responses + +`optional` + +--- + +To minimize the risk of loss of funds to due network errors during critical operations such as minting, swapping, and melting, we introduce a caching mechanism for successful responses. This allows wallet to replay requests on cached endpoints and allow it to recover the desired state after a network interruption. + +## Requests & Responses + +Any Mint implementation should elect a data structure `D` that maps request objects to their respective responses. `D` should be fit for fast insertion, look-up and deletion (eviction) operations. This could be an in-memory database or a dedicated caching service like Redis. + +### Derive & Repeat + +Upon receiving a `request` on a cached endpoint, the mint derives a unique key `k` for it which should depend on the method, path, and the payload of `request`. + +The mint uses `k` to look up a `response = D[k]` and discriminates execution based on the following checks: + +- If no cached `response` is found: `request` has no matching `response`. The mint processes `request` as per usual. +- If a cached `response` is found: `request` has a matching `response`. The mint returns the cached `response`. + +### Store + +For each successful response on a cached endpoint (`status_code == 200`), the mint stores the response in `D` under key `k` (`D[k] = response`). + +### Expiry + +The mint decides the `ttl` (Time To Live) of cached response, after which it can evict the entry from `D`. + +## Settings + +Support for NUT-19 is announced as an extension to the `nuts` field of the `GetInfoResponse` described in [NUT-6](06). + +The entry is structured as follows: + +```json +"nuts": { + ..., + "19": { + "ttl": , + "cached_endpoints": [ + { + "method": "POST", + "path": "/v1/mint/bolt11", + }, + { + "method": "POST", + "path": "/v1/swap", + }, + ... + ] + } +} +``` + +Where: + +- `ttl` is the number of seconds the responses are cached for +- `cached_endpoints` is a list of the methods and paths for which caching is enabled. +- `path` and `method` describe the cached route and its method respectively. + +If `ttl` is `null`, the responses are expected to be cached _indefinitely_. + +[03]: 03.md +[04]: 04.md +[05]: 05.md +[06]: 06.md diff --git a/README.md b/README.md index b63ab38..ac0a5bc 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,7 @@ Wallets and mints `MUST` implement all mandatory specs and `CAN` implement optio | [16][16] | Animated QR codes | [Cashu.me][cashume] | - | | [17][17] | WebSocket subscriptions | [Nutshell][py] | [Nutshell][py] | | [18][18] | Payment requests | [Cashu.me][cashume], [Boardwalk][bwc], [cdk-cli] | - | +| [19][19] | Cached Responses | - | [Nutshell][py], [cdk-mintd] | #### Wallets: @@ -89,3 +90,4 @@ Wallets and mints `MUST` implement all mandatory specs and `CAN` implement optio [16]: 16.md [17]: 17.md [18]: 18.md +[19]: 19.md