@fairblock/stabletrust 2.0.3 → 2.0.5

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,24 @@ 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?)`
+
+Idempotent helper that creates the anonymous account if it doesn't already exist, and (by default) waits until it has settled (no pending CW→EVM action) before returning. If an account with `accountId` already exists on-chain, account creation is skipped entirely — safe to call on every run with a stable `accountId`.
+
+> Note: an auth signer can only ever be bound to a single anonymous account, so reusing a wallet across different `accountId`s will fail at creation time even via `ensureAnonymousAccount`.
+
+```javascript
+const { accountId, accountInfo, created } = await client.ensureAnonymousAccount(
+  wallet,
+  accountId,
+  keys.publicKey,
+);
+```
+
+- **Options**: `deadlineOffset` (default `3600`), `waitUntilReady` (default `true`), `timeoutMs` (default `180000`), `pollIntervalMs` (default `2000`)
+- **Returns**: `{ accountId, accountInfo, created }`
 
 #### `updateAuthKeys(authWallet, accountId, { add, remove }, options?)`
 
@@ -339,6 +367,49 @@ const result = await client.withdraw(wallet, accountId, {
 });
 ```
 
+### Prepaid Fees
+
+Every `transferToPublic` and `transferToAnonymous` call deducts a protocol fee from the sender account's **prepaid fee reserve**. The SDK checks this balance before submitting a transfer and throws a descriptive error if it's insufficient — top up the reserve with `depositFees` before transferring.
+
+#### `getFeeToken()`
+
+Returns the currently configured ERC-20 fee token address (checksummed). `depositFees` deposits must use this token. The fee token can be rotated by the protocol over time, but existing balances in old fee tokens remain withdrawable.
+
+#### `getFeeAmount()`
+
+Returns the protocol fee amount (in raw ERC-20 units of the fee token) deducted from the prepaid reserve on each anonymous transfer. Returns `0n` if no fee is configured.
+
+#### `getPrepaidFeeBalance(accountId, token)`
+
+Returns the prepaid fee balance (in raw ERC-20 units) for an anonymous account and a given fee token.
+
+#### `depositFees(authWallet, accountId, amount, options?)`
+
+Deposits tokens into the prepaid fee reserve for an anonymous account. **The user pays gas** for this operation (mirrors `deposit()`). Handles ERC-20 approval against the active fee token automatically.
+
+```javascript
+const feeToken = await client.getFeeToken();
+const feeAmount = await client.getFeeAmount();
+const feeBalance = await client.getPrepaidFeeBalance(accountId, feeToken);
+
+if (feeBalance < feeAmount) {
+  const result = await client.depositFees(
+    wallet,
+    accountId,
+    ethers.parseUnits("0.5", tokenDecimals),
+  );
+  await client.waitForRequest(result.request_id);
+}
+```
+
+#### `withdrawFees(authWallet, accountId, { token, destination, amount }, options?)`
+
+Withdraws a specific amount from the prepaid fee reserve for a given fee token. The relay pays gas. Use this to reclaim fees from a specific (possibly historical) fee token.
+
+#### `withdrawAllFees(authWallet, accountId, { destination }, options?)`
+
+Withdraws all prepaid fee balances across all (including historical) fee tokens to `destination`. The relay pays gas.
+
 #### Request Tracking
 
 All relay operations return a `{ request_id, tx_hash, status }` object. Use the following to track completion:
@@ -419,10 +490,10 @@ const wallet = new ethers.Wallet(process.env.PRIVATE_KEY);
 const tokenAddress = "0xYourTokenAddress";
 const tokenDecimals = 6;
 
-// 1. Choose a unique account ID, derive keys, then create the account
+// 1. Choose a unique account ID, derive keys, then ensure the account exists
 const accountId = "my-unique-account-id"; // any non-empty string you choose
 const keys = await client.deriveAnonymousKeys(wallet, accountId);
