@fairblock/stabletrust 1.0.8 → 1.0.10

package/README.md

@@ -36,14 +36,14 @@ yarn add @fairblock/stabletrust
 
 The following contract addresses are available for confidential transfers on testnet networks. These are test deployments and should not be used with mainnet assets:
 
-| Network  | Chain ID | Contract Address                             |
-| :------- | :------- | :------------------------------------------- |
-| Stable   | 2201     | `0x29E4fd434758b1677c10854Fa81C2fc496D76E62` |
-| Arc      | 1244     | `0x1Bf79BF5A32D6f3cdce3fe1A93c3fB222Bc93bb3` |
-| Base     | 84532    | `0x73D2bc5B5c7aF5C3726E7bEf0BD8b4931923fdA9` |
-| Ethereum | 11155111 | `0xD765Dff7D734ABE09f88991A46BAb73ACa8910EF` |
-| Arbitrum | 421614   | `0xDC7Df05C2ce67881CDbF9A1af0F4C5d8C94c8A03` |
-| Tempo    | 42431    | `0xB7bdce025c8a25e341Cb55795f8ba865AB3e392C` |
+| Network(Testnet) | Chain ID | Contract Address                             |
+| :--------------- | :------- | :------------------------------------------- |
+| Stable           | 2201     | `0x29E4fd434758b1677c10854Fa81C2fc496D76E62` |
+| Arc              | 1244     | `0xf085e801a6FD9d03b09566a738734B7e2Bb065De` |
+| Base             | 84532    | `0x6FE45A71F5232a4E5e583Ae31A538360fB1e6aDb` |
+| Ethereum         | 11155111 | `0x81a2c161c0327464430658516eE74A669feFC7bC` |
+| Arbitrum         | 421614   | `0xa59462200F6E438c538b914eB5F980B3Fa723aA0` |
+| Tempo            | 42431    | `0xB7bdce025c8a25e341Cb55795f8ba865AB3e392C` |
 
 ## Usage
 
@@ -57,37 +57,40 @@ Import and initialize the client with your network configuration.
 import { ConfidentialTransferClient } from "@fairblock/stabletrust";
 import { ethers } from "ethers";
 
-// Configuration for Arbitrum (example)
+// Configuration for Base Sepolia (uses SDK default StableTrust contract for chainId 84532)
 const client = new ConfidentialTransferClient(
-  "https://arb1.arbitrum.io/rpc",
-  "0x5acE788EF0C9f7f902642001d639AD155fF29A6C",
-  42161,
+  "https://sepolia.base.org",
+  84532,
+);
+```
+
+If you are using a custom deployment, you can still pass an explicit contract address:
+
+```javascript
+const customClient = new ConfidentialTransferClient(
+  "https://sepolia.base.org",
+  "0xYourCustomStableTrustContract",
+  84532,
 );
 ```
 
 #### Network Configuration Examples
 
-For different networks, use the following configurations:
+For testnet networks listed above, use the following configurations:
 
 ```javascript
