@fairblock/stabletrust 1.0.0

package/src/constants.js

@@ -0,0 +1,32 @@
+/**
+ * Contract ABIs and Constants
+ */
+
+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 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 applyPending() external",
+  "function feeAmount() external view returns (uint256)",
+];
+
+export const ERC20_ABI = [
+  "function approve(address spender, uint256 amount) external returns (bool)",
+  "function allowance(address owner, address spender) external view returns (uint256)",
+  "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";

package/src/crypto.js

@@ -0,0 +1,90 @@
+import { ethers } from "ethers";
+
+/**
+ * Derives ElGamal encryption keys deterministically using the user's wallet signature.
+ * This ensures that the user's privacy keys stay tied to their Ethereum account.
+ *
+ * @param {ethers.Wallet} wallet - The wallet to derive keys for
+ * @param {Object} config - Configuration object with chainId and contractAddress
+ * @param {Function} generateKeypair - The WASM function for key generation
+ * @returns {Promise<{publicKey: string, privateKey: string}>}
+ */
+export async function deriveKeys(wallet, config, generateKeypair) {
+  const domain = {
+    name: "Fairblock",
+    version: "1",
+    chainId: config.chainId,
+    verifyingContract: config.contractAddress,
+  };
+
+  const types = {
+    DeriveElGamalKey: [
+      { name: "purpose", type: "string" },
+      { name: "user", type: "address" },
+      { name: "context", type: "bytes32" },
+    ],
+  };
+
+  const contextHash = ethers.keccak256(
+    ethers.solidityPacked(
+      ["uint256", "address", "address", "string"],
+      [config.chainId, config.contractAddress, ethers.ZeroAddress, "main"],
+    ),
+  );
+
+  const message = {
+    purpose: "homomorphic-key-derive-v1",
+    user: wallet.address,
+    context: contextHash,
+  };
+
+  const signature = await wallet.signTypedData(domain, types, message);
+  const domainContext = JSON.stringify({
+    chainId: config.chainId.toString(),
+    verifyingContract: config.contractAddress,
+    user: wallet.address,
+    purpose: "homomorphic-key-derive-v1",
+    version: "1",
+  });
+
+  const keypair = JSON.parse(
+    generateKeypair(signature.slice(2), domainContext),
+  );
+
+  return {
+    publicKey: keypair.public_key,
+    privateKey: keypair.private_key,
+  };
+}
+
+/**
+ * Decrypts a ciphertext using the private key
+ *
+ * @param {string} ciphertext - Base64 encoded ciphertext
+ * @param {string} privateKey - The private key for decryption
+ * @param {Function} decryptFn - The WASM decrypt function
+ * @returns {number} The decrypted amount
+ */
+export function decryptCiphertext(ciphertext, privateKey, decryptFn) {
+  try {
+    const plainStr = decryptFn(ciphertext, privateKey);
+    const result = JSON.parse(plainStr);
+    return result.decrypted_amount || 0;
+  } catch (e) {
+    throw new Error("Decryption failed: " + e.message);
+  }
+}
+
+/**
+ * Combines two elliptic curve points into a single ciphertext
+ *
+ * @param {string} c1 - First component (hex string)
+ * @param {string} c2 - Second component (hex string)
+ * @returns {string} Base64 encoded combined ciphertext
+ */
+export function combineCiphertext(c1, c2) {
+  const combined = new Uint8Array(64);
+  combined.set(ethers.getBytes(c1), 0);
+  combined.set(ethers.getBytes(c2), 32);
+  return Buffer.from(combined).toString("base64");
+}

package/src/index.d.ts

@@ -0,0 +1,275 @@
+declare module "@fairblock/stabletrust" {
+  import { ethers } from "ethers";
+
+  /**
+   * SDK configuration
+   */
+  export interface SdkConfig {
+    rpcUrl: string;
+    contractAddress: string;
+    chainId: number;
+  }
+
+  /**
+   * Encryption keys
+   */
+  export interface Keys {
+    publicKey: string;
+    privateKey: string;
+  }
+
+  /**
+   * Balance information
+   */
+  export interface Balance {
+    amount: number;
+    ciphertext: string | null;
+  }
+
+  /**
+   * Account options
+   */
+  export interface AccountOptions {
+    waitForFinalization?: boolean;
+    maxAttempts?: number;
+  }
+
+  /**
+   * Deposit options
+   */
+  export interface DepositOptions {
+    waitForFinalization?: boolean;
+  }
+
+  /**
+   * Transfer options
+   */
+  export interface TransferOptions {
+    useOffchainVerify?: boolean;
+    waitForFinalization?: boolean;
+  }
+
+  /**
+   * Apply pending options
+   */
+  export interface ApplyPendingOptions {
+    waitForFinalization?: boolean;
+  }
+
+  /**
+   * Withdraw options
+   */
+  export interface WithdrawOptions {
+    useOffchainVerify?: boolean;
+    waitForFinalization?: boolean;
+  }
+
+  /**
+   * Balance options
+   */
+  export interface BalanceOptions {
+    type?: "available" | "pending";
+  }
+
+  /**
+   * Wait for pending balance options
+   */
+  export interface WaitForPendingOptions {
+    maxAttempts?: number;
+    intervalMs?: number;
+  }
+
+  /**
+   * Main SDK client class
+   * WASM auto-initializes on first use - no manual initialization required!
+   */
+  export class ConfidentialTransferClient {
+    /**
+     * Create a new ConfidentialTransferClient
+     * @param rpcUrl RPC endpoint URL
+     * @param contractAddress Confidential transfer contract address
+     * @param chainId Chain ID
+     */
+    constructor(rpcUrl: string, contractAddress: string, chainId?: number);
+
+    /**
+     * Derive encryption keys for a wallet
+     */
+    deriveKeys(wallet: ethers.Wallet | ethers.Signer): Promise<Keys>;
+
+    /**
+     * Get account information from the contract
+     */
+    getAccountInfo(address: string): Promise<any>;
+
+    /**
+     * Create a confidential account if it doesn't exist and wait for finalization
+     */
+    ensureAccount(
+      wallet: ethers.Wallet | ethers.Signer,
+      options?: AccountOptions,
+    ): Promise<Keys>;
+
+    /**
+     * Get decrypted balance for an address
+     * @param address Account address
+     * @param privateKey Private key for decryption
+     * @param tokenAddress Token contract address
+     * @param options Balance options
+     */
+    getBalance(
+      address: string,
+      privateKey: string,
+      tokenAddress: string,
+      options?: BalanceOptions,
+    ): Promise<Balance>;
+
+    /**
+     * Deposit tokens into confidential account
+     * @param wallet Wallet to deposit from
+     * @param tokenAddress Token contract address to deposit
+     * @param amount Amount to deposit
+     * @param options Deposit options
+     */
+    deposit(
+      wallet: ethers.Wallet | ethers.Signer,
+      tokenAddress: string,
+      amount: bigint | string | number,
+      options?: DepositOptions,
+    ): Promise<ethers.ContractTransactionReceipt>;
+
+    /**
+     * Transfer confidential tokens to another address
+     * All necessary data is derived automatically - you only need the wallet and recipient info
+     * @param senderWallet Sender's wallet
+     * @param recipientAddress Recipient's address
+     * @param tokenAddress Token contract address to transfer
+     * @param amount Amount to transfer
+     * @param options Transfer options
+     */
+    transfer(
+      senderWallet: ethers.Wallet | ethers.Signer,
+      recipientAddress: string,
+      tokenAddress: string,
+      amount: number,
+      options?: TransferOptions,
+    ): Promise<ethers.ContractTransactionReceipt>;
+
+    /**
+     * Apply pending balance to available balance
+     */
+    applyPending(
+      wallet: ethers.Wallet | ethers.Signer,
+      options?: ApplyPendingOptions,
+    ): Promise<ethers.ContractTransactionReceipt>;
+
+    /**
+     * Withdraw confidential tokens to public ERC20
+     * @param wallet Wallet to withdraw to
+     * @param tokenAddress Token contract address to withdraw
+     * @param amount Amount to withdraw
+     * @param keys Encryption keys
+     * @param currentBalanceCiphertext Current balance ciphertext
+     * @param currentBalance Current balance (decrypted)
+     * @param options Withdrawal options
+     */
+    withdraw(
+      wallet: ethers.Wallet | ethers.Signer,
+      tokenAddress: string,
+      amount: number,
+      keys: Keys,
+      currentBalanceCiphertext: string,
+      currentBalance: number,
+      options?: WithdrawOptions,
+    ): Promise<ethers.ContractTransactionReceipt>;
+
+    /**
+     * Wait for pending balance to appear
+     * @param address Account address
+     * @param privateKey Private key for decryption
+     * @param tokenAddress Token contract address
+     * @param options Wait options
+     */
+    waitForPendingBalance(
+      address: string,
+      privateKey: string,
+      tokenAddress: string,
+      options?: WaitForPendingOptions,
+    ): Promise<Balance>;
+
+    /**
+     * Get the current fee amount for confidential transfers
+     */
+    getFeeAmount(): Promise<bigint>;
+
+    /**
+     * Get ERC20 token balance
+     * @param address Account address
+     * @param tokenAddress Token contract address
+     */
+    getTokenBalance(address: string, tokenAddress: string): Promise<bigint>;
+  }
+
+  /**
+   * Cryptography utilities
+   */
+
+  /**
+   * Derive encryption keys for a wallet
+   */
+  export function deriveKeys(
+    wallet: ethers.Wallet | ethers.Signer,
+    domainContext: { chainId: number; contractAddress: string },
+    generateKeypairFn: (signature: string, context: string) => string,
+  ): Promise<Keys>;
+
+  /**
+   * Decrypt a ciphertext using a private key
+   */
+  export function decryptCiphertext(
+    ciphertext: string,
+    privateKey: string,
+    decryptFn: (ciphertext: string, privateKey: string) => string,
+  ): number;
+
+  /**
+   * Combine two ciphertext parts (c1, c2)
+   */
+  export function combineCiphertext(c1: string, c2: string): string;
+
+  /**
+   * Utilities
+   */
+
+  /**
+   * Encode a transfer proof for contract submission
+   */
+  export function encodeTransferProof(proof: any): string;
+
+  /**
+   * Encode a withdraw proof for contract submission
+   */
+  export function encodeWithdrawProof(proof: any): string;
+
+  /**
+   * Constants
+   */
+
+  /**
+   * Contract ABI
+   */
+  export const CONTRACT_ABI: any[];
+
+  /**
+   * ERC20 ABI
+   */
+  export const ERC20_ABI: any[];
+
+  /**
+   * Default configuration values
+   */
+  export const DEFAULT_CONFIG: {
+    CHAIN_ID: number;
+    EXPLORER_URL: string;
+  };
+}

package/src/index.js

@@ -0,0 +1,5 @@
+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";
+// Note: initializeWasm is now internal - WASM auto-initializes on first client use

package/src/utils.js

@@ -0,0 +1,84 @@
+import { ethers } from "ethers";
+
+/**
+ * Encodes the ZK-Proof data for a transfer into a format the Solidity contract expects.
+ *
+ * @param {Object} proofData - The proof data object
+ * @returns {string} Encoded proof bytes
+ */
+export function encodeTransferProof(proofData) {
+  const abiCoder = ethers.AbiCoder.defaultAbiCoder();
+  return abiCoder.encode(
+    ["string", "string", "string"],
+    [
+      proofData.equality_proof,
+      proofData.ciphertext_validity_proof,
+      proofData.range_proof,
+    ],
+  );
+}
+
+/**
+ * Encodes the ZK-Proof data for a withdrawal.
+ *
+ * @param {Object} proofData - The proof data object
+ * @returns {string} Encoded proof bytes
+ */
+export function encodeWithdrawProof(proofData) {
+  const abiCoder = ethers.AbiCoder.defaultAbiCoder();
+  return abiCoder.encode(
+    ["string", "string"],
+    [proofData.equality_proof, proofData.range_proof],
+  );
+}
+
+/**
+ * Delays execution for a specified time
+ *
+ * @param {number} ms - Milliseconds to wait
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Logs a transaction with optional privacy note
+ *
+ * @param {string} hash - Transaction hash
+ * @param {string} explorerUrl - Block explorer base URL
+ * @param {boolean} isConfidential - Whether the transaction is confidential
+ */
+export function logTransaction(hash, explorerUrl, isConfidential = false) {
+  console.log(`Transaction submitted: ${explorerUrl}${hash}`);
+  if (isConfidential) {
+    console.log(
+      `Note: This is a confidential transaction - the amount is not visible on-chain.`,
+    );
+  }
+}
+
+/**
+ * Waits for a condition to be true with timeout
+ *
+ * @param {Function} conditionFn - Async function that returns boolean
+ * @param {number} maxAttempts - Maximum number of attempts
+ * @param {number} intervalMs - Interval between attempts in milliseconds
+ * @param {string} actionLabel - Label for logging
+ * @returns {Promise<void>}
+ * @throws {Error} If timeout is reached
+ */
+export async function waitForCondition(
+  conditionFn,
+  maxAttempts = 60,
+  intervalMs = 3000,
+  actionLabel = "operation",
+) {
+  for (let i = 0; i < maxAttempts; i++) {
+    if (await conditionFn()) {
+      return;
+    }
+    await sleep(intervalMs);
+  }
+  throw new Error(`Timeout waiting for ${actionLabel}`);
+}

package/src/wasm-loader.js

@@ -0,0 +1,85 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import init, {
+  generate_deterministic_keypair,
+  generate_transfer_proof,
+  generate_withdraw_proof,
+  decrypt_ciphertext,
+} from "../pkg/confidential_transfer_proof_generation.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let isInitialized = false;
+
+/**
+ * Initialize the WASM module
+ * This must be called before using the SDK
+ *
+ * @param {Buffer|Uint8Array|string} [wasmPath] - Optional custom WASM file path or buffer
+ * @returns {Promise<Object>} WASM module functions
+ */
+export async function initializeWasm(wasmPath) {
+  if (isInitialized) {
+    return {
+      generate_deterministic_keypair,
+      generate_transfer_proof,
+      generate_withdraw_proof,
+      decrypt_ciphertext,
+    };
+  }
+
+  try {
+    let wasmBuffer;
+
+    if (wasmPath) {
+      // If a custom path or buffer is provided
+      if (typeof wasmPath === "string") {
+        wasmBuffer = fs.readFileSync(wasmPath);
+      } else {
+        wasmBuffer = wasmPath;
+      }
+    } else {
+      // Use the bundled WASM file
+      const defaultWasmPath = path.resolve(
+        __dirname,
+        "../pkg/confidential_transfer_proof_generation_bg.wasm",
+      );
+      wasmBuffer = fs.readFileSync(defaultWasmPath);
+    }
+
+    await init(wasmBuffer);
+    isInitialized = true;
+
+    return {
+      generate_deterministic_keypair,
+      generate_transfer_proof,
+      generate_withdraw_proof,
+      decrypt_ciphertext,
+    };
+  } catch (error) {
+    throw new Error(
+      `Failed to initialize WASM module: ${error.message}. ` +
+        `Make sure the WASM file exists at the expected location.`,
+    );
+  }
+}
+
+/**
+ * Check if WASM module is initialized
+ * @returns {boolean}
+ */
+export function isWasmInitialized() {
+  return isInitialized;
+}
+
+/**
+ * Export WASM functions (they will only work after initialization)
+ */
+export {
+  generate_deterministic_keypair,
+  generate_transfer_proof,
+  generate_withdraw_proof,
+  decrypt_ciphertext,
+};