removing payment protocol steps from

blog's example page, as they are already described elsewhere

1 files changed, 12 insertions, 108 deletions

diff --git a/example-essay-store.rst b/example-essay-store.rst
index f3439cc8..a780cdc2 100644
--- a/example-essay-store.rst
+++ b/example-essay-store.rst
@@ -16,123 +16,27 @@
 Example: Essay Store
 ==================================
 
-..
-  The main page of the essay store shows links to essays of the form `/essay?name=:name`.
-  
-  The `/essay` URL takes the following query parameters:
-   * `name`: mandatory, name of the essay
-   * `tid`: optional, transaction ID generated by the merchant for the
-     contract that was used to purchase an instance of the article
-   * `timestamp`, optional, timestamp for the contract that was used to purchase
-     the essay with the given `tid`.
-  
-  These are the steps for showing `/essay`.  If the wallet is not present in
-  steps 2 and 3, the user agent is redirected to a mock credit card
-  payment page.
-  
-  1. The server checks the status of the the essay with the name `name` in the server-side
-     session state
-  
-    * If the essay is marked as payed, display the essay.
-    * Otherwise proceed with step 2
-  
-  2. The server checks if the `tid` and `timestamp` query parameters are present
-  
-    * If `tid` and `timestamp` are present, restore the contract for the essay
-      (using `tid` as transaction id in the contract, `timestamp` as timestamp
-      and `timestamp+REFUND_DELTA` as refund deadline) and emit the
-      `taler-execute-contract` DOM event in the user agent.
-    * Otherwise proceed with step 3
-  
-  3. The server generates a new contract and emits the `taler-confirm-contract` DOM event in the user agent,
-     with the essay name as repurchase correlation identifier and `/essay?name=:name?tid=:tid` as fulfillment url.
-  
-  
-  In step 2, the `taler-execute-contract` event has the following parameters:
-  
-  * `H_contract`: hash of the contract that was restored
-  * `payment_url`: The internal URL `/pay?H_contract=...` of the essay store,
-    will set the server-side session state for the article associated with the
-    contract hash on successful coin deposit.  The contract hash is associated
-    with the article name in the server-side session state when the contract is restored.
-  * `offer_url`: Link to a teaser page (`/teaser?name=...`), which also contains a link to the article
-    page, without the `tid` parameter.
-  
-  
-  Note that we assume that all essays cost the same (otherwise the amount would have to be included in
-  the restoration information in the /essay fulfillment URL).  The refund deadline is computed
-  by adding the merchant-specific constant `REFUND_DELTA` to the contract's timestamp.
-
-..
-  Describing implementation of the above scenario
-
---------------
-Before reading
---------------
 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`,
-are assumed to be known.  Refer to :ref:`contract`, :ref:`payprot` and :ref:`deposit` in order to get
+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.
 
 This section describes how the demonstrator essay store interacts with the Taler system.  As for Taler's
 terminology, the demonstrator essay store is an example of `frontend`.
-This demonstrator's code lies in `examples/blog` of `git://taler.net/merchant/examples/blog`
+This demonstrator's code is hosted at `git://taler.net/merchant-frontends/talerfrontends/blog/` and is
+implemented in Python.
 
 The essay store, available at https://blog.demo.taler.net, is such that its homepage
-is a list of buyable articles and each article is a reference to an `offering
-URL`.  In particular, this offering URL has the following format:
-
-  `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId`
-
-It is worth noting that in our implementation the `offering` and the `fulfillment` URLs
-differ only respect to the parameters given to the path `/essay_fulfillment.php`, therefore
-are served by the same script.  In detail, the offering URL becomes a fulfillment URL whenever
-the user adds the parameters needed to reconstruct the contract, which are `tid` (transaction id)
-and `timestamp`.  For the sake of completeness,
-
-
-  `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId&tid=3489&timestamp=8374738`
-
-would be a fulfillment URL.
-
-Once the user visits the offering URL by clicking on some article's title, the merchant
-
-1. checks if the state associated to this article corresponds to ``payed``.  If this is the
-   case, just return to the user the article.
-
-2. figures out whether the user is visiting a offering or a fulfillment URL
-
-3. if it is a offering URL being visited then return a certain page offering the contract via
-   `taler-confirm-contract` event (FIXME link); if it is a fulfillment URL, then return the same
-   page which offers a `taler-execute-contract` event (FIXME link) instead. In both cases, the page
-   returned to the browser can detect if there is no wallet active, and will abort the payment in
-   that case.
-
-4. the wallet now points the user's browser to the fulfillment URL associated with this purchase
-   (the fulfillment URL is indicated in the contract)
-
-5. the website detects that the user is visiting now a fulfillment URL and creates an entry in
-   the session state about `articleId`. FIXME To be finished.
-
-6. the wallet POSTs the deposit permission to `pay_url`, which is
-
-   `https://blog.demo.taler.net/essay_pay.php?article=articleId`
-   
-   This step is responsible for setting the state for `articleId` as payed;  to that end it uses
-   `articleId` as the key to get `H_contract` from the state and checks if `H_contract` equals
-   the contract's hash contained in the deposit permission.  If they are equal, then the deposit
-   permission is forwarded to the backend.  If the backend return a HTTP status 200, then `essay_pay.php`
-   sets the state for `articleId` as payed and notify the wallet about the payment's outcome.
-   If the backend reports any problem, `essay_pay.php` will just forward the data gotten from the
-   backend to the wallet, which will be in charge of managing the error.
+is a list of titles from buyable articles and each title links to an `offering URL`. 
+In particular, the offering URL has the following format:
 
-7. the wallet visit the fulfillment URL, but now the state for `articleId` is set to payed, so the
-   script will just show the wanted article.
+  `https://blog.demo.taler.net/essay/article_title`
 
-  `https://blog.demo.taler.net/essay_fulfillment.php?article=articleId&tid=3489&timestamp=8374738`
+As for the fulfillment URL, it matches the initial part of an offering URL, but contains also
+those parameters needed to reconstruct the contract, which are `tid` (transaction id) and `timestamp`.
+So a fulfillment URL looks like:
 
-----------------------
-IIG by fulfillment URL
-----------------------
+  `https://blog.demo.taler.net/essay/article_title?tid=3489&timestamp=8374738`
 
-TBD
+We did not need to include any further details in the fulfillment URL because most of them
+do not change in the time, and for simplicity all the articles have the same price.