taler-docs

commit f77e888cccc7e263a36c1632cdd8ac4c73fb0690
parent 7f33ddf3149e490c92cc84554793c072d68569d4
Author: Christian Blättler <blatc2@bfh.ch>
Date:   Thu, 28 Mar 2024 10:41:47 +0100

first draft of tokens in pay api

Diffstat:
M
core/api-common.rst
 | 
19
+++++++++++++++++++
M
core/api-merchant.rst
 | 
69
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
M
design-documents/046-mumimo-contracts.rst
 | 
2
+-

3 files changed, 87 insertions(+), 3 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -816,6 +816,13 @@ uses 512-bit hash codes (64 bytes).
      struct GNUNET_HashCode hash;
    };
 
+.. sourcecode:: c
+
+   struct TALER_OutputCommitmentHash {
+     struct GNUNET_HashCode hash;
+   };
+
+
 
 .. _TALER_EcdhEphemeralPublicKeyP:
 .. sourcecode:: c
@@ -967,6 +974,14 @@ uses 512-bit hash codes (64 bytes).
      uint8_t enc[sizeof (struct TALER_LinkSecretP)];
    };
 
+.. _eddsa-token-pub:
+.. sourcecode:: c
+
+   union TALER_TokenPublicKeyP {
+     uint8_t eddsa_pub[32];
+     uint8_t ecdhe_pub[32];
+   };
+
 .. _Signatures:
 
 Signatures
@@ -1073,6 +1088,10 @@ within the
     struct TALER_AmountNBO deposit_fee;
     struct TALER_MerchantPublicKeyP merchant;
     struct GNUNET_HashCode wallet_data_hash;
+    /* @since protocol **vSUBSCRIBE** */
+    struct TALER_OutputCommitmentHash h_outputs;
+    /* @since protocol **vSUBSCRIBE** */
+    uint16_t choice_index;
   };
 
 .. _TALER_DepositConfirmationPS:
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -350,6 +350,18 @@ Making the payment
       // The coins used to make the payment.
       coins: CoinPaySig[];
 
+      // Index of the chosen sub-contract.
+      // @since protocol **vSUBSCRIBE**
+      choice_index?: Integer;
+
+      // Input tokens required by choice indicated by `choice_index`.
+      // @since protocol **vSUBSCRIBE**
+      tokens: TokenPaySig[];
+
+      // Array of blinded output tokens to be (blindly) signed by the merchant.
+      // @since protocol **vSUBSCRIBE**
+      tokens_evs: TokenEnvelope[];
+
       // Custom inputs from the wallet for the contract.
       wallet_data?: Object;
 
@@ -381,6 +393,59 @@ Making the payment
       exchange_url: string;
     }
 
+  .. ts:def:: TokenPaySig
+
+    interface TokenPaySig {
+
+      // Signature on ``TALER_DepositRequestPS`` with the public key of the
+      // token being provisioned to the merchant.
+      token_sig: EddsaSignature;
+
+      // Public key of the token being provisioned to the merchant.
+      token_pub: EddsaPublicKey;
+
+      // Unblinded signature made by the token family public key of the merchant.
+      ub_sig: UnblindedSignature;
+
+      // The hash of the token family public key associated with this token.
+      h_denom: HashCode;
+
+    }
+
+  .. ts:def:: TokenEnvelope
+
+    // This type depends on the cipher used to sign token families. This is
+    // configured by the merchant and defined for each token family in the
+    // contract terms.
+    type TokenEnvelope = RSATokenEnvelope | CSTokenEnvelope;
+
+  .. ts:def:: RSATokenEnvelope
+
+    interface RSATokenEnvelope {
+
+      // RSA is used for the blind signature.
+      cipher: "RSA";
+
+      // Blinded signature of the token's `public EdDSA key <eddsa-token-pub>`.
+      rsa_blinded_pub: BlindedRsaSignature;
+
+    }
+
+  .. ts:def:: CSTokenEnvelope
+
+    interface CSTokenEnvelope {
+      // Blind Clause-Schnorr signature scheme is used for the blind signature.
+      // See https://taler.net/papers/cs-thesis.pdf for details.
+      cipher: "CS";
+
+      // Public nonce
+      cs_nonce: string;      // Crockford `Base32` encoded
+
+      // Two Curve25519 scalars, each representing a blinded challenge
+      cs_blinded_c0: string; // Crockford `Base32` encoded
+      cs_blinded_c1: string; // Crockford `Base32` encoded
+    }
+
 Querying payment status
 -----------------------
 
@@ -3747,8 +3812,8 @@ protocol **vSUBSCRIBE**.
     type: "token";
 
     // How many units of the input are required. Defaults to 1 if not specified.
-    // Input with number == 0 are ignored by the merchant backend.
-    number?: Integer;
+    // Input with count == 0 are ignored by the merchant backend.
+    count?: Integer;
 
     // Token family slug as configured in the merchant backend. Slug is unique
     // across all configured tokens of a merchant.
diff --git a/design-documents/046-mumimo-contracts.rst b/design-documents/046-mumimo-contracts.rst
@@ -439,7 +439,7 @@ consumes an available discount token, that contract should be moved up in the
 list.
 
 Which specific alternative contract was chosen by the user is indicated in the
-subcontract index field of the :ref:`TALER_DepositRequestPS <taler_depositrequestps>`.
+``choice_index`` field of the :ref:`TALER_DepositRequestPS <taler_depositrequestps>`.
 
 
 Output Commitments