commit 0ff642bbd5ea9383543f6b7d2ab8df1e0f5ff784
parent c9b8dd1bab782d21aafa42fc1eeec97ba8647ed5
Author: Florian Dold <dold@taler.net>
Date: Thu, 27 Aug 2026 16:03:03 +0200
exchange API: document withdrawal denomination filter
Issue: https://bugs.taler.net/n/11750
Diffstat:
1 file changed, 22 insertions(+), 2 deletions(-)
diff --git a/core/exchange/get-keys.rst b/core/exchange/get-keys.rst
@@ -6,6 +6,23 @@
**Request:**
:query last_issue_date: Optional argument specifying the maximum value of any of the ``stamp_start`` members of the denomination keys of a ``/keys`` response that is already known to the client. Allows the exchange to only return keys that have changed since that timestamp. The given value must be an unsigned 64-bit integer representing seconds after 1970. If the timestamp does not exactly match the ``stamp_start`` of one of the denomination keys, all keys are returned.
+ :query denom_filter: Optional denomination filter. The value ``withdraw``
+ requests only denominations relevant for upcoming withdrawals. For every
+ family identified by its cipher, value and age mask, the response contains
+ all keys whose withdrawal validity interval includes the exchange's current
+ time and all keys tied at the family's earliest future ``stamp_start``.
+ Fees do not distinguish families. Thus overlapping current keys are all
+ included, while keys whose withdrawal validity ended and rotations after
+ the immediate successor are omitted. A selected key remains included with
+ ``lost`` set even if its private key is unavailable. Auditor metadata is
+ unchanged, but its ``denomination_keys`` arrays contain signatures only for
+ denominations included in the response. This parameter is mutually
+ exclusive with ``last_issue_date``. If omitted, the exchange returns the
+ existing complete or cherry-picked response.
+
+ The filter does not change the response schema or signature format. Clients
+ using it must also accept a complete response, as older exchanges may ignore
+ the additional query parameter.
**Response:**
@@ -14,7 +31,8 @@
virtually always be successful. It only fails if the exchange is misconfigured or
has not yet been provisioned with key signatures via ``taler-exchange-offline``.
:http:statuscode:`400 Bad Request`:
- A query parameter is malformed.
+ A query parameter is malformed, ``denom_filter`` has an unsupported value,
+ or ``denom_filter`` and ``last_issue_date`` were both specified.
This response comes with a standard `ErrorDetail` response with
a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`502 Bad Gateway`:
@@ -27,7 +45,9 @@
This response comes with a standard `ErrorDetail` response with
a code of ``TALER_EC_GENERIC_JSON_ALLOCATION_FAILURE``.
:http:statuscode:`503 Service Unavailable`:
- The exchange has no valid denomination keys available.
+ The exchange has no valid denomination keys available. For a request with
+ ``denom_filter=withdraw``, this also means that no current or future
+ withdrawal denomination is available.
This response comes with a standard `ErrorDetail` response with
a code of ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``.
