@cofhe/sdk 0.0.0-alpha-20260409113701

package/web/client.web.test.ts

@@ -0,0 +1,159 @@
+import { CofheErrorCode, CofheError, type CofheClient } from '@/core';
+import { arbSepolia as cofheArbSepolia } from '@/chains';
+
+import { describe, it, expect, beforeAll, beforeEach, vi } from 'vitest';
+import { arbitrumSepolia as viemArbitrumSepolia } from 'viem/chains';
+import type { PublicClient, WalletClient } from 'viem';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { createCofheClient, createCofheConfig } from './index.js';
+
+// Real test setup - runs in browser
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const TEST_ACCOUNT = privateKeyToAccount(TEST_PRIVATE_KEY).address;
+
+describe('@cofhe/web - Client', () => {
+  let cofheClient: CofheClient;
+  let publicClient: PublicClient;
+  let walletClient: WalletClient;
+
+  beforeAll(() => {
+    // Create real viem clients
+    publicClient = createPublicClient({
+      chain: viemArbitrumSepolia,
+      transport: http(),
+    });
+
+    const account = privateKeyToAccount(TEST_PRIVATE_KEY);
+    walletClient = createWalletClient({
+      chain: viemArbitrumSepolia,
+      transport: http(),
+      account,
+    });
+  });
+
+  beforeEach(() => {
+    const config = createCofheConfig({
+      supportedChains: [cofheArbSepolia],
+    });
+    cofheClient = createCofheClient(config);
+  });
+
+  describe('Browser Client Initialization', () => {
+    it('should create a client with real tfhe for browser', () => {
+      expect(cofheClient).toBeDefined();
+      expect(cofheClient.config).toBeDefined();
+      expect(cofheClient.connected).toBe(false);
+    });
+
+    it('should automatically use IndexedDB storage as default', () => {
+      expect(cofheClient.config.fheKeyStorage).toBeDefined();
+      expect(cofheClient.config.fheKeyStorage).not.toBeNull();
+    });
+
+    it('should have all expected methods', () => {
+      expect(typeof cofheClient.connect).toBe('function');
+      expect(typeof cofheClient.encryptInputs).toBe('function');
+      expect(typeof cofheClient.decryptForView).toBe('function');
+      expect(typeof cofheClient.getSnapshot).toBe('function');
+      expect(typeof cofheClient.subscribe).toBe('function');
+    });
+  });
+
+  describe('Environment', () => {
+    it('should have the correct environment', () => {
+      expect(cofheClient.config.environment).toBe('web');
+    });
+  });
+
+  describe('Connection', () => {
+    it('should connect to real chain', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      expect(cofheClient.connected).toBe(true);
+
+      const snapshot = cofheClient.getSnapshot();
+      expect(snapshot.connected).toBe(true);
+      expect(snapshot.chainId).toBe(cofheArbSepolia.id);
+      expect(snapshot.account).toBe(TEST_ACCOUNT);
+    }, 30000);
+
+    it('should handle network errors', async () => {
+      try {
+        await cofheClient.connect(
+          {
+            getChainId: vi.fn().mockRejectedValue(new Error('Network error')),
+          } as unknown as PublicClient,
+          walletClient
+        );
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.PublicWalletGetChainIdFailed);
+      }
+    }, 30000);
+  });
+
+  describe('State Management', () => {
+    it('should track connection state changes', async () => {
+      const states: any[] = [];
+      const unsubscribe = cofheClient.subscribe((snapshot) => {
+        states.push({ ...snapshot });
+      });
+
+      await cofheClient.connect(publicClient, walletClient);
+
+      unsubscribe();
+
+      expect(states.length).toBeGreaterThan(0);
+
+      // First state should be connecting
+      const firstState = states.find((s) => s.connecting);
+      expect(firstState).toBeDefined();
+      expect(firstState?.connecting).toBe(true);
+      expect(firstState?.connected).toBe(false);
+
+      // Last state should be connected
+      const lastState = states[states.length - 1];
+      expect(lastState.connected).toBe(true);
+      expect(lastState.connecting).toBe(false);
+      expect(lastState.chainId).toBe(cofheArbSepolia.id);
+    }, 30000);
+  });
+
+  describe('Builder Creation', () => {
+    it('should create encrypt builder after connection', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const builder = cofheClient.encryptInputs([{ data: 100n, utype: 2, securityZone: 0 }]);
+
+      expect(builder).toBeDefined();
+      expect(typeof builder.setChainId).toBe('function');
+      expect(typeof builder.setAccount).toBe('function');
+      expect(typeof builder.setSecurityZone).toBe('function');
+      expect(typeof builder.execute).toBe('function');
+    }, 30000);
+
+    it('should create decrypt builder after connection', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const builder = cofheClient.decryptForView('0x123', 2);
+
+      expect(builder).toBeDefined();
+      expect(typeof builder.setChainId).toBe('function');
+      expect(typeof builder.setAccount).toBe('function');
+      expect(typeof builder.onPoll).toBe('function');
+      expect(typeof builder.execute).toBe('function');
+    }, 30000);
+
+    it('should create decryptForTx builder after connection', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const builder = cofheClient.decryptForTx('0x123');
+
+      expect(builder).toBeDefined();
+      expect(typeof builder.setChainId).toBe('function');
+      expect(typeof builder.setAccount).toBe('function');
+      expect(typeof builder.onPoll).toBe('function');
+    }, 30000);
+  });
+});

