[taler-docs] branch master updated (5be6d4c -> 117b11a)

[gnunet]

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

grothoff pushed a change to branch master
in repository docs.

    from 5be6d4c  fix bug: specify section 5 for sync.conf(5)
     new c5271c3  -remove redundant fields from reply
     new 117b11a  split /recoup handler into /recoup and /recoup-refresh

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 core/api-exchange.rst | 109 +++++++++++++++++++++++++++++++++-----------------
 1 file changed, 73 insertions(+), 36 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 671d6d9..6bb2b45 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2223,18 +2223,6 @@ the API during normal operation.
       // Detailed error code.
       code: Integer;
 
-      // Public key of a melted coin that had insufficient funds.
-      coin_pub: EddsaPublicKey;
-
-      // Original total value of the coin.
-      original_value: Amount;
-
-      // Remaining value of the coin.
-      residual_value: Amount;
-
-      // Amount of the coin's value that was to be melted.
-      requested_value: Amount;
-
       // The transaction list of the respective coin that failed to have 
sufficient funds left.
       // Note that only the transaction history for one bogus coin is given,
       // even if multiple coins would have failed the check.
@@ -2404,11 +2392,10 @@ in using this API.
   exchange. The exchange MUST return a 307 or 308 redirection to the correct
   base URL if this is the case.
 
-  Depending whether ``$COIN_PUB`` is a withdrawn coin or a refreshed coin,
-  the remaining amount on the coin will be credited either on the reserve or
-  the old coin that ``$COIN_PUB`` was withdrawn/refreshed from.
+  The remaining amount on the coin will be credited to the reserve
+  that ``$COIN_PUB`` was withdrawn from.
 
-  Note that the original withdrawal/refresh fees will **not** be recouped.
+  Note that the original withdrawal fees will **not** be recouped.
 
 
   **Request:** The request body must be a `RecoupRequest` object.
@@ -2416,7 +2403,7 @@ in using this API.
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The request was successful, and the response is a `RecoupConfirmation`.
+    The request was successful, and the response is a 
`RecoupWithdrawalConfirmation`.
     Note that repeating exactly the same request
     will again yield the same response, so if the network goes down during the
     transaction or before the client can commit the coin signature to disk, the
@@ -2433,8 +2420,7 @@ in using this API.
     residual value, or because the same public key of the coin has been
     previously used with a different denomination.  Which case it is
     can be decided by looking at the error code
-    (``TALER_EC_EXCHANGE_RECOUP_COIN_BALANCE_ZERO`` or
-    ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
+    (usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS``).
     The response is a `DepositDoubleSpendError`.
   :http:statuscode:`410 Gone`:
     The requested denomination key is not yet or no longer valid.
@@ -2448,7 +2434,7 @@ in using this API.
   .. ts:def:: RecoupRequest
 
     interface RecoupRequest {
-      // Hash of denomination public key (RSA), specifying the type of coin 
the client
+      // Hash of denomination public key, specifying the type of coin the 
client
       // would like the exchange to pay back.
       denom_pub_hash: HashCode;
 
@@ -2462,35 +2448,86 @@ in using this API.
       // the `coin's private key <coin-priv>`.
       coin_sig: EddsaSignature;
 
-      // Was the coin refreshed (and thus the recoup should go to the old 
coin)?
-      // While this information is technically redundant, it helps the exchange
-      // to respond faster.
-      // *Optional* (for backwards compatibility); if absent, ``false`` is 
assumed.
-      refreshed?: boolean;
     }
 
 
-  .. ts:def:: RecoupConfirmation
-
-    type RecoupConfirmation = | RecoupRefreshConfirmation
-                              | RecoupWithdrawalConfirmation;
-
   .. ts:def:: RecoupWithdrawalConfirmation
 
     interface RecoupWithdrawalConfirmation {
-      // Tag to distinguish the `RecoupConfirmation` response type.
-      refreshed: false;
-
       // Public key of the reserve that will receive the recoup.
       reserve_pub: EddsaPublicKey;
     }
 
+
+.. http:post:: /coins/$COIN_PUB/recoup-refresh
+
+  Demand that a coin be refunded via wire transfer to the original owner.
+
+  The base URL for ``/coins/``-requests may differ from the main base URL of 
the
+  exchange. The exchange MUST return a 307 or 308 redirection to the correct
+  base URL if this is the case.
+
+  The remaining amount on the coin will be credited to
+  the old coin that ``$COIN_PUB`` was refreshed from.
+
+  Note that the original refresh fees will **not** be recouped.
+
+
+  **Request:** The request body must be a `RecoupRefreshRequest` object.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The request was successful, and the response is a 
`RecoupRefreshConfirmation`.
+    Note that repeating exactly the same request
+    will again yield the same response, so if the network goes down during the
+    transaction or before the client can commit the coin signature to disk, the
+    coin is not lost.
+  :http:statuscode:`401 Unauthorized`:
+    The coin's signature is invalid.
+  :http:statuscode:`404 Not found`:
+    The denomination key is unknown, or the blinded
+    coin is not known to have been withdrawn.
+    If the denomination key is unknown, the response will be
+    a `DenominationUnknownMessage`.
+  :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
+    previously used with a different denomination.  Which case it is
+    can be decided by looking at the error code
+    (usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_BALANCE``).
+    The response is a `DepositDoubleSpendError`.
+  :http:statuscode:`410 Gone`:
+    The requested denomination key is not yet or no longer valid.
+    It either before the validity start, past the expiration or was not yet 
revoked. The response is a
+    `DenominationExpiredMessage`. Clients must evaluate
+    the error code provided to understand which of the
+    cases this is and handle it accordingly.
+
+  **Details:**
+
+  .. ts:def:: RecoupRefreshRequest
+
+    interface RecoupRefreshRequest {
+      // Hash of denomination public key, specifying the type of coin the 
client
+      // would like the exchange to pay back.
+      denom_pub_hash: HashCode;
+
+      // Signature over the `coin public key <eddsa-coin-pub>` by the 
denomination.
+      denom_sig: DenominationSignature;
+
+      // Coin's blinding factor.
+      coin_blind_key_secret: DenominationBlindingKeySecret;
+
+      // Signature of `TALER_RecoupRefreshRequestPS` created with
+      // the `coin's private key <coin-priv>`.
+      coin_sig: EddsaSignature;
+    }
+
+
   .. ts:def:: RecoupRefreshConfirmation
 
     interface RecoupRefreshConfirmation {
-      // Tag to distinguish the `RecoupConfirmation` response type.
-      refreshed: true;
-
       // Public key of the old coin that will receive the recoup.
       old_coin_pub: EddsaPublicKey;
     }

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