@fairblock/stabletrust 2.0.2 → 2.0.4

package/README.md

@@ -236,19 +236,26 @@ const keys = await client.deriveAnonymousKeys(authWallet, accountId);
 
 ### Key Methods
 
-#### `getNextAccountId()`
+#### `createAccount(authWallet, accountId, elgamalPublicKey, options?)`
 
-Returns the account count. The ID that will be assigned to the **next** new account is `Number(count) + 1`.
+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).
+
+#### `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 count = await client.getNextAccountId();
-const myNewId = Number(count) + 1;
-await client.createAccount(wallet, keys.publicKey);
+const { accountId, accountInfo, created } = await client.ensureAnonymousAccount(
+  wallet,
+  accountId,
+  keys.publicKey,
+);
 ```
 
-#### `createAccount(authWallet, elgamalPublicKey, options?)`
-
-Creates a new anonymous account via the relay. The relay pays gas.
+- **Options**: `deadlineOffset` (default `3600`), `waitUntilReady` (default `true`), `timeoutMs` (default `180000`), `pollIntervalMs` (default `2000`)
+- **Returns**: `{ accountId, accountInfo, created }`
 
 #### `updateAuthKeys(authWallet, accountId, { add, remove }, options?)`
 
@@ -349,6 +356,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:
@@ -429,11 +479,10 @@ const wallet = new ethers.Wallet(process.env.PRIVATE_KEY);
 const tokenAddress = "0xYourTokenAddress";
 const tokenDecimals = 6;
 
-// 1. Determine the ID your account will get, then create it
-const count = await client.getNextAccountId();
-const accountId = Number(count) + 1;
+// 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, keys.publicKey);
+await client.ensureAnonymousAccount(wallet, accountId, keys.publicKey);
 
 // 2. Deposit (user pays gas)
 const depositResult = await client.deposit(
@@ -452,7 +501,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,
@@ -461,7 +524,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,
@@ -505,6 +568,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,16 +5,16 @@
  *   [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
  */
 
 import { ethers } from "ethers";
-import { randomUUID } from "crypto";
 import dotenv from "dotenv";
 import { AnonymousTransferClient } from "@fairblock/stabletrust";
 
@@ -30,9 +30,13 @@ const TOKEN_ADDRESS =
 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 =   25_000n; // 0.025 USDC
+const DEPOSIT_AMOUNT = 100_000n; // 0.1  USDC
+const TRANSFER_AMOUNT = 50_000n; // 0.05 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 =
@@ -121,8 +125,11 @@ async function main() {
 
   console.log("\n── [1] Generate anonymous account IDs ──────────────────");
 
-  const anon1Id = randomUUID();
-  const anon2Id = randomUUID();
+  // 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()}`;
   log("anon1 id:", anon1Id);
   log("anon2 id:", anon2Id);
 
