Merge branch 'master' of git.taler.net:api

17 files changed, 623 insertions, 252 deletions

diff --git a/api-bank.rst b/api-bank.rst
index afb2ba28..48b7075e 100644
--- a/api-bank.rst
+++ b/api-bank.rst
@@ -35,10 +35,10 @@ namely exchanges.
 
 **Response:**
 
-:status 200 OK: The request has been correctly handled, so the funds have been transferred to
-the recipient's account
+:status 200 OK: The request has been correctly handled, so the funds have been transferred to the recipient's account
 
 :status 400 Bad Request: The bank replies a `BankIncomingError`_ object
+
 **Details:**
 
 .. _BankDepositRequest:
diff --git a/api-exchange.rst b/api-exchange.rst
index bc541934..90a708c0 100644
--- a/api-exchange.rst
+++ b/api-exchange.rst
@@ -15,16 +15,18 @@
 
   @author Christian Grothoff
 
-=========================
+=============================
 The Exchange RESTful JSON API
-=========================
+=============================
 
 The API specified here follows the :ref:`general conventions <http-common>`
-for all details not specified in the individual requests.
+for all details not specified in the individual requests. The :ref:`glossary`
+defines all specific terms used in this section.
 
--------------------
+.. _keys:
+-----------------------
 Obtaining Exchange Keys
--------------------
+-----------------------
 
 This API is used by wallets and merchants to obtain global information about
 the exchange, such as online signing keys, available denominations and the fee
@@ -232,8 +234,7 @@ Obtaining wire-transfer information
       // 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:
 
@@ -241,7 +242,7 @@ Obtaining wire-transfer information
   .. _tsref-type-WireTestResponse:
   .. code-block:: tsref
 
-  interface WireTestResponse {
+    interface WireTestResponse {
       // Mandatory indicator that this is a TEST wire response.
       type: "test";
 
@@ -250,14 +251,13 @@ Obtaining wire-transfer information
 
       // URI of the bank
       bank_uri: string;
-
     }
 
-      .. _WireSepaResponse:
+  .. _WireSepaResponse:
   .. _tsref-type-WireSepaResponse:
   .. code-block:: tsref
 
-  interface WireSepaResponse {
+    interface WireSepaResponse {
       // Mandatory indicator that this is a SEPA wire response.
       type: "sepa";
 
@@ -270,13 +270,12 @@ Obtaining wire-transfer information
       // BIC of the bank.
       bic: string;
 
-      // the EdDSA signature_ (binary-only) with purpose
+      // the EdDSA signature (binary-only) with purpose
       // `TALER_SIGNATURE_EXCHANGE_PAYMENT_METHOD_SEPA` signing over the hash over the
       // 0-terminated strings representing the receiver's name, IBAN and the BIC.
       sig: EddsaSignature;
     }
 
-
 ------------------
 Withdrawal
 ------------------
@@ -444,9 +443,9 @@ exchange.
 
 .. _deposit-par:
 
---------------------
+-------
 Deposit
---------------------
+-------
 
 Deposit operations are requested by a merchant during a transaction. For the
 deposit operation, the merchant has to obtain the deposit permission for a coin
@@ -542,9 +541,9 @@ denomination.
   has enough residual value that has not already been deposited or melted.
 
 
+  .. _DepositSuccess:
   .. code-block:: tsref
 
-     .. _DepositSuccess:
      interface DepositSuccess {
       // The string constant "DEPOSIT_OK"
       status: string;
@@ -561,7 +560,7 @@ denomination.
       // explicitly as the client might otherwise be confused by clock skew as to
       // which signing key was used.
       pub: EddsaPublicKey;
-    }
+      }
 
   .. _DepositDoubleSpendError:
   .. code-block:: tsref
@@ -1152,10 +1151,10 @@ Refunds
 
     }
 
+  .. _RefundSuccess:
   .. code-block:: tsref
 
-     .. _RefundSuccess:
-     interface RefundSuccess {
+    interface RefundSuccess {
       // The string constant "REFUND_OK"
       status: string;
 
@@ -1169,7 +1168,7 @@ Refunds
       // explicitly as the client might otherwise be confused by clock skew as to
       // which signing key was used.
       pub: EddsaPublicKey;
-    }
+   }
 
 ------------------------------
 Administrative API: Key update
diff --git a/api-merchant.rst b/api-merchant.rst
index 9c1adf9b..a0c4b938 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -17,11 +17,13 @@
   @author Florian Dold
   @author Christian Grothoff
 
+.. _merchant-api:
+
 ============
 Merchant API
 ============
 
-Before reading the API reference documentation, it is suggested to read the :ref:`merchant-arch`
+Before reading the API reference documentation, see the :ref:`merchant architecture<merchant-arch>` and :ref:`payprot`
 
 ---------------------
 The Frontent HTTP API
@@ -49,8 +51,7 @@ The Frontent HTTP API
 
 
   Send the deposit permission to the merchant. The client should POST a `deposit-permission`_
-  object. Note that ``pay_url`` is make known by the frontent to the wallet via the DOM event
-  ``taler-execute-payment``, documented in :ref:`byoffer`.
+  object.
 
   .. _deposit-permission:
   .. code-block:: tsref
@@ -71,7 +72,7 @@ The Frontent HTTP API
       // maximum fees merchant agreed to cover as per the contract
       max_fee: Amount;
 
