@fairblock/stabletrust 2.0.3 → 2.0.4

package/README.md

@@ -240,6 +240,23 @@ const keys = await client.deriveAnonymousKeys(authWallet, accountId);
 
 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 { 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?)`
 
 Adds or removes authorised signers for an anonymous account. Pass `ethers.Wallet` instances or raw uncompressed hex pubkey strings.
@@ -339,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:
@@ -419,10 +479,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 +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,
@@ -450,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,
@@ -494,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,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 =
@@ -221,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, {
@@ -266,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);
@@ -292,9 +336,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.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
@@ -986,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);
@@ -1118,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);
@@ -1376,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: "0xdA4a410F600E1C245DC1188Ee559833879f62Fbb", //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 ───────────────────────────────────────
 
     /**