refine new denominations structure for /keys

1 files changed, 20 insertions, 3 deletions

diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 59f6cce4..68a297fb 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -145,6 +145,11 @@ possibly by using HTTPS.
       // Denominations offered by this exchange
       denominations: DenomGroup[];
 
+      // Compact EdDSA `signature` (binary-only) over the XOR of all
+      // .hash fields (in binary) in the list "denominations".
+      // Signature of `TALER_ExchangeKeySetPS`
+      denominations_sig: EddsaSignature;
+
       // Denominations for which the exchange currently offers/requests recoup.
       recoup: Recoup[];
 
@@ -170,6 +175,7 @@ possibly by using HTTPS.
       // different users.  If an exchange were to do this, this signature allows the
       // clients to demonstrate to the public that the exchange is dishonest.
       // Signature of `TALER_ExchangeKeySetPS`
+      // DEPRICATED: Will eventually replaced by "denominations_sig"
       eddsa_sig: EddsaSignature;
 
       // Public EdDSA key of the exchange that was used to generate the signature.
@@ -238,6 +244,15 @@ possibly by using HTTPS.
 
     }
 
+
+  .. ts:def:: AgeGroups
+
+    // Representation of the age groups as colon separated edges: Increasing
+    // from left to right, the values mark the beginning of an age group up
+    // to, but not including the next value.  The initial age group starts at
+    // 0 and is not listed.  Example: "8:10:12:14:16:18:21".
+    type AgeGroups string
+
   .. ts:def:: DenomGroup
 
     type DenomGroup =
@@ -270,7 +285,7 @@ possibly by using HTTPS.
 
     interface DenomGroupRsaAgeRestricted extends DenomGroupCommon {
       cipher: "RSA+age_restricted";
-      age_mask: string;
+      age_groups: AgeGroups;
 
       denoms: ({
         rsa_pub: RsaPublicKey;
@@ -281,7 +296,7 @@ possibly by using HTTPS.
 
     interface DenomGroupCSAgeRestricted extends DenomGroupCommon {
       cipher: "CS+age_restricted";
-      age_mask: string;
+      age_groups: AgeGroups;
 
       denoms: ({
         cs_pub: Cs25519Point;
@@ -307,7 +322,9 @@ possibly by using HTTPS.
       // Fee charged by the exchange for refunding a coin of this denomination.
       fee_refund: Amount;
 
-      // Hash of all denominations' public keys in this group.
+      // XOR of all the SHA-512 hash values of the denominations' public keys
+      // in this group.  Note that for hashing, the binary format of the
+      // public keys is used, and not their base32 encoding.
       hash: HashCode;
     }