-      // The merchant instance which is going to receive the final wire transfer. See paragraph `Merchant Instances`
+      // The merchant instance which is going to receive the final wire transfer. See :ref:`instances-lab`
       receiver: string;
 
       // signature by the merchant over the contract, must match signed data of purpose TALER_SIGNATURE_MERCHANT_CONTRACT
@@ -110,7 +111,7 @@ The Frontent HTTP API
 
       // the signature made by the coin's private key on a `struct TALER_DepositRequestPS`. See section `Signatures` on the exchange's API page.
       coin_sig: EddsaSignature;
-  }
+    }
 
   **Success Response:**
 
@@ -208,13 +209,13 @@ The following API are made available by the merchant's `backend` to the merchant
   **Request:**
 
   :query wtid: raw wire transfer identifier identifying the wire transfer (a base32-encoded value)
-  :query exchange_uri: base URI of the exchange that made the wire transfer
+  :query exchange: base URI of the exchange that made the wire transfer
 
   **Response:**
 
   :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`_.  Note that
+    The body of the response is a :ref:`TrackTransactionResponse <TrackTransferResponse>`.  Note that
     the similarity to the response given by the exchange for a /track/transfer
     is completely intended.
 
@@ -228,7 +229,8 @@ The following API are made available by the merchant's `backend` to the merchant
   **Request:**
 
   :query id: ID of the transaction we want to trace (an integer)
-  :query receiver: identificative token for the merchant instance which is to be tracked (optional). See :ref:`instances`.
+  :query receiver: identificative token for the merchant instance which is to be tracked (optional). See :ref:`instances-lab`. This information is needed because the request has to be signed by the merchant, thus we need to pick the instance's private key.
+
   **Response:**
 
   :status 200 OK:
@@ -240,7 +242,7 @@ The following API are made available by the merchant's `backend` to the merchant
     The deposit request has been accepted for processing, but was not yet
     executed.  Hence the exchange does not yet have a wire transfer identifier.
     The merchant should come back later and ask again.
-    The response body is a `TrackTransactionAcceptedResponse`_.  Note that
+    The response body is a :ref:`TrackTransactionAcceptedResponse <TrackTransactionAcceptedResponse>`.  Note that
     the similarity to the response given by the exchange for a /track/transaction
     is completely intended.
 
@@ -285,24 +287,11 @@ Encodings
 
 Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`.
 
-.. _instances:
-
-------------------
-Merchant Instances
-------------------
-
-Any backend can account for multiple bank accounts, and we call `instance` or `receiver` (interchangeably)
-any of those bank accounts. The backend needs that due to the ability we give to a merchant to route money
-(he earns through Taler) to multiple bank accounts, depending on his will. For example, a donation shop using
-Taler needs to know any bank account of any entity which is going to receive money through his website. That
-happens because when the merchant deposits coins to the exchange, he must provide bank details to it about the
-money receiver, see :ref:`deposit-par`.
-
-
 .. _contract:
 
+------------------
 Offer and Contract
-^^^^^^^^^^^^^^^^^^
+------------------
 
 An `offer` is a wrapper around a contract with some additional information
 that is legally non-binding:
