wallet-core: define insufficient balance details

packages/taler-wallet-core/src/operations/balance.ts

@@ -14,6 +14,36 @@
  GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
  */
 
+/**
+ * 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.
  */
@@ -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 {

packages/taler-wallet-core/src/operations/pay-merchant.ts

@@ -191,34 +191,6 @@ export async function getTotalPaymentCost(
     });
 }
 
-export interface CoinSelectionRequest {
-  amount: AmountJson;
-
-  allowedAuditors: AllowedAuditorInfo[];
-  allowedExchanges: AllowedExchangeInfo[];
-
-  /**
-   * Timestamp of the contract.
-   */
-  timestamp: TalerProtocolTimestamp;
-
-  wireMethod: string;
-
-  wireFeeAmortization: number;
-
-  maxWireFee: AmountJson;
-
-  maxDepositFee: AmountJson;
-
-  /**
-   * Minimum age requirement for the coin selection.
-   *
-   * When present, only select coins with either no age restriction
-   * or coins with an age commitment that matches the minimum age.
-   */
-  minimumAge?: number;
-}
-
 async function failProposalPermanently(
   ws: InternalWalletState,
   proposalId: string,
@@ -903,6 +875,51 @@ async function unblockBackup(
     });
 }
 
+/**
+ * Detailed reason for why the wallet's balance is insufficient.
+ */
+export interface PayMerchantInsufficientBalanceDetails {
+  /**
+   * Amount requested by the merchant.
+   */
+  amountRequested: AmountJson;
+
+  /**
+   * Balance of type "available" (see balance.ts for definition).
+   */
+  balanceAvailable: AmountJson;
+
+  /**
+   * Balance of type "material" (see balance.ts for definition).
+   */
+  balanceMaterial: AmountJson;
+
+  /**
+   * Balance of type "age-acceptable" (see balance.ts for definition).
+   */
+  balanceAgeAcceptable: AmountJson;
+
+  /**
+   * Balance of type "merchant-acceptable" (see balance.ts for definition).
+   */
+  balanceMechantAcceptable: AmountJson;
+
+  /**
+   * Balance of type "merchant-wireable" (see balance.ts for definition).
+   */
+  balanceMechantWireable: AmountJson;
+
+  /**
+   * If the payment would succeed without fees,
+   * this field contains an estimate of the amount that would additionally
+   * be required to cover the fees.
+   * 
+   * It is not possible to give an exact value here, since it depends
+   * on the coin selection for the amount that would be additionally withdrawn.
+   */
+  feeGapEstimate: AmountJson
+}
+
 export interface SelectPayCoinRequestNg {
   exchanges: AllowedExchangeInfo[];
   auditors: AllowedAuditorInfo[];