@cofhe/sdk 0.0.0-beta-20251027110729

package/chains/defineChain.ts

@@ -0,0 +1,18 @@
+import { CofheChainSchema, type CofheChain } from './types.js';
+
+/**
+ * Defines and validates a CofheChain configuration
+ * @param chainConfig - The chain configuration object to validate
+ * @returns The validated chain configuration unchanged
+ * @throws {Error} If the chain configuration is invalid
+ */
+export function defineChain(chainConfig: CofheChain): CofheChain {
+  const result = CofheChainSchema.safeParse(chainConfig);
+
+  if (!result.success) {
+    const errorMessages = result.error.errors.map((err) => `${err.path.join('.')}: ${err.message}`);
+    throw new Error(`Invalid chain configuration: ${errorMessages.join(', ')}`);
+  }
+
+  return result.data;
+}

package/chains/index.ts

@@ -0,0 +1,33 @@
+// Export types
+export type { CofheChain, Environment } from './types.js';
+
+// Import and export individual chains
+import { sepolia } from './chains/sepolia.js';
+import { arbSepolia } from './chains/arbSepolia.js';
+import { baseSepolia } from './chains/baseSepolia.js';
+import { hardhat } from './chains/hardhat.js';
+
+export { sepolia, arbSepolia, baseSepolia, hardhat };
+
+// Export all chains as a collection
+export const chains = {
+  sepolia,
+  arbSepolia,
+  baseSepolia,
+  hardhat,
+} as const;
+
+// Import CofheChain type for helper functions
+import type { CofheChain } from './types.js';
+
+// Export chain by ID helper
+export const getChainById = (chainId: number): CofheChain | undefined => {
+  return Object.values(chains).find((chain) => chain.id === chainId);
+};
+
+// Export chain by name helper
+export const getChainByName = (name: string): CofheChain | undefined => {
+  return Object.values(chains).find(
+    (chain) => chain.name.toLowerCase() === name.toLowerCase() || chain.network.toLowerCase() === name.toLowerCase()
+  );
+};

package/chains/types.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+/**
+ * Environment schema for @cofhe/sdk chains
+ */
+export const EnvironmentSchema = z.enum(['MOCK', 'TESTNET', 'MAINNET']);
+
+/**
+ * Zod schema for CofheChain validation
+ */
+export const CofheChainSchema = z.object({
+  /** Chain ID */
+  id: z.number().int().positive(),
+  /** Human-readable chain name */
+  name: z.string().min(1),
+  /** Network identifier */
+  network: z.string().min(1),
+  /** coFhe service URL */
+  coFheUrl: z.string().url(),
+  /** Verifier service URL */
+  verifierUrl: z.string().url(),
+  /** Threshold network service URL */
+  thresholdNetworkUrl: z.string().url(),
+  /** Environment type */
+  environment: EnvironmentSchema,
+});
+
+/**
+ * Type inference from the schema
+ */
+export type CofheChain = z.infer<typeof CofheChainSchema>;
+export type Environment = z.infer<typeof EnvironmentSchema>;

package/core/baseBuilder.ts