diff --git a/configuration-basics.rst b/configuration-basics.rst
new file mode 100644
index 00000000..9296a2b4
--- /dev/null
+++ b/configuration-basics.rst
@@ -0,0 +1,68 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014, 2015, 2016 INRIA
+  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/>
+
+  @author Marcello Stanisci
+
+======================
+Configuration in Taler
+======================
+
+In Taler realm, any component obeys to the same pattern to get configuration
+values.  According to this pattern, once the component has been installed, the
+installation deploys default values in `${prefix}/share/taler/config.d/`, in
+`.conf` files.  In order to override these defaults, the user can write a custom
+`.conf` file and either pass it to the component at execution time, or name it
+`taler.conf` and place it under `$HOME/.config/`.
+
+
+--------------------
+Configuration format
+--------------------
+
+A config file is a text file containing `sections`, and each section contains
+its `values`. The right format follows::
+
+  [section1]
+  value1 = string
+  value2 = 23
+
+  [section2]
+  value21 = string
+  value22 = /path22
+
+Throught any configuration file, it is possible to use ``$``-prefixed variables,
+especially when a value needs a pathname. Some of them are automatically resolved,
+like ``${TALER_DATA_HOME}``, ``${TALER_RUNTIME_DIR}``, or ``${HOME}``. (FIXME: explain
+how/where/when those defaults get resolved) Other variables can be defined under the
+`paths` section. For example::
+
+  [paths]
+  TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
+  ..
+  [section-x]
+  path-x = ${TALER_DEPLOYMENT_SHARED}/x
+
+The utility ``taler-config``, which gets installed along with the exchange, serves to get and
+set configuration values without directly editing the `.conf`.  See ``taler-config --help``.
+
+Note that, in this stage of development, the file ``$HOME/.config/taler.conf``
+can contain sections for *all* the component. For example, both an exchange and
+a bank can read values from it.
+
+The repository ``git://taler.net/deployment`` contains examples of configuration
+file used in our demos. See under ``deployment/config``.
+
+.. note::
+
+  Expectably, some components will not work just by using default values, as their
+  work is often interdependent. For example, a merchant needs to know an exchange
+  URL, or a database name.
diff --git a/dev-exchange.rst b/dev-exchange.rst
new file mode 100644
index 00000000..4d0de76a
--- /dev/null
+++ b/dev-exchange.rst
@@ -0,0 +1,55 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014, 2015, 2016 INRIA
+  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/>
+
+  @author Christian Grothoff
+  @author Marcello Stanisci
+
+========
+Exchange
+========
+
+.. _keys-duration:
+
+-------------
+Keys duration
+-------------
+
+`signkeys`. The option `lookahead_sign` is such that, being `t` the time when `taler-exchange-keyup`
+is run, `taler-exchange-keyup` will generate `n` `signkeys`, where `t + (n * signkey_duration) = t +
+lookahead_sign`. In other words, we generate a number of keys which is sufficient to cover a period of
+`lookahead_sign`. As for the starting date, the first generated key will get a starting time of `t`,
+and the `j`-th key will get a starting time of `x + signkey_duration`, where `x` is the starting time
+of the `(j-1)`-th key.
+
+`denom keys`. The option `lookahead_sign` is such that, being `t` the time when `taler-exchange-keyup`
+is run, `taler-exchange-keyup` will generate `n` `denom keys` for each denomination, where
+`t + (n * duration_withdraw) = t + lookahead_sign`. In other words, for each denomination, we generate a
+number of keys which is sufficient to cover a period of `lookahead_sign`. As for the starting date, the
+first generated key will get a starting time of `t`, and the `j`-th key will get a starting time of
+`x + duration_withdraw`, where `x` is the starting time of the `(j-1)`-th key. 
+
+
+
+---------------
+Database Scheme
+---------------
+
+The exchange database must be initialized using `taler-exchange-dbinit`.  This
+tool creates the tables required by the Taler exchange to operate.  The
+tool also allows you to reset the Taler exchange database, which is useful
+for test cases but should never be used in production.  Finally,
+`taler-exchange-dbinit` has a function to garbage collect a database,
+allowing administrators to purge records that are no longer required.
+
+The database scheme used by the exchange look as follows:
+
+.. image:: exchange-db.png
diff --git a/dev-merchant.rst b/dev-merchant.rst
new file mode 100644
index 00000000..cb834659
--- /dev/null
+++ b/dev-merchant.rst
@@ -0,0 +1,41 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014, 2015, 2016 INRIA
+  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/>
+
+  @author Marcello Stanisci
+
+========
+Merchant
+========
+
+------------
+Introduction
+------------
+TBD
+
+.. _merchant-arch:
+
+------
+Design
+------
+
+TO REVIEW::
+
+  The `frontend` is the existing shopping portal of the merchant.
+  The architecture tries to minimize the amount of modifications necessary
+  to the `frontend` as well as the trust that needs to be placed into the
+  `frontend` logic.  Taler requires the frontend to facilitate two
+  JSON-based interactions between the wallet and the `backend`, and
+  one of those is trivial.
+  
+  The `backend` is a standalone C application intended to implement all
+  the cryptographic routines required to interact with the Taler wallet
+  and a Taler exchange.
diff --git a/dev-wallet-wx.rst b/dev-wallet-wx.rst
index 5995226e..8ba29975 100644
--- a/dev-wallet-wx.rst
+++ b/dev-wallet-wx.rst
@@ -170,12 +170,14 @@ Internationalisation
 Strings in the JavaScript code are internationalised using the following functions:
 
 - *i18n*: translate string with arbitrary arguments, the result is returned as string.
+
 .. code-block:: js
 
   i18n`You have ${n} coins.`
 
 - *i18n.parts*: Interpolate i18nized values with arbitrary objects.
   Useful for example to include HTML elements.
+
 .. code-block:: js
 
   i18n.parts`Visit ${link} to get more coins.`
diff --git a/example-essay-store.rst b/example-essay-store.rst
index ccbf7b5f..2a240f86 100644
--- a/example-essay-store.rst
+++ b/example-essay-store.rst
@@ -21,7 +21,7 @@ Example: Essay Store
 ==================================
 
 To properly understand this example, the reader should be familiar with Taler's terminology;
-in particular, definitions like `contract`, `fulfillment URL`, `offering URL`, `IIG` and `deposit permission`,
+in particular, definitions like `contract`, `fulfillment URL`, `offering URL`, and `deposit permission`,
 are assumed to be known.  Refer to :ref:`contract`, :ref:`payprot` and :ref:`deposit-par` in order to get
 some general insight on terms and interactions between components.
 
@@ -36,12 +36,20 @@ In particular, the offer URLs have the following format:
 
   `https://blog.demo.taler.net/essay/article_title`
 
-The offer URLs trigger the expected interaction with the wallet.
-  FIXME: describe where the contract is generated!
-  FIXME: give the pay URL.
+The offer URLs trigger the expected interaction with the wallet. In practical terms, the
+offer URL returns a HTML page that can either show a pay-form in case Taler is not installed
+in the user's browser or download the contract from the merchant.
+If the user has Taler installed and wants to pay, the wallet will POST the coins to a URL
+of the form:
+
+  `https://blog.demo.taler.net/pay?uuid=${contract_hashcode}`
+
+The URL comes with the contract's hashcode because each contract is an entry in
+the merchant's state, so it can mark it as ``payed`` whenever it receives coins.
+
 
 For the essay store, the fulfillment URL matches the initial part of
-an offering URL, but contains the additional parameters needed to
+an offer URL, but contains the additional parameters needed to
 reconstruct the contract, in this case the `tid` (transaction id) and
 a `timestamp`. Hence, a fulfillment URL for the essay store looks like:
 
