updates to reflect changes to exchange/merchant to support multiple instances and payto:// format for encoding wire account information

3 files changed, 56 insertions, 96 deletions

diff --git a/api-common.rst b/api-common.rst
index ff0e0890..3b0bc4b2 100644
--- a/api-common.rst
+++ b/api-common.rst
@@ -454,7 +454,7 @@ Any piece of signed data, complies to the abstract data structure given below.
     /**
 
     The following constrains apply for a valid amount:
-    
+
     * asd
      * This field is used to express the context in
      * which the signature is made, ensuring that a
@@ -601,10 +601,10 @@ within the
 
   struct TALER_MasterWireDetailsPS {
     /**
-     * purpose.purpose = TALER_SIGNATURE_MASTER_SEPA_DETAILS || TALER_SIGNATURE_MASTER_TEST_DETAILS
+     * purpose.purpose = TALER_SIGNATURE_MASTER_WIRE_DETAILS
      */
     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-    struct GNUNET_HashCode h_sepa_details;
+    struct GNUNET_HashCode h_wire_details;
   };
 
 
diff --git a/api-exchange.rst b/api-exchange.rst
index 0c117775..17c23b5d 100644
--- a/api-exchange.rst
+++ b/api-exchange.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2014-2018 GNUnet e.V. and INRIA
+  Copyright (C) 2014-2018 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU General Public License as published by the Free Software
@@ -256,73 +256,32 @@ Obtaining wire-transfer information
   .. code-block:: tsref
 
     interface WireResponse {
-      // The key is a supported method (i.e. "sepa" or "test").
-      // The value is a method-specific JSON object with account details
-      // (i.e. IBAN number, owner name, bank address, etc.).
-      // The value objects may also contain signatures (if applicable).
-      //
-      // A single /wire response can contain an arbitrary number of these
-      // string-object pairs.  However, the keys must be unique.
-      string: Object;
-     }
-
-  Possible encodings for the objects are right now the following:
-
-  .. _WireTestResponse:
-  .. _tsref-type-WireTestResponse:
-  .. code-block:: tsref
-
-    interface WireTestResponse {
-      // Mandatory indicator that this is a TEST wire response.
-      type: "test";
-
-      // Account number at the bank
-      account_number: number;
-
-      // URL of the bank
-      bank_url: string;
 
-      // Name of the account's owner
-      name: string;
+      // Array of wire accounts operated by the exchange for
+      // incoming wire transfers.
+      accounts: WireAccount[];
 
-      // Salt used to sign, `base32`_ encoded
-      salt: string;
-
-      // Wire transfer fee structure. Specifies aggregate wire transfer fees.
-      fees: AggregateTransferFee[];
-
-      // Signature of `TALER_MasterWireDetailsPS`_ with purpose TALER_SIGNATURE_MASTER_TEST_DETAILS
-      // Note that the `h_sepa_details` field of `TALER_MasterWireDetailsPS`_ is computed
-      // by concatenating all of the above fields (in the same order they appear) and then
-      // by hashing the obtained concatenation.
-      sig: EddsaSignature;
+      // Object mapping names of wire methods (i.e. "sepa" or "x-taler-bank")
+      // to wire fees.
+      fees: { method : AggregateTransferFee };
     }
 
