@cofhe/sdk 0.2.0 → 0.3.0

package/core/client.ts

@@ -2,22 +2,18 @@ import type { CreateSelfPermitOptions, CreateSharingPermitOptions, ImportSharedP
 
 import { createStore } from 'zustand/vanilla';
 import { type PublicClient, type WalletClient } from 'viem';
-import { CofhesdkError, CofhesdkErrorCode } from './error.js';
+import { CofheError, CofheErrorCode } from './error.js';
 import { EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
 import { createKeysStore } from './keyStore.js';
 import { permits } from './permits.js';
-import { DecryptHandlesBuilder } from './decrypt/decryptHandleBuilder.js';
+import { DecryptForViewBuilder } from './decrypt/decryptForViewBuilder.js';
+import { DecryptForTxBuilder, type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js';
 import { getPublicClientChainID, getWalletClientAccount } from './utils.js';
-import type {
-  CofhesdkClientConnectionState,
-  CofhesdkClientParams,
-  CofhesdkClient,
-  CofhesdkClientPermits,
-} from './clientTypes.js';
+import type { CofheClientConnectionState, CofheClientParams, CofheClient, CofheClientPermits } from './clientTypes.js';
 import type { EncryptableItem, FheTypes } from './types.js';
-import type { CofhesdkConfig } from './config.js';
+import type { CofheConfig } from './config.js';
 
-export const InitialConnectStore: CofhesdkClientConnectionState = {
+export const InitialConnectStore: CofheClientConnectionState = {
   connected: false,
   connecting: false,
   connectError: undefined,
@@ -28,22 +24,26 @@ export const InitialConnectStore: CofhesdkClientConnectionState = {
 };
 
 /**
- * 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
+ * Creates a CoFHE client instance (base implementation)
+ * @param {CofheClientParams} opts - Initialization options including config and platform-specific serializers
+ * @returns {CofheClient} - The CoFHE client instance
  */
-export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
-  opts: CofhesdkClientParams<TConfig>
-): CofhesdkClient<TConfig> {
+export function createCofheClientBase<TConfig extends CofheConfig>(
+  opts: CofheClientParams<TConfig>
+): CofheClient<TConfig> {
   // Create keysStorage instance using configured storage
   const keysStorage = createKeysStore(opts.config.fheKeyStorage);
 
   // Zustand store for reactive state management
 
-  const connectStore = createStore<CofhesdkClientConnectionState>(() => InitialConnectStore);
+  const connectStore = createStore<CofheClientConnectionState>(() => InitialConnectStore);
+
+  // Minimal cancellation mechanism: incremented on each connect/disconnect.
+  // If a connect finishes after a disconnect, it must not overwrite the disconnected state.
+  let connectAttemptId = 0;
 
   // Helper to update state
-  const updateConnectState = (partial: Partial<CofhesdkClientConnectionState>) => {
+  const updateConnectState = (partial: Partial<CofheClientConnectionState>) => {
     connectStore.setState((state) => ({ ...state, ...partial }));
   };
 
@@ -53,8 +53,8 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     const notConnected =
       !state.connected || !state.account || !state.chainId || !state.publicClient || !state.walletClient;
     if (notConnected) {
-      throw new CofhesdkError({
-        code: CofhesdkErrorCode.NotConnected,
+      throw new CofheError({
+        code: CofheErrorCode.NotConnected,
         message: 'Client must be connected, account and chainId must be initialized',
         hint: 'Ensure client.connect() has been called and awaited.',
         context: {
@@ -76,6 +76,9 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     // Exit if already connected and clients are the same
     if (state.connected && state.publicClient === publicClient && state.walletClient === walletClient) return;
 
+    connectAttemptId += 1;
+    const localAttemptId = connectAttemptId;
+
     // Set connecting state
     updateConnectState({
       ...InitialConnectStore,
@@ -86,6 +89,10 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     try {
       const chainId = await getPublicClientChainID(publicClient);
       const account = await getWalletClientAccount(walletClient);
+
+      // If a disconnect (or a newer connect) happened while awaiting, ignore this completion.
+      if (localAttemptId !== connectAttemptId) return;
+
       updateConnectState({
         connected: true,
         connecting: false,
@@ -96,6 +103,9 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
         walletClient,
       });
     } catch (e) {
+      // Ignore stale errors too.
+      if (localAttemptId !== connectAttemptId) return;
+
       updateConnectState({
         ...InitialConnectStore,
         connectError: e,
@@ -104,6 +114,11 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     }
   }
 
+  function disconnect() {
+    connectAttemptId += 1;
+    updateConnectState({ ...InitialConnectStore });
+  }
+
   // CLIENT OPERATIONS
 
   function encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilder<[...T]> {
@@ -131,18 +146,34 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     });
   }
 
-  function decryptHandle<U extends FheTypes>(ctHash: bigint, utype: U): DecryptHandlesBuilder<U> {
+  function decryptForView<U extends FheTypes>(ctHash: bigint, utype: U): DecryptForViewBuilder<U> {
     const state = connectStore.getState();
 
-    return new DecryptHandlesBuilder({
+    return new DecryptForViewBuilder({
       ctHash,
       utype,
-      chainId: state.chainId ?? undefined,
-      account: state.account ?? undefined,
+      chainId: state.chainId,
+      account: state.account,
 
       config: opts.config,
-      publicClient: state.publicClient ?? undefined,
-      walletClient: state.walletClient ?? undefined,
+      publicClient: state.publicClient,
+      walletClient: state.walletClient,
+
+      requireConnected: _requireConnected,
+    });
+  }
+
+  function decryptForTx(ctHash: bigint): DecryptForTxBuilderUnset {
+    const state = connectStore.getState();
+
+    return new DecryptForTxBuilder({
+      ctHash,
+      chainId: state.chainId,
+      account: state.account,
+
+      config: opts.config,
+      publicClient: state.publicClient,
+      walletClient: state.walletClient,
 
       requireConnected: _requireConnected,
     });
@@ -156,8 +187,8 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     const _account = account ?? state.account;
 
     if (_chainId == null || _account == null) {
-      throw new CofhesdkError({
-        code: CofhesdkErrorCode.NotConnected,
+      throw new CofheError({
+        code: CofheErrorCode.NotConnected,
         message: 'ChainId or account not available.',
         hint: 'Ensure client.connect() has been called, or provide chainId and account explicitly.',
         context: {
@@ -170,7 +201,7 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     return { chainId: _chainId, account: _account };
   };
 
-  const clientPermits: CofhesdkClientPermits = {
+  const clientPermits: CofheClientPermits = {
     // Pass through store access
     getSnapshot: permits.getSnapshot,
     subscribe: permits.subscribe,
@@ -245,9 +276,9 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
       return permits.selectActivePermit(_chainId, _account, hash);
     },
 
-    removePermit: async (hash: string, chainId?: number, account?: string, force?: boolean) => {
+    removePermit: async (hash: string, chainId?: number, account?: string) => {
       const { chainId: _chainId, account: _account } = _getChainIdAndAccount(chainId, account);
-      return permits.removePermit(_chainId, _account, hash, force);
+      return permits.removePermit(_chainId, _account, hash);
     },
 
     removeActivePermit: async (chainId?: number, account?: string) => {
@@ -267,6 +298,9 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     subscribe: connectStore.subscribe,
 
     // flags (read-only: reflect snapshot)
+    get connection() {
+      return connectStore.getState();
+    },
     get connected() {
       return connectStore.getState().connected;
     },
@@ -278,8 +312,14 @@ export function createCofhesdkClientBase<TConfig extends CofhesdkConfig>(
     config: opts.config,
 
     connect,
+    disconnect,
     encryptInputs,
-    decryptHandle,
+    decryptForView,
+    /**
+     * @deprecated Use `decryptForView` instead. Kept for backward compatibility.
+     */
+    decryptHandle: decryptForView,
+    decryptForTx,
     permits: clientPermits,
 
     // Add SDK-specific methods below that require connection

package/core/clientTypes.ts

@@ -1,7 +1,8 @@
 // TODO: Extract client types to its own file, keep this one as primitives
 import { type PublicClient, type WalletClient } from 'viem';
-import { type CofhesdkConfig, type CofhesdkEnvironment } from './config.js';
-import { type DecryptHandlesBuilder } from './decrypt/decryptHandleBuilder.js';
+import { type CofheConfig } from './config.js';
+import { type DecryptForViewBuilder } from './decrypt/decryptForViewBuilder.js';
+import { type DecryptForTxBuilderUnset } from './decrypt/decryptForTxBuilder.js';
 import { type EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
 import { type ZkBuilderAndCrsGenerator, type ZkProveWorkerFunction } from './encrypt/zkPackProveVerify.js';
 import { type FheKeyDeserializer } from './fetchKeys.js';
@@ -20,12 +21,13 @@ import type {
 
 // CLIENT
 
-export type CofhesdkClient<TConfig extends CofhesdkConfig = CofhesdkConfig> = {
+export type CofheClient<TConfig extends CofheConfig = CofheConfig> = {
   // --- state access ---
-  getSnapshot(): CofhesdkClientConnectionState;
+  getSnapshot(): CofheClientConnectionState;
   subscribe(listener: Listener): () => void;
 
   // --- convenience flags (read-only) ---
+  readonly connection: CofheClientConnectionState;
   readonly connected: boolean;
   readonly connecting: boolean;
 
@@ -33,15 +35,26 @@ export type CofhesdkClient<TConfig extends CofhesdkConfig = CofhesdkConfig> = {
   readonly config: TConfig;
 
   connect(publicClient: PublicClient, walletClient: WalletClient): Promise<void>;
+  /**
+   * Clears the current connection state (account/chainId/clients) and marks the client as disconnected.
+   *
+   * This does not delete persisted permits or stored FHE keys; it only resets the in-memory connection.
+   */
+  disconnect(): void;
   /**
    * Types docstring
    */
   encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilder<[...T]>;
-  decryptHandle<U extends FheTypes>(ctHash: bigint, utype: U): DecryptHandlesBuilder<U>;
-  permits: CofhesdkClientPermits;
+  /**
+   * @deprecated Use `decryptForView` instead. Kept for backward compatibility.
+   */
+  decryptHandle<U extends FheTypes>(ctHash: bigint, utype: U): DecryptForViewBuilder<U>;
+  decryptForView<U extends FheTypes>(ctHash: bigint, utype: U): DecryptForViewBuilder<U>;
+  decryptForTx(ctHash: bigint): DecryptForTxBuilderUnset;
+  permits: CofheClientPermits;
 };
 
-export type CofhesdkClientConnectionState = {
+export type CofheClientConnectionState = {
   connected: boolean;
   connecting: boolean;
   connectError: unknown | undefined;
@@ -51,26 +64,23 @@ export type CofhesdkClientConnectionState = {
   walletClient: WalletClient | undefined;
 };
 
-type Listener = (snapshot: CofhesdkClientConnectionState) => void;
+type Listener = (snapshot: CofheClientConnectionState) => void;
 
-export type CofhesdkClientPermitsClients = {
+export type CofheClientPermitsClients = {
   publicClient: PublicClient;
   walletClient: WalletClient;
 };
 
-export type CofhesdkClientPermits = {
+export type CofheClientPermits = {
   getSnapshot: typeof permits.getSnapshot;
   subscribe: typeof permits.subscribe;
 
   // Creation methods (require connection, no params)
-  createSelf: (options: CreateSelfPermitOptions, clients?: CofhesdkClientPermitsClients) => Promise<SelfPermit>;
-  createSharing: (
-    options: CreateSharingPermitOptions,
-    clients?: CofhesdkClientPermitsClients
-  ) => Promise<SharingPermit>;
+  createSelf: (options: CreateSelfPermitOptions, clients?: CofheClientPermitsClients) => Promise<SelfPermit>;
+  createSharing: (options: CreateSharingPermitOptions, clients?: CofheClientPermitsClients) => Promise<SharingPermit>;
   importShared: (
     options: ImportSharedPermitOptions | string,
-    clients?: CofhesdkClientPermitsClients
+    clients?: CofheClientPermitsClients
   ) => Promise<RecipientPermit>;
 
   // Retrieval methods (chainId/account optional)
@@ -89,7 +99,7 @@ export type CofhesdkClientPermits = {
 
   // Mutation methods (chainId/account optional)
   selectActivePermit: (hash: string, chainId?: number, account?: string) => void;
-  removePermit: (hash: string, chainId?: number, account?: string, force?: boolean) => void;
+  removePermit: (hash: string, chainId?: number, account?: string) => void;
   removeActivePermit: (chainId?: number, account?: string) => void;
 
   // Utils
@@ -98,7 +108,7 @@ export type CofhesdkClientPermits = {
   deserialize: typeof PermitUtils.deserialize;
 };
 
-export type CofhesdkClientParams<TConfig extends CofhesdkConfig> = {
+export type CofheClientParams<TConfig extends CofheConfig> = {
   config: TConfig;
   zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator;
   tfhePublicKeyDeserializer: FheKeyDeserializer;

package/core/config.test.ts

@@ -2,17 +2,17 @@ import { sepolia, hardhat } from '@/chains';
 
 import { describe, it, expect, vi } from 'vitest';
 import {
-  createCofhesdkConfigBase,
-  getCofhesdkConfigItem,
-  type CofhesdkInputConfig,
+  createCofheConfigBase,
+  getCofheConfigItem,
+  type CofheInputConfig,
   getSupportedChainOrThrow,
   getCoFheUrlOrThrow,
   getZkVerifierUrlOrThrow,
   getThresholdNetworkUrlOrThrow,
 } from './config.js';
 
-describe('createCofhesdkConfigBase', () => {
-  const validBaseConfig: CofhesdkInputConfig = {
+describe('createCofheConfigBase', () => {
+  const validBaseConfig: CofheInputConfig = {
     supportedChains: [],
   };
 
@@ -36,18 +36,18 @@ describe('createCofhesdkConfigBase', () => {
     if (log) {
       console.log('expect config invalid', path, value, config);
       try {
-        createCofhesdkConfigBase(config as CofhesdkInputConfig);
+        createCofheConfigBase(config as CofheInputConfig);
       } catch (e) {
         console.log('expect config invalid', path, value, config, e);
       }
     }
-    expect(() => createCofhesdkConfigBase(config as CofhesdkInputConfig)).toThrow('Invalid cofhesdk configuration:');
+    expect(() => createCofheConfigBase(config as CofheInputConfig)).toThrow('Invalid cofhe configuration:');
   };
 
   const expectValidConfigItem = (path: string, value: any, expectedValue: any): void => {
     const config = { ...validBaseConfig };
     setNestedValue(config, path, value);
-    const result = createCofhesdkConfigBase(config);
+    const result = createCofheConfigBase(config);
     expect(getNestedValue(result, path)).toEqual(expectedValue);
   };
 
@@ -72,16 +72,6 @@ describe('createCofhesdkConfigBase', () => {
     expectValidConfigItem('supportedChains', [sepolia, hardhat], [sepolia, hardhat]);
   });
 
-  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);
@@ -116,7 +106,7 @@ describe('createCofhesdkConfigBase', () => {
     };
 
     const config = { ...validBaseConfig, fheKeyStorage: fakeStorage };
-    const result = createCofhesdkConfigBase(config);
+    const result = createCofheConfigBase(config);
 
     expect(result.fheKeyStorage).not.toBeNull();
     await result.fheKeyStorage!.getItem('test');
@@ -126,22 +116,39 @@ describe('createCofhesdkConfigBase', () => {
     expect(getItemCalled).toBe(true);
     expect(setItemCalled).toBe(true);
     expect(removeItemCalled).toBe(true);
+
+    const invalidStorageNotAFunction = {
+      getItem: 'not-a-function',
+      setItem: 'not-a-function',
+      removeItem: 'not-a-function',
+    };
+
+    expectInvalidConfigItem('fheKeyStorage', invalidStorageNotAFunction);
   });
 
   it('mocks', () => {
     expectInvalidConfigItem('mocks', 'not-an-object');
     expectInvalidConfigItem('mocks', null);
+  });
+
+  it('mocks.decryptDelay', () => {
+    expectInvalidConfigItem('mocks.decryptDelay', 'not-a-number');
+    expectInvalidConfigItem('mocks.decryptDelay', null);
 
-    expectValidConfigItem('mocks', { sealOutputDelay: 1000 }, { sealOutputDelay: 1000 });
-    expectValidConfigItem('mocks', undefined, { sealOutputDelay: 0 });
+    expectValidConfigItem('mocks.decryptDelay', undefined, 0);
+    expectValidConfigItem('mocks.decryptDelay', 1000, 1000);
   });
 
-  it('mocks.sealOutputDelay', () => {
-    expectInvalidConfigItem('mocks.sealOutputDelay', 'not-a-number');
-    expectInvalidConfigItem('mocks.sealOutputDelay', null);
+  it('mocks.encryptDelay', () => {
+    expectInvalidConfigItem('mocks.encryptDelay', 'not-a-number');
+    expectInvalidConfigItem('mocks.encryptDelay', null);
+    expectInvalidConfigItem('mocks.encryptDelay', [100, 100, 100]); // wrong tuple length
+    expectInvalidConfigItem('mocks.encryptDelay', ['a', 'b', 'c', 'd', 'e']); // non-number elements
 
-    expectValidConfigItem('mocks.sealOutputDelay', undefined, 0);
-    expectValidConfigItem('mocks.sealOutputDelay', 1000, 1000);
+    expectValidConfigItem('mocks.encryptDelay', undefined, [100, 100, 100, 500, 500]);
+    expectValidConfigItem('mocks.encryptDelay', 200, 200);
+    expectValidConfigItem('mocks.encryptDelay', 0, 0);
+    expectValidConfigItem('mocks.encryptDelay', [10, 20, 30, 40, 50], [10, 20, 30, 40, 50]);
   });
 
   it('useWorkers', () => {
@@ -156,19 +163,19 @@ describe('createCofhesdkConfigBase', () => {
   });
 
   it('should get config item', () => {
-    const config: CofhesdkInputConfig = {
+    const config: CofheInputConfig = {
       supportedChains: [sepolia],
     };
 
-    const result = createCofhesdkConfigBase(config);
+    const result = createCofheConfigBase(config);
 
-    const supportedChains = getCofhesdkConfigItem(result, 'supportedChains');
+    const supportedChains = getCofheConfigItem(result, 'supportedChains');
     expect(supportedChains).toEqual(config.supportedChains);
   });
 });
 
 describe('Config helper functions', () => {
-  const config = createCofhesdkConfigBase({
+  const config = createCofheConfigBase({
     supportedChains: [sepolia, hardhat],
   });
 
@@ -192,7 +199,7 @@ describe('Config helper functions', () => {
     });
 
     it('should throw MissingConfig when url not set', () => {
-      const configWithoutUrl = createCofhesdkConfigBase({
+      const configWithoutUrl = createCofheConfigBase({
         supportedChains: [{ ...sepolia, coFheUrl: undefined } as any],
       });
       expect(() => getCoFheUrlOrThrow(configWithoutUrl, sepolia.id)).toThrow();
@@ -209,7 +216,7 @@ describe('Config helper functions', () => {
     });
 
     it('should throw ZkVerifierUrlUninitialized when url not set', () => {
-      const configWithoutUrl = createCofhesdkConfigBase({
+      const configWithoutUrl = createCofheConfigBase({
         supportedChains: [{ ...sepolia, verifierUrl: undefined } as any],
       });
       expect(() => getZkVerifierUrlOrThrow(configWithoutUrl, sepolia.id)).toThrow();
@@ -226,7 +233,7 @@ describe('Config helper functions', () => {
     });
 
     it('should throw ThresholdNetworkUrlUninitialized when url not set', () => {
-      const configWithoutUrl = createCofhesdkConfigBase({
+      const configWithoutUrl = createCofheConfigBase({
         supportedChains: [{ ...sepolia, thresholdNetworkUrl: undefined } as any],
       });
       expect(() => getThresholdNetworkUrlOrThrow(configWithoutUrl, sepolia.id)).toThrow();