taler-docs

commit ddb66c6480ad5b3e22c6b90b59ef934066a5d4cf
parent d2010a8fe25921c6e467881ac3e3ca3683b141fa
Author: Florian Dold <dold@taler.net>
Date:   Sat,  5 Sep 2026 13:45:24 +0200

wallet: document confirmed and final transaction amounts

Describe settlement timing, abort recovery, ordinary refunds and durable
final amount evidence in the wallet API and DD 41.

Issue: https://bugs.taler.net/n/7903

Diffstat:
M
design-documents/041-wallet-balance-amount-definitions.rst
 | 
26
+++++++++++++++++++++++++-
M
wallet/wallet-core.md
 | 
15
++++++++++++++-

2 files changed, 39 insertions(+), 2 deletions(-)
diff --git a/design-documents/041-wallet-balance-amount-definitions.rst b/design-documents/041-wallet-balance-amount-definitions.rst
@@ -6,7 +6,7 @@ DD 41: Wallet Balance and Amount Definitions
 :DD shepherd: TBD
 :Historical contributors: Sebastian, Christian Grothoff, Florian Dold, Marc Stibane
 :First published: 2023-03-30
-:Last substantive change: 2024-09-12
+:Last substantive change: 2026-09-05
 :Normative references: ``wallet/wallet-core.md``
 
 Summary
@@ -47,6 +47,30 @@ Amounts
   this is the lower bound for the funds that the other party will obtain
   *after* fees.
 
+Confirmed and final transaction amounts
+--------------------------------------
+
+The wallet API's ``amountEffective`` preserves the amount shown when the user
+confirmed a transaction. ``amountRaw`` retains its existing meaning.
+``amountEffectiveFinal`` reports the actual wallet balance effect after the
+transaction and its change/recovery operations have settled. It is a
+nonnegative amount; the transaction type determines debit or credit.
+
+The final amount is absent while settlement is pending or suspended, and when
+historical evidence cannot establish an exact amount. A failed recovery counts
+only completed outputs. Aborting before funds are consumed has a zero final
+cost; fees and unrecovered funds otherwise remain a debit. For incoming
+transactions, only coins actually issued count as the final credit.
+
+Ordinary merchant refunds remain separate credits and do not reduce a
+successful payment's final cost. Abort refunds are included in the original
+unsuccessful payment's final cost; their informational refund records carry
+``isAbortRecovery`` and must not be counted a second time. Associated refreshes
+have zero independent effect; standalone refreshes report their own loss.
+Settled amounts survive deletion of supporting records. Explicitly reopening
+an operation invalidates its final amount until it settles again.
+
+
 Instructed Amount Modes
 -----------------------
 
diff --git a/wallet/wallet-core.md b/wallet/wallet-core.md
@@ -5442,9 +5442,20 @@ export interface TransactionCommon {
    */
   amountRaw: AmountString;
   /**
-   * Amount added or removed from the wallet's balance (including all fees and other costs).
+   * Amount shown when the transaction was confirmed, including estimated fees.
+   * This amount is preserved when execution fails, expires or is aborted.
    */
   amountEffective: AmountString;
+
+  /**
+   * Settled wallet balance effect, including fees and abort recovery.
+   * Nonnegative; the transaction type determines whether this is a debit or
+   * credit. Absent until the transaction and its recovery have settled, or
+   * when historical records cannot establish the amount. Ordinary merchant
+   * refunds remain separate credits. Associated refreshes have zero effect.
+   */
+  amountEffectiveFinal?: AmountString;
+
   error?: TalerErrorDetail;
   abortReason?: TalerErrorDetail;
   failReason?: TalerErrorDetail;
@@ -6235,6 +6246,8 @@ export interface RefundInfoShort {
 ```
 ```{ts:def} TransactionRefund
 export interface TransactionRefund extends TransactionCommon {
+  /** Recovery already included in the unsuccessful payment's final cost. */
+  isAbortRecovery?: boolean;
   type: TransactionType.Refund;
   amountRaw: AmountString;
   amountEffective: AmountString;