-  .. _WireSepaResponse:
-  .. _tsref-type-WireSepaResponse:
-  .. code-block:: tsref
-
-    interface WireSepaResponse {
-      // Mandatory indicator that this is a SEPA wire response.
-      type: "sepa";
+  The specification for the account object is:
 
-      // Legal name of the owner of the account
-      receiver_name: string;
-
-      // Wire transfer fee structure. Specifies aggregate wire transfer fees.
-      fees: AggregateTransferFee[];
+  .. _WireAccouunt:
+  .. _tsref-type-WireAccount:
+  .. code-block:: tsref
 
-      // IBAN account number.
-      iban: string;
+    interface WireAccount {
+      // payto:// URL identifying the account and wire method
+      url: string;
 
-      // BIC of the bank.
-      bic: string;
+      // Salt value (used when hashing 'url' to verify signature)
+      salt: string;
 
-      // Signature of `TALER_MasterWireDetailsPS`_ with purpose TALER_SIGNATURE_MASTER_SEPA_DETAILS
-      // Note that the `h_sepa_details` field of `TALER_MasterWireDetailsPS`_ is computed
-      // by concatenating all of the above fields (in the same order they appear) and then
-      // by hashing the obtained concatenation.
-      sig: EddsaSignature;
+      // Signature using the exchange's offline key
+      // with purpose TALER_SIGNATURE_MASTER_WIRE_DETAILS.
+      master_sig: EddsaSignature;
     }
 
   Aggregate wire transfer fees representing the fees the exchange
@@ -439,8 +398,8 @@ exchange.
       // The fee that was charged for "CLOSING".
       closing_fee?: Amount;
 
-      // Sender account details, only present if type is "DEPOSIT".
-      sender_account_details?: any;
+      // Sender account payto://-URL, only present if type is "DEPOSIT".
+      sender_account_url?: String;
 
       // Receiver account details, only present if type is "PAYBACK".
       receiver_account_details?: any;
diff --git a/wireformats.rst b/wireformats.rst
index 9a5aa4bb..12d23630 100644
--- a/wireformats.rst
+++ b/wireformats.rst
@@ -1,6 +1,6 @@
 .. _wireformats:
 
-Wire Transfer Formats
+Wire Transfer Methods
 =====================
 
 A wire transfer is essential for the exchange to transfer funds into a merchant's
@@ -8,33 +8,39 @@ account upon a successful deposit (see :ref:`deposit request <deposit>`).  The
 merchant has to include the necessary information for the exchange to initiate the
 wire transfer.
 
-The information required for wire transfer depends on the type of wire transfer
+The information required for wire transfer depends on the method of wire transfer
 used.  Since the wire transfers differ for each region, we document here the
 ones currently supported by the exchange.
 
-TEST
-----
+X-TALER-BANK
+------------
 
-The TEST wire format is used for testing and for integration with Taler's
+The "x-taler-bank" wire format is used for testing and for integration with Taler's
 simple "bank" system which in the future might be useful to setup a bank
-for a local / regional currency or accounting system.  Using the TEST
-wire format in combination with the Taler's bank, it is thus possible to
-fully test the Taler system without using "real" currencies.  The wire
-format for "TEST" is very simple, in that it only specifies an account
-number in a field "account_number" and the URL of the bank:
+for a local / regional currency or accounting system.  Using the @code{x-taler-bank}
+wire method in combination with the Taler's bank, it is thus possible to
+fully test the Taler system without using "real" currencies.  The URL
+format for "x-taler-bank" is simple, in that it only specifies an account
+number and the URL of the bank:
 
-  * `type`: the string constant `"test"`
-  * `bank_uri`: the URL of the bank (starting with `http://` or `https://`)
-  * `account_number`: the number of the account at the bank
+  *  payto://x-taler-bank/BANK_URI/ACCOUNT_NUMBER
 
-The account number given must be a positive 53-bit integer.
-Additional fields may be present, but are not required.
+The account number given must be a positive 53-bit integer.  As with
+any payto://-URI, additional fields may be present (after a ?), but
+are not required.  The BANK_URI may include a port number. If none is
+given, @code{https} over port 443 is assumed.  If a port number is
+given, @code{http} over the given port is to be used.  Note that this
+means that you cannot run an x-taler-bank over @code{https} on a
+non-canonical port.
 
 Note that a particular exchange is usually only supporting one
-particular bank with the "TEST" wire format, so it is not possible for
-a merchant with an account at a different bank to use "TEST" to
-transfer funds across banks. After all, this is for testing and not
-for real banking.
+particular bank with the "x-taler-bank" wire format, so it is not
+possible for a merchant with an account at a different bank to use
+"x-taler-bank" to transfer funds across banks. After all, this is for
+testing and not for real banking.
+
+The "x-taler-bank" method is implemented by the @code{taler_bank} plugin.
+
 
 SEPA
 ----
@@ -42,27 +48,22 @@ SEPA
 The Single Euro Payments Area (SEPA) [#sepa]_ is a regulation for electronic
 payments.  Since its adoption in 2012, all of the banks in the Eurozone and some
 banks in other countries adhere to this standard for sending and receiving
-payments.  Note that the currency of the transfer will (currently) always be *EURO*.  In
+payments.  Note that the currency of the transfer will (currently) always be *EUR*.  In
 case the receiving account is in a currency other than EURO, the receiving bank
 may covert the amount into that currency; currency exchange charges may be
 levied by the receiving bank.
 
 For the merchant to receive deposits through SEPA, the deposit request must
-contain a JSON object with the following fields:
+follow the payto:// specification for SEPA:
 
-  .. The following are taken from Page 33, SEPA_SCT.pdf .
+  *  payto://sepa/IBAN
 
-  * `type`: the string constant `"sepa"`
-  * `iban`: the International Bank Account Number (IBAN) of the account of the beneficiary
-  * `name`: the name of the beneficiary
-  * `bic`: the Bank Identification Code (BIC) code of the beneficiary's bank
-  * `salt`: random salt (used to make brute-forcing the hash harder)
 
-The JSON object may optionally contain:
-  * `address`: the address of the Beneficiary
+The implementation of the @code{ebics} plugin which is envisioned to
+support the @code{sepa} method is currently incomplete.  Specifically,
+we need a working implementation of `libebics` which is a sub-project
+trying to implement the EBICS [#ebics]_ standard.
 
-The implementation of the SEPA plugin is currently incomplete.  Specifically, we need a working implementation of `libebics` which is a sub-project trying to implement the EBICS [#ebics]_ standard.
-    
 .. [#sepa] SEPA - Single Euro Payments Area:
            http://www.ecb.europa.eu/paym/sepa/html/index.en.html
 .. [#ebics] EBCIS - European Banking Computer Interface Standard