package/web/config.web.test.ts

@@ -0,0 +1,69 @@
+import { arbSepolia } from '@/chains';
+
+import { describe, it, expect } from 'vitest';
+import { createCofheConfig, createCofheClient } from './index.js';
+
+describe('@cofhe/web - Config', () => {
+  describe('createCofheConfig', () => {
+    it('should automatically inject IndexedDB storage as default', () => {
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+      });
+
+      expect(config.fheKeyStorage).toBeDefined();
+      expect(config.fheKeyStorage).not.toBeNull();
+      expect(config.supportedChains).toEqual([arbSepolia]);
+    });
+
+    it('should allow overriding storage', async () => {
+      const customStorage = {
+        getItem: () => Promise.resolve(10),
+        setItem: () => Promise.resolve(),
+        removeItem: () => Promise.resolve(),
+      };
+
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+        fheKeyStorage: customStorage,
+      });
+
+      expect(await config.fheKeyStorage!.getItem('test')).toBe(10);
+    });
+
+    it('should allow null storage', () => {
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+        fheKeyStorage: null,
+      });
+
+      expect(config.fheKeyStorage).toBeNull();
+    });
+
+    it('should preserve all other config options', () => {
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+        mocks: {
+          decryptDelay: 500,
+        },
+      });
+
+      expect(config.supportedChains).toEqual([arbSepolia]);
+      expect(config.mocks.decryptDelay).toBe(500);
+      expect(config.fheKeyStorage).toBeDefined();
+    });
+  });
+
+  describe('createCofheClient with config', () => {
+    it('should create client with validated config', () => {
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+      });
+
+      const client = createCofheClient(config);
+
+      expect(client).toBeDefined();
+      expect(client.config).toBe(config);
+      expect(client.config.fheKeyStorage).toBeDefined();
+    });
+  });
+});

package/web/const.ts

@@ -0,0 +1,2 @@
+export const hasDOM =
+  typeof (globalThis as any)?.document !== 'undefined' && typeof (globalThis as any)?.window !== 'undefined';

package/web/encryptInputs.web.test.ts