diff --git a/glossary.rst b/glossary.rst
index 7e8e9241..d9a6cfa7 100644
--- a/glossary.rst
+++ b/glossary.rst
@@ -16,6 +16,8 @@
   @author Florian Dold
   @author Christian Grothoff
 
+.. _glossary:
+
 ==============
 Taler Glossary
 ==============
diff --git a/impl-exchange.rst b/impl-exchange.rst
deleted file mode 100644
index 2c118d8e..00000000
--- a/impl-exchange.rst
+++ /dev/null
@@ -1,122 +0,0 @@
-..
-  This file is part of GNU TALER.
-  Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA
-  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/>
-
-  @author Christian Grothoff
-
-===================================
-The Exchange Reference Implementation
-===================================
-
-----------------------
-The Configuration File
-----------------------
-
-The section `[taler]` contains global options for the exchange:
-
-* `currency`: The currency supported by the exchange (i.e. "EUR")
-
-
-The section `[exchange]` contains various global options for the exchange:
-
-* `master_public_key`: Must specify the exchange's master public key.
-* `wireformat`: The wireformat supported by the exchange (i.e. "SEPA")
-
-
-The network configuration for the exchange's HTTP server is configured
-with four options:
-
-* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket
-* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`.
-* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix`
-* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----).
-
-These four options are typically given twice: first in the `[exchange]` section
-for the public Rest API of the exchange, and again in the `[exchange-admin]`
-section for the administrative (/admin) and testing (/test) API of the exchange.
-The exchange can be started with the `-D` option to disable the administrative
-functions entirely.  It is recommended that the administrative API is only
-accessible via a properly protected UNIX domain socket.
-
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-Bank account configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The command line tool `taler-exchange-wire` is used to create a file with
-the JSON response to /wire requests using the exchange's offline
-master key.  The resulting file needs to be added to the configuration
-under the respective option for the wire transfer method, i.e.
-`SEPA_RESPONSE_FILE` in section `[exchange-wire-incoming-sepa]` when the
-`wireformat` option in the configuration file allows `sepa` transactions.
-
-
-^^^^^^^^^^^^^^^^^^^^^^
-Key Management Options
-^^^^^^^^^^^^^^^^^^^^^^
-
-The command line tool `taler-exchange-keyup` updates the signing key and list of denominations offered by the exchange.  This process requires the exchange's master key, and should be done offline in order to protect the master key.  For this, `taler-exchange-keyup` uses additional configuration options.
-
-The section `[exchange_keys]` containts the following entries:
-
-* `signkey_duration`: How long should one signing key be used?
-* `lookahead_sign`:  For how far into the future should keys be issued?  This determines the frequency
-  of offline signing with the master key.
-* `lookahead_provide`: How far into the future should the exchange provide keys?  This determines the attack
-  window on keys.
-
-
-Sections specifying denomination (coin) information start with "coin\_".  By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", i.e. "[coin_eur_ct_10] for a 10 cent piece.  However, only the "coin\_" prefix is mandatory.  Each "coin\_"-section must then have the following options:
-
-* `value`: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION.  For example, a 10 cent piece is "EUR:0.10".
-* `duration_withdraw`: How long can a coin of this type be withdrawn?  This limits the losses incured by the exchange when a denomination key is compromised.
-* `duration_overlap`: What is the overlap of the withdrawal timespan for this coin type?
-* `duration_spend`: How long is a coin of the given type valid?  Smaller values result in lower storage costs for the exchange.
-* `fee_withdraw`: What does it cost to withdraw this coin? Specified using the same format as `value`.
-* `fee_deposit`: What does it cost to deposit this coin? Specified using the same format as `value`.
-* `fee_refresh`: What does it cost to refresh this coin? Specified using the same format as `value`.
-* `rsa_keysize`: How many bits should the RSA modulus (product of the two primes) have for this type of coin.
-
-
-------------------
-Reserve management
-------------------
-
-Incoming transactions to the exchange's provider result in the creation or update of reserves, identified by their withdrawal key.
-
-The command line tool `taler-exchange-reservemod` allows create and add money to reserves in the exchange's database.
-
-
--------------------
-Database Scheme
--------------------
-
-The exchange database must be initialized using `taler-exchange-dbinit`.  This
-tool creates the tables required by the Taler exchange to operate.  The
-tool also allows you to reset the Taler exchange database, which is useful
-for test cases but should never be used in production.  Finally,
-`taler-exchange-dbinit` has a function to garbage collect a database,
-allowing administrators to purge records that are no longer required.
-
-The database scheme used by the exchange look as follows:
-
-.. image:: exchange-db.png
-
-
-------------------
-Key Storage Format
-------------------
-
-The exchange's key directory contains the two subdirectories `signkeys` and `coinkeys`.
-
-The directory `signkeys` contains signkey files, where the name is the start date of the respective key.
-
-The `coinkeys` directory additionaly contains a subdirectory for each coin type alias.  These contain coinkey files, where the name is again the start timestamp of the respective key.
diff --git a/impl-merchant.rst b/impl-merchant.rst
deleted file mode 100644
index a4b6be42..00000000
--- a/impl-merchant.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-..
-  This file is part of GNU TALER.
-  Copyright (C) 2014, 2015, 2016 INRIA
-  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/>
-
-  @author Marcello Stanisci
-  @author Florian Dold
-
-=================================
-Merchant Reference Implementation
-=================================
-
-.. _merchant-arch:
-
------------------------
-Architectural Overview
------------------------
-
-NOTE: this paragraph mirrors the (initial) one in the merchant's API
-section.
-
-The merchant reference implementationis divided into two independent
-compontents, the `frontend` and the `backend`.
-
-The `frontend` is the existing shopping portal of the merchant.
-The architecture tries to minimize the amount of modifications necessary
-to the `frontend` as well as the trust that needs to be placed into the
-`frontend` logic.  Taler requires the frontend to facilitate two
-JSON-based interactions between the wallet and the `backend`, and
-one of those is trivial.
-
-The `backend` is a standalone C application intended to implement all
-the cryptographic routines required to interact with the Taler wallet
-and a Taler exchange.
diff --git a/index.rst b/index.rst
index 23ac97a2..41e7bc05 100644
--- a/index.rst
+++ b/index.rst
@@ -38,11 +38,8 @@ any other banking institution.
 The system will be based on free software and open protocols.
 
 In this document, we describe the REST-based APIs between the various
