[taler-docs] branch master updated: simplify API to match async processing introduced with #6363

[gnunet]

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

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 61eba01  simplify API to match async processing introduced with #6363
61eba01 is described below

commit 61eba011b5d99314a390eedde2d7041639b1f878
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Wed May 3 23:15:54 2023 +0200

    simplify API to match async processing introduced with #6363
---
 core/api-merchant.rst | 191 +-------------------------------------------------
 1 file changed, 3 insertions(+), 188 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 0e1ff01..240bfa7 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -2360,35 +2360,12 @@ Informing the backend about incoming wire transfers
 
   **Response:**
 
-  :http:statuscode:`200 OK`:
-    The wire transfer is known to the exchange, details about it follow in the 
body.
-    The body of the response is a `MerchantTrackTransferResponse`.
-  :http:statuscode:`202 Accepted`:
-    The exchange provided conflicting information about the transfer. Namely,
-    there is at least one deposit among the deposits aggregated by ``wtid``
-    that accounts for a coin whose
-    details don't match the details stored in merchant's database about the 
same keyed coin.
-    The response body contains the `ExchangeConflictDetails`.
-    This is indicative of a malicious exchange that claims one thing, but did
-    something else.  (With respect to the HTTP specficiation, it is not
-    precisely that we did not act upon the request, more that the usual
-    action of filing the transaction as 'finished' does not apply.  In
-    the future, this is a case where the backend actually should report
-    the bad behavior to the auditor -- and then hope for the auditor to
-    resolve it. So in that respect, 202 is the right status code as more
-    work remains to be done for a final resolution.)
+  :http:statuscode:`204 No content`:
+    The wire transfer is now confirmed at the merchant.
   :http:statuscode:`404 Not found`:
     The instance or account are unknown to the exchange.
   :http:statuscode:`409 Conflict`:
-    The wire transfer identifier is already known to us, but for a different 
amount,
-    wire method or exchange, or the amount reported by the exchange differs 
from
-    the amount reported by the merchant.
-  :http:statuscode:`502 Bad gateway`:
-    The exchange returned an error when we asked it about the ``GET 
/transfer`` status
-    for this wire transfer. Details of the exchange error are returned.
-  :http:statuscode:`504 Gateway timeout`:
-    The merchant's interaction with the exchange took too long.
-    The client might want to try again later.
+    The wire transfer identifier is already known to us, but for a different 
amount.
 
   **Details:**
 
@@ -2408,168 +2385,6 @@ Informing the backend about incoming wire transfers
       exchange_url: string;
     }
 