@@ -0,0 +1,172 @@
+import { arbSepolia as cofheArbSepolia } from '@/chains';
+import { Encryptable, FheTypes, type CofheClient, CofheErrorCode, CofheError } from '@/core';
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import type { PublicClient, WalletClient } from 'viem';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { arbitrumSepolia as viemArbitrumSepolia } from 'viem/chains';
+import { createCofheClient, createCofheConfig } from './index.js';
+
+// Real test setup - runs in browser with real tfhe
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+
+describe('@cofhe/web - Encrypt Inputs Browser Tests', () => {
+  let cofheClient: CofheClient;
+  let publicClient: PublicClient;
+  let walletClient: WalletClient;
+
+  beforeAll(() => {
+    // Create real viem clients
+    publicClient = createPublicClient({
+      chain: viemArbitrumSepolia,
+      transport: http(),
+    });
+
+    const account = privateKeyToAccount(TEST_PRIVATE_KEY);
+    walletClient = createWalletClient({
+      chain: viemArbitrumSepolia,
+      transport: http(),
+      account,
+    });
+  });
+
+  beforeEach(() => {
+    const config = createCofheConfig({
+      supportedChains: [cofheArbSepolia],
+    });
+    cofheClient = createCofheClient(config);
+  });
+
+  describe('Browser TFHE Initialization', () => {
+    it('should initialize tfhe on first encryption', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      // This will trigger real TFHE initialization in browser
+      const result = await cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+
+      // If we get here, TFHE was initialized successfully
+      expect(result).toBeDefined();
+    }, 60000); // Longer timeout for real operations
+
+    it('should handle multiple encryptions without re-initializing', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      // First encryption
+      expect(cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute()).resolves.not.toThrow();
+
+      // Second encryption should reuse initialization
+      expect(cofheClient.encryptInputs([Encryptable.uint64(50n)]).execute()).resolves.not.toThrow();
+    }, 60000);
+  });
+
+  describe('Browser Encryption', () => {
+    it('should encrypt a bool with real TFHE in browser', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const result = await cofheClient.encryptInputs([Encryptable.bool(true)]).execute();
+
+      expect(result).toBeDefined();
+      expect(result.length).toBe(1);
+      expect(result[0].utype).toBe(FheTypes.Bool);
+      expect(result[0].ctHash).toBeDefined();
+      expect(typeof result[0].ctHash).toBe('bigint');
+      expect(result[0].signature).toBeDefined();
+      expect(typeof result[0].signature).toBe('string');
+      expect(result[0].securityZone).toBe(0);
+    }, 60000);
+
+    it('should encrypt all supported types together', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const inputs = [
+        Encryptable.bool(false),
+        Encryptable.uint8(1n),
+        Encryptable.uint16(2n),
+        Encryptable.uint32(3n),
+        Encryptable.uint64(4n),
+        Encryptable.uint128(5n),
+        Encryptable.address('0x742d35Cc6634C0532925a3b844D16faC4c175E99'),
+      ];
+
+      const result = await cofheClient.encryptInputs(inputs).execute();
+      expect(result).toBeDefined();
+
+      expect(result.length).toBe(7);
+      // Verify each type
+      expect(result[0].utype).toBe(FheTypes.Bool);
+      expect(result[1].utype).toBe(FheTypes.Uint8);
+      expect(result[2].utype).toBe(FheTypes.Uint16);
+      expect(result[3].utype).toBe(FheTypes.Uint32);
+      expect(result[4].utype).toBe(FheTypes.Uint64);
+      expect(result[5].utype).toBe(FheTypes.Uint128);
+      expect(result[6].utype).toBe(FheTypes.Uint160);
+    }, 90000); // Longer timeout for multiple encryptions
+  });
+
+  describe('Browser Builder Pattern', () => {
+    it('should support chaining builder methods with real encryption', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const snapshot = cofheClient.getSnapshot();
+      const encrypted = await cofheClient
+        .encryptInputs([Encryptable.uint128(100n)])
+        .setChainId(snapshot.chainId!)
+        .setAccount(snapshot.account!)
+        .setSecurityZone(0)
+        .execute();
+
+      expect(encrypted.length).toBe(1);
+      expect(encrypted[0].utype).toBe(FheTypes.Uint128);
+    }, 60000);
+  });
+
+  describe('Browser Error Handling', () => {
+    it('should fail gracefully when not connected', async () => {
+      // Don't connect the client
+      try {
+        const promise = cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.NotConnected);
+      }
+    }, 30000);
+
+    it('should handle invalid CoFHE URL', async () => {
+      const badConfig = createCofheConfig({
+        supportedChains: [
+          {
+            ...cofheArbSepolia,
+            coFheUrl: 'http://invalid-cofhe-url.local',
+            verifierUrl: 'http://invalid-verifier-url.local',
+          },
+        ],
+      });
+
+      const badClient = createCofheClient(badConfig);
+      await badClient.connect(publicClient, walletClient);
+
+      const promise = badClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+      expect(promise).rejects.toThrow();
+    }, 60000);
+  });
+
+  describe('Browser Performance', () => {
+    it('should handle consecutive encryptions efficiently', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const start = Date.now();
+
+      // Perform 5 encryptions
+      for (let i = 0; i < 5; i++) {
+        await cofheClient.encryptInputs([Encryptable.uint128(BigInt(i))]).execute();
+      }
+
+      const duration = Date.now() - start;
+
+      // Should complete all 5 encryptions in reasonable time
+      // This is a sanity check, not a strict benchmark
+      expect(duration).toBeLessThan(120000); // 2 minutes max
+    }, 180000); // 3 minute timeout
+  });
+});