@@ -0,0 +1,138 @@
+import { type PublicClient, type WalletClient } from 'viem';
+import { type CofhesdkConfig } from './config.js';
+import { CofhesdkError, CofhesdkErrorCode } from './error.js';
+
+/**
+ * Base parameters that all builders need
+ */
+export type BaseBuilderParams = {
+  config: CofhesdkConfig | undefined;
+  publicClient: PublicClient | undefined;
+  walletClient: WalletClient | undefined;
+
+  chainId: number | undefined;
+  account: string | undefined;
+
+  requireConnected: (() => void) | undefined;
+};
+
+/**
+ * Abstract base class for builders that provides common functionality
+ * for working with clients, config, and chain IDs
+ */
+export abstract class BaseBuilder {
+  protected config: CofhesdkConfig | undefined;
+  protected publicClient: PublicClient | undefined;
+  protected walletClient: WalletClient | undefined;
+
+  protected chainId: number | undefined;
+  protected account: string | undefined;
+
+  protected requireConnected: (() => void) | undefined;
+
+  constructor(params: BaseBuilderParams) {
+    this.config = params.config;
+    this.publicClient = params.publicClient;
+    this.walletClient = params.walletClient;
+
+    this.chainId = params.chainId;
+    this.account = params.account;
+
+    this.requireConnected = params.requireConnected;
+  }
+
+  /**
+   * Gets the chain ID from the instance or fetches it from the public client
+   * @returns The chain ID
+   * @throws {CofhesdkError} If chainId is not set and publicClient is not available
+   */
+  protected async getChainIdOrThrow(): Promise<number> {
+    if (this.chainId) return this.chainId;
+
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.ChainIdUninitialized,
+      message: 'Chain ID is not set',
+      hint: 'Ensure client.connect() has been called and awaited, or use setChainId(...) to set the chainId explicitly.',
+      context: {
+        chainId: this.chainId,
+      },
+    });
+  }
+
+  /**
+   * Gets the account address from the instance or fetches it from the wallet client
+   * @returns The account address
+   * @throws {CofhesdkError} If account is not set and walletClient is not available
+   */
+  protected async getAccountOrThrow(): Promise<string> {
+    if (this.account) return this.account;
+
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.AccountUninitialized,
+      message: 'Account is not set',
+      hint: 'Ensure client.connect() has been called and awaited, or use setAccount(...) to set the account explicitly.',
+      context: {
+        account: this.account,
+      },
+    });
+  }
+
+  /**
+   * Gets the config or throws an error if not available
+   * @returns The config
+   * @throws {CofhesdkError} If config is not set
+   */
+  protected getConfigOrThrow(): CofhesdkConfig {
+    if (this.config) return this.config;
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.MissingConfig,
+      message: 'Builder config is undefined',
+      hint: 'Ensure client has been created with a config.',
+      context: {
+        config: this.config,
+      },
+    });
+  }
+
+  /**
+   * Gets the public client or throws an error if not available
+   * @returns The public client
+   * @throws {CofhesdkError} If publicClient is not set
+   */
+  protected getPublicClientOrThrow(): PublicClient {
+    if (this.publicClient) return this.publicClient;
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.MissingPublicClient,
+      message: 'Public client not found',
+      hint: 'Ensure client.connect() has been called with a publicClient.',
+      context: {
+        publicClient: this.publicClient,
+      },
+    });
+  }
+
+  /**
+   * Gets the wallet client or throws an error if not available
+   * @returns The wallet client
+   * @throws {CofhesdkError} If walletClient is not set
+   */
+  protected getWalletClientOrThrow(): WalletClient {
+    if (this.walletClient) return this.walletClient;
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.MissingWalletClient,
+      message: 'Wallet client not found',
+      hint: 'Ensure client.connect() has been called with a walletClient.',
+      context: {
+        walletClient: this.walletClient,
+      },
+    });
+  }
+
+  /**
+   * Requires the client to be connected
+   * @throws {CofhesdkError} If client is not connected
+   */
+  protected requireConnectedOrThrow(): void {
+    if (this.requireConnected) this.requireConnected();
+  }
+}

package/core/client.test.ts

