@cofhe/sdk 0.0.0-beta-20251027110729

package/core/client.ts

@@ -0,0 +1,308 @@
+/* eslint-disable no-unused-vars */
+import type { CreateSelfPermitOptions, CreateSharingPermitOptions, ImportSharedPermitOptions } from '@/permits';
+
+import { createStore } from 'zustand/vanilla';
+import { type PublicClient, type WalletClient } from 'viem';
+import { fetchMultichainKeys } from './fetchKeys.js';
+import { CofhesdkError, CofhesdkErrorCode } from './error.js';
+import { EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
+import { type Result, ResultOk, resultWrapper } from './result.js';
+import { createKeysStore } from './keyStore.js';
+import { permits } from './permits.js';
+import { DecryptHandlesBuilder } from './decrypt/decryptHandleBuilder.js';
+import {
+  type CofhesdkClient,
+  type CofhesdkClientParams,
+  type CofhesdkClientConnectionState,
+  type EncryptableItem,
+  type FheTypes,
+  type CofhesdkClientPermits,
+} from './types.js';
+import { getPublicClientChainID, getWalletClientAccount } from './utils.js';
+
+/**
+ * Creates a CoFHE SDK client instance (base implementation)
+ * @param {CofhesdkClientParams} opts - Initialization options including config and platform-specific serializers
+ * @returns {CofhesdkClient} - The CoFHE SDK client instance
+ */
+export function createCofhesdkClientBase(opts: CofhesdkClientParams): CofhesdkClient {
+  // Create keysStorage instance using configured storage
+  const keysStorage = createKeysStore(opts.config.fheKeyStorage);
+
+  // refs captured in closure
+  let _publicClient: PublicClient | undefined = undefined;
+  let _walletClient: WalletClient | undefined = undefined;
+
+  // Zustand store for reactive state management
+  const connectStore = createStore<CofhesdkClientConnectionState>(() => ({
+    connected: false,
+    connecting: false,
+    connectError: undefined,
+    chainId: undefined,
+    account: undefined,
+  }));
+
+  // Helper to update state
+  const updateConnectState = (partial: Partial<CofhesdkClientConnectionState>) => {
+    connectStore.setState((state) => ({ ...state, ...partial }));
+  };
+
+  // single-flight + abortable warmup
+  let _connectPromise: Promise<Result<boolean>> | undefined = undefined;
+
+  // Called before any operation, throws of connection not yet established
+  const _requireConnected = () => {
+    const state = connectStore.getState();
+    const notConnected = !state.connected || !_publicClient || !_walletClient || !state.account || !state.chainId;
+    if (notConnected) {
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.NotConnected,
+        message: 'Client must be connected, account and chainId must be initialized',
+        hint: 'Ensure client.connect() has been called and awaited.',
+        context: {
+          connected: state.connected,
+          account: state.account,
+          chainId: state.chainId,
+          publicClient: _publicClient,
+          walletClient: _walletClient,
+        },
+      });
+    }
+  };
+
+  // INITIALIZATION
+
+  const keyFetchResult = resultWrapper(async () => {
+    // If configured, fetch keys for all supported chains
+    if (opts.config.fheKeysPrefetching === 'SUPPORTED_CHAINS') {
+      await fetchMultichainKeys(
+        opts.config,
+        0,
+        opts.tfhePublicKeyDeserializer,
+        opts.compactPkeCrsDeserializer,
+        keysStorage
+      );
+      return true;
+    }
+
+    return false;
+  });
+
+  // LIFECYCLE
+
+  async function connect(publicClient: PublicClient, walletClient: WalletClient) {
+    const state = connectStore.getState();
+
+    // Exit if already connected and clients are the same
+    if (state.connected && _publicClient === publicClient && _walletClient === walletClient) {
+      return Promise.resolve(ResultOk(true));
+    }
+
+    // Exit if already connecting
+    if (_connectPromise && _publicClient === publicClient && _walletClient === walletClient) {
+      return _connectPromise;
+    }
+
+    // Set connecting state
+    updateConnectState({ connecting: true, connectError: null, connected: false });
+
+    _connectPromise = resultWrapper(
+      // try
+      async () => {
+        _publicClient = publicClient;
+        _walletClient = walletClient;
+
+        const chainId = await getPublicClientChainID(publicClient);
+        const account = await getWalletClientAccount(walletClient);
+
+        updateConnectState({ connecting: false, connected: true, chainId, account });
+
+        return true;
+      },
+      // catch
+      (e) => {
+        updateConnectState({ connecting: false, connected: false, connectError: e });
+        return false;
+      },
+      // finally
+      () => {
+        _connectPromise = undefined;
+      }
+    );
+
+    return _connectPromise;
+  }
+
+  // CLIENT OPERATIONS
+
+  function encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilder<[...T]> {
+    const state = connectStore.getState();
+
+    return new EncryptInputsBuilder({
+      inputs,
+      account: state.account ?? undefined,
+      chainId: state.chainId ?? undefined,
+
+      config: opts.config,
+      publicClient: _publicClient ?? undefined,
+      walletClient: _walletClient ?? undefined,
+      zkvWalletClient: opts.config._internal?.zkvWalletClient,
+
+      tfhePublicKeyDeserializer: opts.tfhePublicKeyDeserializer,
+      compactPkeCrsDeserializer: opts.compactPkeCrsDeserializer,
+      zkBuilderAndCrsGenerator: opts.zkBuilderAndCrsGenerator,
+      initTfhe: opts.initTfhe,
+
+      keysStorage,
+
+      requireConnected: _requireConnected,
+    });
+  }
+
+  function decryptHandle<U extends FheTypes>(ctHash: bigint, utype: U): DecryptHandlesBuilder<U> {
+    const state = connectStore.getState();
+
+    return new DecryptHandlesBuilder({
+      ctHash,
+      utype,
+      chainId: state.chainId ?? undefined,
+      account: state.account ?? undefined,
+
+      config: opts.config,
+      publicClient: _publicClient ?? undefined,
+      walletClient: _walletClient ?? undefined,
+
+      requireConnected: _requireConnected,
+    });
+  }
+
+  // PERMITS - Context-aware wrapper
+
+  const _getChainIdAndAccount = (chainId?: number, account?: string) => {
+    const state = connectStore.getState();
+    const _chainId = chainId ?? state.chainId;
+    const _account = account ?? state.account;
+
+    if (_chainId == null || _account == null) {
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.NotConnected,
+        message: 'ChainId or account not available.',
+        hint: 'Ensure client.connect() has been called, or provide chainId and account explicitly.',
+        context: {
+          chainId: _chainId,
+          account: _account,
+        },
+      });
+    }
+
+    return { chainId: _chainId, account: _account };
+  };
+
+  const clientPermits: CofhesdkClientPermits = {
+    // Pass through store access
+    getSnapshot: permits.getSnapshot,
+    subscribe: permits.subscribe,
+
+    // Creation methods (require connection)
+    createSelf: async (options: CreateSelfPermitOptions) =>
+      resultWrapper(async () => {
+        _requireConnected();
+        return permits.createSelf(options, _publicClient!, _walletClient!);
+      }),
+
+    createSharing: async (options: CreateSharingPermitOptions) =>
+      resultWrapper(async () => {
+        _requireConnected();
+        return permits.createSharing(options, _publicClient!, _walletClient!);
+      }),
+
+    importShared: async (options: ImportSharedPermitOptions | any | string) =>
+      resultWrapper(async () => {
+        _requireConnected();
+        return permits.importShared(options, _publicClient!, _walletClient!);
+      }),
+
+    // Retrieval methods (auto-fill chainId/account)
+    getPermit: async (hash: string, chainId?: number, account?: string) =>
+      resultWrapper(async () => {
+        const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
+        return permits.getPermit(_chainId, _account, hash);
+      }),
+
+    getPermits: async (chainId?: number, account?: string) =>
+      resultWrapper(async () => {
+        const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
+        return permits.getPermits(_chainId, _account);
+      }),
+
+    getActivePermit: async (chainId?: number, account?: string) =>
+      resultWrapper(async () => {
+        const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
+        return permits.getActivePermit(_chainId, _account);
+      }),
+
+    getActivePermitHash: async (chainId?: number, account?: string) =>
+      resultWrapper(async () => {
+        const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
+        return permits.getActivePermitHash(_chainId, _account);
+      }),
+
+    // Mutation methods (auto-fill chainId/account)
+    selectActivePermit: async (hash: string, chainId?: number, account?: string) =>
+      resultWrapper(async () => {
+        const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
+        return permits.selectActivePermit(_chainId, _account, hash);
+      }),
+
+    removePermit: async (hash: string, chainId?: number, account?: string) =>
+      resultWrapper(async () => {
+        const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
+        return permits.removePermit(_chainId, _account, hash);
+      }),
+
+    removeActivePermit: async (chainId?: number, account?: string) =>
+      resultWrapper(async () => {
+        const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
+        return permits.removeActivePermit(_chainId, _account);
+      }),
+
+    // Utils (no context needed)
+    getHash: permits.getHash,
+    serialize: permits.serialize,
+    deserialize: permits.deserialize,
+  };
+
+  return {
+    // Zustand reactive accessors (don't export store directly to prevent mutation)
+    getSnapshot: connectStore.getState,
+    subscribe: connectStore.subscribe,
+
+    // initialization results
+    initializationResults: {
+      keyFetchResult,
+    },
+
+    // flags (read-only: reflect snapshot)
+    get connected() {
+      return connectStore.getState().connected;
+    },
+    get connecting() {
+      return connectStore.getState().connecting;
+    },
+
+    // config & platform-specific (read-only)
+    config: opts.config,
+
+    connect,
+    encryptInputs,
+    decryptHandle,
+    permits: clientPermits,
+
+    // Add SDK-specific methods below that require connection
+    // Example:
+    // async encryptData(data: unknown) {
+    //   requireConnected();
+    //   // Use _publicClient and _walletClient for implementation
+    // },
+  };
+}

