wallet-core: define insufficient balance details

1 files changed, 33 insertions, 0 deletions

diff --git a/packages/taler-wallet-core/src/operations/balance.ts b/packages/taler-wallet-core/src/operations/balance.ts
index cd78b0360..d2a029d53 100644
--- a/packages/taler-wallet-core/src/operations/balance.ts
+++ b/packages/taler-wallet-core/src/operations/balance.ts
@@ -15,6 +15,36 @@
  */
 
 /**
+ * Functions to compute the wallet's balance.
+ * 
+ * There are multiple definition of the wallet's balance.
+ * We use the following terminology:
+ * 
+ * - "available": Balance that the wallet believes will certainly be available
+ *   for spending, modulo any failures of the exchange or double spending issues.
+ *   This includes available coins *not* allocated to any
+ *   spending/refresh/... operation. Pending withdrawals are *not* counted
+ *   towards this balance, because they are not certain to succeed. 
+ *   Pending refreshes *are* counted towards this balance.
+ *   This balance type is nice to show to the user, because it does not
+ *   temporarily decrease after payment when we are waiting for refreshes
+ *
+ * - "material": Balance that the wallet believes it could spend *right now*,
+ *   without waiting for any operations to complete.
+ *   This balance type is important when showing "insufficient balance" error messages.
+ *
+ * - "age-acceptable": Subset of the material balance that can be spent
+ *   with age restrictions applied.
+ *
+ * - "merchant-acceptable": Subset of the material balance that can be spent with a particular
+ *   merchant (restricted via min age, exchange, auditor, wire_method).
+ * 
+ * - "merchant-wireable": Subset of the merchant-acceptable balance that the merchant
+ *   can accept via their supported wire methods.
+ */
+
+
+/**
  * Imports.
  */
 import {
@@ -27,6 +57,9 @@ import { WalletStoresV1 } from "../db.js";
 import { GetReadOnlyAccess } from "../util/query.js";
 import { InternalWalletState } from "../internal-wallet-state.js";
 
+/**
+ * Logger.
+ */
 const logger = new Logger("operations/balance.ts");
 
 interface WalletBalance {