@fairblock/stabletrust 2.0.11 → 2.0.13

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@fairblock/stabletrust",
-  "version": "2.0.11",
+  "version": "2.0.13",
   "description": "SDK for confidential transfers using homomorphic encryption and zero-knowledge proofs",
   "main": "src/index.js",
-  "types": "src/index.d.ts",
+  "types": "src/withdrawal-fees.d.ts",
   "type": "module",
   "sideEffects": [
     "**/*.wasm"
   ],
   "exports": {
     ".": {
-      "types": "./src/index.d.ts",
+      "types": "./src/withdrawal-fees.d.ts",
       "import": "./src/index.js",
       "default": "./src/index.js"
     },

package/src/backend.js

@@ -9,6 +9,7 @@ export const CHAIN_KEY_BY_ID = {
   11155111: "ethereumSepolia",
   421614: "arbitrumSepolia",
   42431: "tempo",
+  42161: "arbitrumOne",
 };
 
 /**

package/src/confidential-client.js

@@ -9,6 +9,7 @@ import {
   ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE,
   ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE,
   getStabletrustContractAddress,
+  STABLETRUST_CONTRACTS_BY_CHAIN_ID,
 } from "./constants.js";
 import { deriveKeys, decryptCiphertext, combineCiphertext } from "./crypto.js";
 import {
@@ -46,6 +47,7 @@ export class ConfidentialTransferClient {
    * @param {string} [options.ipfsUploadUrl] - StableTrust IPFS upload endpoint for off-chain proof uploads
    * @param {string} [options.ipfsApiKey] - Optional bearer token for the StableTrust IPFS upload endpoint
    * @param {string} [options.apiBaseUrl] - StableTrust backend API base URL for request persistence
+   * @param {string} [options.applicationName] - App name stored on request rows (default: "SDK")
    */
   constructor(rpcUrl, contractAddressOrChainId, chainId, options = {}) {
     // Validate required config
@@ -75,9 +77,9 @@ export class ConfidentialTransferClient {
       throw new Error("chainId is required");
     }
     if (!resolvedContractAddress) {
-      const supportedChainIds = [2201, 5042002, 84532, 11155111, 421614, 42431]
-        .map(String)
-        .join(", ");
+      const supportedChainIds = Object.keys(
+        STABLETRUST_CONTRACTS_BY_CHAIN_ID,
+      ).join(", ");
       throw new Error(
         `contractAddress is required for chainId ${resolvedChainId}. No default Stabletrust contract is configured for this chain. Supported chainIds: ${supportedChainIds}`,
       );
@@ -94,6 +96,7 @@ export class ConfidentialTransferClient {
       ipfsUploadUrl: ipfsOptions.ipfsUploadUrl || null,
       ipfsApiKey: ipfsOptions.ipfsApiKey || null,
       apiBaseUrl: ipfsOptions.apiBaseUrl || null,
+      applicationName: ipfsOptions.applicationName || "SDK",
     };
 
     // WASM will be auto-initialized on first use
@@ -126,7 +129,7 @@ export class ConfidentialTransferClient {
     const payload = {
       chainKey: CHAIN_KEY_BY_ID[this.config.chainId] || String(this.config.chainId),
       chainId: this.config.chainId,
-      applicationName: "SDK",
+      applicationName: this.config.applicationName,
       ...data,
     };
     createRequest(payload, apiBaseUrl).catch((err) => {
@@ -869,11 +872,9 @@ export class ConfidentialTransferClient {
         throw new Error("Transfer transaction failed");
       }
 
-      if (waitForFinalization) {
-        await this._waitForGlobalState(senderAddress, "transfer");
-      }
-
-      // IBE-encrypt randomness then persist both records (fire-and-forget, after finalization)
+      // IBE-encrypt randomness and start persisting both records immediately after
+      // the EVM request transaction is mined. This is intentionally independent of
+      // waitForFinalization so the backend record can exist while the action is pending.
       const txHash = receipt.hash;
       const requestId = await this._resolveRequestId(receipt, senderAddress, [
         "TransferRequested",
@@ -897,7 +898,12 @@ export class ConfidentialTransferClient {
             senderEnc.queuedEncrypted && receiverEnc.queuedEncrypted
               ? {
                   queuedEncryptedSenderRandomness: senderEnc.queuedEncrypted,
-                  queuedEncryptedReceiverRandomness: receiverEnc.queuedEncrypted,
+                  queuedEncryptedSenderRandomnessId:
+                    senderEnc.queuedEncryptedId,
+                  queuedEncryptedReceiverRandomness:
+                    receiverEnc.queuedEncrypted,
+                  queuedEncryptedReceiverRandomnessId:
+                    receiverEnc.queuedEncryptedId,
                 }
               : {};
 
@@ -910,7 +916,9 @@ export class ConfidentialTransferClient {
             status: "pending",
             details: transferDetails,
             encryptedSenderRandomness: senderEnc.encrypted,
+            encryptedSenderRandomnessId: senderEnc.encryptedId,
             encryptedReceiverRandomness: receiverEnc.encrypted,
+            encryptedReceiverRandomnessId: receiverEnc.encryptedId,
             ...queuedFields,
           });
 
@@ -923,16 +931,23 @@ export class ConfidentialTransferClient {
             status: "pending",
             details: transferDetails,
             encryptedReceiverRandomness: receiverEnc.encrypted,
+            encryptedReceiverRandomnessId: receiverEnc.encryptedId,
             ...(receiverEnc.queuedEncrypted
               ? {
                   queuedEncryptedReceiverRandomness:
                     receiverEnc.queuedEncrypted,
+                  queuedEncryptedReceiverRandomnessId:
+                    receiverEnc.queuedEncryptedId,
                 }
               : {}),
           });
         })
         .catch(() => {});
 
+      if (waitForFinalization) {
+        await this._waitForGlobalState(senderAddress, "transfer");
+      }
+
       return receipt;
     } catch (error) {
       const message = error?.message ?? String(error);

package/src/constants.js

@@ -12,9 +12,13 @@ const APPLY_PENDING_SIGNATURE = "applyPending()";
 export const TRANSFER_CONFIDENTIAL_SIGNATURE = "transferConfidential(address,address,bytes,bool)";
 export const WITHDRAW_CONFIDENTIAL_SIGNATURE = "withdraw(address,uint256,bytes,bool)";
 export const FEE_TOKEN_SIGNATURE = "feeToken()";
+export const FEE_ACCOUNT_SIGNATURE = "feeAccount()";
 export const NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE = "nonAnonymousTransferFee()";
+export const NON_ANONYMOUS_WITHDRAW_FEE_SIGNATURE = "nonAnonymousWithdrawFee()";
+export const NON_ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE = "nonAnonymousWithdrawFeePpm()";
 export const ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE = "anonymousIpfsTransferFee()";
 export const ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE = "anonymousInlineTransferFee()";
+export const ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE = "anonymousWithdrawFeePpm()";
 
 export const CONTRACT_ABI = [
   `function ${CREATE_CONFIDENTIAL_ACCOUNT_SIGNATURE} external`,
@@ -23,21 +27,29 @@ export const CONTRACT_ABI = [
   `function ${GET_AVAILABLE_SIGNATURE} external view returns (bytes c1, bytes c2)`,
   `function ${GET_PENDING_SIGNATURE} external view returns (bytes c1, bytes c2)`,
   `function ${TRANSFER_CONFIDENTIAL_SIGNATURE} external payable`,
-  `function ${WITHDRAW_CONFIDENTIAL_SIGNATURE} external`,
+  `function ${WITHDRAW_CONFIDENTIAL_SIGNATURE} external payable`,
   `function ${APPLY_PENDING_SIGNATURE} external`,
   `function ${FEE_TOKEN_SIGNATURE} external view returns (address)`,
+  `function ${FEE_ACCOUNT_SIGNATURE} external view returns (address)`,
   `function ${NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE} external view returns (uint256)`,
+  `function ${NON_ANONYMOUS_WITHDRAW_FEE_SIGNATURE} external view returns (uint256)`,
+  `function ${NON_ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE} external view returns (uint256)`,
   `function ${ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE} external view returns (uint256)`,
   `function ${ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE} external view returns (uint256)`,
-  // Events used to extract request/tx IDs from receipts for backend persistence
-  "event DepositRequested(address indexed ownerAddr, uint256 indexed txId, address indexed token, uint256 plainAmount, bytes availableShare, bytes pendingShare)",
-  "event DepositProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, string errorMsg, address token, bytes newAvailC1, bytes newAvailC2, uint64 pendingCreditCounter, uint64 minimumPendingCreditCounter, bytes availableShare, bytes pendingShare)",
-  "event TransferRequested(address indexed sender, address indexed recipient, uint256 indexed txId, address token, bytes proof, uint256 feePaid, bool useOffchainVerify, bytes senderPubkey, bytes recipientPubkey, bytes senderCurrC1, bytes senderCurrC2)",
-  "event TransferProcessed(address indexed sender, address indexed recipient, uint256 indexed txId, bool ok, string errorMsg, address token, bytes senderNewAvailC1, bytes senderNewAvailC2, bytes recipientNewPendingC1, bytes recipientNewPendingC2, uint64 senderPendingCreditCounter, bytes senderAvailableShare, uint64 recipientPendingCreditCounter, uint64 recipientMinimumPendingCreditCounter, bytes recipientPendingShare)",
+  `function ${ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE} external view returns (uint256)`,
+
+  // Current ConfidentialMirror Diamond events. ResultCode is a Solidity enum
+  // and therefore appears as uint8 in the ABI.
+  "event CreateAccountRequested(address indexed ownerAddr, uint256 indexed txId, bytes elgamalPubkey)",
+  "event CreateAccountProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, uint8 code, bytes elgamalPubkey)",
+  "event DepositRequested(address indexed ownerAddr, uint256 indexed txId, address indexed token, uint256 plainAmount, bytes availableC1, bytes availableC2)",
+  "event DepositProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, uint8 code, address token, bytes newAvailC1, bytes newAvailC2, uint64 pendingCreditCounter)",
+  "event TransferRequested(address indexed sender, address indexed recipient, uint256 indexed txId, address token, bytes proof, bytes senderPubkey, bytes recipientPubkey, bytes senderCurrC1, bytes senderCurrC2, bool offchainZKP)",
+  "event TransferProcessed(address indexed sender, address indexed recipient, uint256 indexed txId, bool ok, uint8 code, address token, bytes senderNewAvailC1, bytes senderNewAvailC2, bytes recipientNewPendingC1, bytes recipientNewPendingC2, uint64 senderPendingCreditCounter, uint64 recipientPendingCreditCounter)",
   "event ApplyPendingRequested(address indexed ownerAddr, uint256 indexed txId)",
-  "event ApplyPendingProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, string errorMsg, address[] tokens, bytes[] newAvailC1, bytes[] newAvailC2, uint64 pendingCreditCounter, uint64 minimumPendingCreditCounter, bytes availableShare)",
-  "event WithdrawRequested(address indexed ownerAddr, uint256 indexed txId, address token, uint256 plainAmount, bytes proof, bool useOffchainVerify, bytes userPubkey, bytes userCurrC1, bytes userCurrC2)",
-  "event WithdrawProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, string errorMsg, address token, uint256 plainAmount, bytes newAvailC1, bytes newAvailC2, uint64 pendingCreditCounter, uint64 minimumPendingCreditCounter, bytes availableShare)",
+  "event ApplyPendingProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, uint8 code, address[] tokens, bytes[] newAvailC1, bytes[] newAvailC2, uint64 pendingCreditCounter)",
+  "event WithdrawRequested(address indexed ownerAddr, uint256 indexed txId, address token, uint256 plainAmount, bytes proof, bytes userPubkey, bytes userCurrC1, bytes userCurrC2, bool offchainZKP)",
+  "event WithdrawProcessed(address indexed ownerAddr, uint256 indexed txId, bool ok, uint8 code, address token, uint256 plainAmount, bytes newAvailC1, bytes newAvailC2, uint64 pendingCreditCounter)",
 ];
 
 export const ERC20_ABI = [
@@ -57,6 +69,7 @@ export const STABLETRUST_CONTRACTS_BY_CHAIN_ID = Object.freeze({
   11155111: "0x7507a13352AFAa79D33E994f86f2f62463ba8DE4", //Ethereum
   421614: "0x5acECCdeb5CbD3C727eCB49F8706Eb80EF2f977F", //Arbitrum
   42431: "0xE559fB936C69c46E216bf61B07C16bF1a6d444aa", //Tempo
+  42161: "0xCAA6384D5Ac8b9111D482dd676BB890f2b6e9513", //Arbitrum One (mainnet)
 });
 
 export function getStabletrustContractAddress(chainId) {

package/src/controlled-confidential-client.js

@@ -0,0 +1,265 @@
+import { ethers } from "ethers";
+import { ConfidentialTransferClient } from "./confidential-client.js";
+import { encodeTransferProof, encodeWithdrawProof, toContractScale } from "./utils.js";
+
+/**
+ * ConfidentialTransferClient variant for orchestrators that need explicit
+ * ownership of pending-balance application and transaction lifecycle.
+ *
+ * Backwards compatibility is preserved by keeping autoApplyPending=true by
+ * default. CTS sets it to false so applyPending remains an explicit workload
+ * action rather than being hidden inside deposit/transfer/withdraw helpers.
+ */
+export class ControlledConfidentialTransferClient extends ConfidentialTransferClient {
+  constructor(rpcUrl, contractAddressOrChainId, chainId, options = {}) {
+    const resolvedOptions =
+      typeof chainId === "object" && chainId !== null ? chainId : options || {};
+
+    super(rpcUrl, contractAddressOrChainId, chainId, options);
+    this.autoApplyPending = resolvedOptions.autoApplyPending !== false;
+    const configuredSafetyBps = Number(resolvedOptions.gasLimitSafetyBps ?? 2500);
+    if (!Number.isFinite(configuredSafetyBps) || configuredSafetyBps < 0) {
+      throw new Error("gasLimitSafetyBps must be a non-negative finite number");
+    }
+    this.gasLimitSafetyBps = BigInt(Math.trunc(configuredSafetyBps));
+  }
+
+  async _applyPendingIfNeeded(wallet, privateKey, tokenAddress, actionLabel) {
+    if (!this.autoApplyPending) return false;
+    await super._applyPendingIfNeeded(wallet, privateKey, tokenAddress, actionLabel);
+    return true;
+  }
+
+  /**
+   * Estimate gas immediately before broadcast and add configurable headroom.
+   * Some public RPCs return estimates with too little margin for state that can
+   * change between estimation and execution. Passing an explicit padded limit
+   * prevents otherwise-valid CTS operations from failing with OutOfGas.
+   */
+  async _submitWithGasSafety(contract, methodName, args = [], overrides = {}) {
+    const method = contract[methodName];
+    if (typeof method !== "function" || typeof method.estimateGas !== "function") {
+      throw new Error(`Contract method ${methodName} is unavailable`);
+    }
+    if (overrides.gasLimit !== undefined) {
+      return await method(...args, overrides);
+    }
+    const estimate = await method.estimateGas(...args, overrides);
+    const gasLimit =
+      (estimate * (10000n + this.gasLimitSafetyBps) + 9999n) / 10000n;
+    return await method(...args, { ...overrides, gasLimit });
+  }
+
+  /**
+   * Submit account creation and return immediately after broadcast. The caller
+   * owns receipt waiting and contract-state reconciliation.
+   */
+  async submitCreateAccount(wallet) {
+    if (!wallet) throw new Error("Wallet is required");
+    const address = await wallet.getAddress();
+    const keys = await this._deriveKeys(wallet);
+    const account = await this.getAccountInfo(address);
+    if (account.exists) return { created: false, keys, tx: null, account };
+
+    const contract = this.contract.connect(wallet);
+    const tx = await this._submitWithGasSafety(
+      contract,
+      "createConfidentialAccount",
+      [Buffer.from(keys.publicKey, "base64")],
+    );
+    return { created: true, keys, tx, account };
+  }
+
+  /**
+   * Submit a deposit without performing an implicit ERC-20 approval. This is
+   * intentional for orchestrators: approval is a separate auditable operation.
+   */
+  async submitDeposit(wallet, tokenAddress, amount) {
+    if (!wallet) throw new Error("Wallet is required");
+    if (!ethers.isAddress(tokenAddress)) throw new Error(`Invalid token address: ${tokenAddress}`);
+    const rawAmount = BigInt(amount);
+    if (rawAmount <= 0n) throw new Error("Amount must be greater than 0");
+
+    const address = await wallet.getAddress();
+    const token = this._getTokenContract(tokenAddress);
+    const [decimals, balance, allowance] = await Promise.all([
+      token.decimals(),
+      token.balanceOf(address),
+      token.allowance(address, this.config.contractAddress),
+    ]);
+    if (balance < rawAmount) {
+      throw new Error(`Insufficient token balance. Required: ${rawAmount}, Available: ${balance}`);
+    }
+    if (allowance < rawAmount) {
+      throw new Error(`Insufficient token allowance. Required: ${rawAmount}, Available: ${allowance}`);
+    }
+
+    const plainAmount = toContractScale(rawAmount, decimals);
+    return await this._submitWithGasSafety(
+      this.contract.connect(wallet),
+      "deposit",
+      [tokenAddress, plainAmount],
+    );
+  }
+
+  /** Submit a normal-to-normal confidential transfer after proof generation. */
+  async submitTransfer(wallet, recipientAddress, tokenAddress, amount, options = {}) {
+    if (!wallet) throw new Error("Sender wallet is required");
+    if (!ethers.isAddress(recipientAddress)) throw new Error(`Invalid recipient address: ${recipientAddress}`);
+    if (!ethers.isAddress(tokenAddress)) throw new Error(`Invalid token address: ${tokenAddress}`);
+    const rawAmount = BigInt(amount);
+    if (rawAmount <= 0n) throw new Error("Transfer amount must be greater than 0");
+
+    const offchainZKP = this._resolveOffchainZKP(options);
+    const token = this._getTokenContract(tokenAddress);
+    const tokenDecimals = await token.decimals();
+    const transferAmount = toContractScale(rawAmount, tokenDecimals);
+    const senderAddress = await wallet.getAddress();
+
+    const [senderKeys, recipientAccount] = await Promise.all([
+      this._deriveKeys(wallet),
+      this.getAccountInfo(recipientAddress),
+    ]);
+    if (!senderKeys?.privateKey) throw new Error("Failed to derive sender keys");
+    if (!recipientAccount.exists || !recipientAccount.finalized) {
+      throw new Error(`Recipient account does not exist or is not finalized. Address: ${recipientAddress}`);
+    }
+
+    let recipientPublicKey = recipientAccount.elgamalPubkey;
+    if (!recipientPublicKey) throw new Error("Recipient public key is required");
+    if (typeof recipientPublicKey === "string" && recipientPublicKey.startsWith("0x")) {
+      recipientPublicKey = Buffer.from(recipientPublicKey.slice(2), "hex").toString("base64");
+    }
+
+    const balance = await this.getConfidentialBalance(senderAddress, senderKeys.privateKey, tokenAddress);
+    const available = balance.available.amount;
+    if (!balance.available.ciphertext) throw new Error("Current balance ciphertext is required");
+    if (available < rawAmount) {
+      throw new Error(`Insufficient balance. Required: ${rawAmount}, Available: ${available}`);
+    }
+
+    const currentBalanceContractScale =
+      (BigInt(available) * 100n) / 10n ** BigInt(tokenDecimals);
+    const wasm = await this._getWasm();
+    const proof = JSON.parse(
+      wasm.generate_transfer_proof(
+        JSON.stringify({
+          current_balance_ciphertext: balance.available.ciphertext,
+          current_balance: Number(currentBalanceContractScale),
+          transfer_amount: Number(transferAmount),
+          source_keypair: senderKeys.privateKey,
+          destination_pubkey: recipientPublicKey,
+        }),
+      ),
+    );
+    if (!proof.success) {
+      throw new Error(`Proof generation failed: ${proof.error || "Unknown error"}`);
+    }
+
+    const encodedProof = ethers.getBytes(encodeTransferProof(proof.data));
+    const proofArg = await this._resolveContractProofArg(
+      encodedProof,
+      "transfer-proof.bin",
+      offchainZKP,
+    );
+    const overrides = await this._prepareNonAnonymousTransferFee(wallet);
+    return await this._submitWithGasSafety(
+      this.contract.connect(wallet),
+      "transferConfidential",
+      [recipientAddress, tokenAddress, proofArg, offchainZKP],
+      overrides,
+    );
+  }
+
+  /** Submit an explicit applyPending transaction and return the tx response. */
+  async submitApplyPending(wallet) {
+    if (!wallet) throw new Error("Wallet is required");
+    return await this._submitWithGasSafety(
+      this.contract.connect(wallet),
+      "applyPending",
+    );
+  }
+
+  /** Submit a withdrawal after proof generation and return immediately. */
+  async submitWithdraw(wallet, tokenAddress, amount, options = {}) {
+    if (!wallet) throw new Error("Wallet is required");
+    if (!ethers.isAddress(tokenAddress)) throw new Error(`Invalid token address: ${tokenAddress}`);
+    const rawAmount = BigInt(amount);
+    if (rawAmount <= 0n) throw new Error("Withdrawal amount must be greater than 0");
+
+    const offchainZKP = this._resolveOffchainZKP(options);
+    const token = this._getTokenContract(tokenAddress);
+    const tokenDecimals = await token.decimals();
+    const withdrawAmount = toContractScale(rawAmount, tokenDecimals);
+    const keys = await this._deriveKeys(wallet);
+    if (!keys?.privateKey) throw new Error("Failed to derive keys");
+
+    const address = await wallet.getAddress();
+    const balance = await this.getConfidentialBalance(address, keys.privateKey, tokenAddress);
+    if (!balance.available.ciphertext) throw new Error("Current balance ciphertext is required");
+    if (balance.available.amount < rawAmount) {
+      throw new Error(`Insufficient balance. Required: ${rawAmount}, Available: ${balance.available.amount}`);
+    }
+
+    const currentBalanceContractScale =
+      (BigInt(balance.available.amount) * 100n) / 10n ** BigInt(tokenDecimals);
+    const account = await this.getAccountInfo(address);
+    const txID = BigInt(account.txId ?? 0n);
+    const wasm = await this._getWasm();
+    const proof = JSON.parse(
+      wasm.generate_withdraw_proof(
+        JSON.stringify({
+          current_balance_ciphertext: balance.available.ciphertext,
+          current_balance: Number(currentBalanceContractScale),
+          withdraw_amount: Number(withdrawAmount),
+          keypair: keys.privateKey,
+          nonce: Number(txID + 1n),
+        }),
+      ),
+    );
+    if (!proof.success) {
+      throw new Error(`Withdrawal proof generation failed: ${proof.error || "Unknown error"}`);
+    }
+
+    const encodedProof = ethers.getBytes(encodeWithdrawProof(proof.data));
+    const proofArg = await this._resolveContractProofArg(
+      encodedProof,
+      "withdraw-proof.bin",
+      offchainZKP,
+    );
+    return await this._submitWithGasSafety(
+      this.contract.connect(wallet),
+      "withdraw",
+      [tokenAddress, withdrawAmount, proofArg, offchainZKP],
+    );
+  }
+
+  /**
+   * Compatibility helper that keeps the older wait-for-receipt behavior.
+   */
+  async createAccount(wallet, options = {}) {
+    const { waitForFinalization = true } = options;
+    const submitted = await this.submitCreateAccount(wallet);
+    if (!submitted.created) {
+      let account = submitted.account;
+      if (waitForFinalization && !account.finalized) {
+        await this._waitForGlobalState(await wallet.getAddress(), "account creation");
+        account = await this.getAccountInfo(await wallet.getAddress());
+      }
+      return { created: false, keys: submitted.keys, receipt: null, account };
+    }
+
+    const receipt = await submitted.tx.wait();
+    if (!receipt || receipt.status === 0) throw new Error("Account creation transaction failed");
+    if (waitForFinalization) {
+      await this._waitForGlobalState(await wallet.getAddress(), "account creation");
+    }
+    const account = await this.getAccountInfo(await wallet.getAddress());
+    return { created: true, keys: submitted.keys, receipt, account };
+  }
+
+  /** Public explicit applyPending entry point preserving receipt-wait behavior. */
+  async applyPending(wallet, options = {}) {
+    return await this._applyPending(wallet, options);
+  }
+}

package/src/fee-aware-clients.js

@@ -0,0 +1,430 @@
+import { ethers } from "ethers";
+import { ConfidentialTransferClient as BaseConfidentialTransferClient } from "./confidential-client.js";
+import { ControlledConfidentialTransferClient as BaseControlledConfidentialTransferClient } from "./controlled-confidential-client.js";
+import { AnonymousTransferClient as BaseAnonymousTransferClient } from "./anonymous-client.js";
+import { encodeWithdrawProof, toContractScale, validateAnonymousAccountId } from "./utils.js";
+import {
+  TRANSFER_CONFIDENTIAL_SIGNATURE,
+  WITHDRAW_CONFIDENTIAL_SIGNATURE,
+  FEE_TOKEN_SIGNATURE,
+  FEE_ACCOUNT_SIGNATURE,
+  NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE,
+  NON_ANONYMOUS_WITHDRAW_FEE_SIGNATURE,
+  NON_ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE,
+  ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE,
+  ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE,
+  ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE,
+} from "./constants.js";
+
+export const WITHDRAW_FEE_PPM_DENOMINATOR = 1_000_000n;
+
+function calculatePercentageFee(grossAmount, ppm) {
+  const gross = BigInt(grossAmount);
+  const rate = BigInt(ppm);
+  if (rate < 0n || rate >= WITHDRAW_FEE_PPM_DENOMINATOR) {
+    throw new Error(
+      `Withdrawal fee PPM must be between 0 and ${WITHDRAW_FEE_PPM_DENOMINATOR - 1n}`,
+    );
+  }
+  return (gross * rate) / WITHDRAW_FEE_PPM_DENOMINATOR;
+}
+
+function grossAfterContractScale(rawAmount, tokenDecimals) {
+  const scaled = toContractScale(rawAmount, tokenDecimals);
+  const divisor = 10n ** BigInt(tokenDecimals);
+  return (scaled * divisor) / 100n;
+}
+
+const nonAnonymousFeeMethods = {
+  _assertLatestContractAbi() {
+    const requiredSignatures = [
+      TRANSFER_CONFIDENTIAL_SIGNATURE,
+      WITHDRAW_CONFIDENTIAL_SIGNATURE,
+      FEE_TOKEN_SIGNATURE,
+      FEE_ACCOUNT_SIGNATURE,
+      NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE,
+      NON_ANONYMOUS_WITHDRAW_FEE_SIGNATURE,
+      NON_ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE,
+      ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE,
+      ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE,
+      ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE,
+    ];
+
+    const missingSignatures = requiredSignatures.filter(
+      (signature) => !this.contract.interface.getFunction(signature),
+    );
+    if (missingSignatures.length > 0) {
+      throw new Error(
+        `Installed @fairblock/stabletrust ABI is stale or incomplete. Missing ${missingSignatures.join(", ")}. Reinstall/update the SDK.`,
+      );
+    }
+  },
+
+  async getFeeAccount() {
+    try {
+      return ethers.getAddress(await this.contract.feeAccount());
+    } catch (error) {
+      throw new Error(`Failed to get fee account: ${error.message}`);
+    }
+  },
+
+  async getNonAnonymousWithdrawFee() {
+    try {
+      return await this.contract.nonAnonymousWithdrawFee();
+    } catch (error) {
+      throw new Error(`Failed to get non-anonymous withdrawal fixed fee: ${error.message}`);
+    }
+  },
+
+  async getNonAnonymousWithdrawFeePpm() {
+    try {
+      return await this.contract.nonAnonymousWithdrawFeePpm();
+    } catch (error) {
+      throw new Error(`Failed to get non-anonymous withdrawal percentage fee: ${error.message}`);
+    }
+  },
+
+  async getAnonymousWithdrawFeePpm() {
+    try {
+      return await this.contract.anonymousWithdrawFeePpm();
+    } catch (error) {
+      throw new Error(`Failed to get anonymous withdrawal percentage fee: ${error.message}`);
+    }
+  },
+
+  async _prepareNonAnonymousWithdrawFee(wallet) {
+    const [feeTokenRaw, feeAmountRaw] = await Promise.all([
+      this.contract.feeToken(),
+      this.contract.nonAnonymousWithdrawFee(),
+    ]);
+
+    const feeToken = ethers.getAddress(feeTokenRaw);
+    const feeAmount = BigInt(feeAmountRaw);
+    if (feeAmount === 0n) return { value: 0n };
+
+    if (feeToken === ethers.ZeroAddress) {
+      return { value: feeAmount };
+    }
+
+    const senderAddress = await wallet.getAddress();
+    const feeTokenContract = this._getTokenContract(feeToken);
+    const [balance, allowance] = await Promise.all([
+      feeTokenContract.balanceOf(senderAddress),
+      feeTokenContract.allowance(senderAddress, this.config.contractAddress),
+    ]);
+
+    if (balance < feeAmount) {
+      throw new Error(
+        `Insufficient withdrawal fee token balance. Required: ${feeAmount}, available: ${balance}, fee token: ${feeToken}`,
+      );
+    }
+
+    if (allowance < feeAmount) {
+      const approveTx = await feeTokenContract
+        .connect(wallet)
+        .approve(this.config.contractAddress, ethers.MaxUint256);
+      const approveReceipt = await approveTx.wait();
+      if (!approveReceipt || approveReceipt.status === 0) {
+        throw new Error("Withdrawal fee token approval failed");
+      }
+    }
+
+    return { value: 0n };
+  },
+
+  async getWithdrawalFeeQuote(tokenAddress, amount) {
+    if (!ethers.isAddress(tokenAddress)) {
+      throw new Error(`Invalid token address: ${tokenAddress}`);
+    }
+    const rawAmount = BigInt(amount);
+    if (rawAmount <= 0n) throw new Error("Withdrawal amount must be greater than 0");
+
+    const token = this._getTokenContract(tokenAddress);
+    const [tokenDecimals, fixedFee, fixedFeeToken, percentageFeePpm] = await Promise.all([
+      token.decimals(),
+      this.getNonAnonymousWithdrawFee(),
+      this.getFeeToken(),
+      this.getNonAnonymousWithdrawFeePpm(),
+    ]);
+    const grossAmount = grossAfterContractScale(rawAmount, tokenDecimals);
+    const estimatedPercentageFee = calculatePercentageFee(grossAmount, percentageFeePpm);
+
+    return {
+      grossAmount,
+      fixedFee: BigInt(fixedFee),
+      fixedFeeToken,
+      percentageFeePpm: BigInt(percentageFeePpm),
+      estimatedPercentageFee,
+      withdrawalToken: ethers.getAddress(tokenAddress),
+      estimatedNetAmount: grossAmount - estimatedPercentageFee,
+    };
+  },
+};
+
+export class ConfidentialTransferClient extends BaseConfidentialTransferClient {
+  _assertLatestContractAbi() {
+    return nonAnonymousFeeMethods._assertLatestContractAbi.call(this);
+  }
+  getFeeAccount() { return nonAnonymousFeeMethods.getFeeAccount.call(this); }
+  getNonAnonymousWithdrawFee() { return nonAnonymousFeeMethods.getNonAnonymousWithdrawFee.call(this); }
+  getNonAnonymousWithdrawFeePpm() { return nonAnonymousFeeMethods.getNonAnonymousWithdrawFeePpm.call(this); }
+  getAnonymousWithdrawFeePpm() { return nonAnonymousFeeMethods.getAnonymousWithdrawFeePpm.call(this); }
+  _prepareNonAnonymousWithdrawFee(wallet) { return nonAnonymousFeeMethods._prepareNonAnonymousWithdrawFee.call(this, wallet); }
+  getWithdrawalFeeQuote(tokenAddress, amount) { return nonAnonymousFeeMethods.getWithdrawalFeeQuote.call(this, tokenAddress, amount); }
+
+  async withdraw(wallet, tokenAddress, amount, options = {}) {
+    const { waitForFinalization = true } = options;
+    const offchainZKP = this._resolveOffchainZKP(options);
+
+    try {
+      if (!wallet) throw new Error("Wallet is required");
+      if (!tokenAddress || !ethers.isAddress(tokenAddress)) {
+        throw new Error(`Invalid token address: ${tokenAddress}`);
+      }
+      if (!amount || BigInt(amount) <= 0n) {
+        throw new Error("Withdrawal amount must be greater than 0");
+      }
+
+      const tokenContract = this._getTokenContract(tokenAddress);
+      const tokenDecimals = await tokenContract.decimals();
+      const withdrawAmount = toContractScale(amount, tokenDecimals);
+
+      const derivedKeys = await this._deriveKeys(wallet);
+      if (!derivedKeys?.privateKey) throw new Error("Failed to derive keys");
+
+      const address = await wallet.getAddress();
+      let balanceSummary = await this.getConfidentialBalance(
+        address,
+        derivedKeys.privateKey,
+        tokenAddress,
+      );
+
+      if (balanceSummary.available.amount < BigInt(amount)) {
+        await this._applyPendingIfNeeded(
+          wallet,
+          derivedKeys.privateKey,
+          tokenAddress,
+          "withdraw",
+        );
+        balanceSummary = await this.getConfidentialBalance(
+          address,
+          derivedKeys.privateKey,
+          tokenAddress,
+        );
+      }
+
+      const currentBalanceCiphertext = balanceSummary.available.ciphertext;
+      const currentBalance = balanceSummary.available.amount;
+      if (!currentBalanceCiphertext) {
+        throw new Error("Current balance ciphertext is required. Did you call getConfidentialBalance()?");
+      }
+      if (balanceSummary.amount < BigInt(amount)) {
+        throw new Error(`Insufficient balance. Required: ${amount}, Total: ${balanceSummary.amount}`);
+      }
+      if (currentBalance === undefined || currentBalance < BigInt(amount)) {
+        throw new Error(`Insufficient balance. Required: ${amount}, Available: ${currentBalance}`);
+      }
+
+      const currentBalanceContractScale =
+        (BigInt(currentBalance) * 100n) / 10n ** BigInt(tokenDecimals);
+      const accountInfo = await this.getAccountInfo(address);
+      const txId = BigInt(accountInfo.txId ?? 0n);
+
+      const wasm = await this._getWasm();
+      const proof = JSON.parse(
+        wasm.generate_withdraw_proof(
+          JSON.stringify({
+            current_balance_ciphertext: currentBalanceCiphertext,
+            current_balance: Number(currentBalanceContractScale),
+            withdraw_amount: Number(withdrawAmount),
+            keypair: derivedKeys.privateKey,
+            nonce: Number(txId + 1n),
+          }),
+        ),
+      );
+      if (!proof.success) {
+        throw new Error(
+          `Withdrawal proof generation failed: ${proof.error || "Unknown error. Check your balance and amount."}`,
+        );
+      }
+
+      const encodedProof = ethers.getBytes(encodeWithdrawProof(proof.data));
+      const withdrawZkpArg = await this._resolveContractProofArg(
+        encodedProof,
+        "withdraw-proof.bin",
+        offchainZKP,
+      );
+      const txOverrides = await this._prepareNonAnonymousWithdrawFee(wallet);
+
+      const tx = await this.contract.connect(wallet).withdraw(
+        tokenAddress,
+        BigInt(withdrawAmount),
+        withdrawZkpArg,
+        offchainZKP,
+        txOverrides,
+      );
+      const receipt = await tx.wait();
+      if (!receipt || receipt.status === 0) throw new Error("Withdrawal transaction failed");
+
+      if (waitForFinalization) {
+        await this._waitForGlobalState(address, "withdraw");
+      }
+
+      const requestId = await this._resolveRequestId(receipt, address, [
+        "WithdrawRequested",
+        "WithdrawProcessed",
+      ]);
+      const tokenSymbol = await tokenContract.symbol();
+      this._postRequest({
+        requestId,
+        userAddress: address.toLowerCase(),
+        operationKind: 4,
+        type: "withdraw",
+        transactionHash: receipt.hash,
+        status: "pending",
+        details: {
+          token: tokenSymbol,
+          tokenAddress,
+          amount: withdrawAmount.toString(),
+          amountInWei: true,
+        },
+      });
+
+      return receipt;
+    } catch (error) {
+      const message = error?.message ?? String(error);
+      if (
+        message.includes("Insufficient balance") ||
+        message.includes("fee token balance") ||
+        message.includes("proof generation failed")
+      ) {
+        throw error;
+      }
+      throw new Error(`Failed to withdraw: ${message}`);
+    }
+  }
+}
+
+export class ControlledConfidentialTransferClient extends BaseControlledConfidentialTransferClient {
+  _assertLatestContractAbi() {
+    return nonAnonymousFeeMethods._assertLatestContractAbi.call(this);
+  }
+  getFeeAccount() { return nonAnonymousFeeMethods.getFeeAccount.call(this); }
+  getNonAnonymousWithdrawFee() { return nonAnonymousFeeMethods.getNonAnonymousWithdrawFee.call(this); }
+  getNonAnonymousWithdrawFeePpm() { return nonAnonymousFeeMethods.getNonAnonymousWithdrawFeePpm.call(this); }
+  getAnonymousWithdrawFeePpm() { return nonAnonymousFeeMethods.getAnonymousWithdrawFeePpm.call(this); }
+  _prepareNonAnonymousWithdrawFee(wallet) { return nonAnonymousFeeMethods._prepareNonAnonymousWithdrawFee.call(this, wallet); }
+  getWithdrawalFeeQuote(tokenAddress, amount) { return nonAnonymousFeeMethods.getWithdrawalFeeQuote.call(this, tokenAddress, amount); }
+
+  async _submitWithGasSafety(contract, methodName, args = [], overrides = {}) {
+    let resolvedOverrides = overrides;
+    if (methodName === "withdraw" && overrides.value === undefined) {
+      const feeOverrides = await this._prepareNonAnonymousWithdrawFee(contract.runner);
+      resolvedOverrides = { ...feeOverrides, ...overrides };
+    }
+    return await super._submitWithGasSafety(
+      contract,
+      methodName,
+      args,
+      resolvedOverrides,
+    );
+  }
+}
+
+export class AnonymousTransferClient extends BaseAnonymousTransferClient {
+  async getFeeAccount() {
+    try {
+      const data = await this._fetch("GET", "/v1/views/fee-account");
+      const raw = data.result ?? data;
+      const addr = typeof raw === "string" ? raw : raw.feeAccount ?? raw;
+      return ethers.getAddress(addr);
+    } catch (error) {
+      throw new Error(`Failed to get fee account: ${error.message}`);
+    }
+  }
+
+  async getNonAnonymousWithdrawFee() {
+    try {
+      const data = await this._fetch("GET", "/v1/views/fees/non-anonymous-withdraw-fixed");
+      return BigInt(data.result ?? data);
+    } catch (error) {
+      throw new Error(`Failed to get non-anonymous withdrawal fixed fee: ${error.message}`);
+    }
+  }
+
+  async getNonAnonymousWithdrawFeePpm() {
+    try {
+      const data = await this._fetch("GET", "/v1/views/fees/non-anonymous-withdraw-ppm");
+      return BigInt(data.result ?? data);
+    } catch (error) {
+      throw new Error(`Failed to get non-anonymous withdrawal percentage fee: ${error.message}`);
+    }
+  }
+
+  async getAnonymousWithdrawFeePpm() {
+    try {
+      const data = await this._fetch("GET", "/v1/views/fees/anonymous-withdraw-ppm");
+      return BigInt(data.result ?? data);
+    } catch (error) {
+      throw new Error(`Failed to get anonymous withdrawal percentage fee: ${error.message}`);
+    }
+  }
+
+  async _assertSufficientWithdrawPrepaidFees(accountId, offchainZKP) {
+    validateAnonymousAccountId(accountId, "accountId");
+    const fixedFeePromise = offchainZKP
+      ? this.getAnonymousIpfsWithdrawFee()
+      : this.getAnonymousInlineWithdrawFee();
+    const [feeToken, fixedFee] = await Promise.all([
+      this.getFeeToken(),
+      fixedFeePromise,
+    ]);
+    if (fixedFee === 0n) return;
+
+    const balance = await this.getPrepaidFeeBalance(accountId, feeToken);
+    if (balance < fixedFee) {
+      const path = offchainZKP ? "IPFS" : "inline";
+      throw new Error(
+        `Insufficient prepaid fee balance for anonymous account "${accountId}" (${path} withdrawal). ` +
+          `Required: ${fixedFee} (raw units of fee token ${feeToken}), available: ${balance}. ` +
+          `The success-only percentage withdrawal fee is not part of this prepaid requirement.`,
+      );
+    }
+  }
+
+  async getAnonymousWithdrawalFeeQuote(tokenAddress, amount, { offchainZKP = false } = {}) {
+    if (!ethers.isAddress(tokenAddress)) {
+      throw new Error(`Invalid token address: ${tokenAddress}`);
+    }
+    const rawAmount = BigInt(amount);
+    if (rawAmount <= 0n) throw new Error("Withdrawal amount must be greater than 0");
+
+    const fixedFeePromise = offchainZKP
+      ? this.getAnonymousIpfsWithdrawFee()
+      : this.getAnonymousInlineWithdrawFee();
+    const [tokenDecimals, fixedFee, fixedFeeToken, percentageFeePpm] = await Promise.all([
+      this._fetchTokenDecimals(tokenAddress),
+      fixedFeePromise,
+      this.getFeeToken(),
+      this.getAnonymousWithdrawFeePpm(),
+    ]);
+    const grossAmount = grossAfterContractScale(rawAmount, tokenDecimals);
+    const estimatedPercentageFee = calculatePercentageFee(grossAmount, percentageFeePpm);
+
+    return {
+      grossAmount,
+      fixedFee: BigInt(fixedFee),
+      fixedFeeToken,
+      percentageFeePpm: BigInt(percentageFeePpm),
+      estimatedPercentageFee,
+      withdrawalToken: ethers.getAddress(tokenAddress),
+      estimatedNetAmount: grossAmount - estimatedPercentageFee,
+    };
+  }
+
+  async withdraw(authWallet, accountId, params, options = {}) {
+    const offchainZKP = Boolean(params?.offchainZKP ?? false);
+    await this._assertSufficientWithdrawPrepaidFees(accountId, offchainZKP);
+    return await super.withdraw(authWallet, accountId, params, options);
+  }
+}

package/src/ibe.js

@@ -10,6 +10,16 @@ function extractPublicKey(pubkeyObj) {
   return pubkeyObj?.public_key || pubkeyObj?.pubkey || null;
 }
 
+/**
+ * Build IBE identity: address (lowercase) + chain public key.
+ * @param {string} userAddress
+ * @param {string} publicKey
+ * @returns {string}
+ */
+function buildIbeId(userAddress, publicKey) {
+  return userAddress.toLowerCase() + publicKey;
+}
+
 async function getIbePublicKeys() {
   if (cachedIbePublicKeys) return cachedIbePublicKeys;
 
@@ -40,20 +50,37 @@ async function getIbePublicKeys() {
  * Always encrypts under the active pubkey; also encrypts under the queued
  * pubkey when the chain reports one (backup for key rotation).
  *
- * @param {string} userAddress - Wallet address used as the IBE identity
+ * Identity is address.toLowerCase() + chain pk (active or queued).
+ *
+ * @param {string} userAddress - Wallet address used as part of the IBE identity
  * @param {string} randomnessBase64 - Base64-encoded randomness
- * @returns {Promise<{ encrypted: string, queuedEncrypted: string | null }>}
- *   Hex-encoded IBE ciphertexts
+ * @returns {Promise<{
+ *   encrypted: string,
+ *   encryptedId: string,
+ *   queuedEncrypted: string | null,
+ *   queuedEncryptedId: string | null
+ * }>}
+ *   Hex-encoded IBE ciphertexts plus the identities used for each
  */
 export async function encryptRandomness(userAddress, randomnessBase64) {
   const { active, queued } = await getIbePublicKeys();
-  const id = userAddress.toLowerCase();
   const randomnessBuffer = Buffer.from(randomnessBase64, "base64");
 
-  const [encrypted, queuedEncrypted] = await Promise.all([
-    timelockEncrypt(id, active, randomnessBuffer),
-    queued ? timelockEncrypt(id, queued, randomnessBuffer) : Promise.resolve(null),
-  ]);
+  // Active ciphertext → identity address.toLowerCase() + activePk
+  const encryptedId = buildIbeId(userAddress, active);
+  const encrypted = await timelockEncrypt(encryptedId, active, randomnessBuffer);
+
+  // Queued ciphertext → identity address.toLowerCase() + queuedPk
+  let queuedEncrypted = null;
+  let queuedEncryptedId = null;
+  if (queued) {
+    queuedEncryptedId = buildIbeId(userAddress, queued);
+    queuedEncrypted = await timelockEncrypt(
+      queuedEncryptedId,
+      queued,
+      randomnessBuffer,
+    );
+  }
 
-  return { encrypted, queuedEncrypted };
+  return { encrypted, encryptedId, queuedEncrypted, queuedEncryptedId };
 }

package/src/index.d.ts

@@ -554,6 +554,8 @@ declare module "@fairblock/stabletrust" {
     ipfsApiKey?: string;
     /** StableTrust backend API base URL for persisting request rows. Defaults to the production API. */
     apiBaseUrl?: string;
+    /** App name stored on request rows. Defaults to "SDK". */
+    applicationName?: string;
   }
 
   /**

package/src/index.js

@@ -1,5 +1,9 @@
-export { ConfidentialTransferClient } from "./confidential-client.js";
-export { AnonymousTransferClient } from "./anonymous-client.js";
+export {
+  ConfidentialTransferClient,
+  ControlledConfidentialTransferClient,
+  AnonymousTransferClient,
+  WITHDRAW_FEE_PPM_DENOMINATOR,
+} from "./fee-aware-clients.js";
 export { deriveKeys, decryptCiphertext, combineCiphertext } from "./crypto.js";
 export {
   encodeTransferProof,
@@ -13,9 +17,13 @@ export {
   TRANSFER_CONFIDENTIAL_SIGNATURE,
   WITHDRAW_CONFIDENTIAL_SIGNATURE,
   FEE_TOKEN_SIGNATURE,
+  FEE_ACCOUNT_SIGNATURE,
   NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE,
+  NON_ANONYMOUS_WITHDRAW_FEE_SIGNATURE,
+  NON_ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE,
   ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE,
   ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE,
+  ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE,
   STABLETRUST_CONTRACTS_BY_CHAIN_ID,
   getStabletrustContractAddress,
 } from "./constants.js";

package/src/withdrawal-fees.d.ts

@@ -0,0 +1,83 @@
+/// <reference path="./index.d.ts" />
+
+declare module "@fairblock/stabletrust" {
+  export interface WithdrawalFeeQuote {
+    /** Gross withdrawn-token amount after the SDK's 2-decimal contract-scale normalization. */
+    grossAmount: bigint;
+    /** Fixed request fee, charged even if the later callback fails. */
+    fixedFee: bigint;
+    /** Token used for the fixed request fee. ethers.ZeroAddress means native currency. */
+    fixedFeeToken: string;
+    /** Success-only withdrawal percentage fee rate, in parts per million. */
+    percentageFeePpm: bigint;
+    /** Estimated success-only percentage fee, denominated in the withdrawn token. */
+    estimatedPercentageFee: bigint;
+    /** Token being withdrawn. */
+    withdrawalToken: string;
+    /** Estimated amount delivered on a successful callback. */
+    estimatedNetAmount: bigint;
+  }
+
+  export interface AnonymousWithdrawalQuoteOptions {
+    /** Selects the IPFS/offchainZKP fixed withdrawal fee when true; inline fee otherwise. */
+    offchainZKP?: boolean;
+  }
+
+  export interface ConfidentialTransferClient {
+    /** Get the global fee recipient. */
+    getFeeAccount(): Promise<string>;
+    /** Get the fixed non-anonymous withdrawal request fee. */
+    getNonAnonymousWithdrawFee(): Promise<bigint>;
+    /** Get the success-only non-anonymous withdrawal rate in PPM. */
+    getNonAnonymousWithdrawFeePpm(): Promise<bigint>;
+    /** Get the shared anonymous success-only withdrawal rate in PPM. */
+    getAnonymousWithdrawFeePpm(): Promise<bigint>;
+    /** Quote fixed and percentage fees for a non-anonymous withdrawal. */
+    getWithdrawalFeeQuote(
+      tokenAddress: string,
+      amount: bigint | string | number,
+    ): Promise<WithdrawalFeeQuote>;
+  }
+
+  export interface ControlledConfidentialTransferClient {
+    /** Get the global fee recipient. */
+    getFeeAccount(): Promise<string>;
+    /** Get the fixed non-anonymous withdrawal request fee. */
+    getNonAnonymousWithdrawFee(): Promise<bigint>;
+    /** Get the success-only non-anonymous withdrawal rate in PPM. */
+    getNonAnonymousWithdrawFeePpm(): Promise<bigint>;
+    /** Get the shared anonymous success-only withdrawal rate in PPM. */
+    getAnonymousWithdrawFeePpm(): Promise<bigint>;
+    /** Quote fixed and percentage fees for a non-anonymous withdrawal. */
+    getWithdrawalFeeQuote(
+      tokenAddress: string,
+      amount: bigint | string | number,
+    ): Promise<WithdrawalFeeQuote>;
+  }
+
+  export interface AnonymousTransferClient {
+    /** Get the global fee recipient through Fairycloak. */
+    getFeeAccount(): Promise<string>;
+    /** Get the fixed non-anonymous withdrawal request fee through Fairycloak. */
+    getNonAnonymousWithdrawFee(): Promise<bigint>;
+    /** Get the non-anonymous success-only withdrawal rate in PPM through Fairycloak. */
+    getNonAnonymousWithdrawFeePpm(): Promise<bigint>;
+    /** Get the shared anonymous success-only withdrawal rate in PPM through Fairycloak. */
+    getAnonymousWithdrawFeePpm(): Promise<bigint>;
+    /**
+     * Quote an anonymous withdrawal. The fixed fee is the path-specific prepaid
+     * request fee; the percentage fee is success-only and comes from the withdrawn token.
+     */
+    getAnonymousWithdrawalFeeQuote(
+      tokenAddress: string,
+      amount: bigint | string | number,
+      options?: AnonymousWithdrawalQuoteOptions,
+    ): Promise<WithdrawalFeeQuote>;
+  }
+
+  export const WITHDRAW_FEE_PPM_DENOMINATOR: bigint;
+  export const FEE_ACCOUNT_SIGNATURE: string;
+  export const NON_ANONYMOUS_WITHDRAW_FEE_SIGNATURE: string;
+  export const NON_ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE: string;
+  export const ANONYMOUS_WITHDRAW_FEE_PPM_SIGNATURE: string;
+}