@fairblock/stabletrust 2.0.6 → 2.0.10

package/src/confidential-client.js

@@ -2,6 +2,12 @@ import { ethers } from "ethers";
 import {
   CONTRACT_ABI,
   ERC20_ABI,
+  TRANSFER_CONFIDENTIAL_SIGNATURE,
+  WITHDRAW_CONFIDENTIAL_SIGNATURE,
+  FEE_TOKEN_SIGNATURE,
+  NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE,
+  ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE,
+  ANONYMOUS_INLINE_TRANSFER_FEE_SIGNATURE,
   getStabletrustContractAddress,
 } from "./constants.js";
 import { deriveKeys, decryptCiphertext, combineCiphertext } from "./crypto.js";
@@ -9,9 +15,12 @@ import {
   encodeTransferProof,
   encodeWithdrawProof,
   sleep,
+  toContractScale,
   uploadBytesToIpfs,
 } from "./utils.js";
 import { initializeWasm } from "./wasm-loader.js";
+import { encryptRandomness } from "./ibe.js";
+import { createRequest, CHAIN_KEY_BY_ID } from "./backend.js";
 
 // Auto-initialize WASM on first use
 let wasmModulePromise = null;
@@ -33,8 +42,12 @@ export class ConfidentialTransferClient {
    * @param {string} rpcUrl - RPC endpoint URL
    * @param {string|number} contractAddressOrChainId - Contract address or chain ID
    * @param {number} [chainId] - Chain ID when contract address is provided
+   * @param {Object} [options]
+   * @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
    */
-  constructor(rpcUrl, contractAddressOrChainId, chainId) {
+  constructor(rpcUrl, contractAddressOrChainId, chainId, options = {}) {
     // Validate required config
     if (!rpcUrl) {
       throw new Error("rpcUrl is required");
@@ -42,10 +55,15 @@ export class ConfidentialTransferClient {
 
     let resolvedChainId;
     let resolvedContractAddress;
+    let ipfsOptions = options || {};
 
-    if (typeof contractAddressOrChainId === "number" && chainId === undefined) {
+    if (
+      typeof contractAddressOrChainId === "number" &&
+      (chainId === undefined || typeof chainId === "object")
+    ) {
       resolvedChainId = contractAddressOrChainId;
       resolvedContractAddress = getStabletrustContractAddress(resolvedChainId);
+      ipfsOptions = typeof chainId === "object" && chainId !== null ? chainId : ipfsOptions;
     } else {
       resolvedChainId = chainId;
       resolvedContractAddress =
@@ -73,6 +91,9 @@ export class ConfidentialTransferClient {
       rpcUrl,
       contractAddress: ethers.getAddress(resolvedContractAddress),
       chainId: Number(resolvedChainId),
+      ipfsUploadUrl: ipfsOptions.ipfsUploadUrl || null,
+      ipfsApiKey: ipfsOptions.ipfsApiKey || null,
+      apiBaseUrl: ipfsOptions.apiBaseUrl || null,
     };
 
     // WASM will be auto-initialized on first use
@@ -88,6 +109,7 @@ export class ConfidentialTransferClient {
         CONTRACT_ABI,
         this.provider,
       );
+      this._assertLatestContractAbi();
     } catch (error) {
       throw new Error(
         `Failed to initialize contracts: ${error.message}. Check your RPC URL and contract addresses.`,
@@ -95,6 +117,132 @@ export class ConfidentialTransferClient {
     }
   }
 
+  /**
+   * Fire-and-forget request row creation
+   * @private
+   */
+  _postRequest(data) {
+    const apiBaseUrl = this.config.apiBaseUrl || undefined;
+    const payload = {
+      chainKey: CHAIN_KEY_BY_ID[this.config.chainId] || String(this.config.chainId),
+      chainId: this.config.chainId,
+      ...data,
+    };
+    createRequest(payload, apiBaseUrl).catch((err) => {
+      const status = err?.response?.status;
+      const body = err?.response?.data;
+      console.warn("[StableTrust] Failed to post request:", err.message);
+      if (status) console.warn("[StableTrust] Status:", status);
+      if (body) console.warn("[StableTrust] Response:", JSON.stringify(body, null, 2));
+    });
+  }
+
+  /**
+   * Extract request/tx ID from receipt logs
+   * @private
+   */
+  _getRequestIdFromReceipt(receipt, eventNames) {
+    try {
+      const iface = this.contract.interface;
+      const contractAddr = this.config.contractAddress.toLowerCase();
+
+      for (const log of receipt.logs) {
+        if (log.address.toLowerCase() === contractAddr) {
+          const txId = this._parseLogItem(iface, log, eventNames);
+          if (txId) return txId;
+        }
+      }
+
+      for (const log of receipt.logs) {
+        const txId = this._parseLogItem(iface, log, eventNames);
+        if (txId) return txId;
+      }
+
+      for (const name of eventNames) {
+        try {
+          const topicHash = iface.getEvent(name).topicHash;
+          for (const log of receipt.logs) {
+            if (log.topics[0] === topicHash && log.topics.length >= 3) {
+              const txId = BigInt(log.topics[2]).toString();
+              if (txId !== "0") return txId;
+            }
+          }
+        } catch {
+          // Event not in ABI
+        }
+      }
+
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Parse a single log item to extract txId
+   * @private
+   */
+  _parseLogItem(iface, log, eventNames) {
+    try {
+      const parsed = iface.parseLog({
+        topics: [...log.topics],
+        data: log.data,
+      });
+
+      if (!parsed || !eventNames.includes(parsed.name)) return null;
+
+      if (parsed.args.txId !== undefined && parsed.args.txId !== null) {
+        return parsed.args.txId.toString();
+      }
+      if (parsed.args.requestId !== undefined && parsed.args.requestId !== null) {
+        return parsed.args.requestId.toString();
+      }
+
+      let txId;
+      if (
+        parsed.name === "TransferRequested" ||
+        parsed.name === "TransferProcessed"
+      ) {
+        txId = parsed.args[2];
+      } else {
+        txId = parsed.args[1];
+      }
+
+      return txId !== undefined && txId !== null ? txId.toString() : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get requestId from account core state (txId)
+   * @private
+   */
+  async _getRequestIdFromAccountCore(address) {
+    try {
+      const account = await this.contract.getAccountCore(address);
+      const txId = account.txId?.toString?.() ?? String(account.txId);
+      return txId && txId !== "0" ? txId : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Resolve a request ID from receipt logs, then account state, then tx hash
+   * @private
+   */
+  async _resolveRequestId(receipt, address, eventNames) {
+    let requestId = this._getRequestIdFromReceipt(receipt, eventNames);
+    if (!requestId) {
+      requestId = await this._getRequestIdFromAccountCore(address);
+    }
+    if (!requestId || requestId === "0") {
+      requestId = receipt.hash;
+    }
+    return requestId;
+  }
+
   /**
    * Get WASM module (auto-initializes if needed)
    * @private
@@ -114,6 +262,121 @@ export class ConfidentialTransferClient {
     return new ethers.Contract(tokenAddress, ERC20_ABI, this.provider);
   }
 
+  /**
+   * Fail fast when a stale SDK ABI is installed against the latest contract.
+   * This catches the common dependency-lock problem where the contract has
+   * `bytes,bool` proof methods but node_modules still contains the older ABI.
+   * @private
+   */
+  _assertLatestContractAbi() {
+    const requiredSignatures = [
+      TRANSFER_CONFIDENTIAL_SIGNATURE,
+      WITHDRAW_CONFIDENTIAL_SIGNATURE,
+      FEE_TOKEN_SIGNATURE,
+      NON_ANONYMOUS_TRANSFER_FEE_SIGNATURE,
+      ANONYMOUS_IPFS_TRANSFER_FEE_SIGNATURE,
+      ANONYMOUS_INLINE_TRANSFER_FEE_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.`,
+      );
+    }
+  }
+
+  /**
+   * Resolve whether non-anonymous proof bytes should be submitted inline or via
+   * StableTrust IPFS. `offchainZKP` is the latest contract flag;
+   * `useOffchainVerify` is kept as a deprecated SDK alias for older callers.
+   * Tempo keeps the old SDK behaviour of using IPFS by default.
+   * @private
+   */
+  _resolveOffchainZKP(options = {}) {
+    if (options.offchainZKP !== undefined) return Boolean(options.offchainZKP);
+    if (options.useOffchainVerify !== undefined) return Boolean(options.useOffchainVerify);
+    return this.config.chainId === 42431;
+  }
+
+  /**
+   * Prepare payment for a non-anonymous confidential transfer. Both inline and
+   * IPFS proof paths use the same live `nonAnonymousTransferFee`. Native fees
+   * are attached as msg.value; ERC-20 fees are approved for the diamond and
+   * collected by the contract with transferFrom.
+   * @private
+   */
+  async _prepareNonAnonymousTransferFee(senderWallet) {
+    const [feeTokenRaw, feeAmountRaw] = await Promise.all([
+      this.contract.feeToken(),
+      this.contract.nonAnonymousTransferFee(),
+    ]);
+
+    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 senderWallet.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 fee token balance. Required: ${feeAmount}, available: ${balance}, fee token: ${feeToken}`,
+      );
+    }
+
+    if (allowance < feeAmount) {
+      const approveTx = await feeTokenContract
+        .connect(senderWallet)
+        .approve(this.config.contractAddress, ethers.MaxUint256);
+      const approveReceipt = await approveTx.wait();
+      if (!approveReceipt || approveReceipt.status === 0) {
+        throw new Error("Fee token approval failed");
+      }
+    }
+
+    return { value: 0n };
+  }
+
+  /**
+   * For the latest contract, public transfer/withdraw always pass
+   * `(bytes proof, bool offchainZKP)`. When `offchainZKP=true`, the bytes arg is
+   * the bare CID encoded as UTF-8 bytes. When false, it is the full ABI proof.
+   * @private
+   */
+  async _resolveContractProofArg(encodedProof, proofName, offchainZKP) {
+    if (!offchainZKP) {
+      return encodedProof;
+    }
+
+    try {
+      const cid = await uploadBytesToIpfs(encodedProof, proofName, {
+        uploadUrl: this.config.ipfsUploadUrl,
+        apiKey: this.config.ipfsApiKey,
+      });
+      const bareCid = String(cid || "").trim().replace(/^ipfs:\/\//i, "");
+      if (!bareCid) {
+        throw new Error("IPFS upload returned no CID");
+      }
+      return ethers.toUtf8Bytes(bareCid);
+    } catch (ipfsError) {
+      throw new Error(`Failed to upload proof to IPFS: ${ipfsError.message}`);
+    }
+  }
+
   /**
    * Derive encryption keys for a wallet
    *
@@ -220,10 +483,13 @@ export class ConfidentialTransferClient {
   /**
    * Get total decrypted balance (available + pending) for an address
    *
+   * Amounts are in raw token units (bigint). Note that this differs from the anonymous client, which returns
+   * contract scale (amount * 100 / 10^decimals).
+   *
    * @param {string} address - Account address
    * @param {string} privateKey - Private key for decryption
    * @param {string} tokenAddress - Token address
-   * @returns {Promise<{amount: number, available: {amount: number, ciphertext: string|null}, pending: {amount: number, ciphertext: string|null}}>}
+   * @returns {Promise<{amount: bigint, available: {amount: bigint, ciphertext: string|null}, pending: {amount: bigint, ciphertext: string|null}}>}
    */
   async getConfidentialBalance(address, privateKey, tokenAddress) {
     try {
@@ -329,7 +595,11 @@ export class ConfidentialTransferClient {
 
     if (pendingBalance.amount > 0n) {
       try {
-        await this._applyPending(wallet, { waitForFinalization: true });
+        await this._applyPending(wallet, {
+          waitForFinalization: true,
+          tokenAddress,
+          pendingAmount: pendingBalance.amount,
+        });
       } catch (error) {
         console.warn(
           `Warning: Failed to apply pending balance before ${actionLabel}: ${error.message}. You may have pending balance that is not yet applied.`,
@@ -373,8 +643,7 @@ export class ConfidentialTransferClient {
 
       const tokenContract = this._getTokenContract(tokenAddress);
       const tokenDecimals = await tokenContract.decimals();
-      const depositAmount =
-        (BigInt(amount) * 100n) / 10n ** BigInt(tokenDecimals);
+      const depositAmount = toContractScale(amount, tokenDecimals);
 
       // Check token balance and allowance in parallel
       const [tokenBalance, allowance] = await Promise.all([
@@ -387,6 +656,7 @@ export class ConfidentialTransferClient {
         );
       }
 
+      const depositOverrides = {};
       if (allowance < BigInt(amount)) {
         const approveTx = await tokenContract
           .connect(wallet)
@@ -396,11 +666,17 @@ export class ConfidentialTransferClient {
         if (!approveReceipt || approveReceipt.status === 0) {
           throw new Error("Token approval failed");
         }
+        // Pin the deposit nonce to (approve nonce + 1). The approve was just
+        // broadcast from this same EOA; letting ethers resolve the deposit nonce
+        // via getTransactionCount can still return the pre-approve count on a fast
+        // node and assign the deposit the SAME nonce as the approve, which the node
+        // rejects as "nonce too low" (NONCE_EXPIRED).
+        depositOverrides.nonce = approveTx.nonce + 1;
       }
       // Perform deposit
       const depositTx = await this.contract
         .connect(wallet)
-        .deposit(tokenAddress, depositAmount);
+        .deposit(tokenAddress, depositAmount, depositOverrides);
 
       const receipt = await depositTx.wait();
       if (!receipt || receipt.status === 0) {
@@ -411,6 +687,27 @@ export class ConfidentialTransferClient {
         await this._waitForGlobalState(address, "deposit");
       }
 
+      const tokenSymbol = await tokenContract.symbol();
+      const requestId = await this._resolveRequestId(receipt, address, [
+        "DepositRequested",
+        "DepositProcessed",
+      ]);
+
+      this._postRequest({
+        requestId,
+        userAddress: address.toLowerCase(),
+        operationKind: 1,
+        type: "deposit",
+        transactionHash: receipt.hash,
+        status: "pending",
+        details: {
+          token: tokenSymbol,
+          tokenAddress,
+          amount: depositAmount.toString(),
+          amountInWei: true,
+        },
+      });
+
       return receipt;
     } catch (error) {
       if (error.message.includes("Insufficient token balance")) {
@@ -426,7 +723,7 @@ export class ConfidentialTransferClient {
    * @param {ethers.Wallet|ethers.Signer} senderWallet - Sender's wallet
    * @param {string} recipientAddress - Recipient's address
    * @param {string} tokenAddress - Token address to transfer
-   * @param {number} amount - Amount to transfer
+   * @param {bigint|string|number} amount - Amount to transfer (in token units)
    * @param {Object} [options] - Options
    * @param {boolean} [options.waitForFinalization=true] - Wait for transfer finalization
    * @returns {Promise<Object>} Transaction receipt
@@ -439,6 +736,7 @@ export class ConfidentialTransferClient {
     options = {},
   ) {
     const { waitForFinalization = true } = options;
+    const offchainZKP = this._resolveOffchainZKP(options);
 
     try {
       // Validate inputs
@@ -456,8 +754,7 @@ export class ConfidentialTransferClient {
       }
       const tokenContract = this._getTokenContract(tokenAddress);
       const tokenDecimals = await tokenContract.decimals();
-      const transferAmount =
-        (BigInt(amount) * 100n) / 10n ** BigInt(tokenDecimals);
+      const transferAmount = toContractScale(amount, tokenDecimals);
 
       const senderAddress = await senderWallet.getAddress();
 
@@ -497,14 +794,11 @@ export class ConfidentialTransferClient {
         "transfer",
       );
 
-      const [balanceSummary, fee] = await Promise.all([
-        this.getConfidentialBalance(
-          senderAddress,
-          derivedSenderKeys.privateKey,
-          tokenAddress,
-        ),
-        this.getFeeAmount(),
-      ]);
+      const balanceSummary = await this.getConfidentialBalance(
+        senderAddress,
+        derivedSenderKeys.privateKey,
+        tokenAddress,
+      );
       const derivedCurrentBalanceCiphertext =
         balanceSummary.available.ciphertext;
       const derivedCurrentBalance = balanceSummary.available.amount;
@@ -554,37 +848,20 @@ export class ConfidentialTransferClient {
         );
       }
       const encodedProof = ethers.getBytes(encodeTransferProof(proof.data));
-      let transferZkpArg;
-      let txOverrides;
-
-      if (this.config.chainId === 42431) {
-        // Tempo: upload proof to IPFS and pass an ipfs:// pointer; no native fee
-        try {
-          const cid = await uploadBytesToIpfs(
-            encodedProof,
-            "transfer-proof.bin",
-          );
-          transferZkpArg = ethers.toUtf8Bytes(`ipfs://${cid}`);
-        } catch (ipfsError) {
-          throw new Error(
-            `Failed to upload proof to IPFS: ${ipfsError.message}`,
-          );
-        }
-        txOverrides = { value: 0n };
-      } else {
-        // Standard chains: pass encoded proof bytes with native fee
-        transferZkpArg = encodedProof;
-        txOverrides = { value: await this.contract.feeAmount() };
-      }
+      const transferZkpArg = await this._resolveContractProofArg(
+        encodedProof,
+        "transfer-proof.bin",
+        offchainZKP,
+      );
+      const txOverrides = await this._prepareNonAnonymousTransferFee(senderWallet);
 
-      const tx = await this.contract
-        .connect(senderWallet)
-        .transferConfidential(
-          recipientAddress,
-          tokenAddress,
-          transferZkpArg,
-          txOverrides,
-        );
+      const tx = await this.contract.connect(senderWallet).transferConfidential(
+        recipientAddress,
+        tokenAddress,
+        transferZkpArg,
+        offchainZKP,
+        txOverrides,
+      );
 
       const receipt = await tx.wait();
       if (!receipt || receipt.status === 0) {
@@ -595,6 +872,66 @@ export class ConfidentialTransferClient {
         await this._waitForGlobalState(senderAddress, "transfer");
       }
 
+      // IBE-encrypt randomness then persist both records (fire-and-forget, after finalization)
+      const txHash = receipt.hash;
+      const requestId = await this._resolveRequestId(receipt, senderAddress, [
+        "TransferRequested",
+        "TransferProcessed",
+      ]);
+      const tokenSymbol = await tokenContract.symbol();
+
+      Promise.all([
+        encryptRandomness(senderAddress, proof.data.sender_randomness),
+        encryptRandomness(recipientAddress, proof.data.receiver_randomness),
+      ])
+        .then(([senderEnc, receiverEnc]) => {
+          const transferDetails = {
+            sender: senderAddress.toLowerCase(),
+            recipient: recipientAddress.toLowerCase(),
+            token: tokenSymbol,
+            tokenAddress,
+          };
+
+          const queuedFields =
+            senderEnc.queuedEncrypted && receiverEnc.queuedEncrypted
+              ? {
+                  queuedEncryptedSenderRandomness: senderEnc.queuedEncrypted,
+                  queuedEncryptedReceiverRandomness: receiverEnc.queuedEncrypted,
+                }
+              : {};
+
+          this._postRequest({
+            requestId,
+            userAddress: senderAddress.toLowerCase(),
+            operationKind: 2,
+            type: "transfer",
+            transactionHash: txHash,
+            status: "pending",
+            details: transferDetails,
+            encryptedSenderRandomness: senderEnc.encrypted,
+            encryptedReceiverRandomness: receiverEnc.encrypted,
+            ...queuedFields,
+          });
+
+          this._postRequest({
+            requestId: `received-${requestId}-${recipientAddress.toLowerCase()}`,
+            userAddress: recipientAddress.toLowerCase(),
+            operationKind: 2,
+            type: "received",
+            transactionHash: txHash,
+            status: "pending",
+            details: transferDetails,
+            encryptedReceiverRandomness: receiverEnc.encrypted,
+            ...(receiverEnc.queuedEncrypted
+              ? {
+                  queuedEncryptedReceiverRandomness:
+                    receiverEnc.queuedEncrypted,
+                }
+              : {}),
+          });
+        })
+        .catch(() => {});
+
       return receipt;
     } catch (error) {
       const message = error?.message ?? String(error);
@@ -613,13 +950,14 @@ export class ConfidentialTransferClient {
    *
    * @param {ethers.Wallet|ethers.Signer} wallet - The wallet to withdraw from
    * @param {string} tokenAddress - Token address to withdraw
-   * @param {number} amount - Amount to withdraw
+   * @param {bigint|string|number} amount - Amount to withdraw (in token units)
    * @param {Object} [options] - Options
    * @param {boolean} [options.waitForFinalization=true] - Wait for withdrawal finalization
    * @returns {Promise<Object>} Transaction receipt
    */
   async withdraw(wallet, tokenAddress, amount, options = {}) {
     const { waitForFinalization = true } = options;
+    const offchainZKP = this._resolveOffchainZKP(options);
 
     try {
       // Validate inputs
@@ -635,8 +973,7 @@ export class ConfidentialTransferClient {
 
       const tokenContract = this._getTokenContract(tokenAddress);
       const tokenDecimals = await tokenContract.decimals();
-      const withdrawAmount =
-        (BigInt(amount) * 100n) / 10n ** BigInt(tokenDecimals);
+      const withdrawAmount = toContractScale(amount, tokenDecimals);
 
       // Auto-derive keys
       const derivedKeys = await this._deriveKeys(wallet);
@@ -720,32 +1057,18 @@ export class ConfidentialTransferClient {
 
       // Execute withdrawal
       const encodedProof = ethers.getBytes(encodeWithdrawProof(proof.data));
-      let withdrawZkpArg;
-
-      if (this.config.chainId === 42431) {
-        // Tempo: upload proof to IPFS and pass an ipfs:// pointer
-        try {
-          const cid = await uploadBytesToIpfs(
-            encodedProof,
-            "withdraw-proof.bin",
-          );
-          withdrawZkpArg = ethers.toUtf8Bytes(`ipfs://${cid}`);
-        } catch (ipfsError) {
-          throw new Error(
-            `Failed to upload proof to IPFS: ${ipfsError.message}`,
-          );
-        }
-      } else {
-        withdrawZkpArg = encodedProof;
-      }
+      const withdrawZkpArg = await this._resolveContractProofArg(
+        encodedProof,
+        "withdraw-proof.bin",
+        offchainZKP,
+      );
 
-      const tx = await this.contract
-        .connect(wallet)
-        .withdraw(
-          tokenAddress,
-          BigInt(withdrawAmount),
-          withdrawZkpArg,
-        );
+      const tx = await this.contract.connect(wallet).withdraw(
+        tokenAddress,
+        BigInt(withdrawAmount),
+        withdrawZkpArg,
+        offchainZKP,
+      );
 
       const receipt = await tx.wait();
       if (!receipt || receipt.status === 0) {
@@ -756,6 +1079,27 @@ export class ConfidentialTransferClient {
         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);
@@ -778,7 +1122,7 @@ export class ConfidentialTransferClient {
    * @returns {Promise<Object>} Transaction receipt
    */
   async _applyPending(wallet, options = {}) {
-    const { waitForFinalization = true } = options;
+    const { waitForFinalization = true, tokenAddress, pendingAmount } = options;
 
     try {
       if (!wallet) {
@@ -798,6 +1142,37 @@ export class ConfidentialTransferClient {
         await this._waitForGlobalState(address, "apply pending");
       }
 
+      const requestId = await this._resolveRequestId(receipt, address, [
+        "ApplyPendingRequested",
+        "ApplyPendingProcessed",
+      ]);
+
+      const tokenContract = tokenAddress
+        ? this._getTokenContract(tokenAddress)
+        : null;
+      const tokenSymbol = tokenContract
+        ? await tokenContract.symbol()
+        : "USD₮0";
+
+      this._postRequest({
+        requestId,
+        userAddress: address.toLowerCase(),
+        operationKind: 3,
+        type: "secure claim",
+        transactionHash: receipt.hash,
+        status: "pending",
+        details: {
+          token: tokenSymbol,
+          ...(tokenAddress ? { tokenAddress } : {}),
+          ...(pendingAmount === undefined
+            ? {}
+            : {
+                pendingAmount: pendingAmount.toString(),
+                amountInWei: true,
+              }),
+        },
+      });
+
       return receipt;
     } catch (error) {
       throw new Error(`Failed to apply pending: ${error.message}`);
@@ -841,15 +1216,55 @@ export class ConfidentialTransferClient {
   }
 
   /**
-   * Get the current fee amount for confidential transfers
+   * Get the currently configured fee token. address(0) means native currency.
+   *
+   * @returns {Promise<string>} Checksummed token address
+   */
+  async getFeeToken() {
+    try {
+      return ethers.getAddress(await this.contract.feeToken());
+    } catch (error) {
+      throw new Error(`Failed to get fee token: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get the fixed fee used by all non-anonymous confidential transfers,
+   * regardless of whether the proof is inline or stored on IPFS.
+   *
+   * @returns {Promise<bigint>} Fee amount in raw fee-token units
+   */
+  async getNonAnonymousTransferFee() {
+    try {
+      return await this.contract.nonAnonymousTransferFee();
+    } catch (error) {
+      throw new Error(`Failed to get non-anonymous transfer fee: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get the fixed fee used by anonymous transfers whose proof is stored on IPFS.
+   *
+   * @returns {Promise<bigint>} Fee amount in raw fee-token units
+   */
+  async getAnonymousIpfsTransferFee() {
+    try {
+      return await this.contract.anonymousIpfsTransferFee();
+    } catch (error) {
+      throw new Error(`Failed to get anonymous IPFS transfer fee: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get the fixed fee used by anonymous transfers whose proof is submitted inline.
    *
-   * @returns {Promise<bigint>} Fee amount in wei
+   * @returns {Promise<bigint>} Fee amount in raw fee-token units
    */
-  async getFeeAmount() {
+  async getAnonymousInlineTransferFee() {
     try {
-      return await this.contract.feeAmount();
+      return await this.contract.anonymousInlineTransferFee();
     } catch (error) {
-      throw new Error(`Failed to get fee amount: ${error.message}`);
+      throw new Error(`Failed to get anonymous inline transfer fee: ${error.message}`);
     }
   }