@cofhe/sdk 0.0.0-alpha-20260409113701

package/core/config.ts

@@ -0,0 +1,225 @@
+import { type CofheChain } from '@/chains';
+
+import { z } from 'zod';
+import { type WalletClient } from 'viem';
+import { CofheError, CofheErrorCode } from './error.js';
+import { type IStorage } from './types.js';
+
+export type CofheEnvironment = 'node' | 'hardhat' | 'web' | 'react';
+
+/**
+ * Usable config type inferred from the schema
+ */
+export type CofheConfig = {
+  /** Environment that the SDK is running in */
+  environment: 'node' | 'hardhat' | 'web' | 'react';
+  /** List of supported chains */
+  supportedChains: CofheChain[];
+  /** Default permit expiration in seconds, default is 30 days */
+  defaultPermitExpiration: number;
+  /**
+   * Storage scheme for the fetched fhe keys
+   * FHE keys are large, and caching prevents re-fetching them on each encryptInputs call
+   * (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: {
+    /**
+     * Length of the simulated seal output delay in milliseconds
+     * Default 1000ms on web
+     * Default 0ms on hardhat (will be called during tests no need for fake delay)
+     */
+    decryptDelay: number;
+    /**
+     * Simulated delay(s) in milliseconds for each step of encryptInputs in mock mode.
+     * A single number applies the same delay to all five steps (InitTfhe, FetchKeys, Pack, Prove, Verify).
+     * A tuple of five numbers applies a per-step delay: [InitTfhe, FetchKeys, Pack, Prove, Verify].
+     * Default: [100, 100, 100, 500, 500]
+     */
+    encryptDelay: number | [number, number, number, number, number];
+  };
+  _internal?: CofheInternalConfig;
+};
+
+export type CofheInternalConfig = {
+  zkvWalletClient?: WalletClient;
+};
+
+/**
+ * Zod schema for configuration validation
+ */
+export const CofheConfigSchema = 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>()),
+  /** Default permit expiration in seconds, default is 30 days */
+  defaultPermitExpiration: z
+    .number()
+    .optional()
+    .default(60 * 60 * 24 * 30),
+  /** Storage method for fhe keys (defaults to indexedDB on web, filesystem on node) */
+  fheKeyStorage: z
+    .object({
+      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({
+      decryptDelay: z.number().optional().default(0),
+      encryptDelay: z
+        .union([z.number(), z.tuple([z.number(), z.number(), z.number(), z.number(), z.number()])])
+        .optional()
+        .default([100, 100, 100, 500, 500]),
+    })
+    .optional()
+    .default({ decryptDelay: 0, encryptDelay: [100, 100, 100, 500, 500] }),
+  /** Internal configuration */
+  _internal: z
+    .object({
+      zkvWalletClient: z.any().optional(),
+    })
+    .optional(),
+});
+
+/**
+ * Input config type inferred from the schema
+ */
+export type CofheInputConfig = z.input<typeof CofheConfigSchema>;
+
+/**
+ * Creates and validates a cofhe configuration (base implementation)
+ * @param config - The configuration object to validate
+ * @returns The validated configuration
+ * @throws {Error} If the configuration is invalid
+ */
+export function createCofheConfigBase(config: CofheInputConfig): CofheConfig {
+  const result = CofheConfigSchema.safeParse(config);
+
+  if (!result.success) {
+    throw new Error(`Invalid cofhe configuration: ${z.prettifyError(result.error)}`, { cause: result.error });
+  }
+
+  return result.data;
+}
+
+/**
+ * Access the CofheConfig object directly by providing the key.
+ * This is powerful when you use OnchainKit utilities outside of the React context.
+ */
+export const getCofheConfigItem = <K extends keyof CofheConfig>(config: CofheConfig, key: K): CofheConfig[K] => {
+  return config[key];
+};
+
+/**
+ * Gets a supported chain from config by chainId, throws if not found
+ * @param config - The cofhe configuration
+ * @param chainId - The chain ID to look up
+ * @returns The supported chain configuration
+ * @throws {CofheError} If the chain is not found in the config
+ */
+export function getSupportedChainOrThrow(config: CofheConfig, chainId: number): CofheChain {
+  const supportedChain = config.supportedChains.find((chain) => chain.id === chainId);
+
+  if (!supportedChain) {
+    throw new CofheError({
+      code: CofheErrorCode.UnsupportedChain,
+      message: `Config does not support chain <${chainId}>`,
+      hint: 'Ensure config passed to client has been created with this chain in the config.supportedChains array.',
+      context: {
+        chainId,
+        supportedChainIds: config.supportedChains.map((c) => c.id),
+      },
+    });
+  }
+
+  return supportedChain;
+}
+
+/**
+ * Gets the CoFHE URL for a chain, throws if not found
+ * @param config - The cofhe configuration
+ * @param chainId - The chain ID to look up
+ * @returns The CoFHE URL for the chain
+ * @throws {CofheError} If the chain or URL is not found
+ */
+export function getCoFheUrlOrThrow(config: CofheConfig, chainId: number): string {
+  const supportedChain = getSupportedChainOrThrow(config, chainId);
+  const url = supportedChain.coFheUrl;
+
+  if (!url) {
+    throw new CofheError({
+      code: CofheErrorCode.MissingConfig,
+      message: `CoFHE URL is not configured for chain <${chainId}>`,
+      hint: 'Ensure this chain config includes a coFheUrl property.',
+      context: { chainId },
+    });
+  }
+
+  return url;
+}
+
+/**
+ * Gets the ZK verifier URL for a chain, throws if not found
+ * @param config - The cofhe configuration
+ * @param chainId - The chain ID to look up
+ * @returns The ZK verifier URL for the chain
+ * @throws {CofheError} If the chain or URL is not found
+ */
+export function getZkVerifierUrlOrThrow(config: CofheConfig, chainId: number): string {
+  const supportedChain = getSupportedChainOrThrow(config, chainId);
+  const url = supportedChain.verifierUrl;
+
+  if (!url) {
+    throw new CofheError({
+      code: CofheErrorCode.ZkVerifierUrlUninitialized,
+      message: `ZK verifier URL is not configured for chain <${chainId}>`,
+      hint: 'Ensure this chain config includes a verifierUrl property.',
+      context: { chainId },
+    });
+  }
+
+  return url;
+}
+
+/**
+ * Gets the threshold network URL for a chain, throws if not found
+ * @param config - The cofhe configuration
+ * @param chainId - The chain ID to look up
+ * @returns The threshold network URL for the chain
+ * @throws {CofheError} If the chain or URL is not found
+ */
+export function getThresholdNetworkUrlOrThrow(config: CofheConfig, chainId: number): string {
+  const supportedChain = getSupportedChainOrThrow(config, chainId);
+  const url = supportedChain.thresholdNetworkUrl;
+
+  if (!url) {
+    throw new CofheError({
+      code: CofheErrorCode.ThresholdNetworkUrlUninitialized,
+      message: `Threshold network URL is not configured for chain <${chainId}>`,
+      hint: 'Ensure this chain config includes a thresholdNetworkUrl property.',
+      context: { chainId },
+    });
+  }
+
+  return url;
+}