-// Base
-const baseClient = new ConfidentialTransferClient(
-  "https://mainnet.base.org",
-  "0x05ad3FF447930ad5B4085C07B4Ef9b10Aa0a58F2",
-  8453,
+// Stable testnet
+const stableClient = new ConfidentialTransferClient(
+  "https://rpc.testnet.stable.xyz",
+  2201,
 );
 
-// Ethereum Mainnet
-const ethClient = new ConfidentialTransferClient(
-  "https://eth.public.netzach.io",
-  "0x7B5A0060dE15a1AA1b9712A0146145E9D01A1acA",
-  1,
-);
+// Arc testnet
+const arcClient = new ConfidentialTransferClient("https://rpc.arc.xyz", 1244);
 
 // Tempo (Stablecoin chain with special fee handling)
 const tempoClient = new ConfidentialTransferClient(
   "https://tempo-rpc.example.com",
-  "0x17176c409B66bb03d102215eeEdb34259Db0F5AD",
   42431,
 );
 ```

package/examples/complete-flow.js

@@ -11,8 +11,7 @@ dotenv.config();
  * https://docs.fairblock.network/docs/confidential_transfers/technical_overview
  */
 
-// Currently configured for Stable Testnet confidential mirror contract.
-// You can deploy your own confidential contract on any EVM network and use that.
+// Optional override for custom confidential contract deployments.
 const CONTRACT_ADDRESS =
   process.env.CONTRACT_ADDRESS || "0x29E4fd434758b1677c10854Fa81C2fc496D76E62";
 // Standard ERC20 token contract. Any ERC20 on this chain ID can be used.
@@ -23,7 +22,6 @@ const RPC_URL =
 const EXPLORER_URL =
   process.env.EXPLORER_URL || "https://testnet.stablescan.xyz/tx/";
 const CHAIN_ID = process.env.CHAIN_ID || 2201;
-1;
 
 /**
  * Performance Utility: Tracks execution time and provides timestamps
@@ -47,7 +45,7 @@ async function main() {
   const client = new ConfidentialTransferClient(
     RPC_URL,
     CONTRACT_ADDRESS,
-    CHAIN_ID,
+    Number(CHAIN_ID),
   );
 
   const provider = new ethers.JsonRpcProvider(RPC_URL);

package/examples/simple-snippets.js

@@ -2,17 +2,12 @@ import { ethers } from "ethers";
 import dotenv from "dotenv";
 import { ConfidentialTransferClient } from "@fairblock/stabletrust";
 dotenv.config();
-const RPC_URL =
-  process.env.ETHEREUM_RPC_URL || "https://rpc.testnet.stable.xyz";
+const RPC_URL = process.env.RPC_URL || "https://rpc.testnet.stable.xyz";
 const EXPLORER_URL =
   process.env.EXPLORER_URL || "https://testnet.stablescan.xyz/tx/";
 async function minimalFlow() {
   // 1. Setup Client & Wallets
-  const client = new ConfidentialTransferClient(
-    RPC_URL,
-    "0x29E4fd434758b1677c10854Fa81C2fc496D76E62",
-    2201,
-  );
+  const client = new ConfidentialTransferClient(RPC_URL, 2201);
 
   const provider = new ethers.JsonRpcProvider(RPC_URL);
   const sender = new ethers.Wallet(process.env.SENDER_PRIVATE_KEY, provider);
@@ -26,7 +21,7 @@ async function minimalFlow() {
   await client.ensureAccount(recipient);
 
   const TOKEN = "0x78Cf24370174180738C5B8E352B6D14c83a6c9A9";
-  const amount = ethers.parseUnits("0.001", 6);
+  const amount = ethers.parseUnits("0.1", 2);
   let res;
   // 3. DEPOSIT: Move public ERC20 into the confidential contract
   res = await client.confidentialDeposit(sender, TOKEN, amount);
@@ -37,11 +32,11 @@ async function minimalFlow() {
     sender,
     recipient.address,
     TOKEN,
-    amount / 2n,
+    ethers.parseUnits("0.05", 2),
   );
   console.log("Transfer TX Hash:", EXPLORER_URL + res.hash);
   // 5. WITHDRAW: Convert confidential balance back to public ERC20
-  res = await client.withdraw(recipient, TOKEN, amount / 4n);
+  res = await client.withdraw(recipient, TOKEN, ethers.parseUnits("0.05", 2));
   console.log("Withdraw TX Hash:", EXPLORER_URL + res.hash);
   console.log("Confidential flow complete.");
 }

package/package.json

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

package/src/client.js

@@ -2,7 +2,7 @@ import { ethers } from "ethers";
 import {
   CONTRACT_ABI,
   ERC20_ABI,
-  DEFAULT_CONFIG,
+  getStableTrustContractAddress,
   TEMPO_FEE_TOKEN_ADDRESS,
 } from "./constants.js";
 import { deriveKeys, decryptCiphertext, combineCiphertext } from "./crypto.js";
@@ -27,23 +27,48 @@ export class ConfidentialTransferClient {
    * Create a new ConfidentialTransferClient instance
    *
    * @param {string} rpcUrl - RPC endpoint URL
-   * @param {string} contractAddress - Confidential transfer contract address
-   * @param {number} chainId - Chain ID
+   * @param {string|number} contractAddressOrChainId - Contract address or chain ID
+   * @param {number} [chainId] - Chain ID when contract address is provided
    */
-  constructor(rpcUrl, contractAddress, chainId) {
+  constructor(rpcUrl, contractAddressOrChainId, chainId) {
     // Validate required config
     if (!rpcUrl) {
       throw new Error("rpcUrl is required");
     }
-    if (!contractAddress) {
-      throw new Error("contractAddress is required");
+
+    let resolvedChainId;
+    let resolvedContractAddress;
+
+    if (typeof contractAddressOrChainId === "number" && chainId === undefined) {
+      resolvedChainId = contractAddressOrChainId;
+      resolvedContractAddress = getStableTrustContractAddress(resolvedChainId);
+    } else {
+      resolvedChainId = chainId;
+      resolvedContractAddress =
+        contractAddressOrChainId ||
+        getStableTrustContractAddress(resolvedChainId);
+    }
+
+    if (!resolvedChainId) {
+      throw new Error("chainId is required");
+    }
+    if (!resolvedContractAddress) {
+      const supportedChainIds = [2201, 1244, 84532, 11155111, 421614, 42431]
+        .map(String)
+        .join(", ");
+      throw new Error(
+        `contractAddress is required for chainId ${resolvedChainId}. No default StableTrust contract is configured for this chain. Supported chainIds: ${supportedChainIds}`,
+      );
+    }
+    if (!ethers.isAddress(resolvedContractAddress)) {
+      throw new Error(`Invalid contractAddress: ${resolvedContractAddress}`);
     }
 
     // Build config
     this.config = {
       rpcUrl,
-      contractAddress,
-      chainId,
+      contractAddress: ethers.getAddress(resolvedContractAddress),
+      chainId: Number(resolvedChainId),
     };
 
     // WASM will be auto-initialized on first use
@@ -948,7 +973,7 @@ export class ConfidentialTransferClient {
    * @param {string} tokenAddress - Token address
    * @returns {Promise<bigint>} Token balance
    */
-  async _getTokenBalance(address, tokenAddress) {
+  async getPublicBalance(address, tokenAddress) {
     try {
       if (!address || !ethers.isAddress(address)) {
         throw new Error(`Invalid address: ${address}`);

package/src/constants.js

@@ -20,13 +20,18 @@ export const ERC20_ABI = [
   "function balanceOf(address account) external view returns (uint256)",
 ];
 
-export const DEFAULT_CONFIG = {
-  CHAIN_ID: 421614,
-  EXPLORER_URL: "https://sepolia.arbiscan.io/tx/",
-  RPC_URL: "https://sepolia-rollup.arbitrum.io/rpc",
-  CONTRACT_ADDRESS: "0x30bAc8a17DCACbA7f70F305f4ad908C9fd6d3E2E",
-  TOKEN_ADDRESS: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
-};
-
 export const TEMPO_FEE_TOKEN_ADDRESS =
   "0x20c0000000000000000000000000000000000000";
+
+export const STABLETRUST_CONTRACTS_BY_CHAIN_ID = Object.freeze({
+  2201: "0x29E4fd434758b1677c10854Fa81C2fc496D76E62",
+  1244: "0xf085e801a6FD9d03b09566a738734B7e2Bb065De",
+  84532: "0x6FE45A71F5232a4E5e583Ae31A538360fB1e6aDb",
+  11155111: "0x81a2c161c0327464430658516eE74A669feFC7bC",
+  421614: "0xa59462200F6E438c538b914eB5F980B3Fa723aA0",
+  42431: "0xB7bdce025c8a25e341Cb55795f8ba865AB3e392C",
+});
+
+export function getStableTrustContractAddress(chainId) {
+  return STABLETRUST_CONTRACTS_BY_CHAIN_ID[Number(chainId)] || null;
+}

package/src/index.d.ts

@@ -10,6 +10,14 @@ declare module "@fairblock/stabletrust" {
     chainId: number;
   }
 
+  export type StableTrustChainId =
+    | 1244
+    | 2201
+    | 42431
+    | 84532
+    | 421614
+    | 11155111;
+
   /**
    * Encryption keys
    */
@@ -71,6 +79,13 @@ declare module "@fairblock/stabletrust" {
    * WASM auto-initializes on first use - no manual initialization required!
    */
   export class ConfidentialTransferClient {
+    /**
+     * Create a new ConfidentialTransferClient
+     * @param rpcUrl RPC endpoint URL
+     * @param chainId Chain ID (uses default StableTrust contract for known networks)
+     */
+    constructor(rpcUrl: string, chainId: number);
+
     /**
      * Create a new ConfidentialTransferClient
      * @param rpcUrl RPC endpoint URL
@@ -153,6 +168,13 @@ declare module "@fairblock/stabletrust" {
      * Get the current fee amount for confidential transfers
      */
     getFeeAmount(): Promise<bigint>;
+
+    /**
+     * Get the public ERC20 balance for an address (for comparison with confidential balance)
+     * @param address Account address
+     * @param tokenAddress Token contract address
+     */
+    getPublicBalance(address: string, tokenAddress: string): Promise<bigint>;
   }
 
   /**
@@ -211,10 +233,12 @@ declare module "@fairblock/stabletrust" {
   export const ERC20_ABI: any[];
 
   /**
-   * Default configuration values
+   * StableTrust contract addresses by chain id
+   */
+  export const STABLETRUST_CONTRACTS_BY_CHAIN_ID: Record<number, string>;
+
+  /**
+   * Resolve StableTrust contract address by chain id
    */
-  export const DEFAULT_CONFIG: {
-    CHAIN_ID: number;
-    EXPLORER_URL: string;
-  };
+  export function getStableTrustContractAddress(chainId: number): string | null;
 }

package/src/index.js

@@ -1,5 +1,10 @@
 export { ConfidentialTransferClient } from "./client.js";
 export { deriveKeys, decryptCiphertext, combineCiphertext } from "./crypto.js";
 export { encodeTransferProof, encodeWithdrawProof } from "./utils.js";
-export { CONTRACT_ABI, ERC20_ABI, DEFAULT_CONFIG } from "./constants.js";
+export {
+  CONTRACT_ABI,
+  ERC20_ABI,
+  STABLETRUST_CONTRACTS_BY_CHAIN_ID,
+  getStableTrustContractAddress,
+} from "./constants.js";
 // Note: initializeWasm is now internal - WASM auto-initializes on first client use