@fairblock/stabletrust 1.0.7 → 1.0.9

package/src/client.js

@@ -88,7 +88,7 @@ export class ConfidentialTransferClient {
    * @param {ethers.Wallet|ethers.Signer} wallet - The wallet to derive keys for
    * @returns {Promise<{publicKey: string, privateKey: string}>}
    */
-  async deriveKeys(wallet) {
+  async _deriveKeys(wallet) {
     try {
       if (!wallet) {
         throw new Error("Wallet is required");
@@ -138,7 +138,7 @@ export class ConfidentialTransferClient {
 
     try {
       const address = await wallet.getAddress();
-      const keys = await this.deriveKeys(wallet);
+      const keys = await this._deriveKeys(wallet);
       let accountInfo = await this.getAccountInfo(address);
 
       if (!accountInfo.exists) {
@@ -180,18 +180,61 @@ export class ConfidentialTransferClient {
   }
 
   /**
-   * Get decrypted balance for an address
+   * Get total decrypted balance (available + pending) for an address
    *
    * @param {string} address - Account address
    * @param {string} privateKey - Private key for decryption
    * @param {string} tokenAddress - Token address
-   * @param {Object} [options] - Options
-   * @param {string} [options.type='available'] - Balance type: 'available' or 'pending'
-   * @returns {Promise<{amount: number, ciphertext: string|null}>}
+   * @returns {Promise<{amount: number, available: {amount: number, ciphertext: string|null}, pending: {amount: number, ciphertext: string|null}}>}
    */
-  async getBalance(address, privateKey, tokenAddress, options = {}) {
-    const { type = "available" } = options;
+  async getConfidentialBalance(address, privateKey, tokenAddress) {
+    try {
+      const [available, pending] = await Promise.all([
+        this._getAvailableBalance(address, privateKey, tokenAddress),
+        this._getPendingBalance(address, privateKey, tokenAddress),
+      ]);
+
+      return {
+        amount: available.amount + pending.amount,
+        available,
+        pending,
+      };
+    } catch (error) {
+      throw new Error(`Failed to get confidential balance: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get decrypted available balance for an address
+   * @private
+   */
+  async _getAvailableBalance(address, privateKey, tokenAddress) {
+    return await this._getBalanceByType(
+      address,
+      privateKey,
+      tokenAddress,
+      "available",
+    );
+  }
+
+  /**
+   * Get decrypted pending balance for an address
+   * @private
+   */
+  async _getPendingBalance(address, privateKey, tokenAddress) {
+    return await this._getBalanceByType(
+      address,
+      privateKey,
+      tokenAddress,
+      "pending",
+    );
+  }
 
+  /**
+   * Shared balance retrieval by type
+   * @private
+   */
+  async _getBalanceByType(address, privateKey, tokenAddress, type) {
     try {
       if (!address || !ethers.isAddress(address)) {
         throw new Error(`Invalid address: ${address}`);
@@ -204,7 +247,7 @@ export class ConfidentialTransferClient {
       }
 
       let c1, c2;
-      if (type.toLowerCase() === "pending") {
+      if (type === "pending") {
         [c1, c2] = await this.contract.getPending(address, tokenAddress);
       } else {
         [c1, c2] = await this.contract.getAvailable(address, tokenAddress);
@@ -228,6 +271,29 @@ export class ConfidentialTransferClient {
     }
   }
 
+  /**
+   * Apply pending balance if needed (internal helper)
+   * @private
+   */
+  async _applyPendingIfNeeded(wallet, privateKey, tokenAddress, actionLabel) {
+    const address = await wallet.getAddress();
+    const pendingBalance = await this._getPendingBalance(
+      address,
+      privateKey,
+      tokenAddress,
+    );
+
+    if (pendingBalance.amount > 0) {
+      try {
+        await this._applyPending(wallet, { waitForFinalization: true });
+      } catch (error) {
+        console.warn(
+          `Warning: Failed to apply pending balance before ${actionLabel}: ${error.message}. You may have pending balance that is not yet applied.`,
+        );
+      }
+    }
+  }
+
   /**
    * Deposit tokens into confidential account
    *
@@ -238,7 +304,7 @@ export class ConfidentialTransferClient {
    * @param {boolean} [options.waitForFinalization=true] - Wait for deposit finalization
    * @returns {Promise<Object>} Transaction receipt
    */
-  async deposit(wallet, tokenAddress, amount, options = {}) {
+  async confidentialDeposit(wallet, tokenAddress, amount, options = {}) {
     const { waitForFinalization = true } = options;
 
     try {
@@ -253,6 +319,13 @@ export class ConfidentialTransferClient {
       }
 
       const address = await wallet.getAddress();
+      const derivedKeys = await this._deriveKeys(wallet);
+      await this._applyPendingIfNeeded(
+        wallet,
+        derivedKeys.privateKey,
+        tokenAddress,
+        "deposit",
+      );
       const depositAmount = BigInt(amount);
       const tokenContract = this._getTokenContract(tokenAddress);
 
@@ -280,7 +353,6 @@ export class ConfidentialTransferClient {
           throw new Error("Token approval failed");
         }
       }
-
       // Perform deposit
       const depositTx = await this.contract
         .connect(wallet)
@@ -316,7 +388,7 @@ export class ConfidentialTransferClient {
    * @param {boolean} [options.waitForFinalization=true] - Wait for transfer finalization
    * @returns {Promise<Object>} Transaction receipt
    */
-  async transfer(
+  async confidentialTransfer(
     senderWallet,
     recipientAddress,
     tokenAddress,
@@ -343,7 +415,7 @@ export class ConfidentialTransferClient {
       const senderAddress = await senderWallet.getAddress();
 
       // Auto-derive sender keys
-      const derivedSenderKeys = await this.deriveKeys(senderWallet);
+      const derivedSenderKeys = await this._deriveKeys(senderWallet);
       if (!derivedSenderKeys?.privateKey) {
         throw new Error("Failed to derive sender keys");
       }
@@ -370,22 +442,31 @@ export class ConfidentialTransferClient {
         ).toString("base64");
       }
 
-      // Auto-fetch current balance
-      const balanceInfo = await this.getBalance(
+      await this._applyPendingIfNeeded(
+        senderWallet,
+        derivedSenderKeys.privateKey,
+        tokenAddress,
+        "transfer",
+      );
+
+      const balanceSummary = await this.getConfidentialBalance(
         senderAddress,
         derivedSenderKeys.privateKey,
         tokenAddress,
       );
       const fee = await this.getFeeAmount();
-      if (!balanceInfo) {
-        throw new Error("Failed to fetch sender balance");
-      }
-      const derivedCurrentBalanceCiphertext = balanceInfo.ciphertext;
-      const derivedCurrentBalance = balanceInfo.amount;
+      const derivedCurrentBalanceCiphertext =
+        balanceSummary.available.ciphertext;
+      const derivedCurrentBalance = balanceSummary.available.amount;
 
       if (!derivedCurrentBalanceCiphertext) {
         throw new Error(
-          "Current balance ciphertext is required. Did you call getBalance()?",
+          "Current balance ciphertext is required. Did you call getConfidentialBalance()?",
+        );
+      }
+      if (balanceSummary.amount < amount) {
+        throw new Error(
+          `Insufficient balance. Required: ${amount}, Total: ${balanceSummary.amount}`,
         );
       }
       if (
@@ -612,42 +693,6 @@ export class ConfidentialTransferClient {
 
     return receipt;
   }
-
-  /**
-   * Apply pending balance to available balance
-   *
-   * @param {ethers.Wallet|ethers.Signer} wallet - The wallet to apply pending for
-   * @param {Object} [options] - Options
-   * @param {boolean} [options.waitForFinalization=true] - Wait for operation finalization
-   * @returns {Promise<Object>} Transaction receipt
-   */
-  async applyPending(wallet, options = {}) {
-    const { waitForFinalization = true } = options;
-
-    try {
-      if (!wallet) {
-        throw new Error("Wallet is required");
-      }
-
-      const address = await wallet.getAddress();
-
-      const tx = await this.contract.connect(wallet).applyPending();
-      const receipt = await tx.wait();
-
-      if (!receipt || receipt.status === 0) {
-        throw new Error("Apply pending transaction failed");
-      }
-
-      if (waitForFinalization) {
-        await this._waitForGlobalState(address, "apply pending");
-      }
-
-      return receipt;
-    } catch (error) {
-      throw new Error(`Failed to apply pending: ${error.message}`);
-    }
-  }
-
   /**
    * Withdraw confidential tokens to public ERC20
    *
@@ -675,28 +720,35 @@ export class ConfidentialTransferClient {
       }
 
       // Auto-derive keys
-      const derivedKeys = await this.deriveKeys(wallet);
+      const derivedKeys = await this._deriveKeys(wallet);
       if (!derivedKeys?.privateKey) {
         throw new Error("Failed to derive keys");
       }
 
-      const balanceInfo = await this.getBalance(
-        wallet.address,
+      const address = await wallet.getAddress();
+      await this._applyPendingIfNeeded(
+        wallet,
+        derivedKeys.privateKey,
+        tokenAddress,
+        "withdraw",
+      );
+
+      const balanceSummary = await this.getConfidentialBalance(
+        address,
         derivedKeys.privateKey,
         tokenAddress,
-        {
-          type: "available",
-        },
       );
-      if (!balanceInfo) {
-        throw new Error("Failed to fetch sender balance");
-      }
-      const currentBalanceCiphertext = balanceInfo.ciphertext;
-      const currentBalance = balanceInfo.amount;
+      const currentBalanceCiphertext = balanceSummary.available.ciphertext;
+      const currentBalance = balanceSummary.available.amount;
 
       if (!currentBalanceCiphertext) {
         throw new Error(
-          "Current balance ciphertext is required. Did you call getBalance()?",
+          "Current balance ciphertext is required. Did you call getConfidentialBalance()?",
+        );
+      }
+      if (balanceSummary.amount < amount) {
+        throw new Error(
+          `Insufficient balance. Required: ${amount}, Total: ${balanceSummary.amount}`,
         );
       }
       if (currentBalance === undefined || currentBalance < amount) {
@@ -705,8 +757,6 @@ export class ConfidentialTransferClient {
         );
       }
 
-      const address = await wallet.getAddress();
-
       // Generate withdrawal proof
       const withdrawInput = {
         current_balance_ciphertext: currentBalanceCiphertext,
@@ -762,6 +812,41 @@ export class ConfidentialTransferClient {
     }
   }
 
+  /**
+   * Apply pending balance to available balance
+   *
+   * @param {ethers.Wallet|ethers.Signer} wallet - The wallet to apply pending for
+   * @param {Object} [options] - Options
+   * @param {boolean} [options.waitForFinalization=true] - Wait for operation finalization
+   * @returns {Promise<Object>} Transaction receipt
+   */
+  async _applyPending(wallet, options = {}) {
+    const { waitForFinalization = true } = options;
+
+    try {
+      if (!wallet) {
+        throw new Error("Wallet is required");
+      }
+
+      const address = await wallet.getAddress();
+
+      const tx = await this.contract.connect(wallet).applyPending();
+      const receipt = await tx.wait();
+
+      if (!receipt || receipt.status === 0) {
+        throw new Error("Apply pending transaction failed");
+      }
+
+      if (waitForFinalization) {
+        await this._waitForGlobalState(address, "apply pending");
+      }
+
+      return receipt;
+    } catch (error) {
+      throw new Error(`Failed to apply pending: ${error.message}`);
+    }
+  }
+
   /**
    * Wait for pending action to complete (internal method)
    *
@@ -809,18 +894,20 @@ export class ConfidentialTransferClient {
    * @param {number} [options.intervalMs=3000] - Polling interval in milliseconds
    * @returns {Promise<{amount: number, ciphertext: string}>}
    */
-  async waitForPendingBalance(address, privateKey, tokenAddress, options = {}) {
+  async _waitForPendingBalance(
+    address,
+    privateKey,
+    tokenAddress,
+    options = {},
+  ) {
     const { maxAttempts = 60, intervalMs = 3000 } = options;
 
     try {
       for (let i = 0; i < maxAttempts; i++) {
-        const pending = await this.getBalance(
+        const pending = await this._getPendingBalance(
           address,
           privateKey,
           tokenAddress,
-          {
-            type: "pending",
-          },
         );
 
         if (pending.amount > 0) {
@@ -861,7 +948,7 @@ export class ConfidentialTransferClient {
    * @param {string} tokenAddress - Token address
    * @returns {Promise<bigint>} Token balance
    */
-  async getTokenBalance(address, tokenAddress) {
+  async getPublicBalance(address, tokenAddress) {
     try {
       if (!address || !ethers.isAddress(address)) {
         throw new Error(`Invalid address: ${address}`);

package/src/index.d.ts

@@ -26,6 +26,15 @@ declare module "@fairblock/stabletrust" {
     ciphertext: string | null;
   }
 
+  /**
+   * Confidential balance summary
+   */
+  export interface ConfidentialBalance {
+    amount: number;
+    available: Balance;
+    pending: Balance;
+  }
+
   /**
    * Account options
    */
@@ -49,13 +58,6 @@ declare module "@fairblock/stabletrust" {
     waitForFinalization?: boolean;
   }
 
-  /**
-   * Apply pending options
-   */
-  export interface ApplyPendingOptions {
-    waitForFinalization?: boolean;
-  }
-
   /**
    * Withdraw options
    */
@@ -64,21 +66,6 @@ declare module "@fairblock/stabletrust" {
     waitForFinalization?: boolean;
   }
 
-  /**
-   * Balance options
-   */
-  export interface BalanceOptions {
-    type?: "available" | "pending";
-  }
-
-  /**
-   * Wait for pending balance options
-   */
-  export interface WaitForPendingOptions {
-    maxAttempts?: number;
-    intervalMs?: number;
-  }
-
   /**
    * Main SDK client class
    * WASM auto-initializes on first use - no manual initialization required!
@@ -92,11 +79,6 @@ declare module "@fairblock/stabletrust" {
      */
     constructor(rpcUrl: string, contractAddress: string, chainId: number);
 
-    /**
-     * Derive encryption keys for a wallet
-     */
-    deriveKeys(wallet: ethers.Wallet | ethers.Signer): Promise<Keys>;
-
     /**
      * Get account information from the contract
      */
@@ -111,18 +93,16 @@ declare module "@fairblock/stabletrust" {
     ): Promise<Keys>;
 
     /**
-     * Get decrypted balance for an address
+     * Get total decrypted balance (available + pending) for an address
      * @param address Account address
      * @param privateKey Private key for decryption
      * @param tokenAddress Token contract address
-     * @param options Balance options
      */
-    getBalance(
+    getConfidentialBalance(
       address: string,
       privateKey: string,
       tokenAddress: string,
-      options?: BalanceOptions,
-    ): Promise<Balance>;
+    ): Promise<ConfidentialBalance>;
 
     /**
      * Deposit tokens into confidential account
@@ -131,7 +111,7 @@ declare module "@fairblock/stabletrust" {
      * @param amount Amount to deposit
      * @param options Deposit options
      */
-    deposit(
+    confidentialDeposit(
       wallet: ethers.Wallet | ethers.Signer,
       tokenAddress: string,
       amount: bigint | string | number,
@@ -147,7 +127,7 @@ declare module "@fairblock/stabletrust" {
      * @param amount Amount to transfer
      * @param options Transfer options
      */
-    transfer(
+    confidentialTransfer(
       senderWallet: ethers.Wallet | ethers.Signer,
       recipientAddress: string,
       tokenAddress: string,
@@ -155,14 +135,6 @@ declare module "@fairblock/stabletrust" {
       options?: TransferOptions,
     ): Promise<ethers.ContractTransactionReceipt>;
 
-    /**
-     * Apply pending balance to available balance
-     */
-    applyPending(
-      wallet: ethers.Wallet | ethers.Signer,
-      options?: ApplyPendingOptions,
-    ): Promise<ethers.ContractTransactionReceipt>;
-
     /**
      * Withdraw confidential tokens to public ERC20
      * @param wallet Wallet to withdraw to
@@ -177,31 +149,17 @@ declare module "@fairblock/stabletrust" {
       options?: WithdrawOptions,
     ): Promise<ethers.ContractTransactionReceipt>;
 
-    /**
-     * Wait for pending balance to appear
-     * @param address Account address
-     * @param privateKey Private key for decryption
-     * @param tokenAddress Token contract address
-     * @param options Wait options
-     */
-    waitForPendingBalance(
-      address: string,
-      privateKey: string,
-      tokenAddress: string,
-      options?: WaitForPendingOptions,
-    ): Promise<Balance>;
-
     /**
      * Get the current fee amount for confidential transfers
      */
     getFeeAmount(): Promise<bigint>;
 
     /**
-     * Get ERC20 token balance
+     * Get the public ERC20 balance for an address (for comparison with confidential balance)
      * @param address Account address
      * @param tokenAddress Token contract address
      */
-    getTokenBalance(address: string, tokenAddress: string): Promise<bigint>;
+    getPublicBalance(address: string, tokenAddress: string): Promise<bigint>;
   }
 
   /**