@cofhe/sdk 0.0.0-beta-20251027110729

package/core/config.ts

@@ -0,0 +1,213 @@
+import { type CofheChain } from '@/chains';
+
+import { z } from 'zod';
+import { type WalletClient } from 'viem';
+import { CofhesdkError, CofhesdkErrorCode } from './error.js';
+import { type IStorage } from './types.js';
+
+/**
+ * Usable config type inferred from the schema
+ */
+export type CofhesdkConfig = {
+  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
+   * - ON_DECRYPT_HANDLES: Generate a permit when client.decryptHandles() is called
+   * - MANUAL: Generate a permit manually using client.generatePermit()
+   */
+  permitGeneration: 'ON_CONNECT' | 'ON_DECRYPT_HANDLES' | 'MANUAL';
+  /** 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;
+  /** 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)
+     */
+    sealOutputDelay: number;
+  };
+  _internal?: CofhesdkInternalConfig;
+};
+
+export type CofhesdkInternalConfig = {
+  zkvWalletClient?: WalletClient;
+};
+
+/**
+ * Zod schema for configuration validation
+ */
+export const CofhesdkConfigSchema = z.object({
+  /** 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 */
+  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.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())),
+    })
+    .or(z.null())
+    .default(null),
+  /** Mocks configs */
+  mocks: z
+    .object({
+      sealOutputDelay: z.number().optional().default(0),
+    })
+    .optional()
+    .default({ sealOutputDelay: 0 }),
+  /** Internal configuration */
+  _internal: z
+    .object({
+      zkvWalletClient: z.any().optional(),
+    })
+    .optional(),
+});
+
+/**
+ * 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
+ * @returns The validated configuration
+ * @throws {Error} If the configuration is invalid
+ */
+export function createCofhesdkConfigBase(config: CofhesdkInputConfig): CofhesdkConfig {
+  const result = CofhesdkConfigSchema.safeParse(config);
+
+  if (!result.success) {
+    throw new Error(`Invalid cofhesdk configuration: ${result.error.message}`);
+  }
+
+  return result.data;
+}
+
+/**
+ * Access the CofhesdkConfig object directly by providing the key.
+ * This is powerful when you use OnchainKit utilities outside of the React context.
+ */
+export const getCofhesdkConfigItem = <K extends keyof CofhesdkConfig>(
+  config: CofhesdkConfig,
+  key: K
+): CofhesdkConfig[K] => {
+  return config[key];
+};
+
+/**
+ * Gets a supported chain from config by chainId, throws if not found
+ * @param config - The cofhesdk configuration
+ * @param chainId - The chain ID to look up
+ * @returns The supported chain configuration
+ * @throws {CofhesdkError} If the chain is not found in the config
+ */
+export function getSupportedChainOrThrow(config: CofhesdkConfig, chainId: number): CofheChain {
+  const supportedChain = config.supportedChains.find((chain) => chain.id === chainId);
+
+  if (!supportedChain) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.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 cofhesdk configuration
+ * @param chainId - The chain ID to look up
+ * @returns The CoFHE URL for the chain
+ * @throws {CofhesdkError} If the chain or URL is not found
+ */
+export function getCoFheUrlOrThrow(config: CofhesdkConfig, chainId: number): string {
+  const supportedChain = getSupportedChainOrThrow(config, chainId);
+  const url = supportedChain.coFheUrl;
+
+  if (!url) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.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 cofhesdk configuration
+ * @param chainId - The chain ID to look up
+ * @returns The ZK verifier URL for the chain
+ * @throws {CofhesdkError} If the chain or URL is not found
+ */
+export function getZkVerifierUrlOrThrow(config: CofhesdkConfig, chainId: number): string {
+  const supportedChain = getSupportedChainOrThrow(config, chainId);
+  const url = supportedChain.verifierUrl;
+
+  if (!url) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.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 cofhesdk configuration
+ * @param chainId - The chain ID to look up
+ * @returns The threshold network URL for the chain
+ * @throws {CofhesdkError} If the chain or URL is not found
+ */
+export function getThresholdNetworkUrlOrThrow(config: CofhesdkConfig, chainId: number): string {
+  const supportedChain = getSupportedChainOrThrow(config, chainId);
+  const url = supportedChain.thresholdNetworkUrl;
+
+  if (!url) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.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/decrypt/MockQueryDecrypterAbi.ts

@@ -0,0 +1,129 @@
+export const MockQueryDecrypterAbi = [
+  {
+    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: 'taskManager',
+    inputs: [],
+    outputs: [{ name: '', type: 'address', internalType: 'contract TaskManager' }],
+    stateMutability: 'view',
+  },
+  {
+    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: 'error', name: 'NotAllowed', inputs: [] },
+  { type: 'error', name: 'SealingKeyInvalid', inputs: [] },
+  { type: 'error', name: 'SealingKeyMissing', inputs: [] },
+] as const;

package/core/decrypt/cofheMocksSealOutput.ts

@@ -0,0 +1,57 @@
+import { type Permit, PermitUtils } from '@/permits';
+
+import { type PublicClient } from 'viem';
+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';
+
+export async function cofheMocksSealOutput(
+  ctHash: bigint,
+  utype: FheTypes,
+  permit: Permit,
+  publicClient: PublicClient,
+  mocksSealOutputDelay: number
+): Promise<bigint> {
+  // Configurable delay before decrypting the output to simulate the CoFHE decrypt processing time
+  // Recommended 1000ms on web
+  // Recommended 0ms on hardhat (will be called during tests no need for fake delay)
+  if (mocksSealOutputDelay > 0) await sleep(mocksSealOutputDelay);
+
+  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: MockQueryDecrypterAddress,
+    abi: MockQueryDecrypterAbi,
+    functionName: 'querySealOutput',
+    args: [ctHash, BigInt(utype), permissionWithBigInts],
+  });
+
+  if (error != '') {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.SealOutputFailed,
+      message: `mocks querySealOutput call failed: ${error}`,
+    });
+  }
+
+  if (allowed == false) {
+    throw new CofhesdkError({
+      code: CofhesdkErrorCode.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;
+}

package/core/decrypt/decryptHandleBuilder.ts

@@ -0,0 +1,281 @@
+import { hardhat } from '@/chains';
+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';
+
+/**
+ * API
+ *
+ * await client.decryptHandle(ctHash, utype)
+ *   .setChainId(chainId)
+ *   .setAccount(account)
+ *   .setPermitHash(permitHash)
+ *   .setPermit(permit)
+ *   .decrypt()
+ *
+ * If chainId not set, uses client's chainId
+ * If account not set, uses client's account
+ * 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>>
+ */
+
+type DecryptHandlesBuilderParams<U extends FheTypes> = BaseBuilderParams & {
+  ctHash: bigint;
+  utype: U;
+  permitHash?: string;
+  permit?: Permit;
+};
+
+export class DecryptHandlesBuilder<U extends FheTypes> extends BaseBuilder {
+  private ctHash: bigint;
+  private utype: U;
+  private permitHash?: string;
+  private permit?: Permit;
+
+  constructor(params: DecryptHandlesBuilderParams<U>) {
+    super({
+      config: params.config,
+      publicClient: params.publicClient,
+      walletClient: params.walletClient,
+      chainId: params.chainId,
+      account: params.account,
+      requireConnected: params.requireConnected,
+    });
+
+    this.ctHash = params.ctHash;
+    this.utype = params.utype;
+    this.permitHash = params.permitHash;
+    this.permit = params.permit;
+  }
+
+  /**
+   * @param chainId - Chain to decrypt values from. Used to fetch the threshold network URL and use the correct permit.
+   *
+   * If not provided, the chainId will be fetched from the connected publicClient.
+   *
+   * Example:
+   * ```typescript
+   * const unsealed = await decryptHandle(ctHash, utype)
+   *   .setChainId(11155111)
+   *   .decrypt();
+   * ```
+   *
+   * @returns The chainable DecryptHandlesBuilder instance.
+   */
+  setChainId(chainId: number): DecryptHandlesBuilder<U> {
+    this.chainId = chainId;
+    return this;
+  }
+
+  getChainId(): number | undefined {
+    return this.chainId;
+  }
+
+  /**
+   * @param account - Account to decrypt values from. Used to fetch the correct permit.
+   *
+   * If not provided, the account will be fetched from the connected walletClient.
+   *
+   * Example:
+   * ```typescript
+   * const unsealed = await decryptHandle(ctHash, utype)
+   *   .setAccount('0x1234567890123456789012345678901234567890')
+   *   .decrypt();
+   * ```
+   *
+   * @returns The chainable DecryptHandlesBuilder instance.
+   */
+  setAccount(account: string): DecryptHandlesBuilder<U> {
+    this.account = account;
+    return this;
+  }
+
+  getAccount(): string | undefined {
+    return this.account;
+  }
+
+  /**
+   * @param permitHash - Permit hash to decrypt values from. Used to fetch the correct permit.
+   *
+   * If not provided, the active permit for the chainId and account will be used.
+   * If `setPermit()` is called, it will be used regardless of chainId, account, or permitHash.
+   *
+   * Example:
+   * ```typescript
+   * const unsealed = await decryptHandle(ctHash, utype)
+   *   .setPermitHash('0x1234567890123456789012345678901234567890')
+   *   .decrypt();
+   * ```
+   *
+   * @returns The chainable DecryptHandlesBuilder instance.
+   */
+  setPermitHash(permitHash: string): DecryptHandlesBuilder<U> {
+    this.permitHash = permitHash;
+    return this;
+  }
+
+  getPermitHash(): string | undefined {
+    return this.permitHash;
+  }
+
+  /**
+   * @param permit - Permit to decrypt values with. If provided, it will be used regardless of chainId, account, or permitHash.
+   *
+   * If not provided, the permit will be determined by chainId, account, and permitHash.
+   *
+   * Example:
+   * ```typescript
+   * const unsealed = await decryptHandle(ctHash, utype)
+   *   .setPermit(permit)
+   *   .decrypt();
+   * ```
+   *
+   * @returns The chainable DecryptHandlesBuilder instance.
+   */
+  setPermit(permit: Permit): DecryptHandlesBuilder<U> {
+    this.permit = permit;
+    return this;
+  }
+
+  getPermit(): Permit | undefined {
+    return this.permit;
+  }
+
+  private getThresholdNetworkUrl(chainId: number): string {
+    const config = this.getConfigOrThrow();
+    return getThresholdNetworkUrlOrThrow(config, chainId);
+  }
+
+  private validateUtypeOrThrow(): void {
+    if (!isValidUtype(this.utype))
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.InvalidUtype,
+        message: `Invalid utype to decrypt to`,
+        context: {
+          utype: this.utype,
+        },
+      });
+  }
+
+  private async getResolvedPermit(): Promise<Permit> {
+    if (this.permit) return this.permit;
+
+    const chainId = await this.getChainIdOrThrow();
+    const account = await this.getAccountOrThrow();
+
+    // Fetch with permit hash
+    if (this.permitHash) {
+      const permit = await permits.getPermit(chainId, 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}>`,
+          hint: 'Ensure the permit exists and is valid.',
+          context: {
+            chainId,
+            account,
+            permitHash: this.permitHash,
+          },
+        });
+      }
+      return permit;
+    }
+
+    // Fetch with active permit
+    const permit = await permits.getActivePermit(chainId, account);
+    if (!permit) {
+      throw new CofhesdkError({
+        code: CofhesdkErrorCode.PermitNotFound,
+        message: `Active permit not found for chainId <${chainId}> and account <${account}>`,
+        hint: 'Ensure a permit exists for this account on this chain.',
+        context: {
+          chainId,
+          account,
+        },
+      });
+    }
+    return permit;
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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);
+    const permission = PermitUtils.getPermission(permit, true);
+    const sealed = await tnSealOutput(this.ctHash, chainId, permission, thresholdNetworkUrl);
+    return PermitUtils.unseal(permit, sealed);
+  }
+
+  /**
+   * Final step of the decryption process. MUST BE CALLED LAST IN THE CHAIN.
+   *
+   * This will:
+   * - Use a permit based on provided permit OR chainId + account + permitHash
+   * - Check permit validity
+   * - Call CoFHE `/sealoutput` with the permit, which returns a sealed (encrypted) item
+   * - Unseal the sealed item with the permit
+   * - Return the unsealed item
+   *
+   * Example:
+   * ```typescript
+   * const unsealed = await decryptHandle(ctHash, utype)
+   *   .setChainId(11155111)      // optional
+   *   .setAccount('0x123...890') // optional
+   *   .decrypt();                // execute
+   * ```
+   *
+   * @returns The unsealed item.
+   */
+  decrypt(): Promise<Result<UnsealedItem<U>>> {
+    return resultWrapper(async () => {
+      // Ensure cofhe client is connected
+      await this.requireConnectedOrThrow();
+
+      // Ensure utype is valid
+      this.validateUtypeOrThrow();
+
+      // Resolve permit
+      const permit = await this.getResolvedPermit();
+
+      // Ensure permit validity
+      await PermitUtils.validate(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;
+
+      // Check permit validity on-chain
+      // TODO: PermitUtils.validateOnChain(permit, this.publicClient);
+
+      let unsealed: bigint;
+
+      if (chainId === hardhat.id) {
+        unsealed = await this.mocksSealOutput(permit);
+      } else {
+        unsealed = await this.productionSealOutput(chainId, permit);
+      }
+
+      return convertViaUtype(this.utype, unsealed);
+    });
+  }
+}