taler-docs

commit 01f2af0fe75223784599bc60913d3ea40e079ffe
parent ccb05ec71ca4ab82ff589633ef661a39016bb9ba
Author: Antoine A <>
Date:   Sun, 15 Feb 2026 11:59:08 +0100

dd83: init wallet initiated withdrawal design document

Diffstat:
M
core/api-bank-wire.rst
 | 
2
+-
A
design-documents/083-wallet-initiated-withdrawal.rst
 | 
93
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
M
design-documents/index.rst
 | 
1
+

3 files changed, 95 insertions(+), 1 deletion(-)
diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst
@@ -57,7 +57,7 @@ LibEuFin.
       // @since v0, may become mandatory in the future.
       implementation?: string;
 
-      // Wether implementation support account existence check
+      // Whether implementation support account existence check
       support_account_check: boolean;
     }
 
diff --git a/design-documents/083-wallet-initiated-withdrawal.rst b/design-documents/083-wallet-initiated-withdrawal.rst
@@ -0,0 +1,93 @@
+DD 83: Wallet Initiated Withdrawal
+##################################
+
+Summary
+=======
+
+We want to support wallet-initiated withdrawals in addition to the bank-initiated ones we currently support.
+
+Motivation
+==========
+
+For a system like Cyclos, adding a bank-initiated withdrawal will be difficult and particularly costly to maintain.
+However, with wallet-initiated withdrawals, all the logic would be within the implementation of the adapter we already have and maintain.
+
+
+Requirements
+============
+
+* Must be easy to implement for future adapters
+* Must be easy to implement and maintain in the wallet
+
+Proposed Solution
+=================
+
+We already have a Taler Bank Integration API that is entirely dedicated to integrating withdrawals.
+By adding a single endpoint to enable the creation of a withdrawal, we can then reuse the current endpoints for the rest.
+I think this would make implementation in the wallet easier, as most of the logic should remain the same.
+
+API
+---
+
+.. ts:def:: IntegrationConfig
+
+  interface IntegrationConfig {
+    // Whether this implementation supports wallet initiated withdrawal
+    support_wallet_initiated: boolean;
+  }
+
+.. http:post:: /withdrawal-operation
+
+  This endpoint is used by the GNU Taler wallet to create a new withdraw operation.
+
+  **Request:**
+
+  .. ts:def:: BankWithdrawalOperationCreateRequest
+
+    interface BankWithdrawalOperationCreateRequest {
+
+      // Reserve public key that should become the wire transfer
+      // subject to fund the withdrawal.
+      reserve_pub: EddsaPublicKey;
+
+      // Selected amount to be transferred.
+      amount: Amount;
+    }
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The bank has accepted and created the withdrawal operation chosen by the wallet.
+    The response is a `BankWithdrawalOperationCreateResponse`.
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT``: the reserve public key is already used.
+  :http:statuscode:`501 Not Implemented`:
+    This server does not support wallet initiated withdrawal.
+
+  **Details:**
+
+  .. ts:def:: BankWithdrawalOperationCreateResponse
+
+    interface BankWithdrawalOperationCreateResponse {
+      // ID identifying the operation being created
+      withdrawal_id: string;
+    }
+
+Test Plan
+=========
+
+I would first implement this new endpoint in libeufin-bank first so that this new flow can be easily tested using the demo deployment
+and then I would add it to all adapters that can support it: taler-cyclos and maybe taler-magnet-bank.
+
+
+Alternatives
+============
+
+
+Drawbacks
+=========
+
+* A new flow to test
+
+Discussion / Q&A
+================
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -94,4 +94,5 @@ Design documents that start with "XX" are considered deprecated.
   080-short-wire-subject
   081-shop-discovery
   082-wallet-diagnostics
+  083-wallet-initiated-withdrawal
   999-template