taler-docs

commit d0ea15f579412b20a853a3a635c35b714bab4790
parent b9914bed1042756998e4bc89ba7b4162aeb497cc
Author: Antoine A <>
Date:   Thu, 22 Jan 2026 18:09:00 +0100

dd80: improve PoW

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

1 file changed, 30 insertions(+), 2 deletions(-)
diff --git a/design-documents/080-short-wire-subject.rst b/design-documents/080-short-wire-subject.rst
@@ -227,6 +227,7 @@ As the available entropy space goes down, the difficulty to register a new key i
 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
@@ -240,6 +241,9 @@ The PoW challenge should be based on what makes a transfer unique: the public ke
 
     // Number of lead bits that must be zero for the challenge to be accepted
     difficulty: Integer;
+
+    // Unique salt to use when solving the challenge
+    salt: String;
   }
 
 Auditor
@@ -273,6 +277,15 @@ API
       supported_formats: SubjectFormat[];
     }
 
+.. http:get:: /challenge
+
+  Ask for a PoW challenge to solve.
+
+  **Response:**
+
+  :http:statuscode:`200 Ok`:
+    Response is a `PowChallenge`.
+
 
 .. http:post:: /registration
 
@@ -284,9 +297,13 @@ API
   A mapping public key can also be used for repeated wire transfers. Reusing a 
   mapping public key replace previous mapping.
 
+  As this endpoint is unauthenticated a PoW challenge must be solved. On success the challenge will be consumed.
+
   **Request:**
 
-  .. ts:def:: SubjectRequest {
+  .. ts:def:: SubjectRequest
+    
+    interface SubjectRequest {
       // Public key algorithm;
       alg: "ECDSA";
 
@@ -311,6 +328,14 @@ 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
+
+      // Challenge salt 
+      // Use empty string if challenge alg is ``none``
+      challenge_salt: String;
+
+      // Challenge nonce solution 
+      // Use empty string if challenge alg is ``none``
+      challenge_nonce: String;
     }
 
   **Response:**
@@ -321,9 +346,12 @@ API
     Input data was invalid.
   :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_BANK_CHALLENGE_FAILURE``: PoW challenge solution is wrong or challenge is unknown or challenge have checks failed.
+    * ``TALER_EC_BANK_CHALLENGE_UNKNOWN``: PoW challenge is unknown or already consumed.
     * ``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