@fairblock/stabletrust 2.0.4 → 2.0.6

package/README.md

@@ -212,6 +212,17 @@ The `AnonymousTransferClient` routes all operations through the **Fairycloak rel
 
 > **Access Required** — Anonymous transfers are available to teams building privacy-critical applications. To obtain a Fairycloak relay URL and API key, reach out to the Fairblock team at [hello@fairblock.network](mailto:hello@fairblock.network).
 
+### Anonymous Account ID Rules
+
+Every `accountId` (and `senderAccountId` / `recipientId`) you pass to `AnonymousTransferClient` must follow these rules, enforced both on-chain and by the Fairycloak relay:
+
+- **Non-empty** string
+- **At most 20 characters** long
+- **Alphanumeric characters only** (`A-Z`, `a-z`, `0-9`) — no spaces, punctuation, or Unicode
+- **Case-sensitive** — `"MyAccount"` and `"myaccount"` are different accounts; no normalization is applied
+
+The SDK validates `accountId` (and related fields) before making any request and throws a descriptive `Error` if it doesn't follow these rules.
+
 ### Initialization
 
 ```javascript
@@ -238,7 +249,7 @@ const keys = await client.deriveAnonymousKeys(authWallet, accountId);
 
 #### `createAccount(authWallet, accountId, elgamalPublicKey, options?)`
 
-Creates a new anonymous account via the relay. The relay pays gas. `accountId` is a **caller-chosen string** (non-empty, case-sensitive) — pick any unique identifier you like (e.g. a UUID or a human-readable name).
+Creates a new anonymous account via the relay. The relay pays gas. `accountId` is a **caller-chosen string** — pick any unique identifier you like (e.g. a short UUID fragment or a human-readable name), as long as it follows the [Anonymous Account ID Rules](#anonymous-account-id-rules) above (non-empty, at most 20 characters, alphanumeric only, case-sensitive).
 
 #### `ensureAnonymousAccount(authWallet, accountId, elgamalPublicKey, options?)`
 

package/examples/anonymous-flow.js

@@ -128,8 +128,9 @@ async function main() {
   // An auth signer can only ever be bound to a single anonymous account, so the
   // account ID must be stable per-wallet across runs (random UUIDs would cause
   // "auth signer already used" failures on every re-run with the same .env keys).
-  const anon1Id = `anon-${anon1Wallet.address.toLowerCase()}`;
-  const anon2Id = `anon-${anon2Wallet.address.toLowerCase()}`;
+  // Anonymous account IDs must be alphanumeric and at most 20 characters.
+  const anon1Id = `anon${anon1Wallet.address.slice(2, 6).toLowerCase()}`;
+  const anon2Id = `anon${anon2Wallet.address.slice(2, 6).toLowerCase()}`;
   log("anon1 id:", anon1Id);
   log("anon2 id:", anon2Id);
 

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.4",
+  "version": "2.0.6",
   "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

@@ -1,6 +1,10 @@
 import { ethers } from "ethers";
 import { initializeWasm } from "./wasm-loader.js";
-import { encodeTransferProof, encodeWithdrawProof } from "./utils.js";
+import {
+  encodeTransferProof,
+  encodeWithdrawProof,
+  validateAnonymousAccountId,
+} from "./utils.js";
 import { getStabletrustContractAddress } from "./constants.js";
 
 // EIP-712 domain for anonymous operations (LibAnonAuth domain name)
@@ -38,6 +42,16 @@ function _parseBigInt(v) {
  * Anonymous transfers are routed through the Fairycloak HTTP relay server instead of being
  * submitted directly on-chain. The relay pays gas for all managed transactions; the user only
  * signs EIP-712 authorisation payloads (and a raw EVM transaction for deposits).
+ *
+ * ### Anonymous account ID rules
+ * Every `accountId` / `senderAccountId` / `recipientId` accepted by this client must:
+ *   - be a non-empty string
+ *   - be at most 20 characters long
+ *   - contain only alphanumeric characters (A-Z, a-z, 0-9)
+ *   - be treated as case-sensitive (no normalization is applied)
+ *
+ * IDs that don't follow these rules are rejected with a descriptive error before any
+ * network request is made.
  */
 export class AnonymousTransferClient {
   /**
@@ -191,6 +205,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<{exists:boolean, finalized:boolean, hasPendingAction:boolean, txId:bigint, elgamalPubkey:string, authNonce:bigint}>}
    */
   async getAnonymousAccountInfo(accountId) {
+    validateAnonymousAccountId(accountId, "accountId");
     try {
       const data = await this._fetch(
         "GET",
@@ -234,6 +249,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<boolean>}
    */
   async isAuthorizedSigner(accountId, signerAddress) {
+    validateAnonymousAccountId(accountId, "accountId");
     const data = await this._fetch(
       "GET",
       `/v1/views/anonymous/accounts/${accountId}/authorized-signers/${signerAddress}`,
@@ -312,6 +328,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<{available: {amount: number, ciphertext: string|null}, pending: {amount: number, ciphertext: string|null}}>}
    */
   async getAnonymousBalance(accountId, tokenAddress, elGamalPrivateKey) {
+    validateAnonymousAccountId(accountId, "accountId");
     if (!ethers.isAddress(tokenAddress))
       throw new Error(`Invalid token address: ${tokenAddress}`);
     if (!elGamalPrivateKey) throw new Error("elGamalPrivateKey is required");
@@ -347,6 +364,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<{publicKey:string, privateKey:string}>} Base-64 encoded keypair
    */
   async deriveAnonymousKeys(authWallet, accountId) {
+    validateAnonymousAccountId(accountId, "accountId");
     try {
       const wasm = await this._getWasm();
       const address = await authWallet.getAddress();
@@ -508,13 +526,16 @@ export class AnonymousTransferClient {
    * The relay submits the `createAnonymousAccount` transaction and pays gas.
    *
    * @param {ethers.Wallet|ethers.Signer} authWallet - Initial auth signer
-   * @param {string} accountId - Caller-chosen account ID (non-empty string, case-sensitive)
+   * @param {string} accountId - Caller-chosen account ID. Must be a non-empty, case-sensitive,
+   *   alphanumeric string of at most 20 characters.
    * @param {string} elgamalPublicKey - ElGamal public key as base64 or "0x"-prefixed hex (32 bytes)
    * @param {Object} [options]
    * @param {number} [options.deadlineOffset=3600] - Deadline in seconds from now
    * @returns {Promise<{request_id:string, tx_hash:string, status:string, action:string}>}
+   * @throws {Error} If `accountId` doesn't follow the anonymous account ID rules (see class docs).
    */
   async createAccount(authWallet, accountId, elgamalPublicKey, options = {}) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       const authAddress = await authWallet.getAddress();
@@ -581,7 +602,8 @@ export class AnonymousTransferClient {
    * so reusing a wallet across different `accountId`s will still fail at creation time.
    *
    * @param {ethers.Wallet|ethers.Signer} authWallet - Initial auth signer
-   * @param {string} accountId - Caller-chosen account ID (non-empty string, case-sensitive)
+   * @param {string} accountId - Caller-chosen account ID. Must be a non-empty, case-sensitive,
+   *   alphanumeric string of at most 20 characters.
    * @param {string} elgamalPublicKey - ElGamal public key as base64 or "0x"-prefixed hex (32 bytes)
    * @param {Object} [options]
    * @param {number} [options.deadlineOffset=3600] - Deadline in seconds from now
@@ -589,8 +611,10 @@ export class AnonymousTransferClient {
    * @param {number} [options.timeoutMs=180000] - Max time to wait for creation/readiness
    * @param {number} [options.pollIntervalMs=2000]
    * @returns {Promise<{accountId:string, accountInfo:Object, created:boolean}>}
+   * @throws {Error} If `accountId` doesn't follow the anonymous account ID rules (see class docs).
    */
   async ensureAnonymousAccount(authWallet, accountId, elgamalPublicKey, options = {}) {
+    validateAnonymousAccountId(accountId, "accountId");
     const {
       deadlineOffset = DEFAULT_DEADLINE_OFFSET,
       waitUntilReady = true,
@@ -681,6 +705,7 @@ export class AnonymousTransferClient {
     { add = [], remove = [] } = {},
     options = {},
   ) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       const authNonce = await this.getAuthNonce(accountId);
@@ -760,6 +785,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<{request_id:string, tx_hash:string, status:string}>}
    */
   async deposit(authWallet, accountId, tokenAddress, amount, options = {}) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET, gasLimit = 600000n } =
       options;
     try {
@@ -933,6 +959,7 @@ export class AnonymousTransferClient {
     },
     options = {},
   ) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       if (!ethers.isAddress(recipient))
@@ -1069,6 +1096,8 @@ export class AnonymousTransferClient {
     },
     options = {},
   ) {
+    validateAnonymousAccountId(senderAccountId, "senderAccountId");
+    validateAnonymousAccountId(recipientId, "recipientId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       if (!ethers.isAddress(token))
@@ -1181,6 +1210,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<{request_id:string, tx_hash:string, status:string}>}
    */
   async applyPending(authWallet, accountId, options = {}) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       const authNonce = await this.getAuthNonce(accountId);
@@ -1248,6 +1278,7 @@ export class AnonymousTransferClient {
     },
     options = {},
   ) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       if (!ethers.isAddress(destination))
@@ -1357,6 +1388,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<{ amount: number, available: number, pending: number }>}
    */
   async getBalance(accountId, tokenAddress, elGamalPrivateKey) {
+    validateAnonymousAccountId(accountId, "accountId");
     try {
       if (!ethers.isAddress(tokenAddress)) {
         throw new Error(`Invalid token address: ${tokenAddress}`);
@@ -1430,6 +1462,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<bigint>}
    */
   async getPrepaidFeeBalance(accountId, token) {
+    validateAnonymousAccountId(accountId, "accountId");
     try {
       if (!ethers.isAddress(token))
         throw new Error(`Invalid token address: ${token}`);
@@ -1493,6 +1526,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<{request_id:string, tx_hash:string, status:string}>}
    */
   async depositFees(authWallet, accountId, amount, options = {}) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET, gasLimit = 300000n } =
       options;
     try {
@@ -1643,6 +1677,7 @@ export class AnonymousTransferClient {
     { token, destination, amount },
     options = {},
   ) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       if (!ethers.isAddress(token))
@@ -1706,6 +1741,7 @@ export class AnonymousTransferClient {
    * @returns {Promise<{request_id:string, tx_hash:string, status:string}>}
    */
   async withdrawAllFees(authWallet, accountId, { destination }, options = {}) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       if (!ethers.isAddress(destination))

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: "0x18c8aEc4Ce4fCdB6687Bb99a402277e82394AFF7", //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

@@ -169,6 +169,16 @@ declare module "@fairblock/stabletrust" {
    *
    * All operations (except `deposit`) are gas-free for the user — Fairycloak pays gas.
    * `deposit` requires the user to sign and pay for a raw EVM transaction.
+   *
+   * ### Anonymous account ID rules
+   * Every `accountId` / `senderAccountId` / `recipientId` passed to this client must:
+   * - be a non-empty string
+   * - be at most {@link MAX_ANONYMOUS_ACCOUNT_ID_LENGTH} (20) characters
+   * - contain only alphanumeric characters (A-Z, a-z, 0-9)
+   * - be treated as case-sensitive (no normalization is applied)
+   *
+   * IDs that violate these rules are rejected with a descriptive error before any
+   * network request is made. See `validateAnonymousAccountId`.
    */
   export class AnonymousTransferClient {
     constructor(config: AnonymousTransferClientConfig);
@@ -178,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.
@@ -201,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>;
@@ -211,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>;
@@ -312,7 +320,8 @@ declare module "@fairblock/stabletrust" {
 
     /**
      * Create a new anonymous account. The relay pays gas.
-     * @param accountId Caller-chosen account ID (non-empty string, case-sensitive)
+     * @param accountId Caller-chosen account ID. Must be a non-empty, case-sensitive,
+     *   alphanumeric string of at most {@link MAX_ANONYMOUS_ACCOUNT_ID_LENGTH} (20) characters.
      * @param elgamalPublicKey Base64 or "0x"-prefixed hex (32 bytes)
      */
     createAccount(
@@ -473,7 +482,7 @@ declare module "@fairblock/stabletrust" {
   /**
    * Deposit options
    */
-  export interface DepositOptions {
+  export interface ConfidentialDepositOptions {
     waitForFinalization?: boolean;
   }
 
@@ -549,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>;
 
     /**
@@ -637,6 +646,27 @@ declare module "@fairblock/stabletrust" {
    */
   export function encodeWithdrawProof(proof: any): string;
 
+  /**
+   * Maximum allowed length for an anonymous account ID (20 characters).
+   */
+  export const MAX_ANONYMOUS_ACCOUNT_ID_LENGTH: number;
+
+  /**
+   * Validate an anonymous account ID.
+   *
+   * Rules (must match the Fairycloak relay and on-chain contract):
+   * - Non-empty string
+   * - At most {@link MAX_ANONYMOUS_ACCOUNT_ID_LENGTH} (20) characters
+   * - Alphanumeric characters only (A-Z, a-z, 0-9)
+   * - Case-sensitive (no normalization is applied)
+   *
+   * @throws {Error} If `accountId` violates any of the above rules.
+   */
+  export function validateAnonymousAccountId(
+    accountId: string,
+    fieldName?: string,
+  ): void;
+
   /**
    * Constants
    */

package/src/index.js

@@ -1,7 +1,12 @@
 export { ConfidentialTransferClient } from "./confidential-client.js";
 export { AnonymousTransferClient } from "./anonymous-client.js";
 export { deriveKeys, decryptCiphertext, combineCiphertext } from "./crypto.js";
-export { encodeTransferProof, encodeWithdrawProof } from "./utils.js";
+export {
+  encodeTransferProof,
+  encodeWithdrawProof,
+  validateAnonymousAccountId,
+  MAX_ANONYMOUS_ACCOUNT_ID_LENGTH,
+} from "./utils.js";
 export {
   CONTRACT_ABI,
   ERC20_ABI,

package/src/utils.js

@@ -3,6 +3,40 @@ import { ethers } from "ethers";
 // Docs: https://docs.pinata.cloud
 const PINATA_UPLOAD_URL = "https://uploads.pinata.cloud/v3/files";
 const PINATA_JWT = process.env.PINATA_JWT;
+
+// Anonymous account ID constraints (must match the Fairycloak relay and on-chain contract rules)
+export const MAX_ANONYMOUS_ACCOUNT_ID_LENGTH = 20;
+const ANONYMOUS_ACCOUNT_ID_REGEX = /^[A-Za-z0-9]+$/;
+
+/**
+ * Validate an anonymous account ID against the rules enforced by the Fairycloak
+ * relay and the on-chain contract:
+ *  - non-empty
+ *  - at most 20 characters
+ *  - alphanumeric characters only (A-Z, a-z, 0-9)
+ *  - case-sensitive (no normalization is applied)
+ *
+ * @param {string} accountId - The anonymous account ID to validate.
+ * @param {string} [fieldName="accountId"] - Name of the field, used in error messages.
+ * @throws {Error} If the account ID violates any of the above rules.
+ */
+export function validateAnonymousAccountId(accountId, fieldName = "accountId") {
+  const RULES =
+    `${fieldName} must be a non-empty string of at most ${MAX_ANONYMOUS_ACCOUNT_ID_LENGTH} characters, ` +
+    `containing only alphanumeric characters (A-Z, a-z, 0-9). IDs are case-sensitive.`;
+
+  if (typeof accountId !== "string" || accountId.length === 0) {
+    throw new Error(`Invalid ${fieldName}: ${RULES}`);
+  }
+  if (accountId.length > MAX_ANONYMOUS_ACCOUNT_ID_LENGTH) {
+    throw new Error(
+      `Invalid ${fieldName} "${accountId}": exceeds ${MAX_ANONYMOUS_ACCOUNT_ID_LENGTH} characters (got ${accountId.length}). ${RULES}`,
+    );
+  }
+  if (!ANONYMOUS_ACCOUNT_ID_REGEX.test(accountId)) {
+    throw new Error(`Invalid ${fieldName} "${accountId}": contains non-alphanumeric characters. ${RULES}`);
+  }
+}
 /**
  * Encodes the ZK-Proof data for a transfer into a format the Solidity contract expects.
  *

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)",
-];