-components, as well as the internal architecture of key components.
-However, you do not have to re-implement these APIs to use Taler: the
-project includes free software reference implementations of the
-various components.
-
+components, internal architecture of key components, and how to get them
+installed.
 
 -----------------
 Operator Handbook
@@ -55,8 +52,9 @@ It focuses on how to install, configure and run the required software.
   :maxdepth: 2
 
   global_licensing
-  impl-exchange
-  impl-merchant
+  configuration-basics
+  operate-exchange
+  operate-merchant
   versioning
 
 ------------------------
@@ -106,7 +104,8 @@ core components of the Taler reference implementation.
   :maxdepth: 2
 
   dev-wallet-wx
-
+  dev-exchange
+  dev-merchant
 
 ------------------
 Indices and tables
diff --git a/integration-bank.rst b/integration-bank.rst
index b8e24937..1dc2ec8d 100644
--- a/integration-bank.rst
+++ b/integration-bank.rst
@@ -26,11 +26,11 @@ As a result of the reserve creation request, the following steps will happen in
  2. Upon confirmation, the wallet fetches the desired amount from the user-filled form and
     prompts the user for the *exchange base URL*. Then ask the user to confirm creating the
     reserve.
- 2. The wallet will create a key pair for the reserve.
- 3. The wallet will request the CAPTCHA page to the bank. In that request's parameters it
+ 3. The wallet will create a key pair for the reserve.
+ 4. The wallet will request the CAPTCHA page to the bank. In that request's parameters it
     communicates the desired amount, the reserve's public key and the exchange base URL to the
     bank
- 4. Upon successful resolution of the CAPTCHA by the user, the bank initiates the reserve
+ 5. Upon successful resolution of the CAPTCHA by the user, the bank initiates the reserve
     creation according to the gotten parameters. Together with `200 OK` status code sent back
     to the wallet, it gets also a `ReserveCreated`_ object.
 
diff --git a/integration-general.rst b/integration-general.rst
index fc8f0d68..308ecf5a 100644
--- a/integration-general.rst
+++ b/integration-general.rst
@@ -1,7 +1,15 @@
+.. _integration-general:
+
 ================================
 Taler Wallet Website Integration
 ================================
 
+.. note::
+ The wallet-Websites communication is switching to a new policy which
+ is NOT based on DOM events, therefore obsoleting this page. To be soon
+ documented.
+
+
 Websites (such as banks and online shops) can communicate with
 the Taler wallet by a standardized protocol.
 
diff --git a/integration-merchant.rst b/integration-merchant.rst
index d8be8037..9ac4ece3 100644
--- a/integration-merchant.rst
+++ b/integration-merchant.rst
@@ -1,6 +1,10 @@
 ..
   This file is part of GNU TALER.
 
+..
+  Note that this page is more a protocol-explaination than a guide that teaches
+  merchants how to work with Taler wallets
+
   Copyright (C) 2014, 2015, 2016 INRIA
 
   TALER is free software; you can redistribute it and/or modify it under the
@@ -34,6 +38,10 @@ By design, the Taler payment process ensures the following three properties:
    be able to replay the payment and again retrieve the online resource he paid for.
    In case where a physical item was bought, this online resource is the merchant's
    order status page, which may contain tracking information for the customer.
