From f6c20b01e192c9cbb05722a6194b7441f300b09e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 25 May 2021 20:51:55 +0200 Subject: doc update for #6889 --- core/api-exchange.rst | 43 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 6 deletions(-) (limited to 'core/api-exchange.rst') diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 06f76582..8e41447a 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -993,6 +993,7 @@ This part of the API is for the use by auditors interacting with the exchange. The auditor signature is invalid. :http:statuscode:`404 Not found`: The denomination key for which the auditor is providing a signature is unknown. + The response will be a `DenominationUnkownMessage`. :http:statuscode:`410 Gone`: This auditor is no longer supported by the exchange. :http:statuscode:`412 Precondition failed`: @@ -1000,6 +1001,30 @@ This part of the API is for the use by auditors interacting with the exchange. **Details:** + .. ts:def:: DenominationUnknownMessage + + interface DenominationUnknownMessage { + + // Taler error code. + code: number; + + // Signature by the exchange over a + // `TALER_DenominationUnknownAffirmationPS`. + // Must have purpose ``TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_UNKNOWN``. + exchange_sig: EddsaSignature; + + // Public key of the exchange used to create + // the 'exchange_sig. + exchange_pub: EddsaPublicKey; + + // Hash of the denomination public key that is unknown. + h_denom_pub: HashCode; + + // When was the signature created. + timestamp: Timestamp; + + } + .. ts:def:: AuditorSignatureAddMessage interface AuditorSignatureAddMessage { @@ -1365,8 +1390,9 @@ exchange. :http:statuscode:`404 Not found`: The denomination key or the reserve are not known to the exchange. If the denomination key is unknown, this suggests a bug in the wallet as the - wallet should have used current denomination keys from ``/keys``. If the - reserve is unknown, the wallet should not report a hard error yet, but + wallet should have used current denomination keys from ``/keys``. + In this case, the response will be a `DenominationUnkownMessage`. + If the reserve is unknown, the wallet should not report a hard error yet, but instead simply wait for up to a day, as the wire transaction might simply not yet have completed and might be known to the exchange in the near future. In this case, the wallet should repeat the exact same request later again @@ -1520,8 +1546,10 @@ denomination. :http:statuscode:`401 Unauthorized`: One of the signatures is invalid. :http:statuscode:`404 Not found`: - Either the denomination key is not recognized (expired or invalid) or - the wire type is not recognized. + Either the denomination key is not recognized (expired or invalid), + or the wire type is not recognized. + If the denomination key is unknown, the response will be + a `DenominationUnkownMessage`. :http:statuscode:`409 Conflict`: The deposit operation has either failed because the coin has insufficient residual value, or because the same public key of the coin has been @@ -1956,6 +1984,8 @@ the API during normal operation. :http:statuscode:`404 Not found`: The exchange does not recognize the denomination key as belonging to the exchange, or it has expired. + If the denomination key is unknown, the response will be + a `DenominationUnkownMessage`. :http:statuscode:`409 Conflict`: The operation is not allowed as the coin has insufficient residual value, or because the same public key of the coin has been @@ -2236,6 +2266,8 @@ in using this API. The denomination key is not in the set of denomination keys where emergency pay back is enabled, or the blinded coin is not known to have been withdrawn. + If the denomination key is unknown, the response will be + a `DenominationUnkownMessage`. :http:statuscode:`409 Conflict`: The operation is not allowed as the coin has insufficient residual value, or because the same public key of the coin has been @@ -2679,8 +2711,7 @@ Wallet-to-wallet transfers different contract or total amount already exists. This response comes with a standard `PurseConflict` response. :http:statuscode:`404 Not found`: - Either the denomination key is not recognized (expired or invalid) or - the wire type is not recognized. + FIXME: when exactly does this happen? :http:statuscode:`409 Conflict`: The deposit operation has either failed because a coin has insufficient residual value, or because the same public key of the coin has been -- cgit v1.2.3