@fairblock/stabletrust 2.0.5 → 2.0.7

package/README.md

@@ -572,28 +572,15 @@ try {
 
 ### Common Issues and Solutions
 
-| Issue                          | Cause                                                   | Solution                                                |
-| :----------------------------- | :------------------------------------------------------ | :------------------------------------------------------ |
-| "Account does not exist"       | Recipient hasn't initialized their confidential account | Recipient must call `ensureAccount()` first             |
-| "Insufficient balance"         | Transfer amount exceeds available confidential balance  | Deposit more tokens or reduce transfer amount           |
-| "Account finalization timeout" | Account creation is still processing                    | Wait a few minutes and retry                            |
-| "Proof generation failed"      | Invalid inputs or cryptographic operation error         | Verify all parameters and ensure sufficient balance     |
-| "Amount too small"             | Amount rounds to 0 in contract scale                    | Use a larger amount (minimum depends on token decimals) |
+| Issue                              | Cause                                                                 | Solution                                                                                                            |
+| :--------------------------------- | :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ |
+| "Account does not exist"           | Recipient hasn't initialized their confidential account               | Recipient must call `ensureAccount()` first                                                                         |
+| "Insufficient balance"             | Transfer amount exceeds available confidential balance                | Deposit more tokens or reduce transfer amount                                                                       |
+| "Account finalization timeout"     | Account creation is still processing                                  | Wait a few minutes and retry                                                                                        |
+| "Proof generation failed"          | Invalid inputs or cryptographic operation error                       | Verify all parameters and ensure sufficient balance                                                                 |
+| "Amount too small"                 | Amount rounds to 0 in contract scale                                  | Use a larger amount (minimum depends on token decimals)                                                             |
 | "Insufficient prepaid fee balance" | Anonymous account's prepaid fee reserve is below the per-transfer fee | Call `depositFees(wallet, accountId, amount)` to top up; use `getFeeToken()`/`getFeeAmount()` to check requirements |
-| Fairycloak HTTP error          | Relay unreachable or request rejected                   | Check the relay URL, API key, and account authorization |
-
----
-
-## Performance Metrics
-
-The following are estimated execution times for standard operations. Durations may vary based on network congestion and hardware.
-
-| Operation        | Avg Duration |
-| :--------------- | :----------- |
-| Account Creation | 45s          |
-| Deposit          | 63s          |
-| Transfer         | 58s          |
-| Withdraw         | 58s          |
+| Fairycloak HTTP error              | Relay unreachable or request rejected                                 | Check the relay URL, API key, and account authorization                                                             |
 
 ---
 

package/examples/anonymous-flow.js

@@ -24,7 +24,7 @@ dotenv.config();
 
 const EVM_RPC = process.env.EVM_RPC ?? "http://127.0.0.1:8545";
 const FAIRYCLOAK_URL = process.env.FAIRYCLOAK_URL ?? "http://127.0.0.1:8080";
-const CHAIN_ID = Number(process.env.CHAIN_ID ?? "31337");
+const CHAIN_ID = Number(process.env.CHAIN_ID ?? "5042002");
 const TOKEN_ADDRESS =
   process.env.TOKEN_ADDRESS ?? "0xE915164570b027C2A0FfadcB1B672192E35BF008";
 const TOKEN_DECIMALS = Number(process.env.TOKEN_DECIMALS ?? "6");
@@ -236,34 +236,39 @@ async function main() {
   log("  fee token  :", feeToken);
   log("  fee/xfer   :", fmt(feeAmount, TOKEN_DECIMALS), "tokens");
 
-  const feeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
-  log("  fee balance:", fmt(feeBalance, TOKEN_DECIMALS), "tokens");
-
-  if (feeBalance < MIN_FEE_BALANCE) {
-    log(
-      `  balance < ${fmt(MIN_FEE_BALANCE, TOKEN_DECIMALS)}, depositing ${fmt(FEE_DEPOSIT_AMOUNT, TOKEN_DECIMALS)} fee tokens (anon1 pays gas) …`,
-    );
-    const fd = await client.depositFees(
-      anon1Wallet,
-      anon1Id,
-      FEE_DEPOSIT_AMOUNT,
-    );
-    log("  request_id:", fd.request_id, "  status:", fd.status);
-    if (fd.error) log("    [!] Error:", fd.error);
-    if (fd.tx_hash) log("  tx_hash   :", fd.tx_hash);
-
-    const fdFinal = await client.waitForRequest(fd.request_id, {
-      timeoutMs: 180_000,
-    });
-    log("  status    :", fdFinal.status, "  tx_hash:", fdFinal.tx_hash ?? "—");
-    if (fdFinal.error) log("    [!] Error:", fdFinal.error);
-
-    const newFeeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
-    log("  new fee balance:", fmt(newFeeBalance, TOKEN_DECIMALS), "tokens");
+  if (feeAmount === 0n) {
+    log("  no fee configured — transactions are free, skipping top-up.");
   } else {
-    log(
-      `  fee balance sufficient (${fmt(feeBalance, TOKEN_DECIMALS)} ≥ ${fmt(MIN_FEE_BALANCE, TOKEN_DECIMALS)}), skipping deposit.`,
-    );
+    const feeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
+    log("  fee balance:", fmt(feeBalance, TOKEN_DECIMALS), "tokens");
+
+    if (feeBalance < MIN_FEE_BALANCE) {
+      const currency = feeToken === ethers.ZeroAddress ? "native" : "ERC-20";
+      log(
+        `  balance < ${fmt(MIN_FEE_BALANCE, TOKEN_DECIMALS)}, depositing ${fmt(FEE_DEPOSIT_AMOUNT, TOKEN_DECIMALS)} ${currency} fee tokens (anon1 pays gas) …`,
+      );
+      const fd = await client.depositFees(
+        anon1Wallet,
+        anon1Id,
+        FEE_DEPOSIT_AMOUNT,
+      );
+      log("  request_id:", fd.request_id, "  status:", fd.status);
+      if (fd.error) log("    [!] Error:", fd.error);
+      if (fd.tx_hash) log("  tx_hash   :", fd.tx_hash);
+
+      const fdFinal = await client.waitForRequest(fd.request_id, {
+        timeoutMs: 180_000,
+      });
+      log("  status    :", fdFinal.status, "  tx_hash:", fdFinal.tx_hash ?? "—");
+      if (fdFinal.error) log("    [!] Error:", fdFinal.error);
+
+      const newFeeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
+      log("  new fee balance:", fmt(newFeeBalance, TOKEN_DECIMALS), "tokens");
+    } else {
+      log(
+        `  fee balance sufficient (${fmt(feeBalance, TOKEN_DECIMALS)} ≥ ${fmt(MIN_FEE_BALANCE, TOKEN_DECIMALS)}), skipping deposit.`,
+      );
+    }
   }
 
   // ── [6] Transfer anon1 → anon2 ───────────────────────────────────────────────

package/examples/complete-flow.js

@@ -1,7 +1,6 @@
 import { ethers } from "ethers";
 import dotenv from "dotenv";
-import { ConfidentialTransferClient } from "@fairblock/stabletrust";
-import { ERC20_ABI } from "./constants.js";
+import { ConfidentialTransferClient, ERC20_ABI } from "@fairblock/stabletrust";
 dotenv.config();
 
 /**

package/examples/simple-snippets.js

@@ -1,7 +1,6 @@
 import { ethers } from "ethers";
 import dotenv from "dotenv";
-import { ConfidentialTransferClient } from "@fairblock/stabletrust";
-import { ERC20_ABI } from "./constants.js";
+import { ConfidentialTransferClient, ERC20_ABI } from "@fairblock/stabletrust";
 dotenv.config();
 const RPC_URL = process.env.RPC_URL || "https://rpc.testnet.stable.xyz";
 const EXPLORER_URL =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairblock/stabletrust",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "SDK for confidential transfers using homomorphic encryption and zero-knowledge proofs",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -21,8 +21,7 @@
     "src/",
     "pkg/",
     "examples/",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
   "repository": {
     "type": "git",

package/src/anonymous-client.js

@@ -1488,8 +1488,6 @@ export class AnonymousTransferClient {
     ]);
     if (feeAmount === 0n) return; // no fee configured
 
-    if (feeToken === ethers.ZeroAddress) return; // fee token not set
-
     const balance = await this.getPrepaidFeeBalance(accountId, feeToken);
     if (balance < feeAmount) {
       throw new Error(
@@ -1534,45 +1532,51 @@ export class AnonymousTransferClient {
       if (amountBig <= 0n) throw new Error("Amount must be greater than 0");
 
       const feeToken = await this.getFeeToken();
-      if (feeToken === ethers.ZeroAddress)
-        throw new Error(
-          "No fee token is currently configured on the contract. Contact the protocol operator.",
-        );
+      const isNative = feeToken === ethers.ZeroAddress;
 
       const depositorAddress = await authWallet.getAddress();
       const walletWithProvider = authWallet.connect
         ? authWallet.connect(this.provider)
         : authWallet;
 
-      // 1. Approve if needed
-      const tokenContract = new ethers.Contract(
-        feeToken,
-        [
-          "function balanceOf(address) view returns (uint256)",
-          "function allowance(address,address) view returns (uint256)",
-          "function approve(address,uint256) returns (bool)",
-        ],
-        walletWithProvider,
-      );
+      if (isNative) {
+        // Native currency: check wallet balance, no ERC-20 approve needed
+        const balance = await this.provider.getBalance(depositorAddress);
+        if (balance < amountBig)
+          throw new Error(
+            `Insufficient native balance. Required: ${amountBig}, available: ${balance}`,
+          );
+      } else {
+        // ERC-20: approve if needed
+        const tokenContract = new ethers.Contract(
+          feeToken,
+          [
+            "function balanceOf(address) view returns (uint256)",
+            "function allowance(address,address) view returns (uint256)",
+            "function approve(address,uint256) returns (bool)",
+          ],
+          walletWithProvider,
+        );
 
-      const [balance, allowance] = await Promise.all([
-        tokenContract.balanceOf(depositorAddress),
-        tokenContract.allowance(depositorAddress, this.diamondAddress),
-      ]);
+        const [balance, allowance] = await Promise.all([
+          tokenContract.balanceOf(depositorAddress),
+          tokenContract.allowance(depositorAddress, this.diamondAddress),
+        ]);
 
-      if (balance < amountBig)
-        throw new Error(
-          `Insufficient fee token balance. Required: ${amountBig}, available: ${balance}`,
-        );
+        if (balance < amountBig)
+          throw new Error(
+            `Insufficient fee token balance. Required: ${amountBig}, available: ${balance}`,
+          );
 
-      if (allowance < amountBig) {
-        const approveTx = await tokenContract.approve(
-          this.diamondAddress,
-          ethers.MaxUint256,
-        );
-        const receipt = await approveTx.wait();
-        if (!receipt || receipt.status === 0)
-          throw new Error("Fee token approval failed");
+        if (allowance < amountBig) {
+          const approveTx = await tokenContract.approve(
+            this.diamondAddress,
+            ethers.MaxUint256,
+          );
+          const receipt = await approveTx.wait();
+          if (!receipt || receipt.status === 0)
+            throw new Error("Fee token approval failed");
+        }
       }
 
       // 2. EIP-712 AnonymousAddFees signature
@@ -1614,6 +1618,7 @@ export class AnonymousTransferClient {
         this.provider.getFeeData(),
       ]);
 
+      const txValue = isNative ? amountBig : 0n;
       let txObj;
       if (feeData.maxFeePerGas) {
         txObj = {
@@ -1624,7 +1629,7 @@ export class AnonymousTransferClient {
           gasLimit,
           maxFeePerGas: (feeData.maxFeePerGas * 12n) / 10n,
           maxPriorityFeePerGas: feeData.maxPriorityFeePerGas ?? 0n,
-          value: 0n,
+          value: txValue,
         };
       } else {
         txObj = {
@@ -1634,7 +1639,7 @@ export class AnonymousTransferClient {
           chainId: BigInt(this.chainId),
           gasLimit,
           gasPrice: (feeData.gasPrice * 11n) / 10n,
-          value: 0n,
+          value: txValue,
         };
       }
 

package/src/confidential-client.js

@@ -840,52 +840,6 @@ export class ConfidentialTransferClient {
     );
   }
 
-  /**
-   * Wait for pending balance to appear
-   *
-   * @param {string} address - Account address
-   * @param {string} privateKey - Private key for decryption
-   * @param {string} tokenAddress - Token address
-   * @param {Object} [options] - Options
-   * @param {number} [options.maxAttempts=225] - Maximum polling attempts
-   * @param {number} [options.intervalMs=400] - Polling interval in milliseconds
-   * @returns {Promise<{amount: number, ciphertext: string}>}
-   */
-  async _waitForPendingBalance(
-    address,
-    privateKey,
-    tokenAddress,
-    options = {},
-  ) {
-    const { maxAttempts = 225, intervalMs = 400 } = options;
-    await sleep(1000);
-
-    try {
-      for (let i = 0; i < maxAttempts; i++) {
-        const pending = await this._getPendingBalance(
-          address,
-          privateKey,
-          tokenAddress,
-        );
-
-        if (pending.amount > 0n) {
-          return pending;
-        }
-
-        await sleep(intervalMs);
-      }
-
-      throw new Error(
-        `Timeout waiting for pending balance after ${maxAttempts} attempts. The transfer may still be processing.`,
-      );
-    } catch (error) {
-      if (error.message.includes("Timeout waiting for pending balance")) {
-        throw error;
-      }
-      throw new Error(`Failed to wait for pending balance: ${error.message}`);
-    }
-  }
-
   /**
    * Get the current fee amount for confidential transfers
    *

package/src/constants.js

@@ -24,11 +24,11 @@ export const ERC20_ABI = [
 export const TEMPO_FEE_TOKEN_ADDRESS =
   "0x20c0000000000000000000000000000000000000";
 export const STABLETRUST_CONTRACTS_BY_CHAIN_ID = Object.freeze({
-  2201: "0xA98e5ba75Bb44459916D52Abf1604caB3d98CC4B", //Stable
-  5042002: "0xfc29476B8e53765Ca16ea32882370d850b245336", //Arc
-  84532: "0xF66A0a1670F14AE5D1852B4E7d1e4C693b2Accfd", //Base
-  11155111: "0xa066b5C30382110d19925108BBa1Eef613a3A041", //Ethereum
-  421614: "0xbda65d65A7833D28F9391FF01d0b212B75538Cf2", //Arbitrum
+  2201: "0xe1c1456CAb802312759a8cFc3976f88bf87082cf", //Stable
+  5042002: "0x1B4f05f67CC33788Da4C89a7cd0b2f8E0055E605", //Arc
+  84532: "0x4a251C9D79faCa20b193630A4ee313af7cBCDD93", //Base
+  11155111: "0x7507a13352AFAa79D33E994f86f2f62463ba8DE4", //Ethereum
+  421614: "0x5acECCdeb5CbD3C727eCB49F8706Eb80EF2f977F", //Arbitrum
   42431: "0xE559fB936C69c46E216bf61B07C16bF1a6d444aa", //Tempo
 });
 

package/src/index.d.ts

@@ -188,9 +188,7 @@ declare module "@fairblock/stabletrust" {
     /**
      * Get on-chain core state for an anonymous account.
      */
-    getAnonymousAccountInfo(
-      accountId: number | bigint,
-    ): Promise<AnonymousAccountInfo>;
+    getAnonymousAccountInfo(accountId: string): Promise<AnonymousAccountInfo>;
 
     /**
      * Read the current authNonce for an anonymous account.
@@ -211,7 +209,7 @@ declare module "@fairblock/stabletrust" {
      * Use `.available` and `.pending` for individual balances, `.amount` for the total.
      */
     getBalance(
-      accountId: number | bigint,
+      accountId: string,
       tokenAddress: string,
       elGamalPrivateKey: string,
     ): Promise<AnonymousAccountBalance>;
@@ -221,7 +219,7 @@ declare module "@fairblock/stabletrust" {
      * Use `getBalance` for a simpler numeric summary.
      */
     getAnonymousBalance(
-      accountId: number | bigint,
+      accountId: string,
       tokenAddress: string,
       elGamalPrivateKey: string,
     ): Promise<AnonymousBalance>;
@@ -484,7 +482,7 @@ declare module "@fairblock/stabletrust" {
   /**
    * Deposit options
    */
-  export interface DepositOptions {
+  export interface ConfidentialDepositOptions {
     waitForFinalization?: boolean;
   }
 
@@ -560,7 +558,7 @@ declare module "@fairblock/stabletrust" {
       wallet: ethers.Wallet | ethers.Signer,
       tokenAddress: string,
       amount: bigint | string | number,
-      options?: DepositOptions,
+      options?: ConfidentialDepositOptions,
     ): Promise<ethers.ContractTransactionReceipt>;
 
     /**

package/examples/constants.js

@@ -1,6 +0,0 @@
-export const ERC20_ABI = [
-  "function approve(address spender, uint256 amount) external returns (bool)",
-  "function allowance(address owner, address spender) external view returns (uint256)",
-  "function balanceOf(address account) external view returns (uint256)",
-  "function decimals() external view returns (uint8)",
-];