+   Note that by `replay the payment` we mean reusing the `same coins` used to pay for
+   the product the first time to get the `same product` the user got the first time.
+   So the replay will NOT subtract further credit from the user's total budget.
+
 3. The user must be able to *share* the link to both the page with the unpaid offer or
    the order status page. If the links are shared with another user, they should
    typically allow the other user to perform the same purchase (assuming the item
@@ -45,21 +53,32 @@ contract to the user via the wallet.  The offer URL may include support
 for payment systems other than Taler, for example by including a credit
 card form in the body.  The interaction with the wallet can be started
 over JavaScript or by returning a "402 Payment Required" status code
-with Taler-specific headers.
+with Taler-specific headers. Detailed documentation about involved headers
+is found in a dedicated article, hosted in the wallet git repository, at
+the path `articles/ui/ui.pdf`. It is merchant's choice to initiate the
+communication via JavaScript or "402 Payment Required", but they need to
+take into account that the user may have JavaScript disabled. As for the
+JavaScript tecnique of initiating a communication, please refer to the
+page :ref:`integration-general`.
 
 The merchant may have a *contract URL* which generates the contract
 in JSON format for Taler.  Alternatively, the contract may be embedded
 within the page returned by the offer URL and given to the wallet
 via JavaScript or via an HTTP header.
 
+The merchant must also provide a *pay URL* to which the wallet can
+transmit the payment, which is HTTP POSTing coins. Again, how this
+URL is make known from the merchant to the wallet, it is managed by
+the HTTP headers- or JavaScript-based protocol.
+
 The merchant must have a *fulfillment URL* which checks whether the
 customer has paid.  When the fulfillment URL is triggered the first
-time, this will not (yet) be the case.  In this case, the merchant
-generates another "402 Payment Required" status code which will trigger
-the actual payment from the wallet to the *pay URL*.  The wallet will
-then reload the fulfillment URL, and this time the merchant should
-return the online resource the customer paid for (or the shipping
-status for physical goods).
+time (which happens when the user accepts the contract), this will not
+(yet) be the case.  In this case, the merchant generates another "402
+Payment Required" status code which will trigger the actual payment from
+the wallet to the *pay URL*.  The wallet will then reload the fulfillment
+URL, and this time the merchant should return the online resource the customer
+paid for (or the shipping status for physical goods).
 
 -------
 Example
@@ -74,8 +93,8 @@ Alice's browser detects the response code and displays the contract
 for Alice.
 
 Alice then confirms that she wants to buy the movie. Her wallet
-associates her confirmation with the details of the contract.  After
-Alice confirms, the wallet redirects her to the fulfillment URL, say
+associates her confirmation with the details and a hash of the contract.
+After Alice confirms, the wallet redirects her to the fulfillment URL, say
 *https://merchant/fulfillment?x=8ru42&tid=62* that is specified in the
 contract.
 
@@ -91,8 +110,9 @@ successful, and then reload the fulfillment URL.
 
 This time (and every time in the future where Alice visits the
 fulfillment URL), she receives the movie.  If the browser has lost the
-session state, the merchant will again ask her to pay, and she will
-authenticate by replaying the payment.
+session state, the merchant will again ask her to pay (as it happened the
+very first time she visited the fulfillment URK), and she will authenticate
+by replaying the payment.
 
 If Alice decides to share the fulfillment URL with Bob and he visits
 it, his browser will not have the right session state and furthermore
@@ -100,16 +120,21 @@ his wallet will not be able to replay the payment. Instead, his wallet
 will automatically redirect Bob to the offer URL and allow him to
 purchase the movie himself.
 
-
 ---------------
 Making an offer
 ---------------
 
-The offer URL is a location where the user must pass by in order to
-get a contract.
-
-FIXME: Add more details.
+The offer URL is a location where the user must pass by in order to get a contract.
+Note that this URL is not strictly asked to initiate the interaction with the
+wallet. For example, if a Website lets first pick the item to buy and *then* the
+payment method in a second page, then we call offer URL only the first page,
+although the communication with the wallet will be initialized by the second page.
+Note that, whenever a user accepts a contract, the wallet will automatically store
+that contract's hash in an internal database. That happens for three reasons:
 
+* to have a cryptographic proof of the user's (and merchant's) activity
+* to not show again the same contract to the user when visiting the fulfillment page
+* to associate the same set of coins with this contract, in order to replay payments
 
 -------------------------------
 Fulfillment interaction details
@@ -130,16 +155,18 @@ actually having to write the full contract proposal to its database.
 This allows the merchant to delay disk (write) operations until
 customers actually pay.
 
+Once the payment process has been started, the merchant will then
+reconstruct the contract and re-hash it, sending back to the client
+a "402 Payment required" status code and some HTTP headers which will
+help the wallet to manage the payment, they are:
+
+* `X-taler-contract-hash`
+* `X-taler-pay-URL`
+* `X-taler-offer-URL`
+
+By looking at `X-taler-contract-hash`, the wallet can face two situations:
 
-FIXME: This is outdated! Describe 402 vs. JavaScript interactions
-as in paper!
+1. This hashcode is already present in the wallet's database, so the wallet can send the payment to `X-taler-pay-URL`.  During this operation, the wallet associates the data it sent to `X-taler-pay-URL` with the received hashcode, so that it can replay payments whenever it gets this hashcode again.
+2. This hashcode is unknown to the wallet, so the wallet can point the browser to `X-taler-offer-URL`, so the user will get the contract and decide to accept it or not.  This happens when the user gets the fulfillment URL from someone else.
 
