commit f224155aa1c583aca9c05d466f739c86edbf5138
parent a051ff73eded8754bc377931aa2094df51e34da8
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 14 Jan 2020 11:05:18 +0100
remove wire plugin documentation, as it is obsolete now
Diffstat:
8 files changed, 389 insertions(+), 425 deletions(-)
diff --git a/core/api-bank.rst b/core/api-bank.rst
@@ -21,7 +21,8 @@
Taler Bank API
==============
-This chapter describe the APIs that banks need to offer to tightly integrate with GNU Taler.
+This chapter describe the APIs that banks need to offer towards Taler wallets
+to tightly integrate with GNU Taler.
.. contents:: Table of Contents
diff --git a/core/api-wire-plugin-bank.rst b/core/api-wire-plugin-bank.rst
@@ -1,299 +0,0 @@
-..
- This file is part of GNU TALER.
- Copyright (C) 2019 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
- Foundation; either version 2.1, or (at your option) any later version.
-
- TALER is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License along with
- TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-
-===========================
-Taler Wire Gateway HTTP API
-===========================
-
-This section describes the API offered by the Taler wire gateway. The API is
-used by the exchange to trigger transactions and query incoming transactions, as
-well as by the auditor to query incoming and outgoing transactions.
-
-This API is currently implemented by the Taler Demo Bank, as well as by
-LibEuFin (work in progress).
-
-
---------------
-Authentication
---------------
-
-The wire plugin authenticates requests to the wire gatway via
-`HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_.
-
--------------------
-Making Transactions
--------------------
-
-.. http:post:: ${BASE_URL}/transfer
-
- This API allows the exchange to make a transaction, typically to a merchant. The bank account
- of the exchange is not included in the request, but instead derived from the user name in the
- authentication header and/or the request base URL.
-
- To make the API idempotent, the client must include a nonce. Requests with the same nonce
- are rejected unless the request is the same.
-
- **Request:** The body of this request must have the format of a `TransactionRequest`.
-
- **Response:**
-
- :status 200 OK:
- The request has been correctly handled, so the funds have been transferred to
- the recipient's account. The body is a `TransactionResponse`
- :status 400 Bad Request: The bank replies with a `BankError` object.
- :status 406 Not Acceptable: The request had wrong currency; the bank replies with a `BankError` object.
- :status 409 Conflict:
- A transaction with the same ``transaction_uid`` but different transaction details
- has been submitted before.
-
- **Details:**
-
- .. ts:def:: TransactionResponse
-
- interface TransactionResponse {
-
- // Timestamp that indicates when the wire transfer will be executed.
- // In cases where the wire transfer gateway is unable to know when
- // the wire transfer will be executed, the time at which the request
- // has been received and stored will be returned.
- // The purpose of this field is for debugging (humans trying to find
- // the transaction) as well as for taxation (determining which
- // time period a transaction belongs to).
- timestamp: Timestamp;
-
- // Opaque of the transaction that the bank has made.
- row_id: SafeUint64;
- }
-
-
- .. ts:def:: TransactionRequest
-
- interface TransactionRequest {
- // Nonce to make the request idempotent. Requests with the same
- // transaction_uid that differ in any of the other fields
- // are rejected.
- request_uid: HashCode;
-
- // Amount to transfer.
- amount: Amount;
-
- // Base URL of the exchange. Shall be included by the bank gateway
- // in the approriate section of the wire transfer details.
- exchange_base_url: string;
-
- // Wire transfer identifier chosen by the exchange,
- // used by the merchant to identify the Taler order
- // associated with this wire transfer.
- wtid: ShortHashCode;
-
- // The recipient's account identifier as a payto URI
- credit_account: string;
- }
-
-
- .. ts:def:: BankError
-
- interface BankError {
-
- // Human readable explanation of the failure.
- error: string;
-
- // Numeric Taler error code (`TALER_ErrorCode`)
- ec: number;
- }
-
-
---------------------------------
-Querying the transaction history
---------------------------------
-
-
-.. http:get:: ${BASE_URL}/history/incoming
-
- Return a list of transactions made from or to the exchange.
-
- Incoming transactions must contain a valid reserve public key. If a bank
- transaction does not confirm to the right syntax, the wire gatway must not
- report it to the exchange, and sent funds back to the sender if possible.
-
- The bank account of the exchange is determined via the base URL and/or the
- user name in the ``Authorization`` header. In fact the transaction history
- might come from a "virtual" account, where multiple real bank accounts are
- merged into one history.
-
- Transactions are identified by an opaque numeric identifier, referred to here
- as "row ID". The semantics of the row ID (including its sorting order) are
- determined by the bank server and completely opaque to the client.
-
- The list of returned transactions is determined by a row ID *starting point*
- and a signed non-zero integer *delta*:
-
- * If *delta* is positive, return a list of up to *delta* transactions (all matching
- the filter criteria) strictly **after** the starting point. The transactions are sorted
- in **ascending** order of the row ID.
- * If *delta* is negative, return a list of up to *-delta* transactions (all matching
- the filter criteria) strictly **before** the starting point. The transactions are sorted
- in **descending** order of the row ID.
-
- If *starting point* is not explicitly given, it defaults to:
-
- * A value that is **smaller** than all other row IDs if *delta* is **positive**.
- * A value that is **larger** than all other row IDs if *delta* is **negative**.
-
- **Request**
-
- :query start: *Optional.*
- Row identifier to explicitly set the *starting point* of the query.
- :query delta:
- The *delta* value that determines the range of the query.
- :query long_poll_ms: *Optional.* If this parameter is specified and the
- result of the query would be empty, the bank will wait up to ``long_poll_ms``
- milliseconds for new transactions that match the query to arrive and only
- then send the HTTP response. A client must never rely on this behavior, as
- the bank may return a response immediately or after waiting only a fraction
- of ``long_poll_ms``.
-
- **Response**
-
- :status 200 OK: JSON object whose field ``incoming_transactions`` is an array of type `IncomingBankTransaction`.
- :status 204 No content: in case no records exist for the targeted user.
-
- .. ts:def:: IncomingBankTransaction
-
- interface IncomingBankTransaction {
-
- // 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;
-
- // The reserve public key extracted from the transaction details.
- reserve_pub: EddsaPublicKey;
- }
-
-
-.. http:get:: ${BASE_URL}/history/outgoing
-
- Return a list of transactions made by the exchange, typically to a merchant.
-
- The bank account of the exchange is determined via the base URL and/or the
- user name in the ``Authorization`` header. In fact the transaction history
- might come from a "virtual" account, where multiple real bank accounts are
- merged into one history.
-
- Transactions are identified by an opaque integer, referred to here as "row
- ID". The semantics of the row ID (including its sorting order) are
- determined by the bank server and completely opaque to the client.
-
- The list of returned transactions is determined by a row ID *starting point*
- and a signed non-zero integer *delta*:
-
- * If *delta* is positive, return a list of up to *delta* transactions (all matching
- the filter criteria) strictly **after** the starting point. The transactions are sorted
- in **ascending** order of the row ID.
- * If *delta* is negative, return a list of up to *-delta* transactions (all matching
- the filter criteria) strictly **before** the starting point. The transactions are sorted
- in **descending** order of the row ID.
-
- If *starting point* is not explicitly given, it defaults to:
-
- * A value that is **smaller** than all other row IDs if *delta* is **positive**.
- * A value that is **larger** than all other row IDs if *delta* is **negative**.
-
- **Request**
-
- :query start: *Optional.*
- Row identifier to explicitly set the *starting point* of the query.
- :query delta:
- The *delta* value that determines the range of the query.
- :query long_poll_ms: *Optional.* If this parameter is specified and the
- result of the query would be empty, the bank will wait up to ``long_poll_ms``
- milliseconds for new transactions that match the query to arrive and only
- then send the HTTP response. A client must never rely on this behavior, as
- the bank may return a response immediately or after waiting only a fraction
- of ``long_poll_ms``.
-
- **Response**
-
- :status 200 OK:
- JSON object whose field ``outgoing_transactions`` is
- an array of type `OutgoingBankTransaction`.
- :status 204 No content:
- in case no records exist for the query
-
- .. ts:def:: OutgoingBankTransaction
-
- interface OutgoingBankTransaction {
-
- // 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.
- credit_account: string;
-
- // Payto URI to identify the sender of funds
- // This must be one of the exchange's bank accounts.
- debit_account: string;
-
- // The wire transfer ID in the outgoing transaction.
- wtid: ShortHashCode;
- }
-
-
------------------------
-Wire Transfer Test APIs
------------------------
-
-Endpoints in this section are only used for integration tests and never
-exposed by bank gateways in production.
-
-.. http:post:: ${BASE_URL}/admin/add-incoming
-
- Simulate a transfer from a customer to the exchange. This API is *not*
- idempotent since it's only used in testing.
-
- .. ts:def:: OutgoingBankTransaction
-
- interface AddIncomingRequest {
- // Amount to transfer.
- amount: Amount;
-
- // Reserve public key that is included in the wire transfer details
- // to identify the reserve that is being topped up.
- reserve_pub: EddsaPublicKey
-
- // Account (as payto URI) that makes the wire transfer to the exchange.
- // Usually this account must be created by the test harness before this API is
- // used. An exception is the "exchange-fakebank", where any debit account can be
- // specified, as it is automatically created.
- debit_account: string;
- }
diff --git a/core/api-wire.rst b/core/api-wire.rst
@@ -0,0 +1,299 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2019-2020 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
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+===========================
+Taler Wire Gateway HTTP API
+===========================
+
+This section describes the API offered by the Taler wire gateway. The API is
+used by the exchange to trigger transactions and query incoming transactions, as
+well as by the auditor to query incoming and outgoing transactions.
+
+This API is currently implemented by the Taler Demo Bank, as well as by
+LibEuFin (work in progress).
+
+
+--------------
+Authentication
+--------------
+
+The bank library authenticates requests to the wire gatway via
+`HTTP basic auth <https://tools.ietf.org/html/rfc7617>`_.
+
+-------------------
+Making Transactions
+-------------------
+
+.. http:post:: ${BASE_URL}/transfer
+
+ This API allows the exchange to make a transaction, typically to a merchant. The bank account
+ of the exchange is not included in the request, but instead derived from the user name in the
+ authentication header and/or the request base URL.
+
+ To make the API idempotent, the client must include a nonce. Requests with the same nonce
+ are rejected unless the request is the same.
+
+ **Request:** The body of this request must have the format of a `TransactionRequest`.
+
+ **Response:**
+
+ :status 200 OK:
+ The request has been correctly handled, so the funds have been transferred to
+ the recipient's account. The body is a `TransactionResponse`
+ :status 400 Bad Request: The bank replies with a `BankError` object.
+ :status 406 Not Acceptable: The request had wrong currency; the bank replies with a `BankError` object.
+ :status 409 Conflict:
+ A transaction with the same ``transaction_uid`` but different transaction details
+ has been submitted before.
+
+ **Details:**
+
+ .. ts:def:: TransactionResponse
+
+ interface TransactionResponse {
+
+ // Timestamp that indicates when the wire transfer will be executed.
+ // In cases where the wire transfer gateway is unable to know when
+ // the wire transfer will be executed, the time at which the request
+ // has been received and stored will be returned.
+ // The purpose of this field is for debugging (humans trying to find
+ // the transaction) as well as for taxation (determining which
+ // time period a transaction belongs to).
+ timestamp: Timestamp;
+
+ // Opaque of the transaction that the bank has made.
+ row_id: SafeUint64;
+ }
+
+
+ .. ts:def:: TransactionRequest
+
+ interface TransactionRequest {
+ // Nonce to make the request idempotent. Requests with the same
+ // transaction_uid that differ in any of the other fields
+ // are rejected.
+ request_uid: HashCode;
+
+ // Amount to transfer.
+ amount: Amount;
+
+ // Base URL of the exchange. Shall be included by the bank gateway
+ // in the approriate section of the wire transfer details.
+ exchange_base_url: string;
+
+ // Wire transfer identifier chosen by the exchange,
+ // used by the merchant to identify the Taler order
+ // associated with this wire transfer.
+ wtid: ShortHashCode;
+
+ // The recipient's account identifier as a payto URI
+ credit_account: string;
+ }
+
+
+ .. ts:def:: BankError
+
+ interface BankError {
+
+ // Human readable explanation of the failure.
+ error: string;
+
+ // Numeric Taler error code (`TALER_ErrorCode`)
+ ec: number;
+ }
+
+
+--------------------------------
+Querying the transaction history
+--------------------------------
+
+
+.. http:get:: ${BASE_URL}/history/incoming
+
+ Return a list of transactions made from or to the exchange.
+
+ Incoming transactions must contain a valid reserve public key. If a bank
+ transaction does not confirm to the right syntax, the wire gatway must not
+ report it to the exchange, and sent funds back to the sender if possible.
+
+ The bank account of the exchange is determined via the base URL and/or the
+ user name in the ``Authorization`` header. In fact the transaction history
+ might come from a "virtual" account, where multiple real bank accounts are
+ merged into one history.
+
+ Transactions are identified by an opaque numeric identifier, referred to here
+ as "row ID". The semantics of the row ID (including its sorting order) are
+ determined by the bank server and completely opaque to the client.
+
+ The list of returned transactions is determined by a row ID *starting point*
+ and a signed non-zero integer *delta*:
+
+ * If *delta* is positive, return a list of up to *delta* transactions (all matching
+ the filter criteria) strictly **after** the starting point. The transactions are sorted
+ in **ascending** order of the row ID.
+ * If *delta* is negative, return a list of up to *-delta* transactions (all matching
+ the filter criteria) strictly **before** the starting point. The transactions are sorted
+ in **descending** order of the row ID.
+
+ If *starting point* is not explicitly given, it defaults to:
+
+ * A value that is **smaller** than all other row IDs if *delta* is **positive**.
+ * A value that is **larger** than all other row IDs if *delta* is **negative**.
+
+ **Request**
+
+ :query start: *Optional.*
+ Row identifier to explicitly set the *starting point* of the query.
+ :query delta:
+ The *delta* value that determines the range of the query.
+ :query long_poll_ms: *Optional.* If this parameter is specified and the
+ result of the query would be empty, the bank will wait up to ``long_poll_ms``
+ milliseconds for new transactions that match the query to arrive and only
+ then send the HTTP response. A client must never rely on this behavior, as
+ the bank may return a response immediately or after waiting only a fraction
+ of ``long_poll_ms``.
+
+ **Response**
+
+ :status 200 OK: JSON object whose field ``incoming_transactions`` is an array of type `IncomingBankTransaction`.
+ :status 204 No content: in case no records exist for the targeted user.
+
+ .. ts:def:: IncomingBankTransaction
+
+ interface IncomingBankTransaction {
+
+ // 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;
+
+ // The reserve public key extracted from the transaction details.
+ reserve_pub: EddsaPublicKey;
+ }
+
+
+.. http:get:: ${BASE_URL}/history/outgoing
+
+ Return a list of transactions made by the exchange, typically to a merchant.
+
+ The bank account of the exchange is determined via the base URL and/or the
+ user name in the ``Authorization`` header. In fact the transaction history
+ might come from a "virtual" account, where multiple real bank accounts are
+ merged into one history.
+
+ Transactions are identified by an opaque integer, referred to here as "row
+ ID". The semantics of the row ID (including its sorting order) are
+ determined by the bank server and completely opaque to the client.
+
+ The list of returned transactions is determined by a row ID *starting point*
+ and a signed non-zero integer *delta*:
+
+ * If *delta* is positive, return a list of up to *delta* transactions (all matching
+ the filter criteria) strictly **after** the starting point. The transactions are sorted
+ in **ascending** order of the row ID.
+ * If *delta* is negative, return a list of up to *-delta* transactions (all matching
+ the filter criteria) strictly **before** the starting point. The transactions are sorted
+ in **descending** order of the row ID.
+
+ If *starting point* is not explicitly given, it defaults to:
+
+ * A value that is **smaller** than all other row IDs if *delta* is **positive**.
+ * A value that is **larger** than all other row IDs if *delta* is **negative**.
+
+ **Request**
+
+ :query start: *Optional.*
+ Row identifier to explicitly set the *starting point* of the query.
+ :query delta:
+ The *delta* value that determines the range of the query.
+ :query long_poll_ms: *Optional.* If this parameter is specified and the
+ result of the query would be empty, the bank will wait up to ``long_poll_ms``
+ milliseconds for new transactions that match the query to arrive and only
+ then send the HTTP response. A client must never rely on this behavior, as
+ the bank may return a response immediately or after waiting only a fraction
+ of ``long_poll_ms``.
+
+ **Response**
+
+ :status 200 OK:
+ JSON object whose field ``outgoing_transactions`` is
+ an array of type `OutgoingBankTransaction`.
+ :status 204 No content:
+ in case no records exist for the query
+
+ .. ts:def:: OutgoingBankTransaction
+
+ interface OutgoingBankTransaction {
+
+ // 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.
+ credit_account: string;
+
+ // Payto URI to identify the sender of funds
+ // This must be one of the exchange's bank accounts.
+ debit_account: string;
+
+ // The wire transfer ID in the outgoing transaction.
+ wtid: ShortHashCode;
+ }
+
+
+-----------------------
+Wire Transfer Test APIs
+-----------------------
+
+Endpoints in this section are only used for integration tests and never
+exposed by bank gateways in production.
+
+.. http:post:: ${BASE_URL}/admin/add-incoming
+
+ Simulate a transfer from a customer to the exchange. This API is *not*
+ idempotent since it's only used in testing.
+
+ .. ts:def:: OutgoingBankTransaction
+
+ interface AddIncomingRequest {
+ // Amount to transfer.
+ amount: Amount;
+
+ // Reserve public key that is included in the wire transfer details
+ // to identify the reserve that is being topped up.
+ reserve_pub: EddsaPublicKey
+
+ // Account (as payto URI) that makes the wire transfer to the exchange.
+ // Usually this account must be created by the test harness before this API is
+ // used. An exception is the "exchange-fakebank", where any debit account can be
+ // specified, as it is automatically created.
+ debit_account: string;
+ }
diff --git a/core/index.rst b/core/index.rst
@@ -1,6 +1,6 @@
..
This file is part of GNU TALER.
- Copyright (C) 2014-2018 GNUnet e.V.
+ Copyright (C) 2014-2020 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
@@ -32,7 +32,7 @@ interfaces between the core components of Taler.
api-common
api-error
api-exchange
- api-wire-plugin-bank
+ api-wire
api-merchant
api-auditor
api-bank
diff --git a/developers-manual.rst b/developers-manual.rst
@@ -1,3 +1,21 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014-2020 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
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+
Developer's Manual
##################
@@ -819,7 +837,7 @@ Anonymous E-Cash
Payment Replay
The process of proving to the merchant that the customer is entitled
to view a digital product again, as they already paid for it.
-
+
**Use instead**: In the event history, "re-activated digital content purchase"
could be used.
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
@@ -1,3 +1,22 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2019-2020 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
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+
+
GNU Taler Auditor Operator Manual
#################################
@@ -95,15 +114,6 @@ third parties to verify one's own work.
The Taler software stack for an auditor consists of the following
components:
-- Wire plugin
- A wire plugin enables the auditor to talk to the bank. Its role
- is to allow the auditor to retrieve incoming and outgoing wire
- transfers made by the exchange. Wire plugins are
- *plugins* as there can be many different implementations to deal with
- different banking standards. Wire plugins are automatically located
- and used by the auditor, but must be configured with the appropriate
- credentials.
-
- DBMS
Postgres
The auditor requires a DBMS to stores a local copy of the transaction history for
@@ -127,9 +137,9 @@ components:
of the specification by the exchange. However, for now it is assumed that
the respective cryptographic proofs are reported and verified manually ---
as with a well-behaved exchange this should obviously be a rare event.
-
+
The main binary of this component is the ``taler-auditor-httpd``.
-
+
- The wire-auditor
The wire auditor verifies that the bank transactions performed by the exchange
were done properly. This component must have access to the bank account
@@ -185,7 +195,7 @@ exchange compilation.
- texlive-latex-extra
- python3-jinja2
-
+
- libgnunetutil (from Git)
- GNU Taler exchange (from Git)
@@ -319,7 +329,7 @@ The ``taler-auditor-dbinit`` tool is used to initialize the auditor's
tables. After running this tool, the rights to CREATE or DROP tables
are no longer required and should be removed.
-
+
.. _Deployment:
Deployment
@@ -381,7 +391,7 @@ be fatal. Given the blob, the auditor would sign it using:
Those arguments are all mandatory.
- ``EXCHANGE_MASTER_PUB`` the base32 Crockford-encoded exchange’s
- master public key.
+ master public key.
- ``BLOB`` the blob generated by the ``taler-exchange-keyup`` tool.
@@ -584,5 +594,3 @@ already seen.
More extensive auditor testing where additional transactions
have been made against the database when the audit is being resumed
should be done in the future.
-
-
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
@@ -1,3 +1,21 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2014-2020 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
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+
GNU Taler Exchange Operator Manual
##################################
@@ -110,14 +128,19 @@ components:
computes the expected bank balance, revenue and risk exposure of the
exchange operator. The main binary is the ``taler-auditor``.
-- Wire plugin
- A wire plugin enables the HTTP frontend to talk to the bank. Its role
- is to allow the exchange to validate bank addresses (i.e. IBAN
- numbers), for the aggregator to execute wire transfers and for the
- auditor to query bank transaction histories. Wire plugins are
- *plugins* as there can be many different implementations to deal with
- different banking standards. Wire plugins are automatically located
- and used by the exchange, aggregator and auditor.
+- Wire adapter
+ A wire adapter is a component that enables exchange to talk to a bank.
+ (1) The libtalerfakebank implements a bank with a wire adapter API
+ inside of a testcase.
+ (2) For the demonstration Web site (or local currencies),
+ the Python bank provides a bank that directly provides
+ the wire adapter API.
+ (3) For production, libeufin's Nexus component implements a wire
+ adapter towards the traditional SEPA banking system with IBAN
+ accounts.
+ The client-side wire adapter API is implemented in libtalerbank and
+ is used by the aggregator to execute wire transfers and for the
+ auditor to query bank transaction histories.
- DBMS
Postgres
@@ -397,21 +420,14 @@ information:
The first part of the URL following ``payto://`` (“sepa” or
“x-taler-bank”) is called the wire method.
-- A matching wire plugin that implements a protocol to interact with
- the banking system. For example, the “taler-bank” plugin can interact
- with the Taler bank demonstrator or with libeufin.
- A wire plugin only supports one particular
- wire method. Thus, you must make sure to pick a plugin that supports
- the wire method used in the URL.
-
- A file containing the signed JSON-encoded bank account details for
the /wire API. This is necessary as Taler supports offline signing
for bank accounts for additional security.
-- Finally, the plugin needs to be provided resources for authentication
+- Finally, the exchange needs to be provided resources for authentication
to the respective banking service. The format in which the
- authentication information must be provided depends on the wire
- plugin.
+ authentication information is currently a username and password
+ for HTTP basic authentication, or nothing for the fakebank.
You can configure multiple accounts for an exchange by creating sections
starting with “account-” for the section name. You can ENABLE for each
@@ -424,16 +440,21 @@ wire transfers):
URL = "payto://sepa/CH9300762011623852957"
WIRE_RESPONSE = ${TALER_CONFIG_HOME}/account-1.json
- # Currently, only the 'taler_bank' plugin is implemented.
- PLUGIN = <plugin_name_here>
+ # Wire method supported for merchants, i.e. "IBAN" or
+ # "x-taler-bank"
+ METHOD = <method>
# Use for exchange-aggregator (outgoing transfers)
ENABLE_DEBIT = YES
# Use for exchange-wirewatch (and listed in /wire)
ENABLE_CREDIT = YES
- # Authentication options for the chosen plugin go here.
+ # Authentication options for exchange bank account go here.
# (Next sections have examples of authentication mechanisms)
+ TALER_BANK_AUTH_METHOD = basic
+ USERNAME = exchange
+ PASSWORD = super-secure
+
The command line tool taler-exchange-wire is used to create the
``account-1.json`` file. For example, the utility may be invoked as
@@ -447,37 +468,6 @@ specified by the configuration):
The generated file will be echoed by the exchange when serving
/wire [3]_ requests.
-.. _Wire-plugin-_0060_0060taler_005fbank_0027_0027:
-
-Wire plugin “taler_bank”
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. meta::
- :keywords: x-taler-bank
- :keywords: taler_bank plugin
-
-The ``taler_bank`` plugin implements the wire method “x-taler-bank”.
-
-The format of the ``payto://`` URL is
-``payto://x-taler-bank/HOSTNAME[:PORT]``.
-
-For basic authentication, the ``taler_bank`` plugin only supports simple
-password-based authentication. For this, the configuration must contain
-the “USERNAME” and “PASSWORD” of the respective account at the bank.
-
-::
-
- [account-1]
-
- # Bank account details here..
- # ..
-
- # Authentication options for the taler_bank plugin below:
-
- TALER_BANK_AUTH_METHOD = basic
- USERNAME = exchange
- PASSWORD = super-secure
-
.. _Wire-fee-structure:
Wire fee structure
@@ -487,7 +477,7 @@ Wire fee structure
:keywords: wire fee
:keywords: fee
-For each wire method (“sepa” or “x-taler-wire”, but not per plugin!) the
+For each wire method (“sepa” or “x-taler-wire”) the
exchange configuration must specify applicable wire fees. This is done
in configuration sections of the format ``fees-METHOD``. There are two
types of fees, simple wire fees and closing fees. Wire fees apply
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -561,15 +561,6 @@ Accounts
$ taler-config -s ACCOUNT-bank -o WIRE_RESPONSE \
-V '{$TALER_CONFIG_HOME}/merchant/bank.json'
- - The “PLUGIN” option specifies which wire plugin should be used for
- this account. The plugin must support the wire method used by the
- URL. For example, use:
-
- ::
-
- $ taler-config -s ACCOUNT-bank -o PLUGIN \
- -V taler_bank
-
- For each ``instance`` that should use this account, you should set
``HONOR_instance`` and ``ACTIVE_instance`` to YES. The first
option will cause the instance to accept payments to the account
@@ -587,21 +578,6 @@ Accounts
to use “account-bank” for the “default” instance.
- Depending on which PLUGIN you configured, you may additionally
- specfiy authentication options to enable the plugin to use the
- account.
-
- For example, with ``taler_bank`` plugin, use:
-
- ::
-
- $ taler-config -s ACCOUNT-bank -o TALER_BANK_AUTH_METHOD \
- -V basic
- $ taler-config -s ACCOUNT-bank -o USERNAME \
- -V user42
- $ taler-config -s ACCOUNT-bank -o PASSWORD \
- -V pass42
-
Note that additional instances can be specified using different
tokens in the section name instead of ``default``.
@@ -633,7 +609,6 @@ The following is an example for a complete backend configuration:
[ACCOUNT-bank]
URL = payto://x-taler-bank/bank.demo.taler.net/4
WIRE_RESPONSE = $DATADIR/bank.json
- PLUGIN = taler_bank
HONOR_default = YES
ACTIVE_default = YES
TALER_BANK_AUTH_METHOD = basic
@@ -942,34 +917,6 @@ public key using the ``gnunet-ecc`` command-line tool:
$(taler-config -f -s INSTANCE-default \
-o KEYFILE)
-.. _SEPA-configuration:
-
-Using the SEPA wire transfer method
------------------------------------
-
-SEPA
-EBICS
-The following is a sample configuration for the SEPA wire transfer
-method: [2]_.
-
-Then, to configure the EBICS backend for SEPA payments in EUR, the
-following configuration options need to be set:
-
-::
-
- $ taler-config -s TALER -o CURRENCY -V EUR
- $ taler-config -s ACCOUNT-e -o PLUGIN -V ebics
- $ taler-config -s ACCOUNT-e -o URL \
- -V payto://sepa/XY00111122223333444455556666
- $ taler-config -s ACCOUNT-e -o WIRE_RESPONSE
- -V '${DATADIR}/b.json'
-
-Please note that you will also have to configure an exchange and/or
-auditors that support SEPA. However, we cannot explain how to do this
-yet as such entities do not yet exist. Once such entities do exist, we
-expect future versions of the Taler backend to ship with pre-configured
-exchanges and auditors for common denominations.
-
.. _Tipping-visitors:
Tipping visitors
