[taler-docs] 28/36: doc update for #6889

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

commit f6c20b01e192c9cbb05722a6194b7441f300b09e
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue May 25 20:51:55 2021 +0200

    doc update for #6889
---
 core/api-common.rst   | 15 ++++++++++++++-
 core/api-exchange.rst | 43 +++++++++++++++++++++++++++++++++++++------
 2 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/core/api-common.rst b/core/api-common.rst
index 45e24dd..97ce02d 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -1015,7 +1015,7 @@ within the
 
   struct TALER_RecoupConfirmationPS {
     /**
-     *  purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP
+     * purpose.purpose = TALER_SIGNATURE_EXCHANGE_CONFIRM_RECOUP
      */
     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
     struct GNUNET_TIME_AbsoluteNBO timestamp;
@@ -1025,6 +1025,19 @@ within the
   };
 
 
+.. _TALER_DenominationUnknownAffirmationPS:
+.. sourcecode:: c
+
+  struct TALER_DenominationUnknownAffirmationPS {
+    /**
+     * purpose.purpose = TALER_SIGNATURE_EXCHANGE_AFFIRM_DENOM_UNKNOWN
+     */
+    struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
+    struct GNUNET_TIME_AbsoluteNBO timestamp;
+    struct GNUNET_HashCode h_denom_pub;
+  };
+
+
 .. _TALER_ReserveCloseConfirmationPS:
 .. sourcecode:: c
 
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 06f7658..8e41447 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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.