taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

commit 3368f2a93035c677a0004f6b7ec8a55635f8c5f3
parent 79abb01f5c32af9ff3753ceb7e8b6da4b8180a43
Author: Florian Dold <dold@taler.net>
Date:   Fri, 20 Nov 2026 19:12:33 +0100

exchange API: specify the full amount and zero fee for purse refunds

Diffstat:
Mcore/exchange/get-coins-COIN_PUB-history.rst | 19+++++++++++--------
Mdesign-documents/013-peer-to-peer-payments.rst | 9++++-----
2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/core/exchange/get-coins-COIN_PUB-history.rst b/core/exchange/get-coins-COIN_PUB-history.rst @@ -470,15 +470,12 @@ // the "start" query parameter. history_offset: Integer; - // The total amount of the coin's value restored - // by this transaction. - // The amount given excludes the refund fee. - // The current coin value can thus be computed by - // adding the amount to the coin's denomination value. + // Full amount of the original PURSE-DEPOSIT, including its deposit fee. + // Expiry or DELETEing a purse restores this amount to the coin. amount: Amount; - // Refund fee (of the coin's denomination). The deposit - // fee will be waived. + // Always zero in the coin's currency. The denomination's refund fee + // never applies to PURSE-REFUND. This field is required and signed. refund_fee: Amount; // Signature by the exchange over a @@ -489,11 +486,17 @@ // Public key used to sign 'exchange_sig'. exchange_pub: EddsaPublicKey; - // Public key of the purse that expired. + // Public key of the refunded purse. purse_pub: EddsaPublicKey; } + Older exchanges signed a net ``amount`` and the denomination's + ``refund_fee`` even though they restored the full deposit. Clients reading + these histories verify the signature over the reported fields and check + that their sum equals the original ``PURSE-DEPOSIT`` amount for this purse + and coin. + .. ts:def:: CoinReserveOpenDepositTransaction interface CoinReserveOpenDepositTransaction { diff --git a/design-documents/013-peer-to-peer-payments.rst b/design-documents/013-peer-to-peer-payments.rst @@ -225,8 +225,7 @@ Principles per account is below a configurable threshold. * By charging the purse fee only in case the payee did **not** merge the purse into their account, the purse fee can be limited for payers to - the case where they are receiving a refund --- and here it could be - then entirely avoided if the refund fee is non-zero. + the case where they are receiving a refund. W2W Payment Metadata @@ -281,9 +280,9 @@ Contract metadata for W2W payments can be exchanged in three ways: .. note:: - While the **refund fee** amount can be reused, these types of refunds - are not approved by a merchant's signature. Thus, we will need - a new message type in the coin history to represent these events. + Expiry or DELETEing a purse restores each coin's full contribution, + including its deposit fee. The exchange signs a ``PURSE-REFUND`` + coin history entry with a zero refund fee. Account creation