package/web/index.ts

@@ -0,0 +1,166 @@
+// Web specific functionality only
+
+import {
+  createCofheClientBase,
+  createCofheConfigBase,
+  type CofheClient,
+  type CofheConfig,
+  type CofheInputConfig,
+  type ZkBuilderAndCrsGenerator,
+  type FheKeyDeserializer,
+  type EncryptableItem,
+  fheTypeToString,
+} from '@/core';
+
+// Import web-specific storage (internal use only)
+import { createSsrStorage, createWebStorage } from './storage.js';
+
+// Import worker manager
+import { getWorkerManager, terminateWorker, areWorkersAvailable } from './workerManager.js';
+
+// Import tfhe for web
+import init, { init_panic_hook, TfheCompactPublicKey, ProvenCompactCiphertextList, CompactPkeCrs } from 'tfhe';
+import { hasDOM } from './const';
+
+/**
+ * Internal function to initialize TFHE for web
+ * Called automatically on first encryption - users don't need to call this manually
+ * @returns true if TFHE was initialized, false if already initialized
+ */
+let tfheInitialized = false;
+async function initTfhe(): Promise<boolean> {
+  if (tfheInitialized) return false;
+  await init();
+  await init_panic_hook();
+  tfheInitialized = true;
+  return true;
+}
+
+/**
+ * Utility to convert the hex string key to a Uint8Array for use with tfhe
+ */
+const fromHexString = (hexString: string): Uint8Array => {
+  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
+  const arr = cleanString.replace(/^0x/, '').match(/.{1,2}/g);
+  if (!arr) return new Uint8Array();
+  return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
+};
+
+/**
+ * Serializer for TFHE public keys
+ * Validates that the buffer can be deserialized into a TfheCompactPublicKey
+ */
+const tfhePublicKeyDeserializer: FheKeyDeserializer = (buff: string): void => {
+  TfheCompactPublicKey.deserialize(fromHexString(buff));
+};
+
+/**
+ * Serializer for Compact PKE CRS
+ * Validates that the buffer can be deserialized into ZkCompactPkePublicParams
+ */
+const compactPkeCrsDeserializer: FheKeyDeserializer = (buff: string): void => {
+  CompactPkeCrs.deserialize(fromHexString(buff));
+};
+
+/**
+ * Creates a ZK builder and CRS from FHE public key and CRS buffers
+ * This is used internally by the SDK to create encrypted inputs
+ */
+const zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator = (fhe: string, crs: string) => {
+  const fhePublicKey = TfheCompactPublicKey.deserialize(fromHexString(fhe));
+  const zkBuilder = ProvenCompactCiphertextList.builder(fhePublicKey);
+  const zkCrs = CompactPkeCrs.deserialize(fromHexString(crs));
+
+  return { zkBuilder, zkCrs };
+};
+
+/**
+ * Worker-enabled zkProve function
+ * This submits proof generation to a Web Worker
+ */
+async function zkProveWithWorker(
+  fheKeyHex: string,
+  crsHex: string,
+  items: EncryptableItem[],
+  metadata: Uint8Array
+): Promise<Uint8Array> {
+  // Serialize items for worker (convert enum to string name)
+  const serializedItems = items.map((item) => ({
+    utype: fheTypeToString(item.utype),
+    data: typeof item.data === 'bigint' ? item.data.toString() : item.data,
+  }));
+
+  // Submit to worker
+  const workerManager = getWorkerManager();
+  return await workerManager.submitProof(fheKeyHex, crsHex, serializedItems, metadata);
+}
+
+/**
+ * Creates a CoFHE configuration for web with IndexedDB storage as default
+ * @param config - The CoFHE input configuration (fheKeyStorage will default to IndexedDB if not provided)
+ * @returns The CoFHE configuration with web defaults applied
+ */
+export function createCofheConfig(config: CofheInputConfig): CofheConfig {
+  return createCofheConfigBase({
+    environment: 'web',
+    ...config,
+    fheKeyStorage:
+      config.fheKeyStorage === null ? null : config.fheKeyStorage ?? (hasDOM ? createWebStorage() : createSsrStorage()),
+  });
+}
+
+/**
+ * Creates a CoFHE client instance for web with TFHE automatically configured
+ * TFHE will be initialized automatically on first encryption - no manual setup required
+ * Workers are automatically enabled if available (can be disabled via config.useWorkers)
+ * @param config - The CoFHE configuration (use createCofheConfig to create with web defaults)
+ * @returns The CoFHE client instance
+ */
+export function createCofheClient<TConfig extends CofheConfig>(config: TConfig): CofheClient<TConfig> {
+  return createCofheClientBase({
+    config,
+    zkBuilderAndCrsGenerator,
+    tfhePublicKeyDeserializer,
+    compactPkeCrsDeserializer,
+    initTfhe,
+    // Always provide the worker function if available - config.useWorkers controls usage
+    // areWorkersAvailable will return true if the Worker API is available and false in Node.js
+    zkProveWorkerFn: areWorkersAvailable() ? zkProveWithWorker : undefined,
+  });
+}
+
+/**
+ * Terminate the worker (call on app cleanup)
+ */
+export { terminateWorker };
+
+/**
+ * Check if workers are available
+ */
+export { areWorkersAvailable };
+
+/**
+ * Test helper: Create a client with custom worker function (for testing fallback behavior)
+ * @internal - Only for testing purposes
+ */
+export function createCofheClientWithCustomWorker(
+  config: CofheConfig,
+  customZkProveWorkerFn: (
+    fheKeyHex: string,
+    crsHex: string,
+    items: EncryptableItem[],
+    metadata: Uint8Array
+  ) => Promise<Uint8Array>
+): CofheClient {
+  return createCofheClientBase({
+    config,
+    zkBuilderAndCrsGenerator,
+    tfhePublicKeyDeserializer,
+    compactPkeCrsDeserializer,
+    initTfhe,
+    zkProveWorkerFn: customZkProveWorkerFn,
+  });
+}
+
+export { createSsrStorage };
+export { hasDOM } from './const';

