@cofhe/sdk 0.1.1 → 0.2.0

package/core/clientTypes.ts

@@ -0,0 +1,108 @@
+// 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 EncryptInputsBuilder } from './encrypt/encryptInputsBuilder.js';
+import { type ZkBuilderAndCrsGenerator, type ZkProveWorkerFunction } from './encrypt/zkPackProveVerify.js';
+import { type FheKeyDeserializer } from './fetchKeys.js';
+import { permits } from './permits.js';
+import type { EncryptableItem, FheTypes, TfheInitializer } from './types.js';
+import type { PermitUtils } from 'permits/permit.js';
+import type {
+  CreateSelfPermitOptions,
+  Permit,
+  CreateSharingPermitOptions,
+  ImportSharedPermitOptions,
+  SharingPermit,
+  RecipientPermit,
+  SelfPermit,
+} from 'permits/types.js';
+
+// CLIENT
+
+export type CofhesdkClient<TConfig extends CofhesdkConfig = CofhesdkConfig> = {
+  // --- state access ---
+  getSnapshot(): CofhesdkClientConnectionState;
+  subscribe(listener: Listener): () => void;
+
+  // --- convenience flags (read-only) ---
+  readonly connected: boolean;
+  readonly connecting: boolean;
+
+  // --- config & platform-specific ---
+  readonly config: TConfig;
+
+  connect(publicClient: PublicClient, walletClient: WalletClient): Promise<void>;
+  /**
+   * Types docstring
+   */
+  encryptInputs<T extends EncryptableItem[]>(inputs: [...T]): EncryptInputsBuilder<[...T]>;
+  decryptHandle<U extends FheTypes>(ctHash: bigint, utype: U): DecryptHandlesBuilder<U>;
+  permits: CofhesdkClientPermits;
+};
+
+export type CofhesdkClientConnectionState = {
+  connected: boolean;
+  connecting: boolean;
+  connectError: unknown | undefined;
+  chainId: number | undefined;
+  account: `0x${string}` | undefined;
+  publicClient: PublicClient | undefined;
+  walletClient: WalletClient | undefined;
+};
+
+type Listener = (snapshot: CofhesdkClientConnectionState) => void;
+
+export type CofhesdkClientPermitsClients = {
+  publicClient: PublicClient;
+  walletClient: WalletClient;
+};
+
+export type CofhesdkClientPermits = {
+  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>;
+  importShared: (
+    options: ImportSharedPermitOptions | string,
+    clients?: CofhesdkClientPermitsClients
+  ) => Promise<RecipientPermit>;
+
+  // Retrieval methods (chainId/account optional)
+  getPermit: (hash: string, chainId?: number, account?: string) => Promise<Permit | undefined>;
+  getPermits: (chainId?: number, account?: string) => Promise<Record<string, Permit>>;
+  getActivePermit: (chainId?: number, account?: string) => Promise<Permit | undefined>;
+  getActivePermitHash: (chainId?: number, account?: string) => Promise<string | undefined>;
+
+  // Get or create methods (get active or create new, chainId/account optional)
+  getOrCreateSelfPermit: (chainId?: number, account?: string, options?: CreateSelfPermitOptions) => Promise<Permit>;
+  getOrCreateSharingPermit: (
+    options: CreateSharingPermitOptions,
+    chainId?: number,
+    account?: string
+  ) => Promise<Permit>;
+
+  // Mutation methods (chainId/account optional)
+  selectActivePermit: (hash: string, chainId?: number, account?: string) => void;
+  removePermit: (hash: string, chainId?: number, account?: string, force?: boolean) => void;
+  removeActivePermit: (chainId?: number, account?: string) => void;
+
+  // Utils
+  getHash: typeof PermitUtils.getHash;
+  serialize: typeof PermitUtils.serialize;
+  deserialize: typeof PermitUtils.deserialize;
+};
+
+export type CofhesdkClientParams<TConfig extends CofhesdkConfig> = {
+  config: TConfig;
+  zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator;
+  tfhePublicKeyDeserializer: FheKeyDeserializer;
+  compactPkeCrsDeserializer: FheKeyDeserializer;
+  initTfhe: TfheInitializer;
+  zkProveWorkerFn?: ZkProveWorkerFunction;
+};

package/core/config.test.ts