-This event is listened to by the wallet which can take two decisions based on the `H_contract`
-field: if `H_contract` is known to the wallet, then the user has already accepted the contract
-for this purchase and the wallet will send a deposit permission to `pay_url`. If that is not the
-case, then the wallet will visit the `offering_url` and the user will decide whether or not to
-accept the contract. Once `pay_url` receives and approves the deposit permission, it sets the session
-state for the claimed item(s) to ``payed`` and now the wallet can point again the browser to the
-fulfillment URL and finally get the claimed item(s). It's worth noting that each deposit permission
-is associated with a contract and the wallet can reuse the same deposit permission to get the item(s)
-mentioned in the contract without spending new coins.
+FIXME: explain the JavaScript way ..
diff --git a/operate-exchange.rst b/operate-exchange.rst
new file mode 100644
index 00000000..68a600f6
--- /dev/null
+++ b/operate-exchange.rst
@@ -0,0 +1,151 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA
+  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/>
+
+  @author Christian Grothoff
+
+======================
+Operating the Exchange
+======================
+
++++++++++++++
+Configuration
++++++++++++++
+
+The following data and facilities have to be set up, in order to run an exchange:
+
+* Keying
+* Serving
+* Currency
+* Bank account
+* Coins
+* Database
+
+In this document, we assume that ``$HOME/.config/taler.conf`` is being customized.
+
+------
+Keying
+------
+
+The exchange works with three types of keys:
+
+* `master key`
+* `sign keys`
+* `denomination keys` (see section `Coins`)
+
+`master key`: in section `[exchange]`, edit the two following values:
+
+* `master_priv_file`: Path to the exchange's master private file.
+* `master_public_key`: Must specify the exchange's master public key.
+
+`sign keys`: the following two options under `[exchange_keys]` section control `sign keys`:
+
+* `signkey_duration`: How long should one signing key be used?
+* `lookahead_sign`: How much time we want to cover with our `signkeys`? Note that if `signkey_duration` is bigger than `lookahead_sign`, `taler-exchange-keyup` will generate a quantity of `signkeys` which is sufficient to cover all the gap. See :ref:`keys-duration`.
+
+-------
+Serving
+-------
+
+The exchange can serve HTTP over both TCP and UNIX domain socket. It needs this
+configuration *twice*, because it opens one connection for ordinary REST calls, and one
+for "/admin" and "/test" REST calls, because the operator may want to restrict the access to "/admin".
+
+The following values are to be configured under the section `[exchange]` and `[exchange-admin]`:
+
+* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket
+* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`.
+* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix`
+* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----).
+
+The exchange can be started with the `-D` option to disable the administrative
+functions entirely.  It is recommended that the administrative API is only
+accessible via a properly protected UNIX domain socket.
+
+--------
+Currency
+--------
+
+The exchange supports only one currency. This data is set under the respective
+option `currency` in section `[taler]`.
+
+------------
+Bank account
+------------
+
+The command line tool `taler-exchange-wire` is used to create a file with
+the JSON response to /wire requests using the exchange's offline
+master key.  The resulting file's path needs to be added to the configuration
+under the respective option for the wire transfer method, i.e.
+`sepa_response_file` in section `[exchange-wire-incoming-sepa]` when the
+`wireformat` option in the configuration file allows `sepa` transactions. For example,
+the utility may be invoked as follows::
+  
+  taler-exchange-wire -j '{"name": "The Exchange", "account_number": 10, "bank_uri": "https://bank.demo.taler.net", "type": "test"}' -t test -o exchange.json
+
+Note that the value given to option `-t` must match the value in the JSON's field ``"type"``. `exchange.json` will be the same JSON given to ``-j`` plus the field
+``"sig"``, which holds the signature of the JSON given in option ``-j`` made with exchange's master key. Finally, if `taler-exchange-wire` will not find any master
+key at the location mentioned in `master_priv_file`, it will automatically generate (and use) one.
+
+--------
+Database
+--------
+
+The option `db` under section `[exchange]` gets the DB backend's name the exchange
+is going to use. So far, only `db = postgres` is supported. After choosing the backend,
+it is mandatory to supply the connection string (namely, the database name). This is
+possible in two ways:
+
+* via an environment variable: `TALER_EXCHANGEDB_POSTGRES_CONFIG`.
+* via configuration option `db_conn_str`, under section `[exchangedb-BACKEND]`. For example, the demo exchange is configured as follows:
+
+.. code-block:: text
+
+  [exchange]
+  ...
+  db = postgres
+  ...
+
+  [exchangedb-postgres]
+  db_conn_str = postgres:///talerdemo
+
+-------------------------
+Coins (denomination keys)
+-------------------------
+
+Sections specifying denomination (coin) information start with "coin\_".  By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", i.e. `[coin_eur_ct_10]` for a 10 cent piece.  However, only the "coin\_" prefix is mandatory.  Each "coin\_"-section must then have the following options:
+
+* `value`: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION.  For example, a 10 cent piece is "EUR:0.10".
+* `duration_withdraw`: How long can a coin of this type be withdrawn?  This limits the losses incurred by the exchange when a denomination key is compromised.
+* `duration_overlap`: What is the overlap of the withdrawal timespan for this coin type?
+* `duration_spend`: How long is a coin of the given type valid?  Smaller values result in lower storage costs for the exchange.
+* `fee_withdraw`: What does it cost to withdraw this coin? Specified using the same format as `value`.
+* `fee_deposit`: What does it cost to deposit this coin? Specified using the same format as `value`.
+* `fee_refresh`: What does it cost to refresh this coin? Specified using the same format as `value`.
+* `rsa_keysize`: How many bits should the RSA modulus (product of the two primes) have for this type of coin.
+
+-------------
+Keys duration
+-------------
+
+Both `signkeys` and `denom keys` have a :ref:`starting date <keys-duration>`. The option `lookahead_provide`, under section `[exchange_keys]`, is such that only keys
+whose starting date is younger than `lookahead_provide` will be issued by the exchange.
+
++++++++++
+Utilities
++++++++++
+
+------------------
+Reserve management
+------------------
+
+Incoming transactions to the exchange's provider result in the creation or update of reserves, identified by their withdrawal key.
+The command line tool `taler-exchange-reservemod` allows create and add money to reserves in the exchange's database.
diff --git a/operate-merchant.rst b/operate-merchant.rst
new file mode 100644
index 00000000..418534be
--- /dev/null
+++ b/operate-merchant.rst
@@ -0,0 +1,185 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014, 2015, 2016 INRIA
+  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/>
+
+  @author Marcello Stanisci
+  @author Florian Dold
+
+==============================
+Operating the Merchant Backend
+==============================
+
++++++++++++++
+Configuration
++++++++++++++
+
+The following data and facilities have to be set up, in order to run a merchant backend:
+
+* Serving
+* Currency
+* Database
+* Exchanges
+* Keying
+* Bank account
+* Instances
+
+In this document, we assume that ``$HOME/.config/taler.conf`` is being customized.
+
+-------
+Serving
+-------
+
+The merchant backend can serve HTTP over both TCP and UNIX domain socket.
+
+The following values are to be configured under the section `[merchant]`:
+
+* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket
+* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`.
+* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix`
+* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----).
+
+--------
+Currency
+--------
+
+The merchant backend supports only one currency. This data is set under the respective
+option `currency` in section `[taler]`.
+
+--------
+Database
+--------
+
+The option `db` under section `[merchant]` gets the DB backend's name the merchant
+is going to use. So far, only `db = postgres` is supported. After choosing the backend,
+it is mandatory to supply the connection string (namely, the database name). This is
+possible in two ways:
+
+* via an environment variable: `TALER_MERCHANTDB_POSTGRES_CONFIG`.
+* via configuration option `config`, under section `[merchantdb-BACKEND]`. For example, the demo merchant is configured as follows:
+
+.. code-block:: text
+
+  [merchant]
+  ...
+  db = postgres
+  ...
+
+  [merchantdb-postgres]
+  config = postgres:///talerdemo
+
+---------
+Exchanges
+---------
+
+The options `uri` and `master_key`, under section `[merchant-exchange-MYEXCHANGE]`, let
+the merchant add the exchange `MYEXCHANGE` among the exchanges the merchant wants to work
+with. `MYEXCHAGE` is just a mnemonic name chosen by the merchant (which is not currently used
+in any computation), and the merchant can add as many exchanges as it is needed.
+`uri` is the exchange's base URL. Please note that a valid `uri` complies with the following
+pattern::
+
+   schema://hostname/
+
+`master_key` is the base32 encoding of the exchange's master key (see :ref:`/keys <keys>`).
+In our demo, we use the following configuration::
+
+   [merchant-exchange-test]
+   URI = https://exchange.test.taler.net/
+   MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
+
+------
+Keying
+------
+
+The option `keyfile` under section `[merchant-instance-default]` is the path to the
+merchant's :ref:`default instance <instances-lab>` private key. This key is needed to
+sign certificates and other messages sent to wallets and exchanges.
+To generate a 100% compatible key, it is recommended to use the ``gnunet-ecc`` tool.
+
+------------
+Bank account
+------------
+
+This piece of information is used when the merchant redeems coins to the exchange.
+That way, the exchange will know to which bank account it has to transfer real money.
+The merchant must specify which system it wants receive wire transfers with. We support
+a `test` wire format so far, and supporting `SEPA` is among our priorities.
+
+The wire format is specified in the option `wireformat` under section `[merchant]`,
+and the wire details are given via a JSON file, whose path must be indicated in the
+option `X_response_file` under section `[default-wireformat]`, where `X` matches
+the chosen wireformat. In our demo, we have::
+
+  [merchant]
+  ..
+  wireformat = test
+  ..
+
+  [default-wireforma]
+  test_response_file = ${TALER_CONFIG_HOME}/merchant/wire/test.json
+
+The file `test.json` obeys to the following specification
+
+.. code-block:: tsref
+
+  interface WireDetails {
+    // matches wireformat
+    type: string; 
+
+    // base URL of the merchant's bank
+    bank_uri: string;
+
+    // merchant's signature (unused, can be any value)
+    signature: string; 
+
+    // merchant's account number at the bank
+    account_number: Integer;
+    
+    // the salt (unused, can be any value)
+    salt: any;
+  }
+
+As an example, `test.json` used in our demo is shown below::
+
+  {
+  "type": "test",
+  "bank_uri": "https://bank.test.taler.net/",
+  "sig": "MERCHANTSIGNATURE",
+  "account_number": 6,
+  "salt": "SALT"
+  }
+
+
+
+.. _instances-lab:
+
+---------
+Instances
+---------
+
+In Taler, multiple shops can rely on the same :ref:`merchant backend <merchant-arch>`.
+In Taler terminology, each of those shops is called `(merchant) instance`. Any instance
+is defined by its private key and its wire details. In order to add the instance `X` to
+the merchant backend, we have to add the sections `[merchant-instance-X]` and `[X-wireformat]`,
+and edit them as we did for the `default` instance. For example, in our demo we add the
+instance `Tor` as follows::
+  
+  [merchant-instance-Tor]
+  KEYFILE = ${TALER_DATA_HOME}/merchant/tor.priv
+  
+  ..
+
+  [Tor-wireformat]
+  TEST_RESPONSE_FILE = ${TALER_CONFIG_HOME}/merchant/wire/tor.json
+
+Please note that :ref:`Taler messagging<merchant-api>` is designed so that the merchant
+frontend can instruct the backend on which instance has to be used in the various operations.
+This information is optional, and if not given, the backend will act as the `default` instance.