1 files changed, 49 insertions, 0 deletions
diff --git a/example-essay-store.rst b/example-essay-store.rst
new file mode 100644
index 00000000..74a25990
--- /dev/null
+++ b/example-essay-store.rst
@@ -0,0 +1,49 @@
+==================================
+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.