taler-docs

commit a4b274ccf45219038e4a02ec7397dddc70db3c14
parent d2f671f6749d750dc33a3ee73cf49e306d6f5726
Author: Antoine A <>
Date:   Thu, 29 Jan 2026 15:58:39 +0100

dd80: improve spec

Diffstat:
M
design-documents/080-short-wire-subject.rst
 | 
26
++++++++++----------------

1 file changed, 10 insertions(+), 16 deletions(-)
diff --git a/design-documents/080-short-wire-subject.rst b/design-documents/080-short-wire-subject.rst
@@ -142,22 +142,16 @@ Subject derivation
 
 When the encoding space is not limited or large enough like in SEPA transfers, no special derivation logic is used and we use the existing one.
 
-Short subject are derived from a SHA-512 hash of the key and metadata.
+The manner in which subjects are derived is not specified but the API must be idempotent and the derivation method must use the entire coding space.
 
-SHA-512("RESERVE" + "ECDSA" + raw key bytes)
+An efficient way is to make the derivation idempotent and use hashing, for example you can make a SHA-512 hash of the key and metadata: SHA-512("RESERVE" + "ECDSA" + raw key bytes) or SHA-512("KYC" + "SLH-DSA" + raw key bytes). Then truncate to the number of bytes we can fill in the subject and encoded using a supported alphabet.
 
-SHA-512("KYC" + "SLH-DSA" + raw key bytes)
-
-Then the hash is truncated to the number of bytes we can fill in the subject and encoded using a supported alphabet.
-
-TODO: define derivation with precision
+Client should not have any expectation about how subject derivation works and changing the method should be possible in a non breaking way.
 
 - SIMPLE: BASE32 encode and trunc
 - BTC: trunc and encode in segwit address
 - NZ-SBI: BASE32 encode and trunc 36 char
 
-TODO: do we add a prefix ?
-
 .. ts:def:: TransferSubject
 
   // Union discriminated by the "type" field.
@@ -234,14 +228,14 @@ As the available entropy space goes down, the difficulty to register a new key i
 
   interface PowChallenge {
     // Algorithm used to perform PoW, new ones will be added in the future
-    // PBKDF2-HMAC-SHA256: PBKDF2 using SHA-512
-    alg: "PBKDF2-HMAC-SHA256";
+    // PBKDF2-HMAC-SHA512: PBKDF2 using SHA-512
+    alg: "PBKDF2-HMAC-SHA512";
 
-    // How many iterations to run, used by PBKDF2-HMAC-SHA256
-    // Set to zero for none
+    // How many iterations to run, must be > 0
     iterations: Integer;
 
-    // Number of lead bits that must be zero for the challenge to be accepted
+    // Number of lead bits that must be zero for the challenge to be accepted, 
+    // must be > 0
     difficulty: Integer;
 
     // Unique salt to use when solving the challenge
@@ -326,7 +320,7 @@ API
 
       // Optional signature of the raw public key using the mapping key,
       // required if map is not null
-      signature?: Base32; // TODO add type to common types
+      signature?: string;
     }
 
   **Response:**
@@ -349,7 +343,7 @@ API
 
     interface SubjectResult {
       // Subject to use
-      subject: SimpleSubject;
+      subject: TransferSubject;
 
       // Expiration date after which this subject can be reused and if mapping
       // is used when it expired.