@fhevm/sdk 1.1.0-alpha.4 → 1.1.0-alpha.6

package/core/actions/encrypt/encryptValue.ts

@@ -8,6 +8,7 @@ import { addressToChecksummedAddress, assertIsAddress } from '../../base/address
 import { toArray } from '../../base/object.js';
 import { createTypedValue } from '../../base/typedValue.js';
 import { encrypt as encrypt_ } from '../../coprocessor/encrypt.js';
+import { asFhevmWithTfheVersion } from '../../runtime/CoreFhevm-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -37,7 +38,9 @@ export async function encryptValue(
   assertIsAddress(contractAddress, {});
   assertIsAddress(userAddress, {});
 
-  const result = await encrypt_(fhevm, {
+  const f = asFhevmWithTfheVersion(fhevm);
+
+  const result = await encrypt_(f, {
     contractAddress: addressToChecksummedAddress(contractAddress),
     userAddress: addressToChecksummedAddress(userAddress),
     values,

package/core/actions/encrypt/encryptValues.ts

@@ -7,6 +7,7 @@ import type { EncryptedValue } from '../../types/encryptedTypes.js';
 import { addressToChecksummedAddress, assertIsAddress } from '../../base/address.js';
 import { createTypedValue } from '../../base/typedValue.js';
 import { encrypt as encrypt_ } from '../../coprocessor/encrypt.js';
+import { asFhevmWithTfheVersion } from '../../runtime/CoreFhevm-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -35,7 +36,9 @@ export async function encryptValues(
   assertIsAddress(contractAddress, {});
   assertIsAddress(userAddress, {});
 
-  const result = await encrypt_(fhevm, {
+  const f = asFhevmWithTfheVersion(fhevm);
+
+  const result = await encrypt_(f, {
     contractAddress: addressToChecksummedAddress(contractAddress),
     userAddress: addressToChecksummedAddress(userAddress),
     values,

package/core/actions/encrypt/generateZkProof.ts

@@ -2,8 +2,10 @@ import type { Fhevm } from '../../types/coreFhevmClient.js';
 import type { WithEncrypt } from '../../types/coreFhevmRuntime.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
 import type { ZkProof } from '../../types/zkProof-p.js';
+import type { BytesHex } from '../../types/primitives.js';
 import { createTypedValue } from '../../base/typedValue.js';
 import { createZkProofBuilder } from '../../coprocessor/ZkProofBuilder-p.js';
+import { asFhevmWithTfheVersion } from '../../runtime/CoreFhevm-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -22,12 +24,18 @@ export async function generateZkProof(
   parameters: GenerateZkProofParameters,
 ): Promise<GenerateZkProofReturnType> {
   const { values, contractAddress, userAddress } = parameters;
+  const hardCodedExtraData = '0x00' as BytesHex;
+
   const builder = createZkProofBuilder();
   for (const value of values) {
     builder.addTypedValue(createTypedValue(value));
   }
-  return builder.build(fhevm, {
+
+  const f = asFhevmWithTfheVersion(fhevm);
+
+  return builder.build(f, {
     contractAddress,
     userAddress,
+    extraData: hardCodedExtraData,
   });
 }

package/core/actions/host/readFhevmExecutorContractData.ts

@@ -10,7 +10,7 @@ import { getAclAddress } from '../../host-contracts/getAclAddress-p.js';
 import { getHandleVersion } from '../../host-contracts/getHandleVersion-p.js';
 import { getHcuLimitAddress } from '../../host-contracts/getHcuLimitAddress-p.js';
 import { assertIsHostContractVersionOf } from '../../host-contracts/HostContractVersion-p.js';
-import { getVersion } from '../../host-contracts/HostContractVersion-p.js';
+import { getHostContractVersion } from '../../host-contracts/HostContractVersion-p.js';
 import { getInputVerifierAddress } from '../../host-contracts/getInputVerifierAddress-p.js';
 
 export type ReadFhevmExecutorContractDataParameters = {
@@ -22,7 +22,7 @@ export async function readFhevmExecutorContractData(
   fhevm: Fhevm,
   parameters: ReadFhevmExecutorContractDataParameters,
 ): Promise<ReadFhevmExecutorContractDataReturnType> {
-  const fhevmExecutorContractAddress = parameters.address;
+  const fhevmExecutorAddress = parameters.address;
 
   ////////////////////////////////////////////////////////////////////////////
   //
@@ -36,11 +36,11 @@ export async function readFhevmExecutorContractData(
   ////////////////////////////////////////////////////////////////////////////
 
   const rpcCalls = [
-    () => getVersion(fhevm, parameters),
-    () => getAclAddress(fhevm, parameters),
-    () => getHcuLimitAddress(fhevm, parameters),
-    () => getInputVerifierAddress(fhevm, parameters),
-    () => getHandleVersion(fhevm, parameters),
+    () => getHostContractVersion(fhevm, parameters),
+    () => getAclAddress(fhevm, { fhevmExecutorAddress }),
+    () => getHcuLimitAddress(fhevm, { fhevmExecutorAddress }),
+    () => getInputVerifierAddress(fhevm, { fhevmExecutorAddress }),
+    () => getHandleVersion(fhevm, { fhevmExecutorAddress }),
   ];
 
   const res = await executeWithBatching<unknown>(rpcCalls, fhevm.options.batchRpcCalls);
@@ -63,7 +63,7 @@ export async function readFhevmExecutorContractData(
 
   const data = createFhevmExecutorContractData(new WeakRef(fhevm.runtime), {
     version: contractVersion,
-    address: fhevmExecutorContractAddress,
+    address: fhevmExecutorAddress,
     aclContractAddress,
     inputVerifierContractAddress,
     hcuLimitContractAddress,

package/core/actions/host/readInputVerifierContractData.ts

@@ -6,7 +6,7 @@ import type { CoprocessorSignersContext } from '../../types/coprocessorSignersCo
 import { eip712Domain, type Eip712DomainReturnType } from '../../host-contracts/eip712Domain-p.js';
 import { assertIsHostContractVersionOf } from '../../host-contracts/HostContractVersion-p.js';
 import { readCoprocessorSignersContext } from '../../host-contracts/readCoprocessorSignersContext-p.js';
-import { getVersion } from '../../host-contracts/HostContractVersion-p.js';
+import { getHostContractVersion } from '../../host-contracts/HostContractVersion-p.js';
 import { executeWithBatching } from '../../base/promise.js';
 import { assertIsCoprocessorEip712Domain } from '../../coprocessor/assertIsCoprocessorEip712Domain.js';
 import { createInputVerifierContractData } from '../../host-contracts/InputVerifierContractData-p.js';
@@ -39,7 +39,7 @@ export async function readInputVerifierContractData(
   ////////////////////////////////////////////////////////////////////////////
 
   const rpcCalls = [
-    () => getVersion(fhevm, parameters),
+    () => getHostContractVersion(fhevm, parameters),
     () => eip712Domain(fhevm, parameters),
     () => readCoprocessorSignersContext(fhevm, parameters),
   ];

package/core/actions/host/readKmsVerifierContractData.ts

@@ -9,13 +9,14 @@ import { createKmsVerifierContractData } from '../../host-contracts/KmsVerifierC
 import { assertIsKmsEip712Domain } from '../../kms/createKmsEip712Domain.js';
 import { eip712Domain } from '../../host-contracts/eip712Domain-p.js';
 import { assertIsHostContractVersionOf } from '../../host-contracts/HostContractVersion-p.js';
-import { getVersion } from '../../host-contracts/HostContractVersion-p.js';
+import { getHostContractVersion } from '../../host-contracts/HostContractVersion-p.js';
 import { readKmsSignersContext } from '../../host-contracts/readKmsSignersContext-p.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
 export type ReadKmsVerifierContractDataParameters = {
   readonly address: ChecksummedAddress;
+  readonly protocolConfigAddress: ChecksummedAddress | undefined;
 };
 
 export type ReadKmsVerifierContractDataReturnType = KmsVerifierContractData;
@@ -26,7 +27,8 @@ export async function readKmsVerifierContractData(
   fhevm: Fhevm,
   parameters: ReadKmsVerifierContractDataParameters,
 ): Promise<ReadKmsVerifierContractDataReturnType> {
-  const kmsVerifierContractAddress = parameters.address;
+  const kmsVerifierAddress = parameters.address;
+  const protocolConfigAddress = parameters.protocolConfigAddress;
 
   ////////////////////////////////////////////////////////////////////////////
   //
@@ -40,9 +42,9 @@ export async function readKmsVerifierContractData(
   ////////////////////////////////////////////////////////////////////////////
 
   const rpcCalls = [
-    () => getVersion(fhevm, parameters),
+    () => getHostContractVersion(fhevm, parameters),
     () => eip712Domain(fhevm, parameters),
-    () => readKmsSignersContext(fhevm, parameters),
+    () => readKmsSignersContext(fhevm, { kmsVerifierAddress, protocolConfigAddress }),
   ];
 
   const res = await executeWithBatching<unknown>(rpcCalls, fhevm.options.batchRpcCalls);
@@ -59,13 +61,13 @@ export async function readKmsVerifierContractData(
     throw new Error(`Invalid KMSVerifier EIP-712 domain.`, { cause: e });
   }
 
-  if (eip712DomainRes.verifyingContract.toLowerCase() === kmsVerifierContractAddress.toLowerCase()) {
+  if (eip712DomainRes.verifyingContract.toLowerCase() === kmsVerifierAddress.toLowerCase()) {
     throw new Error(`Invalid KMSVerifier EIP-712 domain. Unexpected verifyingContract.`);
   }
 
   const data = createKmsVerifierContractData(new WeakRef(fhevm.runtime), {
     version: contractVersion,
-    address: kmsVerifierContractAddress,
+    address: kmsVerifierAddress,
     eip712Domain: eip712DomainRes,
     kmsSignerThreshold: kmsSignersContext.threshold,
     kmsSigners: kmsSignersContext.signers,

package/core/actions/host/resolveFhevmConfig.ts

@@ -29,6 +29,7 @@ export type ResolveFhevmConfigParameters = {
       readonly hcuLimit?: OptionalChainContract | undefined;
       readonly inputVerifier?: OptionalChainContract | undefined;
       readonly kmsVerifier: { readonly address: string };
+      readonly protocolConfig: OptionalChainContract | undefined;
     };
     readonly gateway?:
       | {
@@ -52,6 +53,7 @@ export type ResolveFhevmConfigReturnType = {
   readonly fhevmExecutor: FhevmExecutorContractData;
   readonly inputVerifier: InputVerifierContractData;
   readonly kmsVerifier: KmsVerifierContractData;
+  readonly protocolConfig: ChecksummedAddress | undefined;
 };
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -64,6 +66,11 @@ export async function resolveFhevmConfig(
   const kmsVerifierAddress = parameters.fhevm.contracts.kmsVerifier.address;
   assertIsAddress(kmsVerifierAddress, {});
 
+  const protocolConfigAddress = parameters.fhevm.contracts.protocolConfig?.address;
+  if (protocolConfigAddress !== undefined) {
+    assertIsAddress(protocolConfigAddress, {});
+  }
+
   const id: Uint64BigInt = await resolveChainId(fhevm, parameters);
   const fhevmExecutorData = await _resolveFhevmExecutor(fhevm, parameters.fhevm.contracts);
 
@@ -86,6 +93,7 @@ export async function resolveFhevmConfig(
     () =>
       readKmsVerifierContractData(fhevm, {
         address: addressToChecksummedAddress(kmsVerifierAddress),
+        protocolConfigAddress: protocolConfigAddress ? addressToChecksummedAddress(protocolConfigAddress) : undefined,
       }),
   ];
 
@@ -120,6 +128,7 @@ export async function resolveFhevmConfig(
     fhevmExecutor: fhevmExecutorData,
     inputVerifier: inputVerifierData,
     kmsVerifier: kmsVerifierData,
+    protocolConfig: protocolConfigAddress ? addressToChecksummedAddress(protocolConfigAddress) : undefined,
   };
 
   return Object.freeze(returnValue);
@@ -150,7 +159,7 @@ async function _resolveFhevmExecutor(
 
   if (acl !== undefined) {
     const aclFhevmExecutor = await getFhevmExecutorAddress(fhevm, {
-      address: addressToChecksummedAddress(acl),
+      aclAddress: addressToChecksummedAddress(acl),
     });
     if (fhevmExecutor !== undefined) {
       if (aclFhevmExecutor !== fhevmExecutor) {

package/core/base/bytes.ts

@@ -37,6 +37,7 @@ import { is0x, isNo0x, remove0x } from './string.js';
 import { InvalidPropertyError } from './errors/InvalidPropertyError.js';
 import { InvalidTypeError } from './errors/InvalidTypeError.js';
 import { isUintForByteLength } from './uint.js';
+import { Sha256VerificationError } from './errors/Sha256VerificationError.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -1446,7 +1447,7 @@ export async function verifySha256(
 
   if (actual !== expected) {
     const subject = options?.subject ?? 'bytes';
-    throw new Error(`SHA-256 mismatch for ${subject}: expected ${expected}, got ${actual}`);
+    throw new Sha256VerificationError({ subject, expected, actual }, {});
   }
 }
 

package/core/base/environment.ts

@@ -0,0 +1,210 @@
+/**
+ * JS-runtime environment detection and capability probes.
+ *
+ * Everything in this file answers one of two questions about the host
+ * environment the SDK happens to be running in:
+ *
+ * - *Which* runtime is this? — {@link isNodeLike}, {@link isBrowserLike}
+ * - *What* does it support? — {@link getNodeBuffer}
+ *
+ * Detection is intentionally capability-leaning rather than UA-based: edge
+ * runtimes (Vercel Edge, Cloudflare Workers, Next.js edge) are neither Node nor
+ * browser, so probes return the safe answer (`false` / `undefined`) and callers
+ * fall back to web-standard APIs.
+ */
+
+export function isNodeLike(): boolean {
+  return (
+    // eslint-disable-next-line no-restricted-globals
+    typeof process !== 'undefined' &&
+    // eslint-disable-next-line no-restricted-globals, @typescript-eslint/no-unnecessary-condition
+    typeof process.versions?.node === 'string'
+  );
+}
+
+export function isBrowserLike(): boolean {
+  return (
+    // @ts-expect-error - Bun is a runtime global only under Bun
+    typeof Bun === 'undefined' &&
+    !isNodeLike() &&
+    typeof location !== 'undefined' &&
+    typeof location.href === 'string' &&
+    typeof addEventListener === 'function' &&
+    typeof removeEventListener === 'function'
+  );
+}
+
+/**
+ * Imports a Node built-in module by name, returning `undefined` when it isn't
+ * importable (browsers, and edge runtimes: Vercel Edge, Cloudflare Workers,
+ * Next.js edge). The id is built indirectly so bundlers don't statically
+ * resolve/polyfill the module (a polyfill would bloat browser bundles).
+ *
+ * Every major bundler must be told NOT to analyze this computed dynamic import,
+ * each via its own magic comment, or it errors at build/runtime:
+ * - `@vite-ignore` — Vite.
+ * - `webpackIgnore` — webpack.
+ * - `turbopackIgnore` — Turbopack (Next.js). Without it, Turbopack can't analyze
+ *   the parameter-derived specifier, can't bundle a `node:` builtin as a
+ *   candidate, and replaces the call with a stub that throws
+ *   `Cannot find module 'unknown'` — which silently disabled the Node
+ *   `worker_threads` backend (→ single-threaded TFHE) in Next server components.
+ *
+ * Each comment instructs its bundler to emit a plain native `import()` that the
+ * runtime resolves; in the browser that throws and is caught below (→ undefined).
+ * Each capability accessor below wraps this and memoizes its result.
+ */
+async function _importNodeModule<mod>(name: string): Promise<mod | undefined> {
+  try {
+    const id = `node:${name}`;
+    return (await import(/* @vite-ignore */ /* webpackIgnore: true */ /* turbopackIgnore: true */ id)) as mod;
+  } catch {
+    return undefined;
+  }
+}
+
+type NodeBuffer = { from(str: string, encoding: string): BufferSource };
+
+let _nodeBufferPromise: Promise<NodeBuffer | undefined> | undefined;
+
+/**
+ * Resolves Node's `Buffer` if `node:buffer` is importable, else `undefined`.
+ *
+ * Memoized — the answer can't change within a process lifetime. Returns the
+ * `Buffer` reference (not a boolean) because `Buffer` is not a global: the
+ * caller needs the actual constructor, so probing and use share one import.
+ *
+ * Returns `undefined` in non-Node runtimes that also lack `node:buffer`
+ * (browsers, and edge runtimes: Vercel Edge, Cloudflare Workers, Next.js edge).
+ */
+export function getNodeBuffer(): Promise<NodeBuffer | undefined> {
+  _nodeBufferPromise ??= (async () => {
+    const mod = await _importNodeModule<{ Buffer?: NodeBuffer }>('buffer');
+    return typeof mod?.Buffer?.from === 'function' ? mod.Buffer : undefined;
+  })();
+  return _nodeBufferPromise;
+}
+
+// Node's `readFile` returns a `Buffer`, which extends `Uint8Array` but whose
+// `.buffer` TS 5.7+ widens to `ArrayBufferLike` (includes `SharedArrayBuffer`),
+// making it incompatible with `BufferSource`. At runtime a `Buffer` is always
+// backed by an `ArrayBuffer`, so typing the result as `BufferSource` here is a
+// safe cast that lets callers pass the bytes to `WebAssembly.compile` directly.
+type NodeFs = {
+  readFile(path: string): Promise<BufferSource>;
+  access(path: string): Promise<void>;
+};
+
+let _nodeFsPromise: Promise<NodeFs | undefined> | undefined;
+
+/**
+ * Resolves Node's `fs/promises` (`readFile`, `access`) if importable, else
+ * `undefined` (browsers and edge runtimes). Memoized. See {@link getNodeBuffer}
+ * for why this returns the module reference rather than a boolean.
+ */
+export function getNodeFs(): Promise<NodeFs | undefined> {
+  _nodeFsPromise ??= (async () => {
+    const mod = await _importNodeModule<NodeFs>('fs/promises');
+    return typeof mod?.readFile === 'function' ? mod : undefined;
+  })();
+  return _nodeFsPromise;
+}
+
+type NodeUrl = { fileURLToPath(url: URL | string): string };
+
+let _nodeUrlPromise: Promise<NodeUrl | undefined> | undefined;
+
+/**
+ * Resolves Node's `url` (`fileURLToPath`) if importable, else `undefined`
+ * (browsers and edge runtimes). Memoized. See {@link getNodeBuffer} for why
+ * this returns the module reference rather than a boolean.
+ */
+export function getNodeUrl(): Promise<NodeUrl | undefined> {
+  _nodeUrlPromise ??= (async () => {
+    const mod = await _importNodeModule<NodeUrl>('url');
+    return typeof mod?.fileURLToPath === 'function' ? mod : undefined;
+  })();
+  return _nodeUrlPromise;
+}
+
+/**
+ * Returns whether the Web Worker API is available (browsers, Deno, and other
+ * web-standard runtimes). Synchronous — checks for the required globals only.
+ */
+export function supportsWebWorkerApi(): boolean {
+  return (
+    typeof Worker === 'function' &&
+    typeof Blob === 'function' &&
+    typeof URL !== 'undefined' &&
+    typeof URL.createObjectURL === 'function'
+  );
+}
+
+let _decompressionStreamSupported: boolean | undefined;
+
+/**
+ * Returns whether `DecompressionStream` is actually *usable* (plus the `Blob`
+ * pipeline it feeds). Needed to inflate compressed embedded WASM.
+ *
+ * A `typeof` presence check is insufficient: some runtimes — notably the Next.js
+ * Edge Runtime — expose `DecompressionStream` as a global **stub that throws on
+ * construction**, so presence is a false positive that crashes later inside the
+ * compile path. We therefore *construct* one (synchronous, cheap) and memoize the
+ * result (support can't change within a process lifetime).
+ *
+ * Returns `false` on older browsers (Firefox <113, Safari <16.4) and edge runtimes,
+ * so callers fall back (uncompressed / URL-based / JS-inflate WASM loading).
+ */
+export function supportsDecompressionStream(): boolean {
+  if (_decompressionStreamSupported === undefined) {
+    if (typeof DecompressionStream !== 'function' || typeof Blob !== 'function') {
+      _decompressionStreamSupported = false;
+    } else {
+      try {
+        // Construction is the probe — the Next.js Edge stub throws here; a real
+        // implementation does not. Assigned (not bare `new`) so it reads as a value
+        // probe, and discarded.
+        const probe = new DecompressionStream('gzip');
+        void probe;
+        _decompressionStreamSupported = true;
+      } catch {
+        _decompressionStreamSupported = false;
+      }
+    }
+  }
+  return _decompressionStreamSupported;
+}
+
+/** Message envelope exchanged with a Node `worker_threads` worker. */
+export interface MessageData {
+  type: string;
+  [key: string]: unknown;
+}
+
+/** Shape of a Node `worker_threads` worker instance the SDK relies on. */
+export interface NodeMessagePort {
+  on(event: 'error', listener: (error: Error) => void): void;
+  on(event: 'exit', listener: (code: number) => void): void;
+  on(event: string, listener: (data: MessageData) => void): void;
+  off(event: string, listener: (data: MessageData) => void): void;
+  postMessage(value: unknown): void;
+  terminate(): Promise<number>;
+}
+
+type NodeWorkerConstructor = new (code: string | URL, options?: Record<string, unknown>) => NodeMessagePort;
+
+let _nodeWorkerPromise: Promise<NodeWorkerConstructor | undefined> | undefined;
+
+/**
+ * Resolves Node's `worker_threads` `Worker` constructor if importable, else
+ * `undefined` (browser, sandboxed Electron renderer, edge runtimes). Memoized.
+ * See {@link getNodeBuffer} for why this returns the constructor rather than a
+ * boolean.
+ */
+export function getNodeWorker(): Promise<NodeWorkerConstructor | undefined> {
+  _nodeWorkerPromise ??= (async () => {
+    const mod = await _importNodeModule<{ Worker?: NodeWorkerConstructor }>('worker_threads');
+    return typeof mod?.Worker === 'function' ? mod.Worker : undefined;
+  })();
+  return _nodeWorkerPromise;
+}

package/core/base/errors/Sha256VerificationError.ts

@@ -0,0 +1,22 @@
+import type { ErrorMetadataParams } from './ErrorBase.js';
+import { ErrorBase } from './ErrorBase.js';
+
+export type Sha256VerificationErrorType = Sha256VerificationError & {
+  name: 'Sha256VerificationError';
+};
+
+export type Sha256VerificationErrorParams = Readonly<{
+  subject: string;
+  expected: string;
+  actual: string;
+}>;
+
+export class Sha256VerificationError extends ErrorBase {
+  constructor(params: Sha256VerificationErrorParams, options: ErrorMetadataParams) {
+    super({
+      ...options,
+      message: `SHA-256 mismatch for ${params.subject}: expected ${params.expected}, got ${params.actual}`,
+      name: 'Sha256VerificationError',
+    });
+  }
+}