@@ -142,26 +149,25 @@ async function main() {
 
   console.log("\n── [3] Create anonymous accounts ───────────────────────");
 
-  log(`  creating anon1 (id=${anon1Id}) …`);
-  const cr1 = await client.createAccount(anon1Wallet, anon1Id, anon1Keys.publicKey);
-  log(`  request_id: ${cr1.request_id}  status: ${cr1.status}`);
-  if (cr1.error) log(`  [!] Error: ${cr1.error}`);
-
-  log(`  creating anon2 (id=${anon2Id}) …`);
-  const cr2 = await client.createAccount(anon2Wallet, anon2Id, anon2Keys.publicKey);
-  log(`  request_id: ${cr2.request_id}  status: ${cr2.status}`);
-  if (cr2.error) log(`  [!] Error: ${cr2.error}`);
-
-  log("Waiting for Fairycloak to confirm account creations …");
-  const [r1, r2] = await Promise.all([
-    client.waitForRequest(cr1.request_id, { timeoutMs: 180_000 }),
-    client.waitForRequest(cr2.request_id, { timeoutMs: 180_000 }),
-  ]);
-  if (r1.error) log("  [!] create anon1 failed:", r1.error);
-  if (r2.error) log("  [!] create anon2 failed:", r2.error);
+  log(`  ensuring anon1 (id=${anon1Id}) …`);
+  const e1 = await client.ensureAnonymousAccount(
+    anon1Wallet,
+    anon1Id,
+    anon1Keys.publicKey,
+  );
+  log(
+    `  created=${e1.created}  exists=${e1.accountInfo.exists}  finalized=${e1.accountInfo.finalized}`,
+  );
 
-  await waitForAccountReady(client, anon1Id, { label: "anon1" });
-  await waitForAccountReady(client, anon2Id, { label: "anon2" });
+  log(`  ensuring anon2 (id=${anon2Id}) …`);
+  const e2 = await client.ensureAnonymousAccount(
+    anon2Wallet,
+    anon2Id,
+    anon2Keys.publicKey,
+  );
+  log(
+    `  created=${e2.created}  exists=${e2.accountInfo.exists}  finalized=${e2.accountInfo.finalized}`,
+  );
 
   const [i1, i2] = await Promise.all([
     client.getAnonymousAccountInfo(anon1Id),
@@ -190,7 +196,9 @@ async function main() {
   // ── [4] Deposit ──────────────────────────────────────────────────────────────
 
   console.log("\n── [4] Deposit into anon1 ──────────────────────────────");
-  log(`Depositing ${fmt(DEPOSIT_AMOUNT, TOKEN_DECIMALS)} tokens into anon1 (anon1 pays gas) …`);
+  log(
+    `Depositing ${fmt(DEPOSIT_AMOUNT, TOKEN_DECIMALS)} tokens into anon1 (anon1 pays gas) …`,
+  );
 
   const dep = await client.deposit(
     anon1Wallet,
@@ -218,9 +226,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, {
@@ -263,9 +310,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);
@@ -289,10 +336,12 @@ async function main() {
     "anon2:post-apply",
   );
 
-  // ── [7] Withdraw anon2 → public address ──────────────────────────────────────
+  // ── [8] Withdraw anon2 → public address ──────────────────────────────────────
 
-  console.log("\n── [7] Withdraw from anon2 ─────────────────────────────");
-  log(`Withdrawing ${fmt(WITHDRAW_AMOUNT, TOKEN_DECIMALS)} tokens → ${withdrawDest} …`);
+  console.log("\n── [8] Withdraw from anon2 ─────────────────────────────");
+  log(
+    `Withdrawing ${fmt(WITHDRAW_AMOUNT, TOKEN_DECIMALS)} tokens → ${withdrawDest} …`,
+  );
 
   const wd = await client.withdraw(anon2Wallet, anon2Id, {
     destination: withdrawDest,
@@ -327,9 +376,22 @@ async function main() {
   console.log("═══════════════════════════════════════════════════════");
   log("anon1 id   :", anon1Id);
   log("anon2 id   :", anon2Id);
-  log("Deposited  :", ethers.formatUnits(DEPOSIT_AMOUNT, TOKEN_DECIMALS), "tokens → anon1");
-  log("Transferred:", ethers.formatUnits(TRANSFER_AMOUNT, TOKEN_DECIMALS), "tokens → anon2");
-  log("Withdrawn  :", ethers.formatUnits(WITHDRAW_AMOUNT, TOKEN_DECIMALS), "tokens →", withdrawDest);
+  log(
+    "Deposited  :",
+    ethers.formatUnits(DEPOSIT_AMOUNT, TOKEN_DECIMALS),
+    "tokens → anon1",
+  );
+  log(
+    "Transferred:",
+    ethers.formatUnits(TRANSFER_AMOUNT, TOKEN_DECIMALS),
+    "tokens → anon2",
+  );
+  log(
+    "Withdrawn  :",
+    ethers.formatUnits(WITHDRAW_AMOUNT, TOKEN_DECIMALS),
+    "tokens →",
+    withdrawDest,
+  );
 }
 
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairblock/stabletrust",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "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

@@ -10,11 +10,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
@@ -123,22 +127,21 @@ export class AnonymousTransferClient {
   }
 
   /**
-   * Resolve a pubkey-or-wallet to an uncompressed 65-byte hex pubkey (0x04...).
-   * Accepts: ethers.Wallet, ethers.SigningKey, or a hex pubkey string.
+   * Resolve a wallet/address/pubkey to a checksummed EVM address.
+   * Accepts: ethers.Wallet/Signer, an address string, or an uncompressed hex pubkey string.
    * @private
    */
-  _resolvePubkey(walletOrPubkey) {
-    if (typeof walletOrPubkey === "string") {
-      return walletOrPubkey; // already a hex pubkey
-    }
-    if (walletOrPubkey.signingKey) {
-      return walletOrPubkey.signingKey.publicKey; // ethers.Wallet → uncompressed pubkey
+  async _resolveSignerAddress(walletOrAddress) {
+    if (typeof walletOrAddress === "string") {
+      if (ethers.isAddress(walletOrAddress))
+        return ethers.getAddress(walletOrAddress);
+      return ethers.computeAddress(walletOrAddress); // hex pubkey → address
     }
-    if (walletOrPubkey.publicKey) {
-      return walletOrPubkey.publicKey; // ethers.SigningKey
+    if (typeof walletOrAddress.getAddress === "function") {
+      return await walletOrAddress.getAddress();
     }
     throw new Error(
-      "Expected an ethers.Wallet or uncompressed hex public-key string",
+      "Expected an ethers.Wallet/Signer, an address string, or an uncompressed hex public-key string",
     );
   }
 
@@ -515,7 +518,6 @@ export class AnonymousTransferClient {
     const { deadlineOffset = DEFAULT_DEADLINE_OFFSET } = options;
     try {
       const authAddress = await authWallet.getAddress();
-      const authPubkey = this._resolvePubkey(authWallet); // uncompressed 65-byte pubkey
 
       // Normalise elgamal key to hex
       const elgamalHex = elgamalPublicKey.startsWith("0x")
@@ -557,7 +559,7 @@ export class AnonymousTransferClient {
       return await this._fetch("POST", "/v1/anonymous/accounts", {
         account_id: accountId,
         elgamal_pubkey: elgamalHex,
-        auth_pubkeys: [authPubkey],
+        auth_signers: [authAddress],
         client_request_id: clientRequestId,
         deadline: String(deadline),
         signature,
@@ -569,14 +571,106 @@ export class AnonymousTransferClient {
     }
   }
 
+  /**
+   * Create an anonymous account if it doesn't already exist, and (optionally) wait
+   * until it has settled (no pending CW→EVM action) before returning.
+   *
+   * Looks the account up by `accountId` first — if it already exists on-chain this
+   * skips account creation entirely (idempotent re-runs with a stable `accountId`).
+   * Note that an auth signer can only ever be bound to a single anonymous account,
+   * 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} 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
+   * @param {boolean} [options.waitUntilReady=true] - Poll until `hasPendingAction` is false
+   * @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}>}
+   */
+  async ensureAnonymousAccount(authWallet, accountId, elgamalPublicKey, options = {}) {
+    const {
+      deadlineOffset = DEFAULT_DEADLINE_OFFSET,
+      waitUntilReady = true,
+      timeoutMs = 180_000,
+      pollIntervalMs = 2000,
+    } = options;
+
+    const cutoff = Date.now() + timeoutMs;
+    const waitForReady = async () => {
+      let info = await this.getAnonymousAccountInfo(accountId);
+      while (waitUntilReady && info.hasPendingAction) {
+        if (Date.now() > cutoff) {
+          throw new Error(
+            `Timeout waiting for anonymous account ${accountId} to become ready`,
+          );
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+        info = await this.getAnonymousAccountInfo(accountId);
+      }
+      return info;
+    };
+
+    let accountInfo = await this.getAnonymousAccountInfo(accountId);
+    if (accountInfo.exists) {
+      accountInfo = await waitForReady();
+      return { accountId, accountInfo, created: false };
+    }
+
+    const failIfAlreadyUsed = async (err) => {
+      if (typeof err === "string" && err.includes("already used")) {
+        const address = await authWallet.getAddress();
+        throw new Error(
+          `Signer ${address} is already bound to a different anonymous account, ` +
+            `but no account exists with accountId "${accountId}". ` +
+            `The provided accountId is likely incorrect — each auth signer can only ` +
+            `ever be registered to a single anonymous account.`,
+        );
+      }
+    };
+
+    const created = await this.createAccount(authWallet, accountId, elgamalPublicKey, {
+      deadlineOffset,
+    });
+    if (created.status === "failed" || created.error) {
+      await failIfAlreadyUsed(created.error);
+      throw new Error(
+        `Failed to create anonymous account ${accountId}: ${created.error ?? "request failed"}`,
+      );
+    }
+
+    const finalRequest = await this.waitForRequest(created.request_id, { timeoutMs });
+    if (finalRequest.status === "failed" || finalRequest.error) {
+      await failIfAlreadyUsed(finalRequest.error);
+      throw new Error(
+        `Failed to create anonymous account ${accountId}: ${finalRequest.error ?? "request failed"}`,
+      );
+    }
+
+    while (!accountInfo.exists) {
+      if (Date.now() > cutoff) {
+        throw new Error(
+          `Timeout waiting for anonymous account ${accountId} to be created`,
+        );
+      }
+      await new Promise((r) => setTimeout(r, pollIntervalMs));
+      accountInfo = await this.getAnonymousAccountInfo(accountId);
+    }
+
+    accountInfo = await waitForReady();
+    return { accountId, accountInfo, created: true };
+  }
+
   /**
    * Update the set of authorised signers for an anonymous account via Fairycloak.
    *
    * @param {ethers.Wallet|ethers.Signer} authWallet - A currently authorised signer
    * @param {string} accountId
    * @param {Object} keys
-   * @param {Array<string|ethers.Wallet>} [keys.add=[]]    - Pubkeys/wallets to add
-   * @param {Array<string|ethers.Wallet>} [keys.remove=[]] - Pubkeys/wallets to remove
+   * @param {Array<string|ethers.Wallet|ethers.Signer>} [keys.add=[]]    - Addresses/wallets/pubkeys to add
+   * @param {Array<string|ethers.Wallet|ethers.Signer>} [keys.remove=[]] - Addresses/wallets/pubkeys to remove
    * @param {Object} [options]
    * @param {number} [options.deadlineOffset=3600]
    * @returns {Promise<{request_id:string, tx_hash:string, status:string}>}
@@ -592,13 +686,11 @@ export class AnonymousTransferClient {
       const authNonce = await this.getAuthNonce(accountId);
       const deadline = this._makeDeadline(deadlineOffset);
 
-      const addPubkeys = add.map((w) => this._resolvePubkey(w));
-      const removePubkeys = remove.map((w) => this._resolvePubkey(w));
-
-      // EIP-712 signs over address arrays, not raw pubkeys
-      const addAddresses = addPubkeys.map((pk) => ethers.computeAddress(pk));
-      const removeAddresses = removePubkeys.map((pk) =>
-        ethers.computeAddress(pk),
+      const addAddresses = await Promise.all(
+        add.map((w) => this._resolveSignerAddress(w)),
+      );
+      const removeAddresses = await Promise.all(
+        remove.map((w) => this._resolveSignerAddress(w)),
       );
 
       const addSignersHash = ethers.keccak256(
@@ -633,8 +725,8 @@ export class AnonymousTransferClient {
 
       return await this._fetch("POST", "/v1/anonymous/keys/update", {
         account_id: accountId,
-        add_pubkeys: addPubkeys,
-        remove_pubkeys: removePubkeys,
+        add_signers: addAddresses,
+        remove_signers: removeAddresses,
         auth_nonce: String(authNonce),
         deadline: String(deadline),
         signature,
@@ -898,6 +990,8 @@ export class AnonymousTransferClient {
         });
       }
 
+      await this._assertSufficientPrepaidFees(accountId);
+
       const authNonce = await this.getAuthNonce(accountId);
       const deadline = this._makeDeadline(deadlineOffset);
       const proofHash = ethers.keccak256(proofHex);
@@ -1030,6 +1124,8 @@ export class AnonymousTransferClient {
         });
       }
 
+      await this._assertSufficientPrepaidFees(senderAccountId);
+
       const authNonce = await this.getAuthNonce(senderAccountId);
       const deadline = this._makeDeadline(deadlineOffset);
       const proofHash = ethers.keccak256(proofHex);
@@ -1288,6 +1384,368 @@ 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) {
+    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 = {}) {
+    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 = {},
+  ) {
+    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 = {}) {
+    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: "0x3dd15891e6a8C87Ac0eaB0FF9F76D2B8Bb390173", //Arc
+  5042002: "0x18c8aEc4Ce4fCdB6687Bb99a402277e82394AFF7", //Arc
   84532: "0xF66A0a1670F14AE5D1852B4E7d1e4C693b2Accfd", //Base
   11155111: "0xa066b5C30382110d19925108BBa1Eef613a3A041", //Ethereum
   421614: "0xbda65d65A7833D28F9391FF01d0b212B75538Cf2", //Arbitrum

package/src/index.d.ts

@@ -146,6 +146,24 @@ 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.
    *
@@ -229,6 +247,67 @@ 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 ───────────────────────────────────────
 
     /**