@@ -1,4 +1,3 @@
-/* eslint-disable no-unused-vars */
 import { sepolia, hardhat } from '@/chains';
 
 import { describe, it, expect, vi } from 'vitest';
@@ -52,6 +51,17 @@ describe('createCofhesdkConfigBase', () => {
     expect(getNestedValue(result, path)).toEqual(expectedValue);
   };
 
+  it('environment', () => {
+    expectInvalidConfigItem('environment', 'not-a-valid-environment');
+    expectInvalidConfigItem('environment', 123);
+    expectInvalidConfigItem('environment', {});
+
+    expectValidConfigItem('environment', 'node', 'node');
+    expectValidConfigItem('environment', 'hardhat', 'hardhat');
+    expectValidConfigItem('environment', 'web', 'web');
+    expectValidConfigItem('environment', 'react', 'react');
+  });
+
   it('supportedChains', () => {
     expectInvalidConfigItem('supportedChains', {});
     expectInvalidConfigItem('supportedChains', 'not-an-array');
@@ -62,16 +72,6 @@ describe('createCofhesdkConfigBase', () => {
     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);
@@ -144,6 +144,17 @@ describe('createCofhesdkConfigBase', () => {
     expectValidConfigItem('mocks.sealOutputDelay', 1000, 1000);
   });
 
+  it('useWorkers', () => {
+    expectInvalidConfigItem('useWorkers', 'not-a-boolean');
+    expectInvalidConfigItem('useWorkers', null);
+    expectInvalidConfigItem('useWorkers', 123);
+    expectInvalidConfigItem('useWorkers', {});
+
+    expectValidConfigItem('useWorkers', true, true);
+    expectValidConfigItem('useWorkers', false, false);
+    expectValidConfigItem('useWorkers', undefined, true); // defaults to true
+  });
+
   it('should get config item', () => {
     const config: CofhesdkInputConfig = {
       supportedChains: [sepolia],

package/core/config.ts

@@ -5,18 +5,16 @@ import { type WalletClient } from 'viem';
 import { CofhesdkError, CofhesdkErrorCode } from './error.js';
 import { type IStorage } from './types.js';
 
+export type CofhesdkEnvironment = 'node' | 'hardhat' | 'web' | 'react';
+
 /**
  * Usable config type inferred from the schema
  */
 export type CofhesdkConfig = {
+  /** Environment that the SDK is running in */
+  environment: 'node' | 'hardhat' | 'web' | 'react';
+  /** List of supported chains */
   supportedChains: CofheChain[];
-  /**
-   * Strategy for fetching FHE keys
-   * - CONNECTED_CHAIN: Fetch keys for the connected chain (provided by the publicClient)
-   * - SUPPORTED_CHAINS: Fetch keys for all supported chains (provided by the supportedChains config)
-   * - OFF: Do not fetch keys (fetching occurs during encryptInputs)
-   * */
-  fheKeysPrefetching: 'CONNECTED_CHAIN' | 'SUPPORTED_CHAINS' | 'OFF';
   /**
    * How permits are generated
    * - ON_CONNECT: Generate a permit when client.connect() is called
@@ -32,6 +30,12 @@ export type CofhesdkConfig = {
    * (defaults to indexedDB on web, filesystem on node)
    */
   fheKeyStorage: IStorage | null;
+  /**
+   * Whether to use Web Workers for ZK proof generation (web platform only)
+   * When enabled, heavy WASM computation is offloaded to prevent UI freezing
+   * Default: true
+   */
+  useWorkers: boolean;
   /** Mocks configs */
   mocks: {
     /**
@@ -52,10 +56,10 @@ export type CofhesdkInternalConfig = {
  * Zod schema for configuration validation
  */
 export const CofhesdkConfigSchema = z.object({
+  /** Environment that the SDK is running in */
+  environment: z.enum(['node', 'hardhat', 'web', 'react']).optional().default('node'),
   /** List of supported chain configurations */
   supportedChains: z.array(z.custom<CofheChain>()),
-  /** Strategy for fetching FHE keys */
-  fheKeysPrefetching: z.enum(['CONNECTED_CHAIN', 'SUPPORTED_CHAINS', 'OFF']).optional().default('OFF'),
   /** How permits are generated */
   permitGeneration: z.enum(['ON_CONNECT', 'ON_DECRYPT_HANDLES', 'MANUAL']).optional().default('ON_CONNECT'),
   /** Default permit expiration in seconds, default is 30 days */
@@ -72,6 +76,8 @@ export const CofhesdkConfigSchema = z.object({
     })
     .or(z.null())
     .default(null),
+  /** Whether to use Web Workers for ZK proof generation (web platform only) */
+  useWorkers: z.boolean().optional().default(true),
   /** Mocks configs */
   mocks: z
     .object({
@@ -91,6 +97,7 @@ export const CofhesdkConfigSchema = z.object({
  * Input config type inferred from the schema
  */
 export type CofhesdkInputConfig = z.input<typeof CofhesdkConfigSchema>;
+
 /**
  * Creates and validates a cofhesdk configuration (base implementation)
  * @param config - The configuration object to validate

package/core/decrypt/decryptHandleBuilder.ts

@@ -3,13 +3,13 @@ import { type Permit, PermitUtils } from '@/permits';
 
 import { FheTypes, type UnsealedItem } from '../types.js';
 import { getThresholdNetworkUrlOrThrow } from '../config.js';
-import { type Result, resultWrapper } from '../result.js';
 import { CofhesdkError, CofhesdkErrorCode } from '../error.js';
 import { permits } from '../permits.js';
 import { isValidUtype, convertViaUtype } from './decryptUtils.js';
 import { BaseBuilder, type BaseBuilderParams } from '../baseBuilder.js';
 import { cofheMocksSealOutput } from './cofheMocksSealOutput.js';
-import { tnSealOutput } from './tnSealOutput.js';
+// import { tnSealOutputV1 } from './tnSealOutputV1.js';
+import { tnSealOutputV2 } from './tnSealOutputV2.js';
 
 /**
  * API
@@ -26,7 +26,7 @@ import { tnSealOutput } from './tnSealOutput.js';
  * If permitHash not set, uses chainId and account to get active permit
  * If permit is set, uses permit to decrypt regardless of chainId, account, or permitHash
  *
- * Returns a Result<UnsealedItem<U>>
+ * Returns the unsealed item.
  */
 
 type DecryptHandlesBuilderParams<U extends FheTypes> = BaseBuilderParams & {
@@ -151,9 +151,9 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
     return this.permit;
   }
 
-  private getThresholdNetworkUrl(chainId: number): string {
-    const config = this.getConfigOrThrow();
-    return getThresholdNetworkUrlOrThrow(config, chainId);
+  private async getThresholdNetworkUrl(): Promise<string> {
+    this.assertChainId();
+    return getThresholdNetworkUrlOrThrow(this.config, this.chainId);
   }
 
   private validateUtypeOrThrow(): void {
@@ -170,20 +170,20 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
   private async getResolvedPermit(): Promise<Permit> {
     if (this.permit) return this.permit;
 
-    const chainId = await this.getChainIdOrThrow();
-    const account = await this.getAccountOrThrow();
+    this.assertChainId();
+    this.assertAccount();
 
     // Fetch with permit hash
     if (this.permitHash) {
-      const permit = await permits.getPermit(chainId, account, this.permitHash);
+      const permit = await permits.getPermit(this.chainId, this.account, this.permitHash);
       if (!permit) {
         throw new CofhesdkError({
           code: CofhesdkErrorCode.PermitNotFound,
-          message: `Permit with hash <${this.permitHash}> not found for account <${account}> and chainId <${chainId}>`,
+          message: `Permit with hash <${this.permitHash}> not found for account <${this.account}> and chainId <${this.chainId}>`,
           hint: 'Ensure the permit exists and is valid.',
           context: {
-            chainId,
-            account,
+            chainId: this.chainId,
+            account: this.account,
             permitHash: this.permitHash,
           },
         });
@@ -192,15 +192,15 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
     }
 
     // Fetch with active permit
-    const permit = await permits.getActivePermit(chainId, account);
+    const permit = await permits.getActivePermit(this.chainId, this.account);
     if (!permit) {
       throw new CofhesdkError({
         code: CofhesdkErrorCode.PermitNotFound,
-        message: `Active permit not found for chainId <${chainId}> and account <${account}>`,
+        message: `Active permit not found for chainId <${this.chainId}> and account <${this.account}>`,
         hint: 'Ensure a permit exists for this account on this chain.',
         context: {
-          chainId,
-          account,
+          chainId: this.chainId,
+          account: this.account,
         },
       });
     }
@@ -211,18 +211,23 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
    * On hardhat, interact with MockZkVerifier contract instead of CoFHE
    */
   private async mocksSealOutput(permit: Permit): Promise<bigint> {
-    const config = this.getConfigOrThrow();
-    const mocksSealOutputDelay = config.mocks.sealOutputDelay;
-    return cofheMocksSealOutput(this.ctHash, this.utype, permit, this.getPublicClientOrThrow(), mocksSealOutputDelay);
+    this.assertPublicClient();
+
+    const mocksSealOutputDelay = this.config.mocks.sealOutputDelay;
+    return cofheMocksSealOutput(this.ctHash, this.utype, permit, this.publicClient, mocksSealOutputDelay);
   }
 
   /**
    * In the production context, perform a true decryption with the CoFHE coprocessor.
    */
-  private async productionSealOutput(chainId: number, permit: Permit): Promise<bigint> {
-    const thresholdNetworkUrl = this.getThresholdNetworkUrl(chainId);
+  private async productionSealOutput(permit: Permit): Promise<bigint> {
+    this.assertChainId();
+    this.assertPublicClient();
+
+    const thresholdNetworkUrl = await this.getThresholdNetworkUrl();
     const permission = PermitUtils.getPermission(permit, true);
-    const sealed = await tnSealOutput(this.ctHash, chainId, permission, thresholdNetworkUrl);
+    // const sealed = await tnSealOutputV1(this.ctHash, this.chainId, permission, thresholdNetworkUrl);
+    const sealed = await tnSealOutputV2(this.ctHash, this.chainId, permission, thresholdNetworkUrl);
     return PermitUtils.unseal(permit, sealed);
   }
 
@@ -246,36 +251,37 @@ export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
    *
    * @returns The unsealed item.
    */
-  decrypt(): Promise<Result<UnsealedItem<U>>> {
-    return resultWrapper(async () => {
-      // Ensure cofhe client is connected
-      await this.requireConnectedOrThrow();
+  async decrypt(): Promise<UnsealedItem<U>> {
+    // Ensure utype is valid
+    this.validateUtypeOrThrow();
 
-      // Ensure utype is valid
-      this.validateUtypeOrThrow();
+    // Resolve permit
+    const permit = await this.getResolvedPermit();
 
-      // Resolve permit
-      const permit = await this.getResolvedPermit();
+    // Ensure permit validity
+    // TODO: This doesn't validate permit expiration
+    // TODO: This doesn't throw, returns a validation result instead
+    PermitUtils.validate(permit);
 
-      // Ensure permit validity
-      await PermitUtils.validate(permit);
+    // TODO: Add this further validation step for the permit
+    // TODO: Ensure this throws if the permit is invalid
+    PermitUtils.isValid(permit);
 
-      // Extract chainId from signed permit
-      // Use this chainId to fetch the threshold network URL since this.chainId may be undefined
-      const chainId = permit._signedDomain!.chainId;
+    // Extract chainId from signed permit
+    // Use this chainId to fetch the threshold network URL since this.chainId may be undefined
+    const chainId = permit._signedDomain!.chainId;
 
-      // Check permit validity on-chain
-      // TODO: PermitUtils.validateOnChain(permit, this.publicClient);
+    // Check permit validity on-chain
+    // TODO: PermitUtils.validateOnChain(permit, this.publicClient);
 
-      let unsealed: bigint;
+    let unsealed: bigint;
 
-      if (chainId === hardhat.id) {
-        unsealed = await this.mocksSealOutput(permit);
-      } else {
-        unsealed = await this.productionSealOutput(chainId, permit);
-      }
+    if (chainId === hardhat.id) {
+      unsealed = await this.mocksSealOutput(permit);
+    } else {
+      unsealed = await this.productionSealOutput(permit);
+    }
 
-      return convertViaUtype(this.utype, unsealed);
-    });
+    return convertViaUtype(this.utype, unsealed);
   }
 }

package/core/decrypt/{tnSealOutput.ts → tnSealOutputV1.ts}

@@ -2,7 +2,7 @@ import { type Permission, type EthEncryptedData } from '@/permits';
 
 import { CofhesdkError, CofhesdkErrorCode } from '../error.js';
 
-export async function tnSealOutput(
+export async function tnSealOutputV1(
   ctHash: bigint,
   chainId: number,
   permission: Permission,