@cofhe/sdk 0.1.0 → 0.2.0

package/chains/chains.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { sepolia, arbSepolia, baseSepolia, hardhat, chains, getChainById, getChainByName } from './index.js';
+
+describe('Chains', () => {
+  it('should export all chains', () => {
+    expect(Object.keys(chains)).toHaveLength(5);
+    expect(chains).toHaveProperty('sepolia');
+    expect(chains).toHaveProperty('arbSepolia');
+    expect(chains).toHaveProperty('baseSepolia');
+    expect(chains).toHaveProperty('hardhat');
+    expect(chains).toHaveProperty('localcofhe');
+  });
+
+  it('should have correct chain configurations', () => {
+    expect(sepolia.id).toBe(11155111);
+    expect(sepolia.name).toBe('Sepolia');
+    expect(sepolia.environment).toBe('TESTNET');
+
+    expect(hardhat.id).toBe(31337);
+    expect(hardhat.name).toBe('Hardhat');
+    expect(hardhat.environment).toBe('MOCK');
+  });
+
+  it('should find chains by ID', () => {
+    expect(getChainById(11155111)).toBe(sepolia);
+    expect(getChainById(31337)).toBe(hardhat);
+    expect(getChainById(999999)).toBeUndefined();
+  });
+
+  it('should find chains by name', () => {
+    expect(getChainByName('sepolia')).toBe(sepolia);
+    expect(getChainByName('Sepolia')).toBe(sepolia);
+    expect(getChainByName('hardhat')).toBe(hardhat);
+    expect(getChainByName('nonexistent')).toBeUndefined();
+  });
+
+  it('should validate chain properties', () => {
+    const allChains = [sepolia, arbSepolia, baseSepolia, hardhat];
+
+    allChains.forEach((chain) => {
+      expect(typeof chain.id).toBe('number');
+      expect(typeof chain.name).toBe('string');
+      expect(typeof chain.network).toBe('string');
+      expect(typeof chain.coFheUrl).toBe('string');
+      expect(typeof chain.verifierUrl).toBe('string');
+      expect(typeof chain.thresholdNetworkUrl).toBe('string');
+      expect(['MOCK', 'TESTNET', 'MAINNET']).toContain(chain.environment);
+    });
+  });
+});

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,35 @@
+// 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';
+import { localcofhe } from './chains/localcofhe.js';
+
+export { sepolia, arbSepolia, baseSepolia, hardhat, localcofhe };
+
+// Export all chains as a collection
+export const chains = {
+  sepolia,
+  arbSepolia,
+  baseSepolia,
+  hardhat,
+  localcofhe,
+} 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,119 @@
+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;
+
+  protected publicClient: PublicClient | undefined;
+  protected walletClient: WalletClient | undefined;
+
+  protected chainId: number | undefined;
+  protected account: string | undefined;
+
+  constructor(params: BaseBuilderParams) {
+    // Check that config is provided
+    if (!params.config) {
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.MissingConfig,
+        message: 'Builder config is undefined',
+        hint: 'Ensure client has been created with a config.',
+        context: {
+          config: params.config,
+        },
+      });
+    }
+    this.config = params.config;
+
+    this.publicClient = params.publicClient;
+    this.walletClient = params.walletClient;
+
+    this.chainId = params.chainId;
+    this.account = params.account;
+
+    // Require the client to be connected if passed as param
+    params.requireConnected?.();
+  }
+
+  /**
+   * Asserts that this.chainId is populated
+   * @throws {CofhesdkError} If chainId is not set
+   */
+  protected assertChainId(): asserts this is this & { chainId: number } {
+    if (this.chainId) return;
+    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,
+      },
+    });
+  }
+
+  /**
+   * Asserts that this.account is populated
+   * @throws {CofhesdkError} If account is not set
+   */
+  protected assertAccount(): asserts this is this & { account: string } {
+    if (this.account) return;
+    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,
+      },
+    });
+  }
+
+  /**
+   * Asserts that this.publicClient is populated
+   * @throws {CofhesdkError} If publicClient is not set
+   */
+  protected assertPublicClient(): asserts this is this & { publicClient: PublicClient } {
+    if (this.publicClient) return;
+    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,
+      },
+    });
+  }
+
+  /**
+   * Asserts that this.walletClient is populated
+   * @throws {CofhesdkError} If walletClient is not set
+   */
+  protected assertWalletClient(): asserts this is this & { walletClient: WalletClient } {
+    if (this.walletClient) return;
+    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,
+      },
+    });
+  }
+}

package/core/client.test.ts

