@fhevm/sdk 0.0.1 → 1.0.0-alpha.1

package/core/modules/encrypt/module/init-p.ts

@@ -0,0 +1,249 @@
+import type { FhevmRuntime, FhevmRuntimeConfig } from '../../../types/coreFhevmRuntime.js';
+import init_tfhe_lib from '../../../../wasm/tfhe/tfhe.v1.5.3.js';
+import { init_panic_hook, initThreadPool, setWorkerUrlConfig, getWasmInfo } from '../../../../wasm/tfhe/tfhe.v1.5.3.js';
+import { isomorphicCompileWasm, isomorphicCompileWasmFromBase64 } from '../../../base/wasm.js';
+import { isBlobWorkerSupported, isBrowserLike } from '../../../base/isomorphicWorker.js';
+import { threads } from 'wasm-feature-detect';
+import { assertIsFhevmRuntime } from '../../../runtime/CoreFhevmRuntime-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+// IMPORTANT: The import path MUST be a string literal, not a variable.
+// Bundlers (Webpack, Vite, Rollup) statically analyze import() calls to
+// create separate chunks for code-splitting. A variable path like
+// `import(someVar)` makes the target unresolvable — the bundler either
+// includes every possible file or fails entirely.
+// With a literal path, the bundler creates a lazy-loaded chunk for this
+// ~6.5MB base64 file, only downloaded when this function is called.
+function dynamicImportWasmBase64(): Promise<{
+  readonly tfheWasmBase64: string;
+}> {
+  // Bundler Alert: !! KEEP THE PATH AS-IS !!
+  return import('../../../../wasm/tfhe/tfhe_bg.v1.5.3.wasm.base64.js');
+}
+
+const TFHE_WORKER_JS_FILENAME = 'tfhe-worker.v1.5.3.mjs';
+const TFHE_BG_WASM_FILENAME = 'tfhe_bg.v1.5.3.wasm';
+
+////////////////////////////////////////////////////////////////////////////////
+
+// Pure JS file (not compiled by tsc) — provides cross-platform base URL
+// for resolving WASM paths. Uses import.meta.url in ESM, __filename in CJS.
+import { wasmBaseUrl } from '../../../../wasm/wasmBaseUrl.js';
+import type { GetTfheModuleInfoReturnType, TfheModuleInfo } from '../types.js';
+
+// (Node only) Path relative to src/wasm/ where wasmBaseUrl is anchored
+const nodeDefaultLocateFile = (file: string): URL => {
+  return new URL(`./tfhe/${file}`, wasmBaseUrl);
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+type TfheInitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+type InitTfheModuleParameters = {
+  readonly module_or_path: TfheInitInput | Promise<TfheInitInput>;
+  readonly memory?: WebAssembly.Memory;
+  readonly thread_stack_size?: number;
+  readonly num_threads?: number;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// ResolvedTfheModuleConfig
+////////////////////////////////////////////////////////////////////////////////
+
+type ResolvedTfheModuleConfig = {
+  readonly workerUrl: URL | undefined;
+  readonly wasmUrl: URL | undefined;
+  /* if `true`, then `numberOfThreads` is 0, if `false` then `numberOfThreads` > 0 */
+  readonly singleThread: boolean;
+  readonly numberOfThreads: number;
+  readonly logger: FhevmRuntimeConfig['logger'];
+  readonly supportsThreads: boolean | undefined;
+};
+
+let resolvedTfheModuleConfig: ResolvedTfheModuleConfig | undefined = undefined;
+
+/**
+ * @internal
+ * Returns the existing resolved config, or resolves it from the runtime config.
+ */
+async function _getOrResolveTfheModuleConfig(runtime: FhevmRuntime): Promise<ResolvedTfheModuleConfig> {
+  if (resolvedTfheModuleConfig !== undefined) return resolvedTfheModuleConfig;
+
+  resolvedTfheModuleConfig = await _resolveTfheModuleConfig(runtime.config);
+  return resolvedTfheModuleConfig;
+}
+
+/**
+ * @internal
+ * Resolves user-provided {@link FhevmRuntimeConfig} into a fully resolved config
+ * (thread count, worker URL, WASM URL). Must be called before WASM initialization.
+ */
+async function _resolveTfheModuleConfig(parameters: FhevmRuntimeConfig): Promise<ResolvedTfheModuleConfig> {
+  if (cachedTfheModulePromise !== undefined) {
+    throw new Error('Cannot configure module after initialization has started');
+  }
+
+  const { locateFile, singleThread: singleThreadConfig, numberOfThreads: numberOfThreadsConfig } = parameters;
+
+  let singleThread = false;
+  if (singleThreadConfig !== undefined) {
+    singleThread = singleThreadConfig;
+  }
+
+  const canUseBlob = await isBlobWorkerSupported();
+
+  let wasmUrl: URL | undefined;
+  let workerUrl: URL | undefined;
+
+  if (locateFile !== undefined) {
+    workerUrl = locateFile(TFHE_WORKER_JS_FILENAME);
+    wasmUrl = locateFile(TFHE_BG_WASM_FILENAME);
+  } else {
+    /*
+      if run in Node only, use defaultLocateFile!
+    */
+    if (!isBrowserLike()) {
+      workerUrl = nodeDefaultLocateFile(TFHE_WORKER_JS_FILENAME);
+      wasmUrl = nodeDefaultLocateFile(TFHE_BG_WASM_FILENAME);
+    } else {
+      if (!canUseBlob) {
+        throw new Error('Missing locate file function');
+      }
+    }
+  }
+
+  let numberOfThreads: number | undefined;
+  let supportsThreads: boolean | undefined;
+
+  if (!singleThread) {
+    numberOfThreads = numberOfThreadsConfig ?? navigator.hardwareConcurrency; // Node 21+
+
+    if (numberOfThreads > 0) {
+      // SharedArrayBuffer requires COOP/COEP headers in browsers.
+      // Fall back to single-threaded mode when unavailable.
+      supportsThreads = await threads();
+      if (!supportsThreads) {
+        console.warn(
+          'This browser does not support threads. Verify that your server returns correct headers:\n',
+          "'Cross-Origin-Opener-Policy': 'same-origin'\n",
+          "'Cross-Origin-Embedder-Policy': 'require-corp'",
+        );
+        singleThread = true;
+        numberOfThreads = 0;
+      }
+    } else {
+      singleThread = true;
+      numberOfThreads = 0;
+    }
+  } else {
+    numberOfThreads = 0;
+  }
+
+  setWorkerUrlConfig({
+    workerUrl,
+    logger: parameters.logger,
+  });
+
+  const cfg = {
+    numberOfThreads,
+    workerUrl,
+    wasmUrl,
+    singleThread,
+    logger: parameters.logger,
+    supportsThreads,
+  };
+
+  parameters.logger?.debug(JSON.stringify(cfg, null, 2));
+
+  return cfg;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// initTfheModule
+////////////////////////////////////////////////////////////////////////////////
+
+let cachedTfheModulePromise: Promise<void> | undefined;
+let ownerUid: string | undefined = undefined;
+
+/**
+ * Initializes the TFHE module.
+ */
+export async function initTfheModule(runtime: FhevmRuntime): Promise<void> {
+  assertIsFhevmRuntime(runtime, {});
+
+  if (ownerUid !== undefined && runtime.uid !== ownerUid) {
+    throw new Error(
+      `Encrypt WASM module is already owned by runtime '${ownerUid}' and cannot be shared with runtime '${runtime.uid}'`,
+    );
+  }
+
+  ownerUid = runtime.uid;
+
+  if (cachedTfheModulePromise !== undefined) {
+    return cachedTfheModulePromise;
+  }
+
+  // Use existing config if already set, otherwise resolve from runtime
+  const cfg = await _getOrResolveTfheModuleConfig(runtime);
+
+  cachedTfheModulePromise = _initTfheModule(cfg);
+
+  // This is purely theoretical. Retry is not yet possible since the `_initTfheModule`
+  // does not support retry (see tfhe lib internal global variables).
+  cachedTfheModulePromise.catch(() => {
+    // Clear cache on failure so retry is possible
+    cachedTfheModulePromise = undefined;
+  });
+
+  return cachedTfheModulePromise;
+}
+
+let moduleInfo: TfheModuleInfo | undefined = undefined;
+
+async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<void> {
+  // Compile WASM module (see matrix in types.ts)
+  let wasmModule;
+  if (cfg.wasmUrl !== undefined) {
+    cfg.logger?.debug(`compile wasm at: ${cfg.wasmUrl}`);
+    wasmModule = await isomorphicCompileWasm(cfg.wasmUrl);
+  } else {
+    cfg.logger?.debug(`compile wasm from embedded base64`);
+    const { tfheWasmBase64 } = await dynamicImportWasmBase64();
+    wasmModule = await isomorphicCompileWasmFromBase64(tfheWasmBase64);
+  }
+
+  const input: InitTfheModuleParameters = { module_or_path: wasmModule };
+
+  // 2. Load and instantiate the TFHE WASM binary
+  await init_tfhe_lib(input);
+
+  // 3. Route WASM panics to console.error instead of silently aborting
+  init_panic_hook();
+
+  // 4. Spawn Web Workers for parallel FHE operations (skipped when single-threaded)
+  if (!cfg.singleThread) {
+    cfg.logger?.debug(`initThreadPool(${cfg.numberOfThreads})`);
+    await initThreadPool(cfg.numberOfThreads);
+  }
+
+  const wasmInfo = getWasmInfo();
+
+  moduleInfo = Object.freeze({
+    wasmUrl: cfg.wasmUrl ? new URL(cfg.wasmUrl) : undefined,
+    version: wasmInfo.version,
+    name: wasmInfo.name,
+    workerUrl: cfg.workerUrl ? new URL(cfg.workerUrl) : undefined,
+    numberOfThreads: cfg.singleThread ? 0 : cfg.numberOfThreads,
+    threadsAvailable: cfg.supportsThreads,
+  });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// getTfheModuleInfo
+////////////////////////////////////////////////////////////////////////////////
+
+export function getTfheModuleInfo(): GetTfheModuleInfoReturnType {
+  return moduleInfo;
+}

package/core/modules/encrypt/types.ts

@@ -0,0 +1,225 @@
+import type { TypedValue } from '../../types/primitives.js';
+import type { EncryptionBits, FheTypeId } from '../../types/fheType.js';
+import type {
+  FheEncryptionCrs,
+  FheEncryptionCrsBytes,
+  FheEncryptionKeyWasm,
+  FheEncryptionKeyBytes,
+  FheEncryptionPublicKey,
+  FheEncryptionPublicKeyBytes,
+} from '../../types/fheEncryptionKey.js';
+import type { Prettify } from '../../types/utils.js';
+import type { FhevmRuntime } from '../../types/coreFhevmRuntime.js';
+
+////////////////////////////////////////////////////////////////////////////////
+//
+// EncryptModule
+//
+////////////////////////////////////////////////////////////////////////////////
+
+/*
+
+WASM compilation (how to get WebAssembly.Module):
+
+| wasmUrl   | Result                                                         |
+|-----------|----------------------------------------------------------------|
+| defined   | Compile from URL (isomorphicCompileWasm)                       |
+| undefined | Compile from embedded base64 (isomorphicCompileWasmFromBase64) |
+
+Worker creation (how to spawn thread pool workers):
+
+| workerUrl | Result                                    |
+|-----------|-------------------------------------------|
+| defined   | Direct URL → fetch+blob → embedded base64 |
+| undefined | Embedded base64 worker                    |
+
+*/
+
+////////////////////////////////////////////////////////////////////////////////
+// initTfheModuleFunction
+////////////////////////////////////////////////////////////////////////////////
+
+export type InitTfheModuleFunction = {
+  initTfheModule(): Promise<void>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// getTfheModuleInfoFunction
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Information about the running TFHE module configuration.
+ */
+export type TfheModuleInfo = {
+  /**
+   * Number of WASM worker threads.
+   * `0` means single-threaded mode.
+   */
+  readonly numberOfThreads: number;
+  /**
+   * URL used to fetch the TFHE WASM binary.
+   * `undefined` means the base64-embedded fallback is used.
+   */
+  readonly wasmUrl: URL | undefined;
+  /**
+   * URL used to load the TFHE worker script.
+   * `undefined` means the base64-embedded fallback is used.
+   */
+  readonly workerUrl: URL | undefined;
+  /**
+   * Whether the environment supports multi-threading.
+   * - `undefined` — user explicitly requested single-threaded mode.
+   * - `true` — multi-threading is supported and active.
+   * - `false` — multi-threading was requested but unavailable; fell back to single-threaded.
+   */
+  readonly threadsAvailable: boolean | undefined;
+};
+
+export type GetTfheModuleInfoReturnType = TfheModuleInfo | undefined;
+
+export type GetTfheModuleInfoFunction = {
+  /**
+   * Returns {@link TfheModuleInfo} when the module is initialized,
+   * or `undefined` if the module has not completed initialization.
+   */
+  getTfheModuleInfo(): GetTfheModuleInfoReturnType;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// 1. parseTFHEProvenCompactCiphertextList
+////////////////////////////////////////////////////////////////////////////////
+
+export type ParseTFHEProvenCompactCiphertextListParameters = {
+  readonly ciphertextWithZkProof: Uint8Array | string;
+};
+
+export type ParseTFHEProvenCompactCiphertextListReturnType = {
+  fheTypeIds: FheTypeId[];
+  encryptionBits: EncryptionBits[];
+};
+
+export type ParseTFHEProvenCompactCiphertextListModuleFunction = {
+  parseTFHEProvenCompactCiphertextList(
+    parameters: ParseTFHEProvenCompactCiphertextListParameters,
+  ): Promise<ParseTFHEProvenCompactCiphertextListReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// 2. buildWithProofPacked
+////////////////////////////////////////////////////////////////////////////////
+
+export type BuildWithProofPackedReturnTypeParameters = {
+  readonly fheEncryptionKey: FheEncryptionKeyWasm;
+  readonly typedValues: TypedValue[];
+  readonly metaData: Uint8Array;
+};
+
+export type BuildWithProofPackedReturnType = Uint8Array;
+
+export type BuildWithProofPackedModuleFunction = {
+  buildWithProofPacked(parameters: BuildWithProofPackedReturnTypeParameters): Promise<BuildWithProofPackedReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// 3. serializeFheEncryptionKey
+////////////////////////////////////////////////////////////////////////////////
+
+export type SerializeFheEncryptionKeyParameters = {
+  readonly fheEncryptionKey: FheEncryptionKeyWasm;
+};
+
+export type SerializeFheEncryptionKeyReturnType = FheEncryptionKeyBytes;
+
+export type SerializeFheEncryptionKeyModuleFunction = {
+  serializeFheEncryptionKey(
+    parameters: SerializeFheEncryptionKeyParameters,
+  ): Promise<SerializeFheEncryptionKeyReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// 4. serializeFheEncryptionPublicKey
+////////////////////////////////////////////////////////////////////////////////
+
+export type SerializeFheEncryptionPublicKeyParameters = {
+  readonly publicKey: FheEncryptionPublicKey;
+};
+
+export type SerializeFheEncryptionPublicKeyReturnType = FheEncryptionPublicKeyBytes;
+
+export type SerializeFheEncryptionPublicKeyModuleFunction = {
+  serializeFheEncryptionPublicKey(
+    parameters: SerializeFheEncryptionPublicKeyParameters,
+  ): Promise<SerializeFheEncryptionPublicKeyReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// 5. serializeFheEncryptionCrs
+////////////////////////////////////////////////////////////////////////////////
+
+export type SerializeFheEncryptionCrsParameters = {
+  readonly crs: FheEncryptionCrs;
+};
+
+export type SerializeFheEncryptionCrsReturnType = FheEncryptionCrsBytes;
+
+export type SerializeFheEncryptionCrsModuleFunction = {
+  serializeFheEncryptionCrs(
+    parameters: SerializeFheEncryptionCrsParameters,
+  ): Promise<SerializeFheEncryptionCrsReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// 6. deserializeFheEncryptionPublicKey
+////////////////////////////////////////////////////////////////////////////////
+
+export type DeserializeFheEncryptionPublicKeyParameters = {
+  readonly publicKeyBytes: FheEncryptionPublicKeyBytes;
+};
+
+export type DeserializeFheEncryptionPublicKeyReturnType = FheEncryptionPublicKey;
+
+export type DeserializeFheEncryptionPublicKeyModuleFunction = {
+  deserializeFheEncryptionPublicKey(
+    parameters: DeserializeFheEncryptionPublicKeyParameters,
+  ): Promise<DeserializeFheEncryptionPublicKeyReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// 6. deserializeFheEncryptionCrs
+////////////////////////////////////////////////////////////////////////////////
+
+export type DeserializeFheEncryptionCrsParameters = {
+  readonly crsBytes: FheEncryptionCrsBytes;
+};
+
+export type DeserializeFheEncryptionCrsReturnType = FheEncryptionCrs;
+
+export type DeserializeFheEncryptionCrsModuleFunction = {
+  deserializeFheEncryptionCrs(
+    parameters: DeserializeFheEncryptionCrsParameters,
+  ): Promise<DeserializeFheEncryptionCrsReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// EncryptModule
+////////////////////////////////////////////////////////////////////////////////
+
+export type WithEncryptModule = {
+  readonly encrypt: EncryptModule;
+};
+
+export type EncryptModule = Prettify<
+  InitTfheModuleFunction &
+    GetTfheModuleInfoFunction &
+    ParseTFHEProvenCompactCiphertextListModuleFunction &
+    BuildWithProofPackedModuleFunction &
+    SerializeFheEncryptionKeyModuleFunction &
+    SerializeFheEncryptionPublicKeyModuleFunction &
+    SerializeFheEncryptionCrsModuleFunction &
+    DeserializeFheEncryptionPublicKeyModuleFunction &
+    DeserializeFheEncryptionCrsModuleFunction
+>;
+
+export type EncryptModuleFactory = (runtime: FhevmRuntime) => {
+  readonly encrypt: EncryptModule;
+};

package/core/modules/ethereum/createTrustedClient.ts

@@ -0,0 +1,9 @@
+import type { TrustedClient, trustedClientBrand } from './types.js';
+import { createTrustedValue, type TrustedValue } from '../../base/trustedValue.js';
+
+export function createTrustedClient<native>(nativeClient: native, token: symbol): TrustedClient<native> {
+  const tc: TrustedValue<native> = createTrustedValue(nativeClient, token);
+  return tc as typeof tc & {
+    [trustedClientBrand]: never;
+  };
+}

package/core/modules/ethereum/types.ts

@@ -0,0 +1,153 @@
+import type { TrustedValue } from '../../base/trustedValue.js';
+import type { Bytes65Hex, BytesHex, ChecksummedAddress, Uint256 } from '../../types/primitives.js';
+import type { Prettify } from '../../types/utils.js';
+
+////////////////////////////////////////////////////////////////////////////////
+//
+// Ethereum Module
+//
+////////////////////////////////////////////////////////////////////////////////
+
+export declare const trustedClientBrand: unique symbol;
+
+export type TrustedClient<T = unknown> = TrustedValue<T> & {
+  [trustedClientBrand]: never;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// recoverTypedDataAddress
+////////////////////////////////////////////////////////////////////////////////
+
+export type RecoverTypedDataAddressParameters = Readonly<{
+  domain: {
+    chainId: Uint256;
+    name: string;
+    verifyingContract: ChecksummedAddress;
+    version: string;
+  };
+  types: Record<string, Array<{ name: string; type: string }>>;
+  primaryType: string;
+  message: Record<string, unknown>;
+  signature: Bytes65Hex;
+}>;
+
+export type RecoverTypedDataAddressReturnType = ChecksummedAddress;
+
+export type RecoverTypedDataAddressModuleFunction = {
+  recoverTypedDataAddress(parameters: RecoverTypedDataAddressParameters): Promise<RecoverTypedDataAddressReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// signTypedData
+////////////////////////////////////////////////////////////////////////////////
+
+export type SignTypedDataParameters = {
+  readonly account: ChecksummedAddress;
+  readonly domain: {
+    readonly chainId: Uint256;
+    readonly name: string;
+    readonly verifyingContract: ChecksummedAddress;
+    readonly version: string;
+  };
+  readonly types: Readonly<Record<string, ReadonlyArray<{ name: string; type: string }>>>;
+  readonly primaryType: string;
+  readonly message: Readonly<Record<string, unknown>>;
+};
+
+export type SignTypedDataReturnType = Bytes65Hex;
+export type NativeSigner = unknown;
+
+export type SignTypedDataModuleFunction = {
+  signTypedData(signer: NativeSigner, parameters: SignTypedDataParameters): Promise<SignTypedDataReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// encodePacked
+////////////////////////////////////////////////////////////////////////////////
+
+export type EncodePackedParameters = Readonly<{
+  types: readonly string[];
+  values: readonly unknown[];
+}>;
+
+export type EncodePackedReturnType = BytesHex;
+
+export type EncodePackedModuleFunction = {
+  encodePacked(parameters: EncodePackedParameters): EncodePackedReturnType;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// encode
+////////////////////////////////////////////////////////////////////////////////
+
+export type EncodeParameters = Readonly<{
+  types: readonly string[];
+  values: readonly unknown[];
+}>;
+
+export type EncodeReturnType = BytesHex;
+
+export type EncodeModuleFunction = {
+  encode(parameters: EncodeParameters): EncodeReturnType;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// decode
+////////////////////////////////////////////////////////////////////////////////
+
+export type DecodeParameters = Readonly<{
+  types: readonly string[];
+  encodedData: BytesHex;
+}>;
+
+export type DecodeReturnType = unknown[];
+
+export type DecodeModuleFunction = {
+  decode(parameters: DecodeParameters): DecodeReturnType;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// getChainId
+////////////////////////////////////////////////////////////////////////////////
+
+export type GetChainIdReturnType = bigint;
+
+export type GetChainIdModuleFunction = {
+  getChainId(hostPublicClient: TrustedClient): Promise<GetChainIdReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// readContract
+////////////////////////////////////////////////////////////////////////////////
+
+export type ReadContractParameters = {
+  readonly address: ChecksummedAddress;
+  readonly functionName: string;
+  readonly abi: ReadonlyArray<Record<string, unknown>>;
+  readonly args: readonly unknown[];
+};
+
+export type ReadContractReturnType = unknown;
+
+export type ReadContractModuleFunction = {
+  readContract(hostPublicClient: TrustedClient, parameters: ReadContractParameters): Promise<ReadContractReturnType>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+// EthereumModule
+////////////////////////////////////////////////////////////////////////////////
+
+export type EthereumModule = Prettify<
+  RecoverTypedDataAddressModuleFunction &
+    SignTypedDataModuleFunction &
+    ReadContractModuleFunction &
+    EncodeModuleFunction &
+    EncodePackedModuleFunction &
+    DecodeModuleFunction &
+    GetChainIdModuleFunction
+>;
+
+// No runtime as argument. The EthereumModule is passed as argument of the runtime constructor
+export type EthereumModuleFactory = () => {
+  readonly ethereum: EthereumModule;
+};