From 7641ad6d2ab742e1b8305b9db59bcc24f317e77a Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Sun, 9 May 2021 20:01:02 +0200
Subject: extend wire gateway spec for wads

---
 core/api-exchange.rst | 16 ----------------
 core/api-wire.rst     | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 17 deletions(-)

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index d3000259..3f80d4d7 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -2419,28 +2419,12 @@ Refunds
     }
 
 
-
-
-
-
-
 .. _exchange_w2w:
 
 --------------------------
 Wallet-to-wallet transfers
 --------------------------
 
-TODO for the spec:
-
-  * update wire transfer API to enable WAD IDs (and while we are
-    at it, should probably also write extended version to allow
-    _merchants_ to query for their inbound transfers, so spec
-    for both WADs and regular WTID!); also add flag to
-    tell exchange for inbound wire transfers that they are
-    from a partner bank where KYC fees would be waived!
-
-
-
 .. http:GET:: /purses/$PURSE_PUB
 
   Obtain information about a purse. The request header must
diff --git a/core/api-wire.rst b/core/api-wire.rst
index fbf27469..e05aa848 100644
--- a/core/api-wire.rst
+++ b/core/api-wire.rst
@@ -175,7 +175,15 @@ Querying the transaction history
 
   .. ts:def:: IncomingBankTransaction
 
-    interface IncomingBankTransaction {
+    // Union discriminated by the "type" field.
+    type IncomingBankTransaction =
+    | IncomingReserveTransaction
+    | IncomingWadTransaction;
+
+  .. ts:def:: IncomingReserveTransaction
+
+    interface IncomingReserveTransaction {
+      type: "RESERVE";
 
       // Opaque identifier of the returned record.
       row_id: SafeUint64;
@@ -195,6 +203,47 @@ Querying the transaction history
 
       // The reserve public key extracted from the transaction details.
       reserve_pub: EddsaPublicKey;
+
+      // Set to 'true' if this wire transfer originates from
+      // a bank account with a partner bank that implies that
+      // the KYC has already been satisfied for this reserve
+      // because of it.
+      // FIXME: is this acceptable? Seems like users could
+      // easily be tricked into wiring funds to a reserve that
+      // they do NOT own, and then being held responsibe for
+      // the resulting account. So when setting this bit,
+      // we'd need at least a reserve_sig over the credit_account,
+      // which we do not get here... (DANGEROUS API).
+      // => need to discuss KYC more with real banks.
+      kyc_completed: boolean;
+    }
+
+  .. ts:def:: IncomingWadTransaction
+
+    interface IncomingWadTransaction {
+      type: "WAD";
+
+      // Opaque identifier of the returned record.
+      row_id: SafeUint64;
+
+      // Date of the transaction.
+      date: Timestamp;
+
+      // Amount transferred.
+      amount: Amount;
+
+      // Payto URI to identify the receiver of funds.
+      // This must be one of the exchange's bank accounts.
+      credit_account: string;
+
+      // Payto URI to identify the sender of funds.
+      debit_account: string;
+
+      // Base URL of the exchange that originated the wad.
+      origin_exchange_url: string;
+
+      // The reserve public key extracted from the transaction details.
+      wad_id: WadId;
     }
 
 
-- 
cgit v1.2.3