[taler-docs] branch master updated: added protocol changes to the merchant API

[gnunet]

This is an automated email from the git hooks/post-receive script.

oec pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 2d7ebea  added protocol changes to the merchant API
     new 400e586  Merge branch 'master' of ssh://git.taler.net/docs
2d7ebea is described below

commit 2d7ebea9c5e3474350bf7d82b41d411ef3319e49
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Sun Oct 17 13:06:53 2021 +0200

    added protocol changes to the merchant API
---
 design-documents/024-age-restriction.rst | 104 ++++++++++++++++++++++++++++---
 1 file changed, 96 insertions(+), 8 deletions(-)

diff --git a/design-documents/024-age-restriction.rst 
b/design-documents/024-age-restriction.rst
index efa140c..48a258d 100644
--- a/design-documents/024-age-restriction.rst
+++ b/design-documents/024-age-restriction.rst
@@ -103,8 +103,8 @@ TODO: Summarize the design based on the five functions 
``Commit()``,
 Özgür and Christian is published.
 
 
-Changes in the Exchange
-^^^^^^^^^^^^^^^^^^^^^^^
+Changes in the Exchange API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The necessary changes in the exchange involve
 
@@ -292,7 +292,7 @@ Refresh - reveal phase
 During the reveal phase -- that is upon POST to ``/refreshes/$RCH/reveal`` --
 the client has to provide the original age commitment of the old coin (i.e. the
 vector of public keys), iff the corresponding denomination had support for age
-restriction.  The size of the vector ist defined by the Exchange implictely as
+restriction.  The size of the vector ist defined by the Exchange implicetly as
 the amount of age groups defined in the field ``.age_groups`` of the
 ``ExtensionAgeRestriction``.
 
@@ -304,7 +304,7 @@ the amount of age groups defined in the field 
``.age_groups`` of the
       // Iff the corresponding denomination has support for age restriction,
       // the client MUST provide the original age commitment, i.e. the vector
       // of public keys.
-      // The size of the vector ist defined by the Exchange implictely as the
+      // The size of the vector ist defined by the Exchange implicetly as the
       // amount of age groups defined in the field ``.age_groups`` of the
       // ``ExtensionAgeRestriction``.
       old_age_commitment?: EddsaPublicKey[];
@@ -342,7 +342,8 @@ purchase.
    ...
    }
 
-Again, the exchange can now check the validity of the coin by evaluating
+Again, the exchange can now check the validity of the coin with age restriction
+by evaluating
 
 .. math::
    \text{FDH}_N(C_p, h_a)\; \stackrel{?}{=}\; \left(\sigma_C\right)^{e} 
\;\;\text{mod}N
@@ -357,10 +358,97 @@ TODO: maybe rename this field into something more opaque, 
like
 
 
 
-Changes in the Merchant
-^^^^^^^^^^^^^^^^^^^^^^^
+Changes in the Merchant API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-TODO: Spending protocol
+
+Claiming the order
+------------------
+
+If an order requires a minimum age, the merchant MUST express that required
+minimum age in response to order claim by the wallet, that is, a POST to
+``[/instances/$INSTANCE]/orders/$ORDER_ID/claim``.
+
+The object ``ContractTerms`` is extended by an optional field
+``required_minimum_age`` that can be any integer greater than 0.  In reality
+this value will not be smaller than, say, 8, and not larger than, say, 21.
+
+.. ts:def:: ContractTerms
+
+   interface ContractTerms {
+   ...
+   
+   // If the order requires a minimum age greater than 0, this field is set
+   // to the integer value of that age.  In reality this value will not be
+   // smaller than, say, 8, and not larger than, say, 21.
+   required_minimum_age?: Integer;
+
+   ...
+   }
+
+By sending the contract term with the field ``required_minimum_age`` set to an
+non-zero integer value, the merchant implicetly signals that it understands the
+extension ``age_restriction.v1`` for age restriction from the exchange.
+
+
+Making the payment
+------------------
+
+If the ``ContractTerms`` had a non-zero value in field
+``required_minimum_age``, the wallet has to provide evidence of that minimum
+age
+
+#. by using coins which are of denominations that have age support enabled
+
+#. *and*  ―for each coin― it has the right private key of the restricted age
+   commitment to the age group into which the required minimum age falls (i.e.
+   a non-empty entry at the right index in vector of EdDSA keys, see above).
+
+#. and signs the required minimum age with each coin's private key
+   corresponding to the age group,
+
+#. and sends ―for each coin― the complete age commitment and the signature to
+   the merchant.
+
+
+For doing so, the object ``CoinPaySig`` used within a ``PayRequest`` during a
+POST to ``[/instances/$INSTANCE]/orders/$ORDER_ID/pay`` is extended as follows:
+
+.. ts:def:: CoinPaySig
+
+   export interface CoinPaySig {
+   ...
+
+   // If a minimum age was required by the order and the wallet had coins that
+   // are at least commited to the corresponding age group, this is the
+   // signature of the minimum age as a string, using the private key to the
+   // corresponding age group.
+   minimum_age_sig?: EddsaSignature;
+
+   // If a minium age was required by the order, this is age commitment bound
+   // to the coin, i.e. the complete vector of EdDSA public keys, one for each
+   // age group (as defined by the exchange).
+   age_commitment?: EddsaPublicKey[];
+
+   }
+
+
+The merchant can now verify
+
+#. the validity of each (age restricted) coin by evaluating
+
+      .. math:: \text{FDH}_N(C_p, h_a)\; \stackrel{?}{=}\; 
\left(\sigma_C\right)^{e} \;\;\text{mod}N
+
+   Again, :math:`C_p` is the EdDSA public key of a coin, :math:`\sigma_C` is 
its
+   signature, :math:`\langle e, N \rangle` is the RSA public key of the
+   denomination and :math:`h_a` is the SHA512 hash value of the vector in
+   ``age_commitment``.
+
+#. the minimum age requirement by checking the signature in ``minimum_age_sig``
+   against the public key ``age_commitment[k]`` of the corresponding age group,
+   say, ``k``.  (The minimum age must fall into the age group at index ``k`` as
+   defined by the exchange)
+   
 
 
 Changes in the Wallet

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.