commit 8e63e7d7e26bc4a899df6d725b59c4abd4979127
parent 27fad4449371fdec5d64fde0bb52176bd6f99810
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Sun, 21 May 2023 20:45:00 +0200
more doc revision
Diffstat:
7 files changed, 70 insertions(+), 45 deletions(-)
diff --git a/core/api-bank-sandbox.rst b/core/api-bank-sandbox.rst
@@ -57,7 +57,7 @@ For brevity, the list of response statuses for each endpoint may not be exhausti
The following endpoints are served under ``/demobanks/default/circuit-api``.
The client side of this API is offered both along the
-:doc:`CLI <circuit-cli-commands>` and the SPA. The SPA is generally served
+:doc:`CLI <../libeufin/circuit-cli-commands>` and the SPA. The SPA is generally served
along Sandbox ``/`` path.
Accounts
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -18,7 +18,7 @@
.. _http-common:
-=================================
+==================================
Conventions for Taler RESTful APIs
==================================
@@ -186,6 +186,8 @@ Examples:
to decide whether it will talk to the service.
+.. _error-codes:
+
-----------
Error Codes
-----------
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -121,7 +121,7 @@ possibly by using HTTPS.
// Set to true if this exchange allows the use
// of reserves for tipping.
- tipping_allowed: bool;
+ tipping_allowed: boolean;
// EdDSA master public key of the exchange, used to sign entries
// in ``denoms`` and ``signkeys``.
diff --git a/core/index.rst b/core/index.rst
@@ -41,6 +41,7 @@ protocols using JSON.
../wallet/wallet-core
api-auditor
api-sync
+ api-challenger
api-taldir
api-mailbox
api-bank
diff --git a/demo-deployment.rst b/demo-deployment.rst
@@ -1,10 +0,0 @@
-This document explains how to install Taler+LibEuFin
-on gv.taler.net, for demo.taler.net.
-
-1. Login as the ``demo`` user on ``gv.taler.net``.
-2. Pull the latest ``deployment.git`` code.
-3. Navigate to the ``deployment.git/docker/demo`` directory.
-4. The README file is the reference about building and running the services.
-
-Nginx is already configured to reach the services as exported by
-Docker Compose.
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
@@ -1126,7 +1126,7 @@ assign an identifier for the ``$FACADE_NAME`` below:
$CONNECTION_NAME \
$LOCAL_ACCOUNT_NAME
-At this point, the additional :doc:`taler-wire-gateway API <core/api-wire>`
+At this point, the additional :doc:`taler-wire-gateway API <core/api-bank-wire>`
becomes offered by the Nexus. The purpose is to let a Taler exchange rely on
Nexus to manage its bank account.
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -44,11 +44,11 @@ Architecture overview
.. index:: KUDOS
Taler is a pure payment system, not a new crypto-currency. As such, it
-operates in a traditional banking context. In particular, this means
-that in order to receive funds via Taler, the merchant must have a
-regular bank account, and payments can be executed in ordinary
-currencies such as USD or EUR. For testing purposes, Taler uses a
-special currency “KUDOS” and includes its own special bank.
+operates in a traditional banking context. In particular, this means that in
+order to receive funds via Taler, the merchant must have a regular bank
+account, and payments can be executed in ordinary currencies such as USD or
+EUR. Taler can also be used as a regional currency; for such scenarios, the
+Taler system also includes its own stand-alone bank.
.. index:: frontend
.. index:: back-office
@@ -56,8 +56,7 @@ special currency “KUDOS” and includes its own special bank.
.. index:: DBMS
.. index:: PostgreSQL
-The Taler software stack for a merchant consists of four main
-components:
+The Taler software stack for a merchant consists of four main components:
- A *frontend* which interacts with the customer’s browser. The frontend
enables the customer to build a shopping cart and place an order.
@@ -95,13 +94,13 @@ Taler exchange over the Internet. The frontend accesses the backend via a
RESTful API. As a result, the frontend never has to directly communicate with
the exchange, and also does not deal with sensitive data. In particular, the
merchant’s signing keys and bank account information are encapsulated within
-the Taler backend.
+the Taler merchant backend.
A typical deployment will additionally include a full-blown Web server (like
Apache or Nginx). Such a Web server would be responsible for TLS termination and
access control to the ``/private/`` and ``/management/`` API endpoints of the
-merchant backend. Please carefully review the section on :ref:`Secure setup
-<Secure-setup>` before deploying a Taler merchant backend to production.
+merchant backend. Please carefully review the section on :ref:`secure setup
+<Secure-setup>` before deploying a Taler merchant backend into production.
Terminology
@@ -114,21 +113,44 @@ Instances
.. index:: instance
-The backend allows the user to run multiple *instances* of shops with distinct
-business entities sharing a single backend. Each instance uses its own bank
-accounts and key for signing contracts. All major accounting functionality is
-separate per instance. What is shared is the database, HTTP(S) address and
-the main Taler configuration (accepted currency, exchanges and auditors).
+The backend allows a single HTTP server to support multiple independent shops
+with distinct business entities sharing a single backend. An *instance* is
+the name or identifier that allows the single HTTP server to determine which
+shop a request is intended for. Each instance has its own base URL in the
+REST API of the merchant backend (``/instances/$INSTANCE/``). Each instance
+can use its own bank accounts and keys for signing contracts. All major
+accounting functionality is separate per instance. Access to each instance is
+controlled via a bearer token (to be set in the HTTP "Authorization" header).
+All instances share the same *database*, top-level HTTP(S) address and the
+main Taler configuration (especially the accepted *currency* and *exchanges*).
-Accounts
---------
+ .. note::
+
+ This documentation does not use the term "user" or "username" in
+ conjunction with instances as that might create confusion between
+ instances with paying customers using the system. We also do not use the
+ term "account" in conjunction with instances, as that might cause
+ confusion with bank accounts. That said, conceptually it is of course
+ acceptable to consider instances to be the "users" or "accounts" of a
+ merchant backend and the bearer token is equivalent to a passphrase.
-.. index:: account
+
+Instance Bank Accounts
+----------------------
+
+.. index:: instance-bank-account
To receive payments, an instance must have configured one or more bank
-*accounts*. The backend does not have accounts for users, and instances are
-also not really 'accounts'. So whenever we use the term *account*, it is about
-a bank account of a merchant.
+*accounts*. When configuring the bank account of an instance, one should
+ideally also provide the address and credentials of an HTTP service
+implementing the `Taler Bank Merchant HTTP API
+<taler-bank-merchant-http-api>`_. Given such a service, the GNU Taler
+merchant backend can automatically reconcile wire transfers from the
+exchange to the merchant's bank account with the orders that are being
+settled.
+
+This documentation exclusively uses the term *account* for the bank
+accounts of a merchant or shop that may be associated with an instance.
Inventory
---------
@@ -141,21 +163,26 @@ Inventory
The Taler backend offers inventory management as an optional function.
Inventory is tracked per instance and consists of *products* sold in
-*units*. Inventory can be finite or infinite (for digital products).
-Products may include previews (images) to be shown to the user and other
-meta-data. Inventory management allows the frontend to *lock* products,
-reserving them for a particular (unpaid) *order*. The backend can keep
-track of how many units of a product remain in stock and ensure that
-the number of units sold does not exceed the number of units in stock.
+*units*. Inventory can be finite (physical stock) or infinite (for digital
+products). Products may include previews (images) to be shown to the user as
+well as other meta-data. Inventory management allows the frontend to *lock*
+products, reserving a number of units from stock for a particular (unpaid)
+*order*. The backend can keep track of how many units of a product remain in
+stock and ensure that the number of units sold does not exceed the number of
+units in stock.
Inventory management is optional, and it is possible for the frontend to
-include products in orders that are not in the inventory, or to override
-prices of products in the inventory.
+include products in orders that are not in the inventory. The frontend
+can also override prices of products in the inventory or set a total price
+for an order that is different from the price of the sum of the products
+in the order.
+
Orders and Contracts
--------------------
.. index:: order
+.. index:: terms
.. index:: contract
.. index:: claim
.. index:: pay
@@ -164,8 +191,13 @@ Orders and Contracts
.. index:: lock
.. index:: legal expiration
-In Taler, users pay merchants for orders. An order is first created by the
-merchant, where the merchant specifies the specific terms of the order.
+In Taler, users pay merchants for *orders*. An order is first created by the
+merchant. To create an order, the merchant must specify the specific *terms*
+of the order. Order *terms* include details such as the total amount to be
+paid, payment fees the merchant is willing to cover, the set of products to
+deliver, a delivery location and many other details. The `merchant API
+specification <contract-terms>`_ specifies the full set of possible order
+terms.
After an order is created, it is *claimed* by a wallet. Once an order is
claimed by a specific wallet, only that wallet will be able to pay for this