@@ -0,0 +1,298 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createCofhesdkClientBase } from './client.js';
+import { type CofhesdkClient, type CofhesdkClientConnectionState } from './types.js';
+import { createCofhesdkConfigBase } from './config.js';
+import { CofhesdkErrorCode } from './error.js';
+import { type PublicClient, type WalletClient } from 'viem';
+import { EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
+import { Encryptable } from './types.js';
+
+// Mock dependencies
+vi.mock('./keyStore', () => ({
+  createKeysStore: vi.fn(() => ({
+    rehydrateKeysStore: vi.fn().mockResolvedValue(undefined),
+    getFheKey: vi.fn(),
+    getCrs: vi.fn(),
+    setFheKey: vi.fn(),
+    setCrs: vi.fn(),
+    clearKeysStorage: vi.fn(),
+    store: {} as any,
+  })),
+}));
+
+vi.mock('./fetchKeys', () => ({
+  fetchMultichainKeys: vi.fn().mockResolvedValue(undefined),
+}));
+
+// Test helpers
+const createMockPublicClient = (chainId = 11155111): PublicClient =>
+  ({
+    getChainId: vi.fn().mockResolvedValue(chainId),
+  }) as any;
+
+const createMockWalletClient = (addresses = ['0x1234567890123456789012345678901234567890']): WalletClient =>
+  ({
+    getAddresses: vi.fn().mockResolvedValue(addresses),
+  }) as any;
+
+const createTestClient = (): CofhesdkClient => {
+  const config = createCofhesdkConfigBase({ supportedChains: [] });
+  return createCofhesdkClientBase({
+    config,
+    zkBuilderAndCrsGenerator: {} as any,
+    tfhePublicKeyDeserializer: {} as any,
+    compactPkeCrsDeserializer: {} as any,
+    initTfhe: () => Promise.resolve(false),
+  });
+};
+
+describe('createCofhesdkClientBase', () => {
+  let client: CofhesdkClient;
+
+  beforeEach(() => {
+    client = createTestClient();
+  });
+
+  describe('initial state', () => {
+    it('should start disconnected', () => {
+      const snapshot = client.getSnapshot();
+      expect(snapshot.connected).toBe(false);
+      expect(snapshot.connecting).toBe(false);
+      expect(snapshot.connectError).toBe(undefined);
+      expect(snapshot.chainId).toBe(undefined);
+      expect(snapshot.account).toBe(undefined);
+    });
+
+    it('should expose convenience flags', () => {
+      expect(client.connected).toBe(false);
+      expect(client.connecting).toBe(false);
+    });
+
+    it('should expose config', () => {
+      expect(client.config).toBeDefined();
+      expect(client.config.supportedChains).toEqual([]);
+    });
+  });
+
+  describe('reactive state', () => {
+    it('should notify subscribers of state changes', async () => {
+      const states: CofhesdkClientConnectionState[] = [];
+      client.subscribe((snapshot) => states.push(snapshot));
+
+      const publicClient = createMockPublicClient();
+      const walletClient = createMockWalletClient();
+      await client.connect(publicClient, walletClient);
+
+      // Expect states[0] to be the connecting state
+      expect(states[0].connecting).toBe(true);
+      expect(states[0].connected).toBe(false);
+      expect(states[0].chainId).toBe(undefined);
+      expect(states[0].account).toBe(undefined);
+
+      // Expect states[1] to be the connected state
+      expect(states[1].connected).toBe(true);
+      expect(states[1].connecting).toBe(false);
+      expect(states[1].chainId).toBe(11155111);
+      expect(states[1].account).toBe('0x1234567890123456789012345678901234567890');
+    });
+
+    it('should stop notifications after unsubscribe', async () => {
+      const states: CofhesdkClientConnectionState[] = [];
+      const unsubscribe = client.subscribe((snapshot) => states.push(snapshot));
+
+      unsubscribe();
+
+      const publicClient = createMockPublicClient();
+      const walletClient = createMockWalletClient();
+      await client.connect(publicClient, walletClient);
+
+      // Should only have the initial notification
+      expect(states.length).toBe(0);
+    });
+  });
+
+  describe('connect', () => {
+    it('should successfully connect with valid clients', async () => {
+      const publicClient = createMockPublicClient(11155111);
+      const walletClient = createMockWalletClient(['0xabcd']);
+
+      const result = await client.connect(publicClient, walletClient);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toBe(true);
+
+      expect(client.connected).toBe(true);
+      expect(client.connecting).toBe(false);
+
+      const snapshot = client.getSnapshot();
+      expect(snapshot.chainId).toBe(11155111);
+      expect(snapshot.account).toBe('0xabcd');
+    });
+
+    it('should set connecting state during connection', async () => {
+      const publicClient = createMockPublicClient();
+      const walletClient = createMockWalletClient();
+
+      const connectPromise = client.connect(publicClient, walletClient);
+
+      // Check mid-connection state
+      expect(client.connecting).toBe(true);
+      expect(client.connected).toBe(false);
+
+      await connectPromise;
+
+      expect(client.connecting).toBe(false);
+      expect(client.connected).toBe(true);
+    });
+
+    it('should return existing promise if already connecting', async () => {
+      const publicClient = createMockPublicClient();
+      const walletClient = createMockWalletClient();
+
+      const promise1 = client.connect(publicClient, walletClient);
+      const promise2 = client.connect(publicClient, walletClient);
+
+      expect(promise1).toStrictEqual(promise2);
+
+      await promise1;
+    });
+
+    it('should return immediately if already connected with same clients', async () => {
+      const publicClient = createMockPublicClient();
+      const walletClient = createMockWalletClient();
+
+      await client.connect(publicClient, walletClient);
+      const result = await client.connect(publicClient, walletClient);
+
+      expect(result.success).toBe(true);
+    });
+
+    it('should handle getChainId throwing an error', async () => {
+      const publicClient = createMockPublicClient();
+      const error = new Error('Network error');
+      publicClient.getChainId = vi.fn().mockRejectedValue(error);
+      const walletClient = createMockWalletClient();
+
+      const result = await client.connect(publicClient, walletClient);
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe(CofhesdkErrorCode.PublicWalletGetChainIdFailed);
+      expect(result.error?.message).toBe('getting chain ID from public client failed | Caused by: Network error');
+      expect(result.error?.cause).toBe(error);
+      expect(client.connected).toBe(false);
+    });
+
+    it('should handle getChainId returning null', async () => {
+      const publicClient = createMockPublicClient();
+      publicClient.getChainId = vi.fn().mockResolvedValue(null);
+      const walletClient = createMockWalletClient();
+
+      const result = await client.connect(publicClient, walletClient);
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe(CofhesdkErrorCode.PublicWalletGetChainIdFailed);
+      expect(result.error?.message).toBe('chain ID from public client is null');
+      expect(result.error?.cause).toBe(undefined);
+      expect(client.connected).toBe(false);
+    });
+
+    it('should handle getAddresses throwing an error', async () => {
+      const publicClient = createMockPublicClient();
+      const error = new Error('Network error');
+      const walletClient = createMockWalletClient();
+      walletClient.getAddresses = vi.fn().mockRejectedValue(error);
+
+      const result = await client.connect(publicClient, walletClient);
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe(CofhesdkErrorCode.PublicWalletGetAddressesFailed);
+      expect(result.error?.message).toBe('getting address from wallet client failed | Caused by: Network error');
+      expect(result.error?.cause).toBe(error);
+      expect(client.connected).toBe(false);
+    });
+
+    it('should handle getAddresses returning an empty array', async () => {
+      const publicClient = createMockPublicClient();
+      const walletClient = createMockWalletClient([]);
+
+      const result = await client.connect(publicClient, walletClient);
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe(CofhesdkErrorCode.PublicWalletGetAddressesFailed);
+      expect(result.error?.message).toBe('address from wallet client is null');
+      expect(result.error?.cause).toBe(undefined);
+      expect(client.connected).toBe(false);
+    });
+
+    it('should store error in state on failure', async () => {
+      const publicClient = createMockPublicClient();
+      const error = new Error('Network error');
+      publicClient.getChainId = vi.fn().mockRejectedValue(error);
+      const walletClient = createMockWalletClient();
+
+      const result = await client.connect(publicClient, walletClient);
+
+      expect(result.success).toBe(false);
+      const snapshot = client.getSnapshot();
+      expect(snapshot.connectError).toBeTruthy();
+      expect(snapshot.connected).toBe(false);
+    });
+  });
+
+  describe('encryptInputs', () => {
+    it('should throw if not connected', async () => {
+      const result = await client
+        .encryptInputs([Encryptable.uint8(1n), Encryptable.uint8(2n), Encryptable.uint8(3n)])
+        .encrypt();
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe(CofhesdkErrorCode.NotConnected);
+    });
+
+    it('should create EncryptInputsBuilder when connected', async () => {
+      const publicClient = createMockPublicClient(123);
+      const walletClient = createMockWalletClient(['0xtest']);
+
+      await client.connect(publicClient, walletClient);
+
+      const builder = await client.encryptInputs([Encryptable.uint8(1n), Encryptable.uint8(2n), Encryptable.uint8(3n)]);
+
+      expect(builder).toBeDefined();
+      expect(builder).toBeInstanceOf(EncryptInputsBuilder);
+      expect(builder).toHaveProperty('encrypt');
+      expect(builder.getChainId()).toBe(123);
+      expect(builder.getAccount()).toBe('0xtest');
+    });
+  });
+
+  describe('initializationResults', () => {
+    it('should have keyFetchResult promise', () => {
+      expect(client.initializationResults.keyFetchResult).toBeInstanceOf(Promise);
+    });
+
+    it('should resolve keyFetchResult', async () => {
+      const result = await client.initializationResults.keyFetchResult;
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('permits', () => {
+    it('should expose permits', () => {
+      expect(client.permits).toBeDefined();
+      expect(client.permits).toHaveProperty('getSnapshot');
+      expect(client.permits).toHaveProperty('subscribe');
+      expect(client.permits).toHaveProperty('createSelf');
+      expect(client.permits).toHaveProperty('createSharing');
+      expect(client.permits).toHaveProperty('importShared');
+      expect(client.permits).toHaveProperty('getHash');
+      expect(client.permits).toHaveProperty('serialize');
+      expect(client.permits).toHaveProperty('deserialize');
+      expect(client.permits).toHaveProperty('getPermit');
+      expect(client.permits).toHaveProperty('getPermits');
+      expect(client.permits).toHaveProperty('getActivePermit');
+      expect(client.permits).toHaveProperty('getActivePermitHash');
+      expect(client.permits).toHaveProperty('removePermit');
+      expect(client.permits).toHaveProperty('selectActivePermit');
+      expect(client.permits).toHaveProperty('removeActivePermit');
+    });
+  });
+});