@cofhe/sdk 0.1.1 → 0.2.1

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 */
@@ -66,12 +70,20 @@ export const CofhesdkConfigSchema = z.object({
   /** Storage method for fhe keys (defaults to indexedDB on web, filesystem on node) */
   fheKeyStorage: z
     .object({
-      getItem: z.function().args(z.string()).returns(z.promise(z.any())),
-      setItem: z.function().args(z.string(), z.any()).returns(z.promise(z.void())),
-      removeItem: z.function().args(z.string()).returns(z.promise(z.void())),
+      getItem: z.custom<IStorage['getItem']>((val) => typeof val === 'function', {
+        message: 'getItem must be a function',
+      }),
+      setItem: z.custom<IStorage['setItem']>((val) => typeof val === 'function', {
+        message: 'setItem must be a function',
+      }),
+      removeItem: z.custom<IStorage['removeItem']>((val) => typeof val === 'function', {
+        message: 'removeItem must be a function',
+      }),
     })
     .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 +103,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
@@ -101,7 +114,7 @@ export function createCofhesdkConfigBase(config: CofhesdkInputConfig): CofhesdkC
   const result = CofhesdkConfigSchema.safeParse(config);
 
   if (!result.success) {
-    throw new Error(`Invalid cofhesdk configuration: ${result.error.message}`);
+    throw new Error(`Invalid cofhesdk configuration: ${z.prettifyError(result.error)}`, { cause: result.error });
   }
 
   return result.data;

package/core/consts.ts

@@ -0,0 +1,18 @@
+/** Main Task Manager contract address */
+export const TASK_MANAGER_ADDRESS = '0xeA30c4B8b44078Bbf8a6ef5b9f1eC1626C7848D9' as const;
+
+/** Mock ZK Verifier contract address (used for testing) */
+export const MOCKS_ZK_VERIFIER_ADDRESS = '0x0000000000000000000000000000000000005001' as const;
+
+/** Mock Query Decrypter contract address (used for testing) */
+export const MOCKS_QUERY_DECRYPTER_ADDRESS = '0x0000000000000000000000000000000000005002' as const;
+
+/** Test Bed contract address (used for testing) */
+export const TEST_BED_ADDRESS = '0x0000000000000000000000000000000000005003' as const;
+
+/** Private key for the Mock ZK Verifier signer account */
+export const MOCKS_ZK_VERIFIER_SIGNER_PRIVATE_KEY =
+  '0x6C8D7F768A6BB4AAFE85E8A2F5A9680355239C7E14646ED62B044E39DE154512' as const;
+
+/** Address for the Mock ZK Verifier signer account */
+export const MOCKS_ZK_VERIFIER_SIGNER_ADDRESS = '0x6E12D8C87503D4287c294f2Fdef96ACd9DFf6bd2' as const;

package/core/decrypt/cofheMocksSealOutput.ts

@@ -5,9 +5,7 @@ import { sleep } from '../utils.js';
 import { MockQueryDecrypterAbi } from './MockQueryDecrypterAbi.js';
 import { FheTypes } from '../types.js';
 import { CofhesdkError, CofhesdkErrorCode } from '../error.js';
-
-// Address the Mock Query Decrypter contract is deployed to on the Hardhat chain
-export const MockQueryDecrypterAddress = '0x0000000000000000000000000000000000000200';
+import { MOCKS_QUERY_DECRYPTER_ADDRESS } from '../consts.js';
 
 export async function cofheMocksSealOutput(
   ctHash: bigint,
@@ -29,7 +27,7 @@ export async function cofheMocksSealOutput(
   };
 
   const [allowed, error, result] = await publicClient.readContract({
-    address: MockQueryDecrypterAddress,
+    address: MOCKS_QUERY_DECRYPTER_ADDRESS,
     abi: MockQueryDecrypterAbi,
     functionName: 'querySealOutput',
     args: [ctHash, BigInt(utype), permissionWithBigInts],

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,

package/core/decrypt/tnSealOutputV2.ts

@@ -0,0 +1,298 @@
+import { type Permission, type EthEncryptedData } from '@/permits';
+
+import { CofhesdkError, CofhesdkErrorCode } from '../error.js';
+
+// Polling configuration
+const POLL_INTERVAL_MS = 1000; // 1 second
+const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+// V2 API response types
+type SealOutputSubmitResponse = {
+  request_id: string;
+};
+
+type SealOutputStatusResponse = {
+  request_id: string;
+  status: 'PROCESSING' | 'COMPLETED';
+  submitted_at: string;
+  completed_at?: string;
+  is_succeed?: boolean;
+  sealed?: {
+    data: number[];
+    public_key: number[];
+    nonce: number[];
+  };
+  signature?: string;
+  encryption_type?: number;
+  error_message?: string | null;
+};
+
+/**
+ * Converts a number array to Uint8Array
+ */
+function numberArrayToUint8Array(arr: number[]): Uint8Array {
+  return new Uint8Array(arr);
+}
+
+/**
+ * Converts the sealed data from the API response to EthEncryptedData
+ */
+function convertSealedData(sealed: SealOutputStatusResponse['sealed']): EthEncryptedData {
+  if (!sealed) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.SealOutputReturnedNull,
+      message: 'Sealed data is missing from completed response',
+    });
+  }
+
+  return {
+    data: numberArrayToUint8Array(sealed.data),
+    public_key: numberArrayToUint8Array(sealed.public_key),
+    nonce: numberArrayToUint8Array(sealed.nonce),
+  };
+}
+
+/**
+ * Submits a sealoutput request to the v2 API and returns the request_id
+ */
+async function submitSealOutputRequest(
+  thresholdNetworkUrl: string,
+  ctHash: bigint,
+  chainId: number,
+  permission: Permission
+): Promise<string> {
+  const body = {
+    ct_tempkey: ctHash.toString(16).padStart(64, '0'),
+    host_chain_id: chainId,
+    permit: permission,
+  };
+
+  let response: Response;
+  try {
+    response = await fetch(`${thresholdNetworkUrl}/v2/sealoutput`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.SealOutputFailed,
+      message: `sealOutput request failed`,
+      hint: 'Ensure the threshold network URL is valid and reachable.',
+      cause: e instanceof Error ? e : undefined,
+      context: {
+        thresholdNetworkUrl,
+        body,
+      },
+    });
+  }
+
+  // Handle non-200 status codes
+  if (!response.ok) {
+    let errorMessage = `HTTP ${response.status}`;
+    try {
+      const errorBody = await response.json();
+      errorMessage = errorBody.error_message || errorBody.message || errorMessage;
+    } catch {
+      // Ignore JSON parse errors, use status text
+      errorMessage = response.statusText || errorMessage;
+    }
+
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.SealOutputFailed,
+      message: `sealOutput request failed: ${errorMessage}`,
+      hint: 'Check the threshold network URL and request parameters.',
+      context: {
+        thresholdNetworkUrl,
+        status: response.status,
+        statusText: response.statusText,
+        body,
+      },
+    });
+  }
+
+  let submitResponse: SealOutputSubmitResponse;
+  try {
+    submitResponse = (await response.json()) as SealOutputSubmitResponse;
+  } catch (e) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.SealOutputFailed,
+      message: `Failed to parse sealOutput submit response`,
+      cause: e instanceof Error ? e : undefined,
+      context: {
+        thresholdNetworkUrl,
+        body,
+      },
+    });
+  }
+
+  if (!submitResponse.request_id) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.SealOutputFailed,
+      message: `sealOutput submit response missing request_id`,
+      context: {
+        thresholdNetworkUrl,
+        body,
+        submitResponse,
+      },
+    });
+  }
+
+  return submitResponse.request_id;
+}
+
+/**
+ * Polls for the sealoutput status until completed or timeout
+ */
+async function pollSealOutputStatus(thresholdNetworkUrl: string, requestId: string): Promise<EthEncryptedData> {
+  const startTime = Date.now();
+  let completed = false;
+
+  while (!completed) {
+    // Check timeout
+    if (Date.now() - startTime > POLL_TIMEOUT_MS) {
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.SealOutputFailed,
+        message: `sealOutput polling timed out after ${POLL_TIMEOUT_MS}ms`,
+        hint: 'The request may still be processing. Try again later.',
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+          timeoutMs: POLL_TIMEOUT_MS,
+        },
+      });
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(`${thresholdNetworkUrl}/v2/sealoutput/${requestId}`, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+    } catch (e) {
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.SealOutputFailed,
+        message: `sealOutput status poll failed`,
+        hint: 'Ensure the threshold network URL is valid and reachable.',
+        cause: e instanceof Error ? e : undefined,
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+        },
+      });
+    }
+
+    // Handle 404 - request not found
+    if (response.status === 404) {
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.SealOutputFailed,
+        message: `sealOutput request not found: ${requestId}`,
+        hint: 'The request may have expired or been invalid.',
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+        },
+      });
+    }
+
+    // Handle other non-200 status codes
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}`;
+      try {
+        const errorBody = await response.json();
+        errorMessage = errorBody.error_message || errorBody.message || errorMessage;
+      } catch {
+        errorMessage = response.statusText || errorMessage;
+      }
+
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.SealOutputFailed,
+        message: `sealOutput status poll failed: ${errorMessage}`,
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+          status: response.status,
+          statusText: response.statusText,
+        },
+      });
+    }
+
+    let statusResponse: SealOutputStatusResponse;
+    try {
+      statusResponse = (await response.json()) as SealOutputStatusResponse;
+    } catch (e) {
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.SealOutputFailed,
+        message: `Failed to parse sealOutput status response`,
+        cause: e instanceof Error ? e : undefined,
+        context: {
+          thresholdNetworkUrl,
+          requestId,
+        },
+      });
+    }
+
+    // Check if completed
+    if (statusResponse.status === 'COMPLETED') {
+      // Check if succeeded
+      if (statusResponse.is_succeed === false) {
+        const errorMessage = statusResponse.error_message || 'Unknown error';
+        throw new CofhesdkError({
+          code: CofhesdkErrorCode.SealOutputFailed,
+          message: `sealOutput request failed: ${errorMessage}`,
+          context: {
+            thresholdNetworkUrl,
+            requestId,
+            statusResponse,
+          },
+        });
+      }
+
+      // Check if sealed data exists
+      if (!statusResponse.sealed) {
+        throw new CofhesdkError({
+          code: CofhesdkErrorCode.SealOutputReturnedNull,
+          message: `sealOutput request completed but returned no sealed data`,
+          context: {
+            thresholdNetworkUrl,
+            requestId,
+            statusResponse,
+          },
+        });
+      }
+
+      // Convert and return the sealed data
+      return convertSealedData(statusResponse.sealed);
+    }
+
+    // Still processing, wait before next poll
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+
+  // This should never be reached, but TypeScript requires it
+  throw new CofhesdkError({
+    code: CofhesdkErrorCode.SealOutputFailed,
+    message: 'Polling loop exited unexpectedly',
+    context: {
+      thresholdNetworkUrl,
+      requestId,
+    },
+  });
+}
+
+export async function tnSealOutputV2(
+  ctHash: bigint,
+  chainId: number,
+  permission: Permission,
+  thresholdNetworkUrl: string
+): Promise<EthEncryptedData> {
+  // Step 1: Submit the request and get request_id
+  const requestId = await submitSealOutputRequest(thresholdNetworkUrl, ctHash, chainId, permission);
+
+  // Step 2: Poll for status until completed
+  return await pollSealOutputStatus(thresholdNetworkUrl, requestId);
+}