commit 34e724f935fcc957c5a69e403faceba629a7fd1d
parent a3851226f2f5057d6bb7f75b5958a741b824b5d0
Author: Antoine A <>
Date: Fri, 10 Jul 2026 13:52:54 +0200
depolymerization: start documenting depolymerizer-bitcoin limitations
Diffstat:
2 files changed, 39 insertions(+), 0 deletions(-)
diff --git a/depolymerization/bitcoin-limitation-manual.rst b/depolymerization/bitcoin-limitation-manual.rst
@@ -0,0 +1,38 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2026 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Antoine d'Aligny
+
+Bitcoin Depolymerizer Limitations
+#################################
+
+The Bitcoin blockchain operates differently from fiat currencies and traditional bank accounts.
+Consequently, certain design choices must be made to integrate it with GNU Taler.
+
+Creditor Address
+================
+
+In the GNU Taler model, accounts are unique, and transactions occur between a unique creditor and a unique debtor account.
+
+Because Bitcoin aims to provide a form of pseudonymization, it does not follow this one-to-one model. We use a single Bitcoin address as the identifier for a unique account. To fit the Taler model, we must designate one of the transaction inputs (vin) as the debtor. We always consider the first input of the transaction as the incoming source, and the corresponding scriptPubKey of that input's origin vout as the debtor account.
+
+If you want to perform KYC verification to prove ownership of a Bitcoin address, you must manually create a transaction that uses the corresponding address as the first input.
+
+Boucing transactions
+====================
+
+When a withdrawal is malformed, an adapter should attempt to return the funds to the debtor. We have chosen to implement this logic for depolymerizer-bitcoin, even though it is not a perfect solution.
+
+Under this logic, we return all funds to the address we identified as the debtor (the first input). If you share an address with other users (which is common on third-party platforms or exchanges), it may be difficult for you to identify the returned funds as yours.
diff --git a/depolymerization/index.rst b/depolymerization/index.rst
@@ -27,3 +27,4 @@ Depolymerization is a project providing free software tooling for blockchain.
:glob:
bitcoin-manual
+ bitcoin-limitation-manual