package/web/storage.ts

@@ -0,0 +1,49 @@
+import type { IStorage } from '@/core';
+import { constructClient } from 'iframe-shared-storage';
+import { hasDOM } from './const';
+/**
+ * Creates a web storage implementation using IndexedDB.
+ * Must only be called in a browser environment (requires `document` for iframe injection).
+ * @returns IStorage implementation for browser environments
+ */
+export const createWebStorage = (opts = { enableLog: false }): IStorage => {
+  if (!hasDOM) throw new Error('createWebStorage can only be used in a browser environment');
+
+  const client = constructClient({
+    iframe: {
+      src: 'https://iframe-shared-storage.vercel.app/hub.html',
+      messagingOptions: {
+        enableLog: opts.enableLog ? 'both' : undefined,
+      },
+
+      iframeReadyTimeoutMs: 30_000, // if the iframe is not initied during this interval AND a reuqest is made, such request will throw an error
+      methodCallTimeoutMs: 10_000, // if a method call is not answered during this interval, the call will throw an error
+      methodCallRetries: 3, // number of retries for a method call if it times out
+    },
+  });
+
+  const indexedDBKeyval = client.indexedDBKeyval;
+  return {
+    getItem: async (name: string) => {
+      // IndexedDBKeyval returns undefined if not found, but we want null (a json-deserialized value is expected)
+      return (await indexedDBKeyval.get(name)) ?? null;
+    },
+    setItem: async (name: string, value: any) => {
+      await indexedDBKeyval.set(name, value);
+    },
+    removeItem: async (name: string) => {
+      await indexedDBKeyval.del(name);
+    },
+  };
+};
+
+export function createSsrStorage(): IStorage {
+  // TODO: consider doing something like wagmi's cookies storage for SSR - this in-memory storage will not persist across requests, but it also won't throw errors if accessed in SSR (e.g. during getServerSideProps in Next.js)
+  // https://wagmi.sh/react/guides/ssr#_1-set-up-cookie-storage
+  console.warn('using no-op server-side SSR storage');
+  return {
+    getItem: async () => null,
+    setItem: async () => {},
+    removeItem: async () => {},
+  };
+}