@fairblock/stabletrust 1.0.22 → 2.0.0

package/src/{client.js → confidential-client.js}

@@ -428,7 +428,6 @@ export class ConfidentialTransferClient {
    * @param {string} tokenAddress - Token address to transfer
    * @param {number} amount - Amount to transfer
    * @param {Object} [options] - Options
-   * @param {boolean} [options.useOffchainVerify=false] - Use offchain verification
    * @param {boolean} [options.waitForFinalization=true] - Wait for transfer finalization
    * @returns {Promise<Object>} Transaction receipt
    */
@@ -439,7 +438,7 @@ export class ConfidentialTransferClient {
     amount,
     options = {},
   ) {
-    const { useOffchainVerify = false, waitForFinalization = true } = options;
+    const { waitForFinalization = true } = options;
 
     try {
       // Validate inputs
@@ -476,7 +475,7 @@ export class ConfidentialTransferClient {
           `Recipient account does not exist. Address: ${recipientAddress}`,
         );
       }
-      let derivedRecipientPublicKey = recipientAccountInfo.pubkey;
+      let derivedRecipientPublicKey = recipientAccountInfo.elgamalPubkey;
       if (!derivedRecipientPublicKey) {
         throw new Error("Recipient public key is required");
       }
@@ -584,7 +583,6 @@ export class ConfidentialTransferClient {
           recipientAddress,
           tokenAddress,
           transferZkpArg,
-          useOffchainVerify,
           txOverrides,
         );
 
@@ -617,12 +615,11 @@ export class ConfidentialTransferClient {
    * @param {string} tokenAddress - Token address to withdraw
    * @param {number} amount - Amount to withdraw
    * @param {Object} [options] - Options
-   * @param {boolean} [options.useOffchainVerify=false] - Use offchain verification
    * @param {boolean} [options.waitForFinalization=true] - Wait for withdrawal finalization
    * @returns {Promise<Object>} Transaction receipt
    */
   async withdraw(wallet, tokenAddress, amount, options = {}) {
-    const { useOffchainVerify = false, waitForFinalization = true } = options;
+    const { waitForFinalization = true } = options;
 
     try {
       // Validate inputs
@@ -692,12 +689,19 @@ export class ConfidentialTransferClient {
       const currentBalanceContractScale =
         (BigInt(currentBalance) * 100n) / 10n ** BigInt(tokenDecimals);
 
+      // Fetch the contract's per-account txId. Withdraw proofs bind to the *next*
+      // tx id (txId + 1), not the current one — the contract increments the counter
+      // on every action, and the proof must commit to what it will be after submission.
+      const accountInfo = await this.getAccountInfo(address);
+      const txId = BigInt(accountInfo.txId ?? 0n);
+
       // Generate withdrawal proof
       const withdrawInput = {
         current_balance_ciphertext: currentBalanceCiphertext,
         current_balance: Number(currentBalanceContractScale),
         withdraw_amount: Number(withdrawAmount),
         keypair: derivedKeys.privateKey,
+        nonce: Number(txId + 1n),
       };
 
       const wasm = await this._getWasm();
@@ -741,7 +745,6 @@ export class ConfidentialTransferClient {
           tokenAddress,
           BigInt(withdrawAmount),
           withdrawZkpArg,
-          useOffchainVerify,
         );
 
       const receipt = await tx.wait();
@@ -816,7 +819,7 @@ export class ConfidentialTransferClient {
     while (attempts < maxAttempts) {
       try {
         const info = await this.contract.getAccountCore(address);
-        if (!info.hasPendingAction) {
+        if (!info.pendingAction) {
           return; // Success
         }
       } catch (error) {

package/src/constants.js

@@ -5,11 +5,11 @@
 export const CONTRACT_ABI = [
   "function createConfidentialAccount(bytes elgamalPubkey) external",
   "function deposit(address token, uint256 plainAmount) external",
-  "function getAccountCore(address ownerAddr) external view returns ((bool exists, bool finalized, bool hasPendingAction, uint256 lastUpdate, bytes pubkey, bytes availableC1, bytes availableC2, uint64 nonce, uint64 lastProcessedNonce))",
+  "function getAccountCore(address ownerAddr) external view returns ((bool exists, bool finalized, bool pendingAction, uint256 txId, bytes elgamalPubkey, uint64 pendingCreditCounter))",
   "function getAvailable(address ownerAddr, address token) external view returns (bytes c1, bytes c2)",
   "function getPending(address ownerAddr, address token) external view returns (bytes c1, bytes c2)",
-  "function transferConfidential(address recipient, address token, bytes proof, bool useOffchainVerify) external payable",
-  "function withdraw(address token, uint256 plainAmount, bytes proof, bool useOffchainVerify) external",
+  "function transferConfidential(address recipient, address token, bytes proof) external payable",
+  "function withdraw(address token, uint256 plainAmount, bytes proof) external",
   "function applyPending() external",
   "function feeAmount() external view returns (uint256)",
 ];
@@ -23,13 +23,12 @@ export const ERC20_ABI = [
 
 export const TEMPO_FEE_TOKEN_ADDRESS =
   "0x20c0000000000000000000000000000000000000";
-
 export const STABLETRUST_CONTRACTS_BY_CHAIN_ID = Object.freeze({
-  2201: "0xdf43bC80B5b22A858860947d383b6F4d6C81d8EC", //Stable
-  5042002: "0x5d43CE5269Cd46badC67B3664369862F20eC5649", //Arc
-  84532: "0xFBEa2AbCf1208E09dd90266fE94Fb76d8BfC34d9", //Base
-  11155111: "0x72B87207791996F416D2F3B0dcAcbb07F445C496", //Ethereum
-  421614: "0x6C9eDBDd028Fe610b054187A34712714E341D112", //Arbitrum
+  2201: "0xA98e5ba75Bb44459916D52Abf1604caB3d98CC4B", //Stable
+  5042002: "0xdCF31bd9f325C34E0fb346b1975E141D99AEf731", //Arc
+  84532: "0xF66A0a1670F14AE5D1852B4E7d1e4C693b2Accfd", //Base
+  11155111: "0xa066b5C30382110d19925108BBa1Eef613a3A041", //Ethereum
+  421614: "0xbda65d65A7833D28F9391FF01d0b212B75538Cf2", //Arbitrum
   42431: "0xE559fB936C69c46E216bf61B07C16bF1a6d444aa", //Tempo
 });
 

package/src/index.d.ts

@@ -1,6 +1,349 @@
 declare module "@fairblock/stabletrust" {
   import { ethers } from "ethers";
 
+  // ─────────────────── AnonymousTransferClient ────────────────────────────
+
+  export interface AnonymousTransferClientConfig {
+    /** Fairycloak relay server base URL, e.g. "http://127.0.0.1:8080" */
+    fairycloakUrl: string;
+    /** Chain ID — used to auto-resolve the contract address for supported networks */
+    chainId: number | string;
+    /** EVM JSON-RPC URL */
+    rpcUrl: string;
+    /** Optional override for the diamond contract address. Auto-resolved from chainId if omitted. */
+    diamondAddress?: string;
+    /** Optional API key for Fairycloak */
+    apiKey?: string;
+  }
+
+  export interface AnonymousAccountInfo {
+    exists: boolean;
+    finalized: boolean;
+    hasPendingAction: boolean;
+    txId: bigint;
+    elgamalPubkey: string;
+    authNonce: bigint;
+  }
+
+  export interface FairycloakResponse {
+    request_id: string;
+    tx_hash?: string;
+    status: string;
+    action?: string;
+    [key: string]: unknown;
+  }
+
+  export interface RequestEventHistory {
+    request_id: string;
+    events: Array<{
+      request_id: string;
+      sequence: number;
+      type: string;
+      action: string;
+      status: string;
+      created_at: string;
+      [key: string]: unknown;
+    }>;
+  }
+
+  export interface TransferProofParams {
+    currentBalanceCiphertext: string;
+    currentBalanceContractScale: number;
+    transferAmountContractScale: number;
+    destinationPublicKey: string;
+  }
+
+  export interface WithdrawProofParams {
+    currentBalanceCiphertext: string;
+    currentBalanceContractScale: number;
+    withdrawAmountContractScale: number;
+    /**
+     * The *next* contract-level per-account transaction ID ("user tx-id + 1").
+     * Withdraw proofs commit to the txId the account will have **after** the
+     * withdrawal is processed — pass `txId + 1`, not the current `txId`.
+     *
+     * - Confidential accounts: `Number(getAccountInfo(address).txId) + 1`
+     * - Anonymous accounts:    `getAnonymousAccountInfo(accountId).txId + 1n`
+     *
+     * This is NOT the Ethereum account nonce, and NOT the EIP-712 `authNonce`.
+     */
+    nonce: number | bigint;
+  }
+
+  export interface TransferToPublicParams {
+    recipient: string;
+    token: string;
+    /** Pre-computed ZK proof hex. Required if elGamalPrivateKey is not provided. */
+    proof?: string;
+    /** ElGamal private key (base64) for auto-proof generation. */
+    elGamalPrivateKey?: string;
+    /** Transfer amount in token units (e.g. 3000000 for 3 USDC). Required for auto-proof. */
+    amount?: bigint | string | number;
+    /** Recipient ElGamal public key (base64). Auto-resolved from the chain if omitted. */
+    destinationPublicKey?: string;
+  }
+
+  export interface TransferToAnonymousParams {
+    recipientId: number | bigint;
+    token: string;
+    /** Pre-computed ZK proof hex. Required if elGamalPrivateKey is not provided. */
+    proof?: string;
+    /** ElGamal private key (base64) for auto-proof generation. */
+    elGamalPrivateKey?: string;
+    /** Transfer amount in token units (e.g. 2000000 for 2 USDC). Required for auto-proof. */
+    amount?: bigint | string | number;
+    /** Recipient ElGamal public key (base64). Auto-resolved from the chain if omitted. */
+    destinationPublicKey?: string;
+  }
+
+  export interface WithdrawParams {
+    destination: string;
+    token: string;
+    /** Withdrawal amount in token units. */
+    plainAmount: bigint | string | number;
+    /** Pre-computed ZK proof hex. Required if elGamalPrivateKey is not provided. */
+    proof?: string;
+    /** ElGamal private key (base64) for auto-proof generation. Contract scale is derived automatically. */
+    elGamalPrivateKey?: string;
+  }
+
+  export interface AnonymousAccountBalance {
+    /** Total balance: available + pending. Same units as amounts passed to deposit/transfer/withdraw. */
+    amount: number;
+    /** Spendable balance (already settled on-chain). */
+    available: number;
+    /** Incoming balance not yet applied via applyPending(). */
+    pending: number;
+  }
+
+  export interface AnonymousBalanceEntry {
+    /** Decrypted balance in contract-scale units (plainAmount × tokenMul). */
+    amount: number;
+    /** Base64 combined ciphertext, or null if no balance exists. */
+    ciphertext: string | null;
+  }
+
+  export interface AnonymousBalance {
+    available: AnonymousBalanceEntry;
+    pending: AnonymousBalanceEntry;
+  }
+
+  export interface UpdateAuthKeysParams {
+    add?: Array<string | ethers.Wallet>;
+    remove?: Array<string | ethers.Wallet>;
+  }
+
+  export interface WaitForRequestOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+  }
+
+  export interface DeadlineOptions {
+    deadlineOffset?: number;
+  }
+
+  export interface DepositOptions extends DeadlineOptions {
+    gasLimit?: bigint;
+  }
+
+  /**
+   * 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.
+   */
+  export class AnonymousTransferClient {
+    constructor(config: AnonymousTransferClientConfig);
+
+    // ── on-chain reads ──────────────────────────────────────────────
+
+    /**
+     * Get on-chain core state for an anonymous account.
+     */
+    getAnonymousAccountInfo(
+      accountId: number | bigint,
+    ): Promise<AnonymousAccountInfo>;
+
+    /**
+     * Read the current authNonce for an anonymous account.
+     */
+    getAuthNonce(accountId: number | bigint): Promise<bigint>;
+
+    /**
+     * Read the next anonymous account ID that will be assigned.
+     */
+    getNextAccountId(): Promise<bigint>;
+
+    /**
+     * Check whether an address is an authorised signer for an anonymous account.
+     */
+    isAuthorizedSigner(
+      accountId: number | bigint,
+      signerAddress: string,
+    ): Promise<boolean>;
+
+    /**
+     * Get the decrypted balance summary (available + pending) for an anonymous account.
+     * Returns plain numbers in the same units as the amounts passed to deposit/transfer/withdraw.
+     * Use `.available` and `.pending` for individual balances, `.amount` for the total.
+     */
+    getBalance(
+      accountId: number | bigint,
+      tokenAddress: string,
+      elGamalPrivateKey: string,
+    ): Promise<AnonymousAccountBalance>;
+
+    /**
+     * Get the decrypted available and pending balances, including raw ciphertexts.
+     * Use `getBalance` for a simpler numeric summary.
+     */
+    getAnonymousBalance(
+      accountId: number | bigint,
+      tokenAddress: string,
+      elGamalPrivateKey: string,
+    ): Promise<AnonymousBalance>;
+
+    // ── key derivation ──────────────────────────────────────────────
+
+    /**
+     * Derive a deterministic ElGamal keypair for an anonymous account.
+     * Tied to (chainId, diamondAddress, accountId, authWallet).
+     */
+    deriveAnonymousKeys(
+      authWallet: ethers.Wallet | ethers.Signer,
+      accountId: number | bigint,
+    ): Promise<Keys>;
+
+    // ── proof generation ────────────────────────────────────────────
+
+    /**
+     * Generate a ZK transfer proof via WASM.
+     * Pass the returned string to `transferToPublic` or `transferToAnonymous`.
+     */
+    generateTransferProof(
+      elGamalPrivateKey: string,
+      params: TransferProofParams,
+    ): Promise<string>;
+
+    /**
+     * Generate a ZK withdraw proof via WASM.
+     * Pass the returned string to `withdraw`.
+     */
+    generateWithdrawProof(
+      elGamalPrivateKey: string,
+      params: WithdrawProofParams,
+    ): Promise<string>;
+
+    // ── Fairycloak operations ───────────────────────────────────────
+
+    /**
+     * Create a new anonymous account. The relay pays gas.
+     * @param elgamalPublicKey Base64 or "0x"-prefixed hex (32 bytes)
+     */
+    createAccount(
+      authWallet: ethers.Wallet | ethers.Signer,
+      elgamalPublicKey: string,
+      options?: DeadlineOptions,
+    ): Promise<FairycloakResponse>;
+
+    /**
+     * Update the set of authorised signers. The relay pays gas.
+     * Pass ethers.Wallet objects or raw uncompressed hex pubkey strings.
+     */
+    updateAuthKeys(
+      authWallet: ethers.Wallet | ethers.Signer,
+      accountId: number | bigint,
+      keys: UpdateAuthKeysParams,
+      options?: DeadlineOptions,
+    ): Promise<FairycloakResponse>;
+
+    /**
+     * Deposit tokens. The user pays gas for this raw EVM transaction.
+     * Handles ERC-20 approval automatically.
+     */
+    deposit(
+      authWallet: ethers.Wallet,
+      accountId: number | bigint,
+      tokenAddress: string,
+      amount: bigint | string | number,
+      options?: DepositOptions,
+    ): Promise<FairycloakResponse>;
+
+    /**
+     * Transfer from an anonymous account to a public EVM address. The relay pays gas.
+     *
+     * Auto-proof: pass `elGamalPrivateKey`, `transferAmountContractScale`, and `destinationPublicKey`.
+     * Manual proof: pass a pre-computed `proof` hex string from `generateTransferProof()`.
+     */
+    transferToPublic(
+      authWallet: ethers.Wallet | ethers.Signer,
+      accountId: number | bigint,
+      params: TransferToPublicParams,
+      options?: DeadlineOptions,
+    ): Promise<FairycloakResponse>;
+
+    /**
+     * Transfer between two anonymous accounts. The relay pays gas.
+     *
+     * Auto-proof: pass `elGamalPrivateKey`, `transferAmountContractScale`, and `destinationPublicKey`.
+     * Manual proof: pass a pre-computed `proof` hex string from `generateTransferProof()`.
+     */
+    transferToAnonymous(
+      authWallet: ethers.Wallet | ethers.Signer,
+      senderAccountId: number | bigint,
+      params: TransferToAnonymousParams,
+      options?: DeadlineOptions,
+    ): Promise<FairycloakResponse>;
+
+    /**
+     * Apply a pending balance (move incoming credit to available). The relay pays gas.
+     */
+    applyPending(
+      authWallet: ethers.Wallet | ethers.Signer,
+      accountId: number | bigint,
+      options?: DeadlineOptions,
+    ): Promise<FairycloakResponse>;
+
+    /**
+     * Withdraw from an anonymous account to a public address. The relay pays gas.
+     *
+     * Auto-proof: pass `elGamalPrivateKey` and `withdrawAmountContractScale` — the SDK fetches
+     * the ciphertext and generates the proof internally.
+     * Manual proof: pass a pre-computed `proof` hex string from `generateWithdrawProof()`.
+     */
+    withdraw(
+      authWallet: ethers.Wallet | ethers.Signer,
+      accountId: number | bigint,
+      params: WithdrawParams,
+      options?: DeadlineOptions,
+    ): Promise<FairycloakResponse>;
+
+    // ── request tracking ────────────────────────────────────────────
+
+    /**
+     * Get the current status of a Fairycloak request.
+     * Terminal statuses: completed | failed
+     * Tx statuses: confirmed | mined | submitted
+     */
+    getRequestStatus(requestId: string): Promise<FairycloakResponse>;
+
+    /**
+     * Fetch durable event history for a request.
+     */
+    getRequestEvents(
+      requestId: string,
+      options?: { afterSeq?: number; limit?: number },
+    ): Promise<RequestEventHistory>;
+
+    /**
+     * Poll until a request reaches a terminal state (completed/confirmed/failed).
+     */
+    waitForRequest(
+      requestId: string,
+      options?: WaitForRequestOptions,
+    ): Promise<FairycloakResponse>;
+  }
+
   /**
    * SDK configuration
    */
@@ -10,7 +353,7 @@ declare module "@fairblock/stabletrust" {
     chainId: number;
   }
 
-  export type StabletrustChainId =
+  export type StableTrustChainId =
     | 5042002
     | 2201
     | 42431

package/src/index.js

@@ -1,4 +1,5 @@
-export { ConfidentialTransferClient } from "./client.js";
+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 {