taler-docs

commit 7cab363f023c05aab7214110fb3ec8a776b9efab
parent 2c3c7027abb1e30befa9c92c43bc991afeeab344
Author: Antoine A <>
Date:   Wed, 21 Jan 2026 10:39:56 +0100

dd80: single endpoint design

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

1 file changed, 22 insertions(+), 51 deletions(-)
diff --git a/design-documents/080-short-wire-subject.rst b/design-documents/080-short-wire-subject.rst
@@ -224,13 +224,14 @@ The algorithm and the difficulty can change over time and the client needs to ha
 
 As the available entropy space goes down, the difficulty to register a new key increase automatically as new derived keys will collide with existing ones. The PoW difficulty is another layer of protection that should be based on request rate.
 
-TODO: what is a good value for no POW: null or none or identify
+The PoW challenge should be based on what makes a transfer unique: the public key algorithm, the public key bytes, and the transfer type. We deliberately made the subject format not part of the challenge so that users could easily try different formats. This is not a problem because key formatting is fast, idempotent and stateless. Wallets should store the associated PoW solution for reuse.
 
 .. ts:def:: PowChallenge
   interface PowChallenge {
     // Algorithm used to perform PoW, new ones will be added in the future
     // PBKDF2-HMAC-SHA256: PBKDF2 using SHA-512
     // none: no PoW is required
+    // TODO: what is a good value for no POW: null or none or identify
     alg: "PBKDF2-HMAC-SHA256" | "none";
 
     // How many iterations to run, used by PBKDF2-HMAC-SHA256
@@ -273,9 +274,15 @@ API
     }
 
 
-.. http:post:: /subject
+.. http:post:: /registration
+
+  Register a public key for wire transfer use.
+  
+  This endpoint generate an appropriate subject to link a transfer to the 
+  registered public key.
 
-  Get an appropriate subject to link a transfer to a public key.
+  A mapping public key can also be used for repeated wire transfers. Reusing a 
+  mapping public key replace previous mapping.
 
   **Request:**
 
@@ -287,7 +294,7 @@ API
       key: EddsaPublicKey;
 
       // Transfer types
-      type: "reserve" | "kyc" | "link";
+      type: "reserve" | "kyc";
 
       // Pow salt used
       pow: String;
@@ -297,6 +304,13 @@ API
 
       // Optional expiration date, null or never will use a default expiration
       expiration?: Timestamp;
+
+      // Optional mapping public key that will be used in the encoded subject instead
+      map?: EddsaPublicKey;
+
+      // 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
     }
 
   **Response:**
@@ -308,8 +322,8 @@ API
   :http:statuscode:`409 Conflict`:
     * ``TALER_EC_BANK_UNSUPPORTED_FORMAT``: format is not supported.
     * ``TALER_EC_BANK_POW_FAILURE``: PoW checks failed, the PoW configuration might have changed.
-    * ``TALER_EC_DERIVATION_REUSE``: derived short subject is already used, you should retry using another key.
-
+    * ``TALER_EC_BANK_DERIVATION_REUSE``: derived short subject is already used, you should retry using another key.
+    * ``TALER_EC_BANK_BAD_SIGNATURE``: signature is invalid.
   **Details:**
 
   .. ts:def:: SubjectResult
@@ -318,51 +332,8 @@ API
       // Subject to use
       subject: SimpleSubject;
 
-      // Expiration date after which this subject can be reused.
-      expiration: Timestamp;
-    }
-
-.. http:post:: /registration
-
-  Link a registration public key to a transfer public key.
-
-  TODO: How is this endpoint used ?
-
-  **Request:**
-
-  .. ts:def:: RegistrationRequest {
-      // Mapping public key algorithm;
-      link_alg: "ECDSA";
-
-      // Encoded registration key
-      link_key: EddsaPublicKey;
-
-      // Public key algorithm;
-      alg: "ECDSA";
-
-      // Encoded public key
-      key: EddsaPublicKey;
-
-      // Transfer types
-      type: "reserve" | "kyc";
-
-      // Optional expiration date, null or never will use a default expiration
-      expiration?: Timestamp;
-    }
-
-  **Response:**
-
-  :http:statuscode:`200 Ok`:
-    Response is a `RegistrationResult`.
-  :http:statuscode:`400 Bad request`:
-    Input data was invalid.
-
-  **Details:**
-
-  .. ts:def:: RegistrationResult
-
-    interface RegistrationResult {
-      // Expiration date after which this mapping will expired.
+      // Expiration date after which this subject can be reused and if mapping
+      // is used when it expired.
       expiration: Timestamp;
     }