@@ -0,0 +1,315 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createCofhesdkClientBase } from './client.js';
+import { type CofhesdkClient, type CofhesdkClientConnectionState } from './clientTypes.js';
+import { createCofhesdkConfigBase, type CofhesdkEnvironment } from './config.js';
+import { CofhesdkError, 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,
+  })),
+}));
+
+// 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);
+      expect(snapshot.publicClient).toBe(undefined);
+      expect(snapshot.walletClient).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('environment', () => {
+    it('should create a client with the correct environment', async () => {
+      const environments: CofhesdkEnvironment[] = ['node', 'hardhat', 'web', 'react'];
+      for (const environment of environments) {
+        const config = createCofhesdkConfigBase({ environment, supportedChains: [] });
+        const client = createCofhesdkClientBase({
+          config,
+          zkBuilderAndCrsGenerator: {} as any,
+          tfhePublicKeyDeserializer: {} as any,
+          compactPkeCrsDeserializer: {} as any,
+          initTfhe: () => Promise.resolve(false),
+        });
+
+        expect(client.config.environment).toBe(environment);
+      }
+    });
+  });
+
+  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[0].publicClient).toBe(undefined);
+      expect(states[0].walletClient).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');
+      expect(states[1].publicClient).toBe(publicClient);
+      expect(states[1].walletClient).toBe(walletClient);
+    });
+
+    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']);
+
+      await client.connect(publicClient, walletClient);
+
+      expect(client.connected).toBe(true);
+      expect(client.connecting).toBe(false);
+
+      const snapshot = client.getSnapshot();
+      expect(snapshot.chainId).toBe(11155111);
+      expect(snapshot.account).toBe('0xabcd');
+      expect(snapshot.publicClient).toBe(publicClient);
+      expect(snapshot.walletClient).toBe(walletClient);
+    });
+
+    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 handle publicClient.getChainId throwing an error', async () => {
+      const publicClient = createMockPublicClient();
+      const getChainIdError = new Error('Network error');
+      publicClient.getChainId = vi.fn().mockRejectedValue(getChainIdError);
+      const walletClient = createMockWalletClient();
+
+      try {
+        await client.connect(publicClient, walletClient);
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofhesdkError);
+        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetChainIdFailed);
+        expect((error as CofhesdkError).message).toBe(
+          'getting chain ID from public client failed | Caused by: Network error'
+        );
+        expect((error as CofhesdkError).cause).toBe(getChainIdError);
+      }
+    });
+
+    it('should handle publicClient.getChainId returning null', async () => {
+      const publicClient = createMockPublicClient();
+      publicClient.getChainId = vi.fn().mockResolvedValue(null);
+      const walletClient = createMockWalletClient();
+
+      const connectPromise = client.connect(publicClient, walletClient);
+
+      try {
+        await connectPromise;
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofhesdkError);
+        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetChainIdFailed);
+        expect((error as CofhesdkError).message).toBe('chain ID from public client is null');
+      }
+    });
+
+    it('should handle walletClient.getAddresses throwing an error', async () => {
+      const publicClient = createMockPublicClient();
+      const getAddressesError = new Error('Network error');
+      const walletClient = createMockWalletClient();
+      walletClient.getAddresses = vi.fn().mockRejectedValue(getAddressesError);
+
+      const connectPromise = client.connect(publicClient, walletClient);
+
+      try {
+        await connectPromise;
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofhesdkError);
+        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetAddressesFailed);
+        expect((error as CofhesdkError).message).toBe(
+          'getting address from wallet client failed | Caused by: Network error'
+        );
+        expect((error as CofhesdkError).cause).toBe(getAddressesError);
+      }
+    });
+
+    it('should handle walletClient.getAddresses returning an empty array', async () => {
+      const publicClient = createMockPublicClient();
+      const walletClient = createMockWalletClient([]);
+
+      const connectPromise = client.connect(publicClient, walletClient);
+
+      try {
+        await connectPromise;
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofhesdkError);
+        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetAddressesFailed);
+        expect((error as CofhesdkError).message).toBe('address from wallet client is null');
+      }
+    });
+
+    it('should store error in state on failure', async () => {
+      const publicClient = createMockPublicClient();
+      const getChainIdError = new Error('Network error');
+      publicClient.getChainId = vi.fn().mockRejectedValue(getChainIdError);
+      const walletClient = createMockWalletClient();
+
+      const connectPromise = client.connect(publicClient, walletClient);
+
+      try {
+        await connectPromise;
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofhesdkError);
+        expect((error as CofhesdkError).code).toBe(CofhesdkErrorCode.PublicWalletGetChainIdFailed);
+        expect((error as CofhesdkError).message).toBe(
+          'getting chain ID from public client failed | Caused by: Network error'
+        );
+        expect((error as CofhesdkError).cause).toBe(getChainIdError);
+      }
+    });
+  });
+
+  describe('encryptInputs', () => {
+    it('should throw if not connected', async () => {
+      try {
+        await client.encryptInputs([Encryptable.uint8(1n), Encryptable.uint8(2n), Encryptable.uint8(3n)]).encrypt();
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofhesdkError);
+        expect((error as CofhesdkError).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('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');
+    });
+  });
+});