package/core/consts.ts

@@ -0,0 +1,22 @@
+/** 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 Threshold Network contract address (used for testing) */
+export const MOCKS_THRESHOLD_NETWORK_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;
+
+/** Private key for the Mock decrypt result signer account */
+export const MOCKS_DECRYPT_RESULT_SIGNER_PRIVATE_KEY =
+  '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d' as const;

package/core/decrypt/MockThresholdNetworkAbi.ts

@@ -0,0 +1,179 @@
+export const MockThresholdNetworkAbi = [
+  {
+    type: 'function',
+    name: 'acl',
+    inputs: [],
+    outputs: [{ name: '', type: 'address', internalType: 'contract ACL' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'decodeLowLevelReversion',
+    inputs: [{ name: 'data', type: 'bytes', internalType: 'bytes' }],
+    outputs: [{ name: 'error', type: 'string', internalType: 'string' }],
+    stateMutability: 'pure',
+  },
+  {
+    type: 'function',
+    name: 'exists',
+    inputs: [],
+    outputs: [{ name: '', type: 'bool', internalType: 'bool' }],
+    stateMutability: 'pure',
+  },
+  {
+    type: 'function',
+    name: 'initialize',
+    inputs: [
+      { name: '_taskManager', type: 'address', internalType: 'address' },
+      { name: '_acl', type: 'address', internalType: 'address' },
+    ],
+    outputs: [],
+    stateMutability: 'nonpayable',
+  },
+  {
+    type: 'function',
+    name: 'queryDecrypt',
+    inputs: [
+      { name: 'ctHash', type: 'uint256', internalType: 'uint256' },
+      { name: '', type: 'uint256', internalType: 'uint256' },
+      {
+        name: 'permission',
+        type: 'tuple',
+        internalType: 'struct Permission',
+        components: [
+          { name: 'issuer', type: 'address', internalType: 'address' },
+          { name: 'expiration', type: 'uint64', internalType: 'uint64' },
+          { name: 'recipient', type: 'address', internalType: 'address' },
+          { name: 'validatorId', type: 'uint256', internalType: 'uint256' },
+          { name: 'validatorContract', type: 'address', internalType: 'address' },
+          { name: 'sealingKey', type: 'bytes32', internalType: 'bytes32' },
+          { name: 'issuerSignature', type: 'bytes', internalType: 'bytes' },
+          { name: 'recipientSignature', type: 'bytes', internalType: 'bytes' },
+        ],
+      },
+    ],
+    outputs: [
+      { name: 'allowed', type: 'bool', internalType: 'bool' },
+      { name: 'error', type: 'string', internalType: 'string' },
+      { name: '', type: 'uint256', internalType: 'uint256' },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'querySealOutput',
+    inputs: [
+      { name: 'ctHash', type: 'uint256', internalType: 'uint256' },
+      { name: '', type: 'uint256', internalType: 'uint256' },
+      {
+        name: 'permission',
+        type: 'tuple',
+        internalType: 'struct Permission',
+        components: [
+          { name: 'issuer', type: 'address', internalType: 'address' },
+          { name: 'expiration', type: 'uint64', internalType: 'uint64' },
+          { name: 'recipient', type: 'address', internalType: 'address' },
+          { name: 'validatorId', type: 'uint256', internalType: 'uint256' },
+          { name: 'validatorContract', type: 'address', internalType: 'address' },
+          { name: 'sealingKey', type: 'bytes32', internalType: 'bytes32' },
+          { name: 'issuerSignature', type: 'bytes', internalType: 'bytes' },
+          { name: 'recipientSignature', type: 'bytes', internalType: 'bytes' },
+        ],
+      },
+    ],
+    outputs: [
+      { name: 'allowed', type: 'bool', internalType: 'bool' },
+      { name: 'error', type: 'string', internalType: 'string' },
+      { name: '', type: 'bytes32', internalType: 'bytes32' },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'seal',
+    inputs: [
+      { name: 'input', type: 'uint256', internalType: 'uint256' },
+      { name: 'key', type: 'bytes32', internalType: 'bytes32' },
+    ],
+    outputs: [{ name: '', type: 'bytes32', internalType: 'bytes32' }],
+    stateMutability: 'pure',
+  },
+  {
+    type: 'function',
+    name: 'unseal',
+    inputs: [
+      { name: 'hashed', type: 'bytes32', internalType: 'bytes32' },
+      { name: 'key', type: 'bytes32', internalType: 'bytes32' },
+    ],
+    outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+    stateMutability: 'pure',
+  },
+  {
+    type: 'function',
+    name: 'mockAcl',
+    inputs: [],
+    outputs: [{ name: '', type: 'address', internalType: 'contract MockACL' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'mockTaskManager',
+    inputs: [],
+    outputs: [{ name: '', type: 'address', internalType: 'contract MockTaskManager' }],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'mockQueryDecrypt',
+    inputs: [
+      { name: 'ctHash', type: 'uint256', internalType: 'uint256' },
+      { name: '', type: 'uint256', internalType: 'uint256' },
+      { name: 'issuer', type: 'address', internalType: 'address' },
+    ],
+    outputs: [
+      { name: 'allowed', type: 'bool', internalType: 'bool' },
+      { name: 'error', type: 'string', internalType: 'string' },
+      { name: '', type: 'uint256', internalType: 'uint256' },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'decryptForTxWithPermit',
+    inputs: [
+      { name: 'ctHash', type: 'uint256', internalType: 'uint256' },
+      {
+        name: 'permission',
+        type: 'tuple',
+        internalType: 'struct Permission',
+        components: [
+          { name: 'issuer', type: 'address', internalType: 'address' },
+          { name: 'expiration', type: 'uint64', internalType: 'uint64' },
+          { name: 'recipient', type: 'address', internalType: 'address' },
+          { name: 'validatorId', type: 'uint256', internalType: 'uint256' },
+          { name: 'validatorContract', type: 'address', internalType: 'address' },
+          { name: 'sealingKey', type: 'bytes32', internalType: 'bytes32' },
+          { name: 'issuerSignature', type: 'bytes', internalType: 'bytes' },
+          { name: 'recipientSignature', type: 'bytes', internalType: 'bytes' },
+        ],
+      },
+    ],
+    outputs: [
+      { name: 'allowed', type: 'bool', internalType: 'bool' },
+      { name: 'error', type: 'string', internalType: 'string' },
+      { name: 'decryptedValue', type: 'uint256', internalType: 'uint256' },
+    ],
+    stateMutability: 'view',
+  },
+  {
+    type: 'function',
+    name: 'decryptForTxWithoutPermit',
+    inputs: [{ name: 'ctHash', type: 'uint256', internalType: 'uint256' }],
+    outputs: [
+      { name: 'allowed', type: 'bool', internalType: 'bool' },
+      { name: 'error', type: 'string', internalType: 'string' },
+      { name: 'decryptedValue', type: 'uint256', internalType: 'uint256' },
+    ],
+    stateMutability: 'view',
+  },
+] as const;

package/core/decrypt/cofheMocksDecryptForTx.ts

@@ -0,0 +1,84 @@
+import { type Permit, PermitUtils } from '@/permits';
+
+import { encodePacked, keccak256, type PublicClient } from 'viem';
+import { sign } from 'viem/accounts';
+import { MockThresholdNetworkAbi } from './MockThresholdNetworkAbi.js';
+import { FheTypes } from '../types.js';
+import { CofheError, CofheErrorCode } from '../error.js';
+import { MOCKS_DECRYPT_RESULT_SIGNER_PRIVATE_KEY } from '../consts.js';
+import { MOCKS_THRESHOLD_NETWORK_ADDRESS } from '../consts.js';
+
+export type DecryptForTxMocksResult = {
+  ctHash: bigint | string;
+  decryptedValue: bigint;
+  signature: `0x${string}`;
+};
+
+export async function cofheMocksDecryptForTx(
+  ctHash: bigint | string,
+  utype: FheTypes,
+  permit: Permit | null,
+  publicClient: PublicClient
+): Promise<DecryptForTxMocksResult> {
+  let allowed: boolean;
+  let error: string;
+  let decryptedValue: bigint;
+
+  // With permit
+  if (permit !== null) {
+    let permission = PermitUtils.getPermission(permit, true);
+    const permissionWithBigInts = {
+      ...permission,
+      expiration: BigInt(permission.expiration),
+      validatorId: BigInt(permission.validatorId),
+    };
+
+    [allowed, error, decryptedValue] = await publicClient.readContract({
+      address: MOCKS_THRESHOLD_NETWORK_ADDRESS,
+      abi: MockThresholdNetworkAbi,
+      functionName: 'decryptForTxWithPermit',
+      args: [BigInt(ctHash), permissionWithBigInts],
+    });
+  } else {
+    // Without permit (global allowance)
+    [allowed, error, decryptedValue] = await publicClient.readContract({
+      address: MOCKS_THRESHOLD_NETWORK_ADDRESS,
+      abi: MockThresholdNetworkAbi,
+      functionName: 'decryptForTxWithoutPermit',
+      args: [BigInt(ctHash)],
+    });
+  }
+
+  if (error != '') {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: `mocks decryptForTx call failed: ${error}`,
+    });
+  }
+
+  if (allowed == false) {
+    throw new CofheError({
+      code: CofheErrorCode.DecryptFailed,
+      message: `mocks decryptForTx call failed: ACL Access Denied (NotAllowed)`,
+    });
+  }
+
+  // decryptForTx returns plaintext directly (no sealing/unsealing needed)
+  // Generate a mock threshold network signature (in production, this would be the actual signature)
+  // The signature must be valid for MockTaskManager verification.
+  const packed = encodePacked(['uint256', 'uint256'], [BigInt(ctHash), decryptedValue]);
+  const messageHash = keccak256(packed);
+
+  // Raw digest signature (no EIP-191 prefix). Must verify against OpenZeppelin ECDSA.recover(messageHash, signature).
+  const signature = await sign({
+    hash: messageHash,
+    privateKey: MOCKS_DECRYPT_RESULT_SIGNER_PRIVATE_KEY,
+    to: 'hex',
+  });
+
+  return {
+    ctHash,
+    decryptedValue,
+    signature,
+  };
+}

package/core/decrypt/cofheMocksDecryptForView.ts

@@ -0,0 +1,48 @@
+import { type Permit, PermitUtils } from '@/permits';
+
+import { type PublicClient } from 'viem';
+import { MockThresholdNetworkAbi } from './MockThresholdNetworkAbi.js';
+import { FheTypes } from '../types.js';
+import { CofheError, CofheErrorCode } from '../error.js';
+import { MOCKS_THRESHOLD_NETWORK_ADDRESS } from '../consts.js';
+
+export async function cofheMocksDecryptForView(
+  ctHash: bigint | string,
+  utype: FheTypes,
+  permit: Permit,
+  publicClient: PublicClient
+): Promise<bigint> {
+  const permission = PermitUtils.getPermission(permit, true);
+  const permissionWithBigInts = {
+    ...permission,
+    expiration: BigInt(permission.expiration),
+    validatorId: BigInt(permission.validatorId),
+  };
+
+  const [allowed, error, result] = await publicClient.readContract({
+    address: MOCKS_THRESHOLD_NETWORK_ADDRESS,
+    abi: MockThresholdNetworkAbi,
+    functionName: 'querySealOutput',
+    args: [BigInt(ctHash), BigInt(utype), permissionWithBigInts],
+  });
+
+  if (error != '') {
+    throw new CofheError({
+      code: CofheErrorCode.SealOutputFailed,
+      message: `mocks querySealOutput call failed: ${error}`,
+    });
+  }
+
+  if (allowed == false) {
+    throw new CofheError({
+      code: CofheErrorCode.SealOutputFailed,
+      message: `mocks querySealOutput call failed: ACL Access Denied (NotAllowed)`,
+    });
+  }
+
+  const sealedBigInt = BigInt(result);
+  const sealingKeyBigInt = BigInt(permission.sealingKey);
+  const unsealed = sealedBigInt ^ sealingKeyBigInt;
+
+  return unsealed;
+}