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:
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