@fairblock/stabletrust 2.0.1 → 2.0.3

package/README.md

@@ -236,19 +236,9 @@ 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`.
-
-```javascript
-const count = await client.getNextAccountId();
-const myNewId = Number(count) + 1;
-await client.createAccount(wallet, keys.publicKey);
-```
-
-#### `createAccount(authWallet, elgamalPublicKey, options?)`
-
-Creates a new anonymous account via the relay. The relay pays gas.
+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).
 
 #### `updateAuthKeys(authWallet, accountId, { add, remove }, options?)`
 
@@ -429,11 +419,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 create the account
+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.createAccount(wallet, accountId, keys.publicKey);
 
 // 2. Deposit (user pays gas)
 const depositResult = await client.deposit(

package/examples/anonymous-flow.js

@@ -14,7 +14,6 @@
  */
 
 import { ethers } from "ethers";
-import { randomUUID } from "crypto";
 import dotenv from "dotenv";
 import { AnonymousTransferClient } from "@fairblock/stabletrust";
 
@@ -30,9 +29,9 @@ 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 = 50_000n; // 0.025 USDC
 
 // Anvil test accounts — override via .env
 const ANON1_PK =
@@ -121,8 +120,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 +144,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 +191,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,
@@ -292,7 +295,9 @@ async function main() {
   // ── [7] Withdraw anon2 → public address ──────────────────────────────────────
 
   console.log("\n── [7] Withdraw from anon2 ─────────────────────────────");
-  log(`Withdrawing ${fmt(WITHDRAW_AMOUNT, TOKEN_DECIMALS)} tokens → ${withdrawDest} …`);
+  log(
+    `Withdrawing ${fmt(WITHDRAW_AMOUNT, TOKEN_DECIMALS)} tokens → ${withdrawDest} …`,
+  );
 
   const wd = await client.withdraw(anon2Wallet, anon2Id, {
     destination: withdrawDest,
@@ -327,9 +332,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.1",
+  "version": "2.0.3",
   "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

@@ -123,22 +123,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
+  async _resolveSignerAddress(walletOrAddress) {
+    if (typeof walletOrAddress === "string") {
+      if (ethers.isAddress(walletOrAddress))
+        return ethers.getAddress(walletOrAddress);
+      return ethers.computeAddress(walletOrAddress); // hex pubkey → address
     }
-    if (walletOrPubkey.signingKey) {
-      return walletOrPubkey.signingKey.publicKey; // ethers.Wallet → uncompressed pubkey
-    }
-    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 +514,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 +555,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 +567,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 +682,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 +721,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,

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: "0x0E56ade5A9d05D5fDa3ffe08Df64cFc0eD597D94", //Arc
+  5042002: "0xdA4a410F600E1C245DC1188Ee559833879f62Fbb", //Arc
   84532: "0xF66A0a1670F14AE5D1852B4E7d1e4C693b2Accfd", //Base
   11155111: "0xa066b5C30382110d19925108BBa1Eef613a3A041", //Ethereum
   421614: "0xbda65d65A7833D28F9391FF01d0b212B75538Cf2", //Arbitrum