taler-docs

commit 556165f148f0ad5b1800d94e3f67cf45698453da
parent d8aac30a57cd55f6a75c237f3d25351ef7e719a9
Author: Florian Dold <florian@dold.me>
Date:   Fri,  3 Jun 2022 13:58:05 +0200

new denominations structure, minor fixes

Diffstat:
M
core/api-exchange.rst
 | 
83
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
M
design-documents/013-peer-to-peer-payments.rst
 | 
2
+-
M
design-documents/024-age-restriction.rst
 | 
2
--

3 files changed, 81 insertions(+), 6 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -138,8 +138,13 @@ possibly by using HTTPS.
       wallet_balance_limit_without_kyc?: Amount;
 
       // Denominations offered by this exchange.
+      // DEPRECATED: Will eventually be replaced by the
+      // differently structured "denominations" field.
       denoms: Denom[];
 
+      // Denominations offered by this exchange
+      denominations: DenominationGroup[];
+
       // Denominations for which the exchange currently offers/requests recoup.
       recoup: Recoup[];
 
@@ -233,6 +238,78 @@ possibly by using HTTPS.
 
     }
 
+  .. ts:def:: DenomGroup
+
+    // Common attributes for all denomination groups
+    interface DenomGroupCommon {
+      // How much are coins of this denomination worth?
+      value: Amount;
+
+      // Fee charged by the exchange for withdrawing a coin of this denomination.
+      fee_withdraw: Amount;
+
+      // Fee charged by the exchange for depositing a coin of this denomination.
+      fee_deposit: Amount;
+
+      // Fee charged by the exchange for refreshing a coin of this denomination.
+      fee_refresh: Amount;
+
+      // Fee charged by the exchange for refunding a coin of this denomination.
+      fee_refund: Amount;
+
+      // Hash of all denominations in this group.
+      hash: HashCode;
+    }
+
+    interface DenomCommon {
+      // Signature of `TALER_DenominationKeyValidityPS`.
+      master_sig: EddsaSignature;
+
+      // When does the denomination key become valid?
+      stamp_start: Timestamp;
+
+      // When is it no longer possible to deposit coins
+      // of this denomination?
+      stamp_expire_withdraw: Timestamp;
+
+      // Timestamp indicating by when legal disputes relating to these coins must
+      // be settled, as the exchange will afterwards destroy its evidence relating to
+      // transactions involving this coin.
+      stamp_expire_legal: Timestamp;
+    }
+
+    type DenomGroup =
+      | DenomGroupRsa
+      | DenomGroupCs
+      | DenomGroupRsaAgeRestricted
+      | DenomGroupCsAgeRestricted;
+
+    interface DenomGroupRsa extends DenomGroupCommon {
+      cipher: "RSA";
+
+      denoms: ({
+        rsa_pub: string;
+      } & DenomGroupCommon)[];
+    }
+
+    interface DenomGroupCs extends DenomGroupCommon {
+      cipher: "CS";
+
+      denoms: ({
+        cs_pub: Cs25519Point;
+        age_mask: string;
+      } & DenomGroupCommon)[];
+    }
+
+    interface DenomGroupRsaAgeRestricted extends DenomGroupCommon {
+      cipher: "RSA+age_restricted";
+
+      denoms: ({
+        rsa_pub: string;
+        age_mask: string;
+      } & DenomGroupCommon)[];
+    }
+
   .. ts:def:: Denom
 
     interface Denom {
@@ -1810,7 +1887,7 @@ denomination.
     previously used with a different denomination.  Which case it is
     can be decided by looking at the error code
     (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
-     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
+    ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
     The fields of the response are the same in both cases.
     The request should not be repeated again with this coin.
     In this case, the response is a `DepositDoubleSpendError`.
@@ -2345,7 +2422,7 @@ the API during normal operation.
     previously used with a different denomination.  Which case it is
     can be decided by looking at the error code
     (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
-     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
+    ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
     The response is `MeltForbiddenResponse` in both cases.
   :http:statuscode:`410 Gone`:
     The requested denomination key is not yet or no longer valid.
@@ -3133,7 +3210,7 @@ Wallet-to-wallet transfers
     Which case it is
     can be decided by looking at the error code
     (``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
-     ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or
+    ``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or
     ``TALER_EC_EXCHANGE_PURSE_CREATE_CONFLICTING_META_DATA`` or
     ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_CONFLICTING_META_DATA`` or
     ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_CONFLICTING_META_DATA``).
diff --git a/design-documents/013-peer-to-peer-payments.rst b/design-documents/013-peer-to-peer-payments.rst
@@ -376,7 +376,7 @@ In this protocol variant, the payer is initiating the process.
 3. The payer shares the purse's private key and the base URL
    of the exchange where the purse was created with the payee.
    This can be done using a ``taler://purse/$BASE_URL/$PURSE_PRIV`` URL.
-   The chapter on ``Refinements'' below clarifies why this
+   The chapter on ``Refinements`` below clarifies why this
    step is not quite OK and was modified when implementing the   design.
 4. The payee uses the new ``/purse/$PURSE_PUB`` endpoint to retrieve
    the encrypted contract (if available) and purse balance, which includes all
diff --git a/design-documents/024-age-restriction.rst b/design-documents/024-age-restriction.rst
@@ -677,5 +677,3 @@ The scheme is as follows:
       return [s] * G == R + [SHA-512(R ∥ P ∥ message)] * P
     }
 
-::
-