package/core/config.test.ts

@@ -0,0 +1,224 @@
+/* eslint-disable no-unused-vars */
+import { sepolia, hardhat } from '@/chains';
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  createCofhesdkConfigBase,
+  getCofhesdkConfigItem,
+  type CofhesdkInputConfig,
+  getSupportedChainOrThrow,
+  getCoFheUrlOrThrow,
+  getZkVerifierUrlOrThrow,
+  getThresholdNetworkUrlOrThrow,
+} from './config.js';
+
+describe('createCofhesdkConfigBase', () => {
+  const validBaseConfig: CofhesdkInputConfig = {
+    supportedChains: [],
+  };
+
+  const setNestedValue = (obj: any, path: string, value: any): void => {
+    const keys = path.split('.');
+    const lastKey = keys.pop()!;
+    const target = keys.reduce((acc, key) => {
+      if (!acc[key]) acc[key] = {};
+      return acc[key];
+    }, obj);
+    target[lastKey] = value;
+  };
+
+  const getNestedValue = (obj: any, path: string): any => {
+    return path.split('.').reduce((acc, key) => acc?.[key], obj);
+  };
+
+  const expectInvalidConfigItem = (path: string, value: any, log = false): void => {
+    const config = { ...validBaseConfig };
+    setNestedValue(config, path, value);
+    if (log) {
+      console.log('expect config invalid', path, value, config);
+      try {
+        createCofhesdkConfigBase(config as CofhesdkInputConfig);
+      } catch (e) {
+        console.log('expect config invalid', path, value, config, e);
+      }
+    }
+    expect(() => createCofhesdkConfigBase(config as CofhesdkInputConfig)).toThrow('Invalid cofhesdk configuration:');
+  };
+
+  const expectValidConfigItem = (path: string, value: any, expectedValue: any): void => {
+    const config = { ...validBaseConfig };
+    setNestedValue(config, path, value);
+    const result = createCofhesdkConfigBase(config);
+    expect(getNestedValue(result, path)).toEqual(expectedValue);
+  };
+
+  it('supportedChains', () => {
+    expectInvalidConfigItem('supportedChains', {});
+    expectInvalidConfigItem('supportedChains', 'not-an-array');
+    expectInvalidConfigItem('supportedChains', null);
+    expectInvalidConfigItem('supportedChains', undefined);
+
+    expectValidConfigItem('supportedChains', [sepolia], [sepolia]);
+    expectValidConfigItem('supportedChains', [sepolia, hardhat], [sepolia, hardhat]);
+  });
+
+  it('fheKeysPrefetching', () => {
+    expectInvalidConfigItem('fheKeysPrefetching', 'invalid-option');
+    expectInvalidConfigItem('fheKeysPrefetching', 5);
+
+    expectValidConfigItem('fheKeysPrefetching', 'CONNECTED_CHAIN', 'CONNECTED_CHAIN');
+    expectValidConfigItem('fheKeysPrefetching', 'SUPPORTED_CHAINS', 'SUPPORTED_CHAINS');
+    expectValidConfigItem('fheKeysPrefetching', 'OFF', 'OFF');
+    expectValidConfigItem('fheKeysPrefetching', undefined, 'OFF');
+  });
+
+  it('permitGeneration', () => {
+    expectInvalidConfigItem('permitGeneration', 'not-a-boolean');
+    expectInvalidConfigItem('permitGeneration', null);
+
+    expectValidConfigItem('permitGeneration', 'ON_CONNECT', 'ON_CONNECT');
+    expectValidConfigItem('permitGeneration', 'ON_DECRYPT_HANDLES', 'ON_DECRYPT_HANDLES');
+    expectValidConfigItem('permitGeneration', 'MANUAL', 'MANUAL');
+    expectValidConfigItem('permitGeneration', undefined, 'ON_CONNECT');
+  });
+
+  it('defaultPermitExpiration', () => {
+    expectInvalidConfigItem('defaultPermitExpiration', 'not-a-number');
+    expectInvalidConfigItem('defaultPermitExpiration', null);
+
+    expectValidConfigItem('defaultPermitExpiration', 5, 5);
+    expectValidConfigItem('defaultPermitExpiration', undefined, 60 * 60 * 24 * 30);
+  });
+
+  it('fheKeyStorage', async () => {
+    expectInvalidConfigItem('fheKeyStorage', 'not-an-object');
+
+    expectValidConfigItem('fheKeyStorage', undefined, null);
+    expectValidConfigItem('fheKeyStorage', null, null);
+
+    let getItemCalled = false;
+    let setItemCalled = false;
+    let removeItemCalled = false;
+
+    const fakeStorage = {
+      getItem: (name: string) => {
+        getItemCalled = true;
+        return Promise.resolve(null);
+      },
+      setItem: (name: string, value: any) => {
+        setItemCalled = true;
+        return Promise.resolve();
+      },
+      removeItem: (name: string) => {
+        removeItemCalled = true;
+        return Promise.resolve();
+      },
+    };
+
+    const config = { ...validBaseConfig, fheKeyStorage: fakeStorage };
+    const result = createCofhesdkConfigBase(config);
+
+    expect(result.fheKeyStorage).not.toBeNull();
+    await result.fheKeyStorage!.getItem('test');
+    await result.fheKeyStorage!.setItem('test', 'test');
+    await result.fheKeyStorage!.removeItem('test');
+
+    expect(getItemCalled).toBe(true);
+    expect(setItemCalled).toBe(true);
+    expect(removeItemCalled).toBe(true);
+  });
+
+  it('mocks', () => {
+    expectInvalidConfigItem('mocks', 'not-an-object');
+    expectInvalidConfigItem('mocks', null);
+
+    expectValidConfigItem('mocks', { sealOutputDelay: 1000 }, { sealOutputDelay: 1000 });
+    expectValidConfigItem('mocks', undefined, { sealOutputDelay: 0 });
+  });
+
+  it('mocks.sealOutputDelay', () => {
+    expectInvalidConfigItem('mocks.sealOutputDelay', 'not-a-number');
+    expectInvalidConfigItem('mocks.sealOutputDelay', null);
+
+    expectValidConfigItem('mocks.sealOutputDelay', undefined, 0);
+    expectValidConfigItem('mocks.sealOutputDelay', 1000, 1000);
+  });
+
+  it('should get config item', () => {
+    const config: CofhesdkInputConfig = {
+      supportedChains: [sepolia],
+    };
+
+    const result = createCofhesdkConfigBase(config);
+
+    const supportedChains = getCofhesdkConfigItem(result, 'supportedChains');
+    expect(supportedChains).toEqual(config.supportedChains);
+  });
+});
+
+describe('Config helper functions', () => {
+  const config = createCofhesdkConfigBase({
+    supportedChains: [sepolia, hardhat],
+  });
+
+  describe('getSupportedChainOrThrow', () => {
+    it('should return chain when found', () => {
+      expect(getSupportedChainOrThrow(config, sepolia.id)).toEqual(sepolia);
+    });
+
+    it('should throw UnsupportedChain error when not found', () => {
+      expect(() => getSupportedChainOrThrow(config, 999999)).toThrow();
+    });
+  });
+
+  describe('getCoFheUrlOrThrow', () => {
+    it('should return coFheUrl', () => {
+      expect(getCoFheUrlOrThrow(config, sepolia.id)).toBe(sepolia.coFheUrl);
+    });
+
+    it('should throw when chain not found', () => {
+      expect(() => getCoFheUrlOrThrow(config, 999999)).toThrow();
+    });
+
+    it('should throw MissingConfig when url not set', () => {
+      const configWithoutUrl = createCofhesdkConfigBase({
+        supportedChains: [{ ...sepolia, coFheUrl: undefined } as any],
+      });
+      expect(() => getCoFheUrlOrThrow(configWithoutUrl, sepolia.id)).toThrow();
+    });
+  });
+
+  describe('getZkVerifierUrlOrThrow', () => {
+    it('should return verifierUrl', () => {
+      expect(getZkVerifierUrlOrThrow(config, sepolia.id)).toBe(sepolia.verifierUrl);
+    });
+
+    it('should throw when chain not found', () => {
+      expect(() => getZkVerifierUrlOrThrow(config, 999999)).toThrow();
+    });
+
+    it('should throw ZkVerifierUrlUninitialized when url not set', () => {
+      const configWithoutUrl = createCofhesdkConfigBase({
+        supportedChains: [{ ...sepolia, verifierUrl: undefined } as any],
+      });
+      expect(() => getZkVerifierUrlOrThrow(configWithoutUrl, sepolia.id)).toThrow();
+    });
+  });
+
+  describe('getThresholdNetworkUrlOrThrow', () => {
+    it('should return thresholdNetworkUrl', () => {
+      expect(getThresholdNetworkUrlOrThrow(config, sepolia.id)).toBe(sepolia.thresholdNetworkUrl);
+    });
+
+    it('should throw when chain not found', () => {
+      expect(() => getThresholdNetworkUrlOrThrow(config, 999999)).toThrow();
+    });
+
+    it('should throw ThresholdNetworkUrlUninitialized when url not set', () => {
+      const configWithoutUrl = createCofhesdkConfigBase({
+        supportedChains: [{ ...sepolia, thresholdNetworkUrl: undefined } as any],
+      });
+      expect(() => getThresholdNetworkUrlOrThrow(configWithoutUrl, sepolia.id)).toThrow();
+    });
+  });
+});