polishing merchant's documetation

1 files changed, 33 insertions, 68 deletions

diff --git a/api-merchant.rst b/api-merchant.rst
index 749681d3..a15e0b28 100644
--- a/api-merchant.rst
+++ b/api-merchant.rst
@@ -57,11 +57,13 @@ The Frontent HTTP API
   .. code-block:: tsref
 
     interface DepositPermission {
-      // the hashed :ref:`wire details <wireformats>` of this merchant. The wallet takes this value as-is from the contract
-      // `MyStruct`_
-      H_wire: MyStruct;
+      // the hashed `wire details <wireformats>`_ of this merchant.
+      // The wallet takes this value as-is from the contract 
+      H_wire: HashCode;
 
-      // the base32 encoding of the field `h_contract` of the contract `blob <contract-blob>`. The wallet can choose whether to take this value obtained from the field `h_contract`, or regenerating one starting from the values it gets within the contract
+      // `base32`_ encoded `TALER_ContractPS`_. The wallet can choose whether
+      // to take this value obtained from the field `h_contract`,
+      // or regenerating one starting from the values it gets within the contract
       H_contract: HashCode;
 
       // a 53-bit number corresponding to the contract being agreed on
@@ -73,10 +75,11 @@ 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 :ref:`instances-lab`
+      // The merchant instance which is going to receive the final wire transfer.
+      // See `instances-lab`_
       receiver: string;
 
-      // signature by the merchant over the contract, must match signed data of purpose TALER_SIGNATURE_MERCHANT_CONTRACT
+      // Signature of `TALER_ContractPS`_
       merchant_sig: EddsaSignature;
 
       // a timestamp of this deposit permission. It equals just the contract's timestamp
@@ -107,10 +110,10 @@ The Frontent HTTP API
       // denomination key
       denom_pub: RsaPublicKey;
 
-      // exchange's signature over this coin's public key
+      // exchange's signature over this `coin's public key <eddsa-coin-pub>`_
       ub_sig: RsaSignature;
 
-      // the signature made by the coin's private key on a `struct TALER_DepositRequestPS`. See section `Signatures` on the exchange's API page.
+      // Signature of `TALER_DepositRequestPS`_
       coin_sig: EddsaSignature;
     }
 
@@ -204,7 +207,7 @@ The following API are made available by the merchant's `backend` to the merchant
   .. code-block:: tsref
 
     interface PaymentResponse {
-      // Signature of TALER_SIGNATURE_MERCHANT_PAYMENT_OK made by the merchant
+      // Signature of `TALER_PaymentResponsePS`_
       merchant_sig: EddsaSignature;
 
       // Contract's hash being signed over
@@ -322,12 +325,6 @@ The following API are made available by the merchant's `backend` to the merchant
       total_amount: Amount;
     }
 
----------
-Encodings
----------
-
-Data such as dates, binary blobs, and other useful formats, are encoded as described in :ref:`encodings-ref`.
-
 .. _contract:
 
 ------------------
@@ -345,16 +342,24 @@ that is legally non-binding:
       // The actual contract
       contract: Contract;
 
-      // The hash of the contract, encoded in base32, provided
-      // as a convenience.  All components that do not fully trust
-      // the merchant must verify this field.
+      // Contract's hash, provided as a convenience.  All components that do
+      // not fully trust the merchant must verify this field.
       H_contract: HashCode ;
 
-      // Signature over the contract made by the merchant.
-      // Must confirm to the `Signature specification`_ below.
+      // Signature over the hashcode of `contract` made by the merchant.
       merchant_sig: EddsaSignature;
     }
 
+.. note::
+  When the contract is signed by the merchant or the wallet, the
+  signature is made over the hash of the JSON text, as the contract may
+  be confidential between merchant and customer and should not be
+  exposed to the exchange.  The hashcode is generated by hashing the
+  encoding of the contract's JSON obtained by using the flags
+  ``JSON_COMPACT | JSON_PRESERVE_ORDER``, as described in the `libjansson
+  documentation
+  <https://jansson.readthedocs.org/en/2.7/apiref.html?highlight=json_dumps#c.json_dumps>`_.
+
 The `contract` must have the following structure:
 
   .. _tsref-type-Contract:
@@ -419,9 +424,8 @@ The `contract` must have the following structure:
       // Exchanges that the merchant accepts even if it does not accept any auditors that audit them.
       exchanges: Exchange[];
 
-      // Map from label to a `Location`_.
-      // The label strings must not contain a colon (`:`).
-      locations: { [label: string]: Location>;
+      // Map from label to a location
+      locations: { [label: string]: Location }; // FIXME make 'Location' clickable
     }
 
   The wallet must select a exchange that either the mechant accepts directly by listing it in the exchanges arry, or for which the merchant accepts an auditor that audits that exchange by listing it in the auditors array.
@@ -488,19 +492,22 @@ The `contract` must have the following structure:
       street_number?: string;
     }
 
-  .. code-block:: ts
+  .. _tsref-type-Auditor:
+  .. code-block:: tsref
 
     interface Auditor {
       // official name
       name: string;
 
-      auditor_pub: EddsaPublicKey
+      // Auditor's public key
+      auditor_pub: EddsaPublicKey;
 
       // Base URL of the auditor
       url: string;
     }
 
-  .. code-block:: ts
+  .. _tsref-type-Exchange:
+  .. code-block:: tsref
 
     interface Exchange {
       // the exchange's base URL
@@ -509,45 +516,3 @@ The `contract` must have the following structure:
       // master public key of the exchange
       master_pub: EddsaPublicKey;
     }
-
-
-.. _`Signature specification`:
-
-When the contract is signed by the merchant or the wallet, the
-signature is made over the hash of the JSON text, as the contract may
-be confidential between merchant and customer and should not be
-exposed to the exchange.  The hashcode is generated by hashing the
-encoding of the contract's JSON obtained by using the flags
-``JSON_COMPACT | JSON_PRESERVE_ORDER``, as described in the `libjansson
-documentation
-<https://jansson.readthedocs.org/en/2.7/apiref.html?highlight=json_dumps#c.json_dumps>`_.
-The following structure is a container for the signature. The purpose
-should be set to ``TALER_SIGNATURE_MERCHANT_CONTRACT``.
-
-.. _contract-blob:
-.. code-block:: c
-
-   struct MERCHANT_Contract
-   {
-     struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
-     /**
-      * Transaction ID must match the one in the JSON contract, here given
-      * in big endian.
-      */
-     uint64_t transaction_id;
-
-     /**
-      * Total amount to be paid for the contract, must match JSON "amount".
-      */
-     struct TALER_AmountNBO total_amount;
-
-     /**
-      * Total amount to be paid for the contract, must match JSON "max_fee".
-      */
-     struct TALER_AmountNBO max_fee;
-
-     /**
-      * Hash of the overall JSON contract.
-      */
-     struct GNUNET_HashCode h_contract;
-   }