-  .. ts:def:: MerchantTrackTransferResponse
-
-    interface MerchantTrackTransferResponse {
-      // Total amount transferred.
-      total: Amount;
-
-      // Applicable wire fee that was charged.
-      wire_fee: Amount;
-
-      // Time of the execution of the wire transfer by the exchange, according 
to the exchange.
-      execution_time: Timestamp;
-
-      // Details about the deposits.
-      deposits_sums: MerchantTrackTransferDetail[];
-    }
-
-  .. ts:def:: MerchantTrackTransferDetail
-
-    interface MerchantTrackTransferDetail {
-      // Business activity associated with the wire transferred amount
-      // ``deposit_value``.
-      order_id: string;
-
-      // The total amount the exchange paid back for ``order_id``.
-      deposit_value: Amount;
-
-      // Applicable fees for the deposit.
-      deposit_fee: Amount;
-    }
-
-
-  .. ts:def:: ExchangeConflictDetails
-
-    type ExchangeConflictDetails = WireFeeConflictDetails |
-                                   TrackTransferConflictDetails;
-
-
-  .. ts:def:: WireFeeConflictDetails
-
-    // Note: this is not the full 'proof' of misbehavior, as
-    // the bogus message from the exchange with a signature
-    // over the 'different' wire fee is missing.
-    //
-    // This information is NOT provided by the current implementation,
-    // because this would be quite expensive to generate and is
-    // hardly needed _here_. Once we add automated reports for
-    // the Taler auditor, we need to generate this data anyway
-    // and should probably return it here as well.
-    interface WireFeeConflictDetails {
-      // Numerical `error code <error-codes>`:
-      code: "TALER_EC_MERCHANT_PRIVATE_POST_TRANSFERS_BAD_WIRE_FEE";
-
-      // Text describing the issue for humans.
-      hint: string;
-
-      // Wire fee (wrongly) charged by the exchange, breaking the
-      // contract affirmed by the ``exchange_sig``.
-      wire_fee: Amount;
-
-      // Timestamp of the wire transfer.
-      execution_time: Timestamp;
-
-      // The expected wire fee (as signed by the exchange).
-      expected_wire_fee: Amount;
-
-      // Expected closing fee (needed to verify signature).
-      expected_closing_fee: Amount;
-
-      // Start date of the expected fee structure.
-      start_date: Timestamp;
-
-      // End date of the expected fee structure.
-      end_date: Timestamp;
-
-      // Signature of the exchange affirming the expected fee structure.
-      master_sig: EddsaSignature;
-
-      // Master public key of the exchange.
-      master_pub: EddsaPublicKey;
-    }
-
-
-  .. ts:def:: TrackTransferConflictDetails
-
-    interface TrackTransferConflictDetails {
-      // Numerical `error code <error-codes>`.
-      code: "TALER_EC_MERCHANT_PRIVATE_POST_TRANSFERS_CONFLICTING_REPORTS";
-
-      // Text describing the issue for humans.
-      hint: string;
-
-      // Offset in the ``exchange_transfer`` where the
-      // exchange's response fails to match the ``exchange_deposit_proof``.
-      conflict_offset: number;
-
-      // The response from the exchange which tells us when the
-      // coin was returned to us, except that it does not match
-      // the expected value of the coin.
-      //
-      // This field is NOT provided by the current implementation,
-      // because this would be quite expensive to generate and is
-      // hardly needed _here_. Once we add automated reports for
-      // the Taler auditor, we need to generate this data anyway
-      // and should probably return it here as well.
-      exchange_transfer?: TrackTransferResponse;
-
-      // Public key of the exchange used to sign the response to
-      // our deposit request.
-      deposit_exchange_pub: EddsaPublicKey;
-
-      // Signature of the exchange signing the (conflicting) response.
-      // Signs over a ``struct TALER_DepositConfirmationPS``.
-      deposit_exchange_sig: EddsaSignature;
-
-      // Hash of the merchant's bank account the wire transfer went to.
-      h_wire: HashCode;
-
-      // Hash of the contract terms with the conflicting deposit.
-      h_contract_terms: HashCode;
-
-      // At what time the exchange received the deposit.  Needed
-      // to verify the ``exchange_sig``.
-      deposit_timestamp: Timestamp;
-
-      // At what time the refund possibility expired (needed to verify 
``exchange_sig``).
-      refund_deadline: Timestamp;
-
-      // Public key of the coin for which we have conflicting information.
-      coin_pub: EddsaPublicKey;
-
-      // Amount the exchange counted the coin for in the transfer.
-      amount_with_fee: Amount;
-
-      // Expected value of the coin.
-      coin_value: Amount;
-
-      // Expected deposit fee of the coin.
-      coin_fee: Amount;
-
-      // Expected deposit fee of the coin.
-      deposit_fee: Amount;
-
-    }
-
-  .. ts:def:: TrackTransferProof
-
-    interface TrackTransferProof {
-      // Signature from the exchange made with purpose
-      // ``TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE_DEPOSIT``.
-      exchange_sig: EddsaSignature;
-
-      // Public EdDSA key of the exchange that was used to generate the 
signature.
-      // Should match one of the exchange's signing keys from ``/keys``.  
Again given
-      // explicitly as the client might otherwise be confused by clock skew as 
to
-      // which signing key was used.
-      exchange_pub: EddsaSignature;
-
-      // Hash of the wire details (identical for all deposits).
-      // Needed to check the ``exchange_sig``
-      h_wire: HashCode;
-    }
-
 
 Querying known wire transfers
 -----------------------------

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