-await client.createAccount(wallet, accountId, keys.publicKey);
+await client.ensureAnonymousAccount(wallet, accountId, keys.publicKey);
 
 // 2. Deposit (user pays gas)
 const depositResult = await client.deposit(
@@ -441,7 +512,21 @@ const balance = await client.getBalance(
 );
 console.log("Available:", balance.available, "Pending:", balance.pending);
 
-// 4. Transfer to a public address (relay pays gas)
+// 4. Top up the prepaid fee reserve if needed (user pays gas)
+// transferToPublic/transferToAnonymous deduct a protocol fee from this reserve.
+const feeToken = await client.getFeeToken();
+const feeAmount = await client.getFeeAmount();
+const feeBalance = await client.getPrepaidFeeBalance(accountId, feeToken);
+if (feeBalance < feeAmount) {
+  const feeResult = await client.depositFees(
+    wallet,
+    accountId,
+    ethers.parseUnits("0.5", tokenDecimals),
+  );
+  await client.waitForRequest(feeResult.request_id);
+}
+
+// 5. Transfer to a public address (relay pays gas)
 const transferResult = await client.transferToPublic(wallet, accountId, {
   recipient: "0xRecipientAddress",
   token: tokenAddress,
@@ -450,7 +535,7 @@ const transferResult = await client.transferToPublic(wallet, accountId, {
 });
 await client.waitForRequest(transferResult.request_id);
 
-// 5. Withdraw (relay pays gas)
+// 6. Withdraw (relay pays gas)
 const withdrawResult = await client.withdraw(wallet, accountId, {
   destination: wallet.address,
   token: tokenAddress,
@@ -494,6 +579,7 @@ try {
 | "Account finalization timeout" | Account creation is still processing                    | Wait a few minutes and retry                            |
 | "Proof generation failed"      | Invalid inputs or cryptographic operation error         | Verify all parameters and ensure sufficient balance     |
 | "Amount too small"             | Amount rounds to 0 in contract scale                    | Use a larger amount (minimum depends on token decimals) |
+| "Insufficient prepaid fee balance" | Anonymous account's prepaid fee reserve is below the per-transfer fee | Call `depositFees(wallet, accountId, amount)` to top up; use `getFeeToken()`/`getFeeAmount()` to check requirements |
 | Fairycloak HTTP error          | Relay unreachable or request rejected                   | Check the relay URL, API key, and account authorization |
 
 ---

package/examples/anonymous-flow.js

@@ -5,9 +5,10 @@
  *   [2] Derive ElGamal keypairs for both accounts
  *   [3] Create both anonymous accounts via Fairycloak
  *   [4] Deposit tokens into anon1
- *   [5] Transfer anon1 → anon2
- *   [6] Apply pending balance for anon2
- *   [7] Withdraw anon2 → public address
+ *   [5] Top up prepaid fees for anon1 (if balance < 0.1)
+ *   [6] Transfer anon1 → anon2
+ *   [7] Apply pending balance for anon2
+ *   [8] Withdraw anon2 → public address
  *
  * Run:
  *   node examples/anonymous-flow.js
@@ -31,7 +32,11 @@ const TOKEN_DECIMALS = Number(process.env.TOKEN_DECIMALS ?? "6");
 // Amounts in raw ERC-20 units (6 decimals — matches complete-flow.js)
 const DEPOSIT_AMOUNT = 100_000n; // 0.1  USDC
 const TRANSFER_AMOUNT = 50_000n; // 0.05 USDC
-const WITHDRAW_AMOUNT = 50_000n; // 0.025 USDC
+const WITHDRAW_AMOUNT = 20_000n; // 0.02 USDC
+
+// Prepaid fee thresholds (raw units, assumes fee token uses TOKEN_DECIMALS)
+const MIN_FEE_BALANCE = 1_000_000n; // 0.1  — deposit if balance falls below this
+const FEE_DEPOSIT_AMOUNT = 2_000_000n; // 0.5  — how much to top up in one shot
 
 // Anvil test accounts — override via .env
 const ANON1_PK =
@@ -123,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);
 
@@ -221,9 +227,48 @@ async function main() {
     "anon1:post-deposit",
   );
 
-  // ── [5] Transfer anon1 → anon2 ───────────────────────────────────────────────
+  // ── [5] Top up prepaid fees for anon1 ───────────────────────────────────────
+
+  console.log("\n── [5] Top up prepaid fees for anon1 ───────────────────");
+
+  const feeToken = await client.getFeeToken();
+  const feeAmount = await client.getFeeAmount();
+  log("  fee token  :", feeToken);
+  log("  fee/xfer   :", fmt(feeAmount, TOKEN_DECIMALS), "tokens");
+
+  const feeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
+  log("  fee balance:", fmt(feeBalance, TOKEN_DECIMALS), "tokens");
+
+  if (feeBalance < MIN_FEE_BALANCE) {
+    log(
+      `  balance < ${fmt(MIN_FEE_BALANCE, TOKEN_DECIMALS)}, depositing ${fmt(FEE_DEPOSIT_AMOUNT, TOKEN_DECIMALS)} fee tokens (anon1 pays gas) …`,
+    );
+    const fd = await client.depositFees(
+      anon1Wallet,
+      anon1Id,
+      FEE_DEPOSIT_AMOUNT,
+    );
+    log("  request_id:", fd.request_id, "  status:", fd.status);
+    if (fd.error) log("    [!] Error:", fd.error);
+    if (fd.tx_hash) log("  tx_hash   :", fd.tx_hash);
+
+    const fdFinal = await client.waitForRequest(fd.request_id, {
+      timeoutMs: 180_000,
+    });
+    log("  status    :", fdFinal.status, "  tx_hash:", fdFinal.tx_hash ?? "—");
+    if (fdFinal.error) log("    [!] Error:", fdFinal.error);
+
+    const newFeeBalance = await client.getPrepaidFeeBalance(anon1Id, feeToken);
+    log("  new fee balance:", fmt(newFeeBalance, TOKEN_DECIMALS), "tokens");
+  } else {
+    log(
+      `  fee balance sufficient (${fmt(feeBalance, TOKEN_DECIMALS)} ≥ ${fmt(MIN_FEE_BALANCE, TOKEN_DECIMALS)}), skipping deposit.`,
+    );
+  }
+
+  // ── [6] Transfer anon1 → anon2 ───────────────────────────────────────────────
 
-  console.log("\n── [5] Transfer anon1 → anon2 ──────────────────────────");
+  console.log("\n── [6] Transfer anon1 → anon2 ──────────────────────────");
   log(`Transferring ${fmt(TRANSFER_AMOUNT, TOKEN_DECIMALS)} tokens …`);
 
   const txAnon = await client.transferToAnonymous(anon1Wallet, anon1Id, {
@@ -266,9 +311,9 @@ async function main() {
     "anon2:post-transfer",
   );
 
-  // ── [6] Apply pending for anon2 ──────────────────────────────────────────────
+  // ── [7] Apply pending for anon2 ──────────────────────────────────────────────
 
-  console.log("\n── [6] Apply pending balance for anon2 ─────────────────");
+  console.log("\n── [7] Apply pending balance for anon2 ─────────────────");
   log("Moving incoming credit from pending → available …");
 
   const ap = await client.applyPending(anon2Wallet, anon2Id);
@@ -292,9 +337,9 @@ async function main() {
     "anon2:post-apply",
   );
 
-  // ── [7] Withdraw anon2 → public address ──────────────────────────────────────
+  // ── [8] Withdraw anon2 → public address ──────────────────────────────────────
 
-  console.log("\n── [7] Withdraw from anon2 ─────────────────────────────");
+  console.log("\n── [8] Withdraw from anon2 ─────────────────────────────");
   log(
     `Withdrawing ${fmt(WITHDRAW_AMOUNT, TOKEN_DECIMALS)} tokens → ${withdrawDest} …`,
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairblock/stabletrust",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "SDK for confidential transfers using homomorphic encryption and zero-knowledge proofs",
   "main": "src/index.js",
   "types": "src/index.d.ts",

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)
@@ -10,11 +14,15 @@ const ANON_DOMAIN_VERSION = "1";
 // Default deadline offset: 1 hour
 const DEFAULT_DEADLINE_OFFSET = 3600;
 
-// Minimal ABI — only used for deposit calldata encoding (reads go through Fairycloak views)
+// Minimal ABI — only used for deposit/fee calldata encoding (reads go through Fairycloak views)
 const DEPOSIT_INTERFACE = new ethers.Interface([
   "function depositAnonymous(string accountId, address token, uint256 plainAmount, uint256 authNonce, uint256 deadline, bytes authSig) external",
 ]);
 
+const ADD_FEES_INTERFACE = new ethers.Interface([
+  "function addFees(string accountId, address token, uint256 amount, uint256 authNonce, uint256 deadline, bytes signature) external payable",
+]);
+
 /**
  * Internal helper to parse values as BigInt, handling hex strings and null/undefined.
  * @private
@@ -34,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 {
   /**
@@ -187,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",
@@ -230,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}`,
@@ -308,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");
@@ -343,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();
@@ -504,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();
@@ -577,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
@@ -585,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,
@@ -677,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);
@@ -756,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 {
@@ -929,6 +959,7 @@ export class AnonymousTransferClient {
     },
     options = {},
   ) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       if (!ethers.isAddress(recipient))
@@ -986,6 +1017,8 @@ export class AnonymousTransferClient {
         });
       }
 
+      await this._assertSufficientPrepaidFees(accountId);
+
       const authNonce = await this.getAuthNonce(accountId);
       const deadline = this._makeDeadline(deadlineOffset);
       const proofHash = ethers.keccak256(proofHex);
@@ -1063,6 +1096,8 @@ export class AnonymousTransferClient {
     },
     options = {},
   ) {
+    validateAnonymousAccountId(senderAccountId, "senderAccountId");
+    validateAnonymousAccountId(recipientId, "recipientId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       if (!ethers.isAddress(token))
@@ -1118,6 +1153,8 @@ export class AnonymousTransferClient {
         });
       }
 
+      await this._assertSufficientPrepaidFees(senderAccountId);
+
       const authNonce = await this.getAuthNonce(senderAccountId);
       const deadline = this._makeDeadline(deadlineOffset);
       const proofHash = ethers.keccak256(proofHex);
@@ -1173,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);
@@ -1240,6 +1278,7 @@ export class AnonymousTransferClient {
     },
     options = {},
   ) {
+    validateAnonymousAccountId(accountId, "accountId");
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       if (!ethers.isAddress(destination))
@@ -1349,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}`);
@@ -1376,6 +1416,372 @@ export class AnonymousTransferClient {
     }
   }
 
+  // ─────────────────── prepaid fee reads ─────────────────────────
+
+  /**
+   * Get the currently configured fee token address from the contract.
+   *
+   * Deposits via `depositFees` must use this token. Rotate-aware: the fee token
+   * can change over time, but existing balances for old tokens remain withdrawable.
+   *
+   * @returns {Promise<string>} Checksummed ERC-20 token address (or address(0) if none set)
+   */
+  async getFeeToken() {
+    try {
+      const data = await this._fetch("GET", "/v1/views/fee-token");
+      const raw = data.result ?? data;
+      const addr = typeof raw === "string" ? raw : raw.feeToken ?? raw;
+      return ethers.getAddress(addr);
+    } catch (e) {
+      throw new Error(`Failed to get fee token: ${e.message}`);
+    }
+  }
+
+  /**
+   * Get the currently configured protocol fee amount (in raw ERC-20 units of the fee token).
+   *
+   * This is the amount deducted from the prepaid reserve on each anonymous transfer.
+   * Returns 0n if no fee is configured.
+   *
+   * @returns {Promise<bigint>}
+   */
+  async getFeeAmount() {
+    try {
+      const data = await this._fetch("GET", "/v1/views/fee-amount");
+      return _parseBigInt(data.result ?? data);
+    } catch (e) {
+      throw new Error(`Failed to get fee amount: ${e.message}`);
+    }
+  }
+
+  /**
+   * Get the prepaid fee balance for an anonymous account and token (in raw ERC-20 units).
+   *
+   * @param {string} accountId
+   * @param {string} token - ERC-20 token address (use `getFeeToken()` to get the active fee token)
+   * @returns {Promise<bigint>}
+   */
+  async getPrepaidFeeBalance(accountId, token) {
+    validateAnonymousAccountId(accountId, "accountId");
+    try {
+      if (!ethers.isAddress(token))
+        throw new Error(`Invalid token address: ${token}`);
+      const data = await this._fetch(
+        "GET",
+        `/v1/views/anonymous/accounts/${accountId}/prepaid-fees/${token}`,
+      );
+      return _parseBigInt(data.result ?? data);
+    } catch (e) {
+      throw new Error(`Failed to get prepaid fee balance: ${e.message}`);
+    }
+  }
+
+  /**
+   * Check that the anonymous account has sufficient prepaid fees to cover one transfer.
+   * Throws a descriptive error if the balance is insufficient.
+   * @private
+   */
+  async _assertSufficientPrepaidFees(accountId) {
+    const [feeToken, feeAmount] = await Promise.all([
+      this.getFeeToken(),
+      this.getFeeAmount(),
+    ]);
+    if (feeAmount === 0n) return; // no fee configured
+
+    if (feeToken === ethers.ZeroAddress) return; // fee token not set
+
+    const balance = await this.getPrepaidFeeBalance(accountId, feeToken);
+    if (balance < feeAmount) {
+      throw new Error(
+        `Insufficient prepaid fee balance for anonymous account "${accountId}". ` +
+          `Required: ${feeAmount} (raw units of fee token ${feeToken}), ` +
+          `available: ${balance}. ` +
+          `Call depositFees(wallet, accountId, amount) to top up the prepaid fee reserve. ` +
+          `Use getFeeToken() to get the active fee token address and getFeeAmount() to see the required deposit amount per transfer.`,
+      );
+    }
+  }
+
+  // ─────────────────── prepaid fee actions ────────────────────────
+
+  /**
+   * Deposit tokens into the prepaid fee reserve for an anonymous account.
+   *
+   * Mirrors `deposit()` from a transaction-signing perspective: the user wallet pays
+   * gas and signs the raw EVM transaction. Fairycloak validates and broadcasts it.
+   *
+   * Steps:
+   *   1. Fetch the active fee token from the contract
+   *   2. ERC-20 approve if allowance is insufficient
+   *   3. Sign EIP-712 AnonymousAddFees authorisation payload
+   *   4. Build and sign the raw `addFees(...)` EVM transaction
+   *   5. Submit to Fairycloak `/v1/anonymous/fees/add/raw-tx`
+   *
+   * @param {ethers.Wallet} authWallet - Wallet that owns the tokens and pays gas
+   * @param {string} accountId - Target anonymous account ID
+   * @param {bigint|string|number} amount - Amount in raw ERC-20 units of the active fee token
+   * @param {Object} [options]
+   * @param {number}  [options.deadlineOffset=3600]
+   * @param {bigint}  [options.gasLimit=300000n]
+   * @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 {
+      const amountBig = BigInt(amount);
+      if (amountBig <= 0n) throw new Error("Amount must be greater than 0");
+
+      const feeToken = await this.getFeeToken();
+      if (feeToken === ethers.ZeroAddress)
+        throw new Error(
+          "No fee token is currently configured on the contract. Contact the protocol operator.",
+        );
+
+      const depositorAddress = await authWallet.getAddress();
+      const walletWithProvider = authWallet.connect
+        ? authWallet.connect(this.provider)
+        : authWallet;
+
+      // 1. Approve if needed
+      const tokenContract = new ethers.Contract(
+        feeToken,
+        [
+          "function balanceOf(address) view returns (uint256)",
+          "function allowance(address,address) view returns (uint256)",
+          "function approve(address,uint256) returns (bool)",
+        ],
+        walletWithProvider,
+      );
+
+      const [balance, allowance] = await Promise.all([
+        tokenContract.balanceOf(depositorAddress),
+        tokenContract.allowance(depositorAddress, this.diamondAddress),
+      ]);
+
+      if (balance < amountBig)
+        throw new Error(
+          `Insufficient fee token balance. Required: ${amountBig}, available: ${balance}`,
+        );
+
+      if (allowance < amountBig) {
+        const approveTx = await tokenContract.approve(
+          this.diamondAddress,
+          ethers.MaxUint256,
+        );
+        const receipt = await approveTx.wait();
+        if (!receipt || receipt.status === 0)
+          throw new Error("Fee token approval failed");
+      }
+
+      // 2. EIP-712 AnonymousAddFees signature
+      const authNonce = await this.getAuthNonce(accountId);
+      const deadline = this._makeDeadline(deadlineOffset);
+
+      const domain = this._buildDomain();
+      const types = {
+        AnonymousAddFees: [
+          { name: "accountId", type: "string" },
+          { name: "token", type: "address" },
+          { name: "amount", type: "uint256" },
+          { name: "authNonce", type: "uint256" },
+          { name: "deadline", type: "uint256" },
+        ],
+      };
+      const value = {
+        accountId: String(accountId),
+        token: feeToken,
+        amount: amountBig,
+        authNonce,
+        deadline: BigInt(deadline),
+      };
+
+      const signature = await authWallet.signTypedData(domain, types, value);
+
+      // 3. Build and sign the raw addFees transaction
+      const calldata = ADD_FEES_INTERFACE.encodeFunctionData("addFees", [
+        accountId,
+        feeToken,
+        amountBig,
+        authNonce,
+        BigInt(deadline),
+        signature,
+      ]);
+
+      const [nonce, feeData] = await Promise.all([
+        this.provider.getTransactionCount(depositorAddress),
+        this.provider.getFeeData(),
+      ]);
+
+      let txObj;
+      if (feeData.maxFeePerGas) {
+        txObj = {
+          to: this.diamondAddress,
+          data: calldata,
+          nonce,
+          chainId: BigInt(this.chainId),
+          gasLimit,
+          maxFeePerGas: (feeData.maxFeePerGas * 12n) / 10n,
+          maxPriorityFeePerGas: feeData.maxPriorityFeePerGas ?? 0n,
+          value: 0n,
+        };
+      } else {
+        txObj = {
+          to: this.diamondAddress,
+          data: calldata,
+          nonce,
+          chainId: BigInt(this.chainId),
+          gasLimit,
+          gasPrice: (feeData.gasPrice * 11n) / 10n,
+          value: 0n,
+        };
+      }
+
+      const signedTx = await authWallet.signTransaction(txObj);
+
+      // 4. Submit to Fairycloak
+      return await this._fetch("POST", "/v1/anonymous/fees/add/raw-tx", {
+        raw_tx: signedTx,
+      });
+    } catch (e) {
+      const msg = e?.message ?? String(e);
+      if (
+        msg.startsWith("Fairycloak") ||
+        msg.startsWith("Insufficient") ||
+        msg.startsWith("No fee token")
+      )
+        throw e;
+      throw new Error(`Failed to deposit fees: ${msg}`);
+    }
+  }
+
+  /**
+   * Withdraw a specific amount from the prepaid fee reserve via Fairycloak. The relay pays gas.
+   *
+   * Use this to reclaim fees for a specific (possibly historical) fee token.
+   *
+   * @param {ethers.Wallet|ethers.Signer} authWallet - Authorised signer for the anonymous account
+   * @param {string} accountId
+   * @param {Object} params
+   * @param {string}              params.token       - Fee token address to withdraw
+   * @param {string}              params.destination - Destination EVM address
+   * @param {bigint|string|number} params.amount     - Amount in raw ERC-20 units
+   * @param {Object} [options]
+   * @param {number} [options.deadlineOffset=3600]
+   * @returns {Promise<{request_id:string, tx_hash:string, status:string}>}
+   */
+  async withdrawFees(
+    authWallet,
+    accountId,
+    { token, destination, amount },
+    options = {},
+  ) {
+    validateAnonymousAccountId(accountId, "accountId");
+    const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
+    try {
+      if (!ethers.isAddress(token))
+        throw new Error(`Invalid token address: ${token}`);
+      if (!ethers.isAddress(destination))
+        throw new Error(`Invalid destination address: ${destination}`);
+      const amountBig = BigInt(amount);
+      if (amountBig <= 0n) throw new Error("Amount must be greater than 0");
+
+      const authNonce = await this.getAuthNonce(accountId);
+      const deadline = this._makeDeadline(deadlineOffset);
+
+      const domain = this._buildDomain();
+      const types = {
+        AnonymousWithdrawFees: [
+          { name: "accountId", type: "string" },
+          { name: "token", type: "address" },
+          { name: "destination", type: "address" },
+          { name: "amount", type: "uint256" },
+          { name: "authNonce", type: "uint256" },
+          { name: "deadline", type: "uint256" },
+        ],
+      };
+      const value = {
+        accountId: String(accountId),
+        token,
+        destination,
+        amount: amountBig,
+        authNonce,
+        deadline: BigInt(deadline),
+      };
+
+      const signature = await authWallet.signTypedData(domain, types, value);
+
+      return await this._fetch("POST", "/v1/anonymous/fees/withdraw", {
+        account_id: accountId,
+        token,
+        destination,
+        amount: String(amountBig),
+        auth_nonce: String(authNonce),
+        deadline: String(deadline),
+        signature,
+      });
+    } catch (e) {
+      const msg = e?.message ?? String(e);
+      if (msg.startsWith("Fairycloak") || msg.startsWith("Invalid")) throw e;
+      throw new Error(`Failed to withdraw fees: ${msg}`);
+    }
+  }
+
+  /**
+   * Withdraw all prepaid fee balances across all (including historical) fee tokens via Fairycloak.
+   * The relay pays gas.
+   *
+   * @param {ethers.Wallet|ethers.Signer} authWallet - Authorised signer for the anonymous account
+   * @param {string} accountId
+   * @param {Object} params
+   * @param {string} params.destination - Destination EVM address
+   * @param {Object} [options]
+   * @param {number} [options.deadlineOffset=3600]
+   * @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))
+        throw new Error(`Invalid destination address: ${destination}`);
+
+      const authNonce = await this.getAuthNonce(accountId);
+      const deadline = this._makeDeadline(deadlineOffset);
+
+      const domain = this._buildDomain();
+      const types = {
+        AnonymousWithdrawAllFees: [
+          { name: "accountId", type: "string" },
+          { name: "destination", type: "address" },
+          { name: "authNonce", type: "uint256" },
+          { name: "deadline", type: "uint256" },
+        ],
+      };
+      const value = {
+        accountId: String(accountId),
+        destination,
+        authNonce,
+        deadline: BigInt(deadline),
+      };
+
+      const signature = await authWallet.signTypedData(domain, types, value);
+
+      return await this._fetch("POST", "/v1/anonymous/fees/withdraw-all", {
+        account_id: accountId,
+        destination,
+        auth_nonce: String(authNonce),
+        deadline: String(deadline),
+        signature,
+      });
+    } catch (e) {
+      const msg = e?.message ?? String(e);
+      if (msg.startsWith("Fairycloak") || msg.startsWith("Invalid")) throw e;
+      throw new Error(`Failed to withdraw all fees: ${msg}`);
+    }
+  }
+
   // ──────────────────── request tracking ─────────────────────────
 
   /**

package/src/constants.js

@@ -25,7 +25,7 @@ export const TEMPO_FEE_TOKEN_ADDRESS =
   "0x20c0000000000000000000000000000000000000";
 export const STABLETRUST_CONTRACTS_BY_CHAIN_ID = Object.freeze({
   2201: "0xA98e5ba75Bb44459916D52Abf1604caB3d98CC4B", //Stable
-  5042002: "0xdA4a410F600E1C245DC1188Ee559833879f62Fbb", //Arc
+  5042002: "0xfc29476B8e53765Ca16ea32882370d850b245336", //Arc
   84532: "0xF66A0a1670F14AE5D1852B4E7d1e4C693b2Accfd", //Base
   11155111: "0xa066b5C30382110d19925108BBa1Eef613a3A041", //Ethereum
   421614: "0xbda65d65A7833D28F9391FF01d0b212B75538Cf2", //Arbitrum

package/src/index.d.ts

@@ -146,11 +146,39 @@ declare module "@fairblock/stabletrust" {
     gasLimit?: bigint;
   }
 
+  export interface DepositFeesOptions extends DeadlineOptions {
+    gasLimit?: bigint;
+  }
+
+  export interface WithdrawFeesParams {
+    /** Fee token address (use `getFeeToken()` to get the active token). */
+    token: string;
+    /** Destination EVM address to receive the withdrawn tokens. */
+    destination: string;
+    /** Amount in raw ERC-20 units of the fee token. */
+    amount: bigint | string | number;
+  }
+
+  export interface WithdrawAllFeesParams {
+    /** Destination EVM address to receive all withdrawn fee tokens. */
+    destination: string;
+  }
+
   /**
    * AnonymousTransferClient — SDK class for anonymous confidential transfers via the Fairycloak relay.
    *
    * 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);
@@ -229,11 +257,73 @@ declare module "@fairblock/stabletrust" {
       params: WithdrawProofParams,
     ): Promise<string>;
 
+    // ── prepaid fee reads ───────────────────────────────────────────
+
+    /**
+     * Get the currently configured fee token address from the contract.
+     * Deposits via `depositFees` must use this token.
+     */
+    getFeeToken(): Promise<string>;
+
+    /**
+     * Get the protocol fee amount in raw ERC-20 units of the fee token.
+     * This is the amount deducted per anonymous transfer. Returns 0n if no fee is set.
+     */
+    getFeeAmount(): Promise<bigint>;
+
+    /**
+     * Get the prepaid fee balance for an anonymous account and token (raw ERC-20 units).
+     * Use `getFeeToken()` to get the active fee token address.
+     */
+    getPrepaidFeeBalance(accountId: string, token: string): Promise<bigint>;
+
+    // ── prepaid fee actions ─────────────────────────────────────────
+
+    /**
+     * Deposit tokens into the prepaid fee reserve for an anonymous account.
+     * The user wallet pays gas for this raw EVM transaction.
+     * Handles ERC-20 approval automatically.
+     *
+     * The fee token is read from the contract — use `getFeeToken()` to see it.
+     * Use `getFeeAmount()` to see how much is deducted per transfer.
+     *
+     * @param amount Amount in raw ERC-20 units of the active fee token
+     */
+    depositFees(
+      authWallet: ethers.Wallet,
+      accountId: string,
+      amount: bigint | string | number,
+      options?: DepositFeesOptions,
+    ): Promise<FairycloakResponse>;
+
+    /**
+     * Withdraw a specific amount from the prepaid fee reserve. The relay pays gas.
+     * Supports historical fee tokens (after a fee-token rotation).
+     */
+    withdrawFees(
+      authWallet: ethers.Wallet | ethers.Signer,
+      accountId: string,
+      params: WithdrawFeesParams,
+      options?: DeadlineOptions,
+    ): Promise<FairycloakResponse>;
+
+    /**
+     * Withdraw all prepaid fee balances across all (including historical) fee tokens.
+     * The relay pays gas.
+     */
+    withdrawAllFees(
+      authWallet: ethers.Wallet | ethers.Signer,
+      accountId: string,
+      params: WithdrawAllFeesParams,
+      options?: DeadlineOptions,
+    ): Promise<FairycloakResponse>;
+
     // ── Fairycloak operations ───────────────────────────────────────
 
     /**
      * 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(
@@ -558,6 +648,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.
  *