Restructuring

4 files changed, 126 insertions, 225 deletions

diff --git a/api-merchant.rst b/api-merchant.rst
index 752b167f..c61a6df7 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -1,12 +1,13 @@
-================
-The Merchant API
-================
+=====================
+The Merchant HTTP API
+=====================
 
-This Merchant API defines the
-interactions between a browser-based wallet and an HTTP-based RESTful merchant.
-The protocol allows the customer and the merchant to agree upon a
-contract and for the customer to spend coins according to the contract
-proposed by the merchant.
+The merchant API defines 
+
+This Merchant API defines the interactions between a browser-based wallet and
+an HTTP-based RESTful merchant.  The protocol allows the customer and the
+merchant to agree upon a contract and for the customer to spend coins according
+to the contract proposed by the merchant.
 
 It is assumed that the browser has a secure and possibly
 customer-anonymizing channel to the merchant, typically by using the
@@ -23,28 +24,9 @@ is expected to check that the time of his machine is approximately
 correct.
 
 
------------------------
-Architecture's Overview
------------------------
-
-In our settlement, the "merchant" is divided in 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 mint.
-
-
-+++++++++++++++++++++++++++++
+-----------------------------
 Wallet-Frontend communication
-+++++++++++++++++++++++++++++
+-----------------------------
 
 Taler's wallet is designed to notify the user when a certain webpage
 is offering Taler as a payment option. It does so by simply changing the color of
@@ -87,9 +69,9 @@ A precise specification and sample code for implementing the signalling
 is provided in the dedicated :ref:`section <message-passing-ref>`.
 
 
-++++++++++++++++++++++++++++++
+------------------------------
 Frontend-Backend communication
-++++++++++++++++++++++++++++++
+------------------------------
 
 To create a contract, the `frontend` needs to generate the body of a
 `contract` in JSON format.  This `proposition` is then signed by the
@@ -106,16 +88,16 @@ responsible for generating the fullfillment page.
 The contract format is specified in the `contract`_ section.
 
 
-+++++++++
+---------
 Encodings
-+++++++++
+---------
 
 Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`.
 
 .. _contract:
 
 Contract
---------
+^^^^^^^^
 
 A `contract` is a JSON object having the following structure, which is returned as a
 successful response to the following two calls:
@@ -222,9 +204,9 @@ Wallet-Frontend
 
 .. _message-passing-ref:
 
-+++++++++++++++++++
+-------------------
 Messagging protocol
-+++++++++++++++++++
+-------------------
 
 In order to reach mutual acknowledgement, and to avoid signaling loops,
 we define two interactions.  One is initiated by the HTML page inquiring
@@ -427,58 +409,4 @@ cookies to identify the shopping session.
 
   The error codes and data sent to the wallet are a mere copy of those gotten from the mint when attempting to pay. The section about :ref:`deposit <deposit>` explains them in detail.
 
-----------------
-Frontend-Backend
-----------------
-
-+++++++++++++++
-The RESTful API
-+++++++++++++++
-
-The following API are made available by the merchant's `backend` to the merchant's `frontend`.
-
-.. http:post:: /contract
-
-  Ask the backend to add some missing (mostly related to cryptography) information to the contract.
-
-  :reqheader Content-Type: application/json
-
-  The `proposition` that is to be sent from the frontend is a `contract` object without the fields
-
-  * `merchant_pub`
-  * `mints`
-  * `H_wire`
-
-  The `backend` then completes this information based on its configuration.
-
-  **Success Response**
-
-  :status 200 OK: The backend has successfully created the contract.
-  :resheader Content-Type: application/json
-
-  The `frontend` should pass this response verbatim to the wallet.
-
-  **Failure Responses: Bad contract**
-
-  :status 400 Bad Request: Request not understood. The JSON was invalid. Possibly due to some error in formatting the JSON by the `frontend`.
-
-.. http:post:: /pay
-
-  Asks the `backend` to execute the transaction with the mint and deposit the coins.
-
-  :reqheader Content-Type: application/json
-
-  The `frontend` passes the :ref:`deposit permission <deposit-permission>` received from the wallet, by adding the fields `max_fee`, `amount` (see :ref:`contract`) and optionally adding a field named `edate`, indicating a deadline by which he would expect to receive the bank transfer for this deal
-
-  **Success Response: OK**
-
-  :status 200 OK: The mint accepted all of the coins. The `frontend` should now fullfill the contract.  This response has no meaningful body, the frontend needs to generate the fullfillment page.
-
-  **Failure Responses: Bad mint**
-
-  :status 400 Precondition failed: The given mint is not acceptable for this merchant, as it is not in the list of accepted mints and not audited by an approved auditor.
-
-
-  **Failure Responses: Mint trouble**
 
-  The `backend` will return verbatim the error codes received from the mint's :ref:`deposit <deposit>` API.  If the wallet made a mistake, like by double-spending for example, the `frontend` should pass the reply verbatim to the browser/wallet. This should be the expected case, as the `frontend` cannot really make mistakes; the only reasonable exception is if the `backend` is unavailable, in which case the customer might appreciate some reassurance that the merchant is working on getting his systems back online.
diff --git a/banks.rst b/banks.rst
deleted file mode 100644
index c6565261..00000000
--- a/banks.rst
+++ /dev/null
@@ -1,131 +0,0 @@
-===================================
-Interaction with banks Web portals
-===================================
-
-This section describes the interactions that should occur between
-a wallet and a bank which chooses to adapt its Web portal to interact
-with the Taler wallet. This interaction is supposed to occur when
-the user is sending a SEPA transfer to some mint (i.e. he is creating
-a new reserve).
-
-Through this interaction, the wallet can generate a new reserve's public
-key and insert it into the 'subject' field of the transfer without manual
-copy&paste. Secondly, the wallet is then able to fetch the amount to be
-tranferred to the mint directly from the Web form, in order to poll the mint
-to check if the desired amount has been transferred.
-
-----------------------
-Mutual acknowledgement
-----------------------
-
-The mutual acknowledgement between a wallet and a bank portal occurs when
-the user is on the page which hosts the SEPA form, and is realized by the
-mean of JavaScript signals issued on the `body` HTML element.
-
-When the bank wants to notify to a wallet, it sends the following event:
-
-  .. js:data:: taler-wire-probe
-
-This event must be sent from a callback for the `onload` event of the
-`body` element, otherwise the extension would have not time to
-register a listener for this event.  It also needs to be sent when
-the Taler extension is dynamically loaded, like when the user activates
-the extension while he is on the SEPA form page.  This is done by
-listening for the
-
-  .. js:data:: taler-load
-
-event.  If the Taler extension is present, it will respond with a
-
-  .. js:data:: taler-wallet-present
-
-event.  The handler should then activate its mechanism to trigger the generation
-of a new reserve key in the wallet, for example by updating the DOM to enable a
-dedicated button.
-
-If the Taler extension is unloaded while the user is visiting a SEPA form page,
-the page should listen for a
-
-  .. js:data:: taler-unload
-
-event, in order to hide the previously enabled button.
-
--------------------------
-How to trigger the wallet
--------------------------
-
-This interaction will make the wallet generate a new reserve public key,
-as well as allowing the user to choose his wanted mint. Finally, the wallet
-will directly paste this information inside the SEPA form and submit it.
-Lastly, it allows the wallet to fetch the desired amount to be transferred
-to the mint from the SEPA form. Typically, this trigger is initiated by the
-user pushing a button while he is on the page which hosts the SEPA Web form.
-
-The wallet listens to a 
-
-  .. js:data:: taler-create-reserve
-
-event, through which it expects to receive the following object:
-
-.. sourcecode:: javascript
-
-  {form_id: sepa-form-id,
-   input_amount: input-amount-id,
-   input_pub: input-pub-id,
-   mint_rcv: receiving-money-mint}
-
-`input_amount` is the `id` attribute of the HTML `input` element which
-hosts the amount to wire to the desired mint. Please note that the wallet will
-only accept amounts of the form `n[.x[y]] CUR`, where `CUR` is the ISO code
-of the specified currency. So it may be necessary for the bank's webmaster to
-preprocess this data to give it to the wallet in the right format.
-
-`input_pub` must be the `id` attribute of the `input` element within the form
-which represents this SEPA transfer's "subject".
-`form_id` must be the `id` attribute of the SEPA `form` element (needed by the wallet to
-call `submit()` on it).
-Finally, `mint_rcv` is the `id` attribute of the `input` element within the form
-from which the server side handler of this form will fetch the mint base URL to issue
-`/admin/add/incoming` on; see :ref:`add-incoming`.
-
-The following source code highlights the key steps for adding the Taler button
-to trigger the wallet on a SEPA form page:
-
-.. sourcecode:: javascript
-
-    function has_taler_wallet_callback(aEvent){
-       // This function is called if a Taler wallet is available.
-       // suppose the radio button for the Taler option has
-       // the DOM ID attribute 'taler-wallet-trigger'
-      var tbutton = document.getElementById("taler-wallet-trigger");
-      tbutton.removeAttribute("disabled");
-    };
-
-    function taler_wallet_load_callback(aEvent){
-      // let the Taler wallet know that this is a SEPA form page
-      // which supports Taler (the extension will have
-      // missed our initial 'taler-wire-probe' from onload())
-      document.body.dispatchEvent(new Event('taler-wire-probe'));
-    };
-
-    function taler_wallet_unload_callback(aEvent){
-       // suppose the button which triggers the wallet has
-       // the DOM ID attribute 'taler-wallet-trigger'
-       var tbutton = document.getElementById("taler-wallet-trigger");
-       tbutton.setAttribute("disabled", "true");
-    };
-
-.. sourcecode:: html
-
-   <body onload="function(){
-        // First, we set up the listener to be called if a wallet is present.
-        document.body.addEventListener("taler-wallet-present", has_taler_wallet_callback, false);
-        // Detect if a wallet is dynamically added (rarely needed)
-        document.body.addEventListener("taler-load", taler_wallet_load_callback, false);
-        // Detect if a wallet is dynamically removed (rarely needed)
-        document.body.addEventListener("taler-unload", taler_wallet_unload_callback, false);
-        // Finally, signal the wallet that this is a payment page.
-        document.body.dispatchEvent(new Event('taler-wire-probe'));
-      };">
-     ...
-   </body>
diff --git a/index.rst b/index.rst
index 1517cd8e..1a17a2d0 100644
--- a/index.rst
+++ b/index.rst
@@ -25,22 +25,44 @@ which is at the heart of the system.
 Operator Handbook
 -----------------
 
+The *Operator Handbook* is for people who want to run a mint or a merchant.
+It focuses on how to install, configure and run the required software.
+
 .. toctree::
   :maxdepth: 2
 
   impl-mint
 
 
-----------------------
-Protocol Specification
-----------------------
+------------------------
+Web Integration Handbook
+------------------------
+
+The *Web Integration Handbook* is for those who want to interact with Taler
+wallets on their own website.  Integrators will also have to be familiar with
+the material covered in the *Operator Handbook*.
+
+
+.. toctree::
+  :maxdepth: 2
+
+  integration-general
+  integration-bank
+  integration-merchant
+
+
+---------------------------
+HTTP Protocol Specification
+---------------------------
+
+The *Protocol Specification* defines the HTTP-based, predominantly RESTful
+interfaces between the core components of Taler.
 
 .. toctree::
   :maxdepth: 2
 
   api-mint
   api-merchant
-  banks
 
   wallet
 
@@ -51,15 +73,24 @@ Protocol Specification
 Developer Handbook
 ------------------
 
+The *Developer Handbook* brings developers up to speed who want to hack on the
+core components of the Taler reference implementation.
+
 .. toctree::
   :maxdepth: 2
 
   dev-wallet-wx
+  dev-merchant
 
 
 ------------------
 Indices and tables
 ------------------
 
+.. toctree::
+  :maxdepth: 1
+
+  glossary
+
 * :ref:`search`
 
diff --git a/integration-bank.rst b/integration-bank.rst
new file mode 100644
index 00000000..58015cf2
--- /dev/null
+++ b/integration-bank.rst
@@ -0,0 +1,73 @@
+==============================
+Interaction with bank websites
+==============================
+
+This section describes how bank websites can interact with the
+Taler wallet.
+
+Currently the following functionality is supported:
+ * Querying for the presence of a Taler wallet.
+ * Receiving change notifications from the Taler wallet.
+ * Creating a reserve.
+
+
+For JavaScript code examples, see :ref:`communication`.
+
+--------------
+Presence Query
+--------------
+
+The bank website queries the wallet's presence by sending a ``taler-wire-probe`` event. The
+event data should be `null`.
+
+If the wallet is present and active, it will respond with a ``taler-wallet-present`` event.
+
+-------------------
+Change Notification
+-------------------
+
+While the user agent is displaying a bank website, the user might deactivate or
+re-activate the wallet.  A bank website *should* react to those events, and
+indicate to the user that they should (re-)enable if necessary.
+
+When the wallet is activated, the ``taler-wallet-load`` event is sent
+by the wallet.  When the wallet is deactivated, the ``taler-wallet-unload`` event
+is sent by the wallet.
+
+-------------------------
+Reserve Creation Request
+-------------------------
+
+The bank website can request the creation of a :term:`reserve`.  Note that the
+user will always be prompted by the wallet before a reserve is created in the
+wallet.
+
+As a result of the reserve creation request, the following steps will happen insequence:
+ 1. The wallet will prompt the user for the *mint base URL* and ask the user to
+    confirm creating the reserve.
+ 2. The wallet will create a key pair for the reserve.
+ 3. The wallet will make a request to the bank, containing
+    the reserve's public key and the mint base URL chosen by the user
+
+The bank should then take steps that will establish the reserve at the
+customer's requested mint.  This could, depending on the bank and mint, either
+be a SEPA wire transfer or some other means.
+
+In response to the reserve creation request, the Taler wallet MAY cause the
+current document location to be changed, in order to navigate to a
+wallet-internal confirmation page.
+
+The bank requests reserve creation with the ``taler-create-reserve`` event.
+The event data must be a JavaScript ``object`` with the following fields:
+
+ * ``form_id``: The ``id`` of the ``form`` HTML element that contains data for the HTTP POST request
+   that confirms reserve creation with the bank.
+ * ``input_amount``: Amount of the reserve in the format ``N.C CUR``, where ``CUR`` is the
+   currency code.
+ * ``mint_rcv``: The ``id`` of the ``input`` HTML element in the reserve creation form
+   that will contain mint base URL for the reserve
+ * ``input_pub``: The ``id`` of the ``input`` HTML element in the reserve creation form
+   that will contain the reserve's public key.
+
+Note that the bank website MUST contain an HTML form with the data required for the request and
+input fields for receiving data from the mint.