update docs to follow v8 protocol evolution, disambiguate struct names

1 files changed, 76 insertions, 28 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 4737e0a1..0d3f983c 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -808,15 +808,10 @@ Receiving Payments
   .. ts:def:: OrderHistoryEntry
 
     interface OrderHistoryEntry {
-      // The serial number this entry has in the merchant's DB.
-      row_id: number;
 
       // order ID of the transaction related to this entry.
       order_id: string;
 
-      // Transaction's timestamp
-      timestamp: Timestamp;
-
     }
 
 
@@ -1151,7 +1146,7 @@ Receiving Payments
     interface TransactionWireTransfer {
 
       // Responsible exchange
-      exchange_uri: string;
+      exchange_url: string;
 
       // 32-byte wire transfer identifier
       wtid: Base32;
@@ -1404,13 +1399,13 @@ Tracking Wire Transfers
 
   :status 200 OK:
     The wire transfer is known to the exchange, details about it follow in the body.
-    The body of the response is a `TrackTransferResponse`.
+    The body of the response is a `MerchantTrackTransferResponse`.
   :status 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 `TrackTransferConflictDetails`.
+    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
@@ -1446,9 +1441,9 @@ Tracking Wire Transfers
       exchange_url: string;
     }
 
-  .. ts:def:: TrackTransferResponse
+  .. ts:def:: MerchantTrackTransferResponse
 
-    interface TrackTransferResponse {
+    interface MerchantTrackTransferResponse {
       // Total amount transferred
       total: Amount;
 
@@ -1459,13 +1454,13 @@ Tracking Wire Transfers
       execution_time: Timestamp;
 
       // details about the deposits
-      deposits_sums: TrackTransferDetail[];
+      deposits_sums: MerchantTrackTransferDetail[];
 
     }
 
-  .. ts:def:: TrackTransferDetail
+  .. ts:def:: MerchantTrackTransferDetail
 
-    interface TrackTransferDetail {
+    interface MerchantTrackTransferDetail {
       // Business activity associated with the wire transferred amount
       // ``deposit_value``.
       order_id: string;
@@ -1478,19 +1473,67 @@ Tracking Wire Transfers
     }
 
 
+  .. ts:def:: ExchangeConflictDetails
+
+  type ExchangeConflictDetails = WireFeeConflictDetails | TrackTransferConflictDetails
+
+
+  .. ts:def:: WireFeeConflictDetails
+
+    // Note: this is not the full 'proof' of missbehavior, 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_POST_TRANSFERS_JSON_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: number;
+      code: TALER_EC_POST_TRANSFERS_CONFLICTING_REPORTS;
 
       // Text describing the issue for humans.
       hint: string;
 
-      // A /deposit response matching ``coin_pub`` showing that the
-      // exchange accepted ``coin_pub`` for ``amount_with_fee``.
-      exchange_deposit_proof: DepositSuccess;
-
       // Offset in the ``exchange_transfer`` where the
       // exchange's response fails to match the ``exchange_deposit_proof``.
       conflict_offset: number;
@@ -1498,13 +1541,21 @@ Tracking Wire Transfers
       // 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.
-      exchange_transfer: TrackTransferResponse;
+      //
+      // 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
-      exchange_pub: EdDSAPublicKey;
+      // 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
-      exchange_sig: EdDSASignature;
+      // 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;
@@ -1512,7 +1563,8 @@ Tracking Wire Transfers
       // Hash of the contract terms with the conflicting deposit.
       h_contract_terms: HashCode;
 
-      // At what time the exchange received the deposit.
+      // 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``).
@@ -1521,10 +1573,6 @@ Tracking Wire Transfers
       // Public key of the coin for which we have conflicting information.
       coin_pub: EddsaPublicKey;
 
-      // Merchant transaction in which ``coin_pub`` was involved for which
-      // we have conflicting information.
-      transaction_id: number;
-
       // Amount the exchange counted the coin for in the transfer.
       amount_with_fee: Amount;