comments/changes for ttn

1 files changed, 83 insertions, 21 deletions

diff --git a/taler-mcig.rst b/taler-mcig.rst
index 5c2115c4..c8c3d82a 100644
--- a/taler-mcig.rst
+++ b/taler-mcig.rst
@@ -67,32 +67,38 @@ This guide assumes you and the customer agree to use the Taler payment system.
 At this point, you generate a *contract* and present it to the customer for
 authorization.
 The contract includes:
-- some kind of identification for the selected product(s);
-- an itemized price list;
-- applicable taxes and fees;
-- (optional) information on how you deal with *forgettable customer details*;
-- (optional) the duration of the lock on the product(s);
+- the total amount due;
+- a short summary;
+- a *fulfillment URI*;
+- the *duration* of the offer
+  (how long the customer has to authorize before timeout);
+- (optional) an itemized product list, with
+  - (optional) some kind of identification for the selected product(s);
+- (optional) applicable taxes and fee limits;
+- (optional) an order ID (if omitted, the backend will auto-generate one);
+- (optional) information which details are *forgettable*;
 - (optional) a *claim token* that the customer can use later;
 - (optional) information on the *refund deadline*;
 - (optional) information on the the *auto-refund period* (how long does
-  the wallet check for refunds without user prompting for it);
-- the total amount due;
-- the *duration* of the offer
-  (how long the customer has to authorize before timeout).
+  the wallet check for refunds without user prompting for it).
 
 If the customer does nothing (timeout / the contract expires),
-you *unlock* the product(s) and end the transaction.
+the merchant backend automatically *unlocks* the product(s),
+allowing other consumers to add more items of the limited stock
+to their orders.
 
-On the other hand, if the customer authorizes the contract,
+On the other hand, if the customer authorizes payment,
 the customer's wallet transfers payment coins to you,
-and you display to the customer the *fulfillment URI*.
+previously locked products are removed from inventory,
+and (if possible) the wallet redirects the customer
+to the *fulfillment URI*.
 
 The individual product selection / purchase experience is like the shopping
 cart experience with the following exceptions:
 - there is no shopping cart -- the order is solely the selected product;
 - Taler payment method is assumed;
 - customer selection moves directly to checkout;
-- there is *repurchase detection / prevention* (for digital products).
+- *repurchase detection / prevention* can be useful (for digital products).
 
 
 Taler Details
@@ -119,24 +125,33 @@ in the next section.
   the product by using the same API call, specifying a ``quantity`` of 0 (zero).
   (Products are also unlocked automatically on timeout / contract expiration.)
 
+  Before you can lock products, you need to manage the inventory, creating
+  an entry for the product (assigning a $PRODUCT_ID) and configure the
+  available stock. This can be done using the
+  Taler merchant backoffice Web interface.
+
+  .. note::
+
+     Once we have documentation for that web interface, we should link to it here.
+
 **taxes**
   The default taxes for each product is part of the product ``price``
   maintained by the backend.
-  This is set when the product is added to the inventory,
+  Taxes can be set when the product is added to the inventory,
   prior to any customer purchase experience
   (see :http:post:`[/instances/$INSTANCE]/private/products`,
   :http:get:`[/instnaces/$INSTANCE]/private/products`,
-  and :http:get:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID`).
-
-  FIXME: Front-end override?
+  and :http:get:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID`)
+  or specified explicitly by the frontend when adding
+  products products to an order that are not managed by the backend inventory.
 
 **fees**
   The Taler protocol charges a *deposit fee* (see step 5, above),
   which you may choose to pay or to pass on to the customer.
-  This can be configured to a maximum amount, per customer.
+  This can be configured to a maximum amount, per order.
 
   You can set ``default_max_deposit_fee`` in :http:post:`/private/instances`,
-  and ``max_fee`` in the contract.
+  or override the default by setting and ``max_fee`` when creating an order.
 
   There is also the *wire fee* (see step 6, above),
   which you may choose to pay or to pass on to the customer.
@@ -158,12 +173,13 @@ in the next section.
 **forgettable customer details**
   Although Taler allows the customer to remain anonymous, you may need to
   collect customer details (e.g. for shipping).
-  Taler has support for forgetting these details, to comply with GDPR
+  Taler has support for forgetting such details, to comply with GDPR
   (for example).
   This can occur even in the face of refunds (see below).
 
   To forget a set of details, first the details that are to be forgotten
-  must be marked (FIXME: How?, When?).
+  must be marked by including the names of the respective fields
+  in a special field " (FIXME: How?, When? => see: https://bugs.gnunet.org/view.php?id=6365).
   Then, you can use:
   :http:patch:`[/instances/$INSTANCE]/private/orders/$ORDER_ID/forget`
   to forget those details.
@@ -172,10 +188,25 @@ in the next section.
   The claim token is a sort of handle on the order and its payment.
   With it, the customer can access the fulfillment URI from a different
   device than the one where the wallet is installed.
+  FIXME: that is not the point. The point is that even if the
+  $ORDER_ID can be guessed, the claim token cannot. Thus, a
+  merchant can prevent a third party from claiming an order
+  (by guessing the order ID). Imagine selling concert tickets,
+  and your order IDs are 1,2,3,4,5,. I could try to hijack other
+  visitor's orders (before they have a chance to claim them),
+  using a claim token prevents this.
 
   By default, Taler creates a claim token for each order.
   To disable this, you can specify ``create_token`` to be ``False``
   in :http:post:`[/instances/$INSTANCE]/private/orders`.
+  => needs guideance as to when to do this, i.e. when
+     there is no worry about people 'stealing' orders
+     compiled by others, either because the order ID is
+     high-entropy OR [[because there is an infinite supply
+     and we are not concerned about order-theft attacks
+     (say by a competitor trying to prevent legitimate
+      customers from claiming their orders) AND want the
+     QR code to get smaller / scan more easily.]]
 
 **refund deadline**
   The refund deadline specifies the time after which you will prohibit
@@ -197,6 +228,14 @@ in the next section.
   FIXME: Is this the same as the refund deadline?
 
   FIXME: API call?
+  This is useful if it is impossible to notify the customer
+  about a refund. Example is the Snack machine, where a failure
+  to dispense a product triggers a refund, but the snack machine
+  has no good way to tell the shopper that it has issued a refund.
+  So here, the wallet will _watch_ for say 5 minutes for an auto-refund,
+  which is automatically issued by the snack machine (if the optical
+  barrier detects that it could not dispense the product) and appears in the
+  wallet without the buyer needing to take any action.
 
 **repurchase detection / prevention**
   Taler can detect a repurchase attempt and prevent it from going through.
@@ -206,6 +245,10 @@ in the next section.
 
   This feature is automatic in the protocol;
   you do not need to do anything to enable it.
+  EH, I think you must ensure that you use the
+  same fulfillment URI for the same product for this to work,
+  and IIRC you must similarly NOT (re)use the same fulfillment
+  URL for different products.
 
 **fulfillment URI**
   This may be the actual product (digital goods),
@@ -216,6 +259,9 @@ in the next section.
 
   The fulfillment URI is normally included in the contract.
   You specify it in :http:post:`[/instances/$INSTANCE]/private/orders`.
+  NOTE: explain hack to have the backend include the order ID in
+  the fulfillment URI somewhere (useful if the backend auto-generates
+  an order ID).
 
 
 Sample Interaction Traces
@@ -235,6 +281,17 @@ Pre-Sales Configuration
 In the pre-sales configuration step, you set up the *default instance*,
 and add products to the inventory.
 
+NOTE: not sure we want to ultimately document this HERE. Most merchants
+should do _this_ part via the Merchant Web interface that Sebastian is
+building right now, and for that we want a separate guide that explains
+the API (as you do here), and the Web interface.  In this document,
+we should focus on how the merchant integrates the (Web)front-end with the
+backend, not how the backend itself is configured.
+(This also applies to the other instance setup parts you described
+above => refer to other guide, but of course specify how we can
+override defaults from instance setup per-order.)
+
+
 M: :http:post:`/private/instances`
 
 .. code-block:: javascript
@@ -259,6 +316,7 @@ M: :http:post:`/private/instances`
    // (backend returns 204 No content)
 
    // FIXME: Does InstanceAuthConfigurationMessage require re-configuration?
+   // => Don't understand question, note that API changed here recently.
 
 The fictitious store, Pretty Pianos, has only two products:
 - pianos (physical good);
@@ -280,6 +338,10 @@ M: :http:post:`/instances/default/private/products`
    }
    // (backend returns 204 No content)
 
+   // FIXME: also add product preview image, and
+   // maybe use that as a good example for a
+   // forgettable detail
+
 M: :http:post:`/instances/default/private/products`
 
 .. code-block:: javascript