@fhevm/sdk 0.0.1 → 1.0.0-alpha.1

package/core/key/FheEncryptionKeyWasm-p.ts

@@ -0,0 +1,97 @@
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type {
+  FheEncryptionCrs,
+  FheEncryptionKeyMetadata,
+  FheEncryptionKeyWasm,
+  FheEncryptionPublicKey,
+} from '../types/fheEncryptionKey.js';
+import { assertOwnedBy } from '../runtime/CoreFhevmRuntime-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+const PRIVATE_TOKEN = Symbol('FheEncryptionKeyWasm.token');
+const VERIFY_FUNC = Symbol('FheEncryptionKeyWasm.verify');
+
+////////////////////////////////////////////////////////////////////////////////
+// FheEncryptionKeyWasmImpl (private implementation)
+////////////////////////////////////////////////////////////////////////////////
+
+class FheEncryptionKeyWasmImpl implements FheEncryptionKeyWasm {
+  readonly #owner: WeakRef<FhevmRuntime>;
+  readonly #crs: FheEncryptionCrs;
+  readonly #publicKey: FheEncryptionPublicKey;
+  readonly #metadata: FheEncryptionKeyMetadata;
+
+  constructor(
+    privateToken: symbol,
+    owner: WeakRef<FhevmRuntime>,
+    parameters: {
+      readonly publicKey: FheEncryptionPublicKey;
+      readonly crs: FheEncryptionCrs;
+      readonly metadata: FheEncryptionKeyMetadata;
+    },
+  ) {
+    if (privateToken !== PRIVATE_TOKEN) {
+      throw new Error('Unauthorized');
+    }
+    this.#owner = owner;
+    this.#publicKey = parameters.publicKey;
+    this.#crs = parameters.crs;
+    this.#metadata = Object.freeze({ ...parameters.metadata });
+
+    Object.freeze(this);
+  }
+
+  public get publicKey(): FheEncryptionPublicKey {
+    return this.#publicKey;
+  }
+
+  public get crs(): FheEncryptionCrs {
+    return this.#crs;
+  }
+
+  public get metadata(): FheEncryptionKeyMetadata {
+    return this.#metadata;
+  }
+
+  public static [VERIFY_FUNC](privateToken: symbol, instance: unknown, owner: FhevmRuntime): void {
+    if (privateToken !== PRIVATE_TOKEN) {
+      throw new Error('Unauthorized');
+    }
+    if (!(instance instanceof FheEncryptionKeyWasmImpl)) {
+      throw new Error('Invalid FheEncryptionKey instance');
+    }
+    assertOwnedBy({
+      actualOwner: instance.#owner,
+      expectedOwner: owner,
+      name: 'FheEncryptionKey',
+    });
+  }
+}
+
+// Prevent prototype pollution and constructor access
+Object.freeze(FheEncryptionKeyWasmImpl.prototype);
+Object.freeze(FheEncryptionKeyWasmImpl);
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createFheEncryptionKeyWasm(
+  owner: WeakRef<FhevmRuntime>,
+  parameters: {
+    readonly publicKey: FheEncryptionPublicKey;
+    readonly crs: FheEncryptionCrs;
+    readonly metadata: FheEncryptionKeyMetadata;
+  },
+): FheEncryptionKeyWasm {
+  return new FheEncryptionKeyWasmImpl(PRIVATE_TOKEN, owner, parameters);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Verifies that the given `FheEncryptionKeyWasm` instance is owned
+ * by the given runtime. Throws if not.
+ */
+export function assertFheEncryptionKeyWasmOwnedBy(data: FheEncryptionKeyWasm, owner: FhevmRuntime): void {
+  FheEncryptionKeyWasmImpl[VERIFY_FUNC](PRIVATE_TOKEN, data, owner);
+}

package/core/key/deserializeFheEncryptionKey.ts

@@ -0,0 +1,24 @@
+import type { WithEncrypt } from '../types/coreFhevmRuntime.js';
+import type { FheEncryptionKeyWasm, FheEncryptionKeyBytes } from '../types/fheEncryptionKey.js';
+import { createFheEncryptionKeyWasm } from './FheEncryptionKeyWasm-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export async function deserializeFheEncryptionKey(
+  context: { readonly runtime: WithEncrypt },
+  parameters: FheEncryptionKeyBytes,
+): Promise<FheEncryptionKeyWasm> {
+  const publicKeyNative = await context.runtime.encrypt.deserializeFheEncryptionPublicKey({
+    publicKeyBytes: parameters.publicKeyBytes,
+  });
+
+  const crsNative = await context.runtime.encrypt.deserializeFheEncryptionCrs({
+    crsBytes: parameters.crsBytes,
+  });
+
+  return createFheEncryptionKeyWasm(new WeakRef(context.runtime), {
+    publicKey: publicKeyNative,
+    crs: crsNative,
+    metadata: parameters.metadata,
+  });
+}

package/core/key/fetchFheEncryptionKey.ts

@@ -0,0 +1,46 @@
+import type { RelayerKeyUrlOptions } from '../types/relayer.js';
+import type { WithEncrypt } from '../types/coreFhevmRuntime.js';
+import type { FhevmChain } from '../types/fhevmChain.js';
+import type { FheEncryptionKeyWasm } from '../types/fheEncryptionKey.js';
+import { deserializeFheEncryptionKey } from './deserializeFheEncryptionKey.js';
+import { globalFheEncryptionKeyCache } from './FheEncryptionKeyCache-p.js';
+
+export async function fetchFheEncryptionKeyWasm(
+  context: { readonly chain: FhevmChain; readonly runtime: WithEncrypt },
+  parameters?: {
+    readonly options?: RelayerKeyUrlOptions | undefined;
+    readonly ignoreCache?: boolean | undefined;
+  },
+): Promise<FheEncryptionKeyWasm> {
+  const relayerUrl = context.chain.fhevm.relayerUrl;
+  const runtime = context.runtime;
+
+  // Ensure a bytes fetch is in-flight
+  globalFheEncryptionKeyCache.ensureBytes({
+    owner: runtime,
+    relayerUrl,
+    fetcher: () =>
+      runtime.relayer.fetchFheEncryptionKeyBytes({ relayerUrl, chainId: context.chain.id }, parameters ?? {}),
+    metadata: { chainId: context.chain.id, relayerUrl },
+  });
+
+  // Upgrade bytes → wasm (chains from pending bytes if still in-flight)
+  globalFheEncryptionKeyCache.ensureWasm({
+    owner: runtime,
+    relayerUrl,
+    deserializeFn: (bytes) => deserializeFheEncryptionKey(context, bytes),
+  });
+
+  const entry = globalFheEncryptionKeyCache.get(relayerUrl);
+  if (entry === undefined) {
+    throw new Error('Failed to fetch global FHE PKE params');
+  }
+
+  await entry.ready;
+
+  if (entry.resolvedKind !== 'wasm') {
+    throw new Error('Expected wasm params but got ' + JSON.stringify(entry.resolvedKind));
+  }
+
+  return entry.value as FheEncryptionKeyWasm;
+}

package/core/key/fetchFheEncryptionKeyBytes.ts

@@ -0,0 +1,69 @@
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type { FhevmChain } from '../types/fhevmChain.js';
+import type { FheEncryptionKeyBytes, FheEncryptionKeyWasm } from '../types/fheEncryptionKey.js';
+import type { RelayerKeyUrlOptions } from '../types/relayer.js';
+import type { FetchFheEncryptionKeyBytesParameters } from '../modules/relayer/types.js';
+import { globalFheEncryptionKeyCache } from './FheEncryptionKeyCache-p.js';
+import { serializeFheEncryptionKeyWasm } from './serializeFheEncryptionKey.js';
+import { asFhevmRuntimeWith } from '../runtime/CoreFhevmRuntime-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export async function fetchFheEncryptionKeyBytes(
+  context: { readonly chain: FhevmChain; readonly runtime: FhevmRuntime },
+  parameters?: {
+    readonly options?: RelayerKeyUrlOptions | undefined;
+    readonly ignoreCache?: boolean | undefined;
+  },
+): Promise<FheEncryptionKeyBytes> {
+  const relayerUrl = context.chain.fhevm.relayerUrl;
+  const runtime = context.runtime;
+
+  // Caller-provided options override runtime config defaults (e.g. auth)
+  const relayerParameters: FetchFheEncryptionKeyBytesParameters = {
+    ...parameters,
+    options: { auth: context.runtime.config.auth, ...parameters?.options },
+  };
+
+  // Ensure a fetch is in-flight
+  globalFheEncryptionKeyCache.ensureBytes({
+    owner: runtime,
+    relayerUrl,
+    fetcher: () =>
+      runtime.relayer.fetchFheEncryptionKeyBytes({ relayerUrl, chainId: context.chain.id }, relayerParameters),
+    metadata: { chainId: context.chain.id, relayerUrl },
+  });
+
+  const bytes = await globalFheEncryptionKeyCache.resolveBytes({
+    relayerUrl,
+    serializeFn: _getSerializeFn(context),
+  });
+
+  if (bytes === undefined) {
+    throw new Error('Failed to fetch global FHE PKE params bytes');
+  }
+
+  return bytes;
+}
+
+/**
+ * Returns a serialize function that converts wasm params to bytes,
+ * or `undefined` if the encrypt module is not available on the runtime.
+ */
+function _getSerializeFn(context: {
+  readonly chain: FhevmChain;
+  readonly runtime: FhevmRuntime;
+}): ((args: FheEncryptionKeyWasm) => Promise<FheEncryptionKeyBytes>) | undefined {
+  // Try to get a serialize fn if the encrypt module is available
+  let serializeFn: ((args: FheEncryptionKeyWasm) => Promise<FheEncryptionKeyBytes>) | undefined;
+
+  try {
+    // check if the 'encrypt' module is available
+    const r = asFhevmRuntimeWith(context.runtime, 'encrypt');
+    serializeFn = (args) => serializeFheEncryptionKeyWasm({ runtime: r }, args);
+  } catch {
+    // encrypt module not available
+  }
+
+  return serializeFn;
+}

package/core/key/fetchFheEncryptionKeyBytesWithSource.ts

@@ -0,0 +1,72 @@
+import type { FheEncryptionKeyBytes, FheEncryptionKeySource } from '../types/fheEncryptionKey.js';
+import type { Bytes } from '../types/primitives.js';
+import { FetchError } from '../base/errors/FetchError.js';
+import { fetchWithRetry, getResponseBytes, type FetchWithRetryParameters } from '../base/fetch.js';
+
+////////////////////////////////////////////////////////////////////////////////
+// fetchFheEncryptionKeyBytesWithSource
+////////////////////////////////////////////////////////////////////////////////
+
+export async function fetchFheEncryptionKeyBytesWithSource(
+  source: FheEncryptionKeySource,
+  options?: FetchWithRetryParameters,
+): Promise<FheEncryptionKeyBytes> {
+  if (source.crsSource.capacity !== 2048) {
+    throw new FetchError({
+      url: source.crsSource.url,
+      message: `Invalid pke crs capacity ${source.crsSource.capacity.toString()}. Expecting 2048.`,
+    });
+  }
+
+  const [publicKeyBytes, pkeCrsBytes]: [Bytes, Bytes] = await Promise.all([
+    _fetchBytes({ url: source.publicKeySource.url, ...options }),
+    _fetchBytes({ url: source.crsSource.url, ...options }),
+  ]);
+
+  return Object.freeze({
+    publicKeyBytes: Object.freeze({
+      id: source.publicKeySource.id,
+      bytes: publicKeyBytes,
+    }),
+    crsBytes: Object.freeze({
+      id: source.crsSource.id,
+      capacity: source.crsSource.capacity,
+      bytes: pkeCrsBytes,
+    }),
+    metadata: Object.freeze({ ...source.metadata }),
+  }) as FheEncryptionKeyBytes;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// _fetchBytes
+////////////////////////////////////////////////////////////////////////////////
+
+async function _fetchBytes(params: { url: string } & FetchWithRetryParameters): Promise<Bytes> {
+  const url = params.url;
+
+  // Fetching a public key must use GET (the default method)
+  if (params.init?.method !== undefined && params.init.method !== 'GET') {
+    throw new FetchError({
+      url,
+      message: `Invalid fetch method: expected 'GET', got '${params.init.method}'`,
+    });
+  }
+
+  const response = await fetchWithRetry({
+    url,
+    init: params.init,
+    retries: params.retries,
+    retryDelayMs: params.retryDelayMs,
+  });
+
+  if (!response.ok) {
+    throw new FetchError({
+      url,
+      message: `HTTP error! status: ${response.status} on ${response.url}`,
+    });
+  }
+
+  const compactPkeCrsBytes: Uint8Array = await getResponseBytes(response);
+
+  return compactPkeCrsBytes;
+}

package/core/key/serializeFheEncryptionKey.ts

@@ -0,0 +1,36 @@
+import type { WithEncrypt } from '../types/coreFhevmRuntime.js';
+import { assertFheEncryptionKeyWasmOwnedBy } from './FheEncryptionKeyWasm-p.js';
+import {
+  type FheEncryptionCrsBytes,
+  type FheEncryptionKeyWasm,
+  type FheEncryptionKeyBytes,
+  type FheEncryptionKeyMetadata,
+  type FheEncryptionPublicKeyBytes,
+} from '../types/fheEncryptionKey.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export async function serializeFheEncryptionKeyWasm(
+  context: { readonly runtime: WithEncrypt },
+  parameters: FheEncryptionKeyWasm,
+): Promise<FheEncryptionKeyBytes> {
+  assertFheEncryptionKeyWasmOwnedBy(parameters, context.runtime);
+
+  const publicKeyBytes: FheEncryptionPublicKeyBytes = await context.runtime.encrypt.serializeFheEncryptionPublicKey({
+    publicKey: parameters.publicKey,
+  });
+
+  const crsBytes: FheEncryptionCrsBytes = await context.runtime.encrypt.serializeFheEncryptionCrs({
+    crs: parameters.crs,
+  });
+
+  const metadata: FheEncryptionKeyMetadata = Object.freeze({
+    ...parameters.metadata,
+  });
+
+  return Object.freeze({
+    publicKeyBytes: publicKeyBytes,
+    crsBytes: crsBytes,
+    metadata,
+  });
+}

package/core/kms/KmsSigncryptedShares-p.ts

@@ -0,0 +1,169 @@
+import type { KmsSigncryptedSharesMetadata, KmsSigncryptedShare } from '../types/kms-p.js';
+import type { KmsSigncryptedShares, KmsSigncryptedSharesBrand } from '../types/kms.js';
+import type { BytesHex, BytesHexNo0x, ChecksummedAddress } from '../types/primitives.js';
+import type { KmsSignersContext } from '../types/kmsSignersContext.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type { FhevmChain } from '../types/fhevmChain.js';
+import { assertIsKmsSignersContext } from '../host-contracts/KmsSignersContext-p.js';
+import { ensure0x } from '../base/string.js';
+import { assertIsKmsExtraData } from './kmsExtraData.js';
+import { reconcileKmsSignersContext } from '../host-contracts/readKmsSignersContext-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+const PRIVATE_KMS_SIGNCRYPTED_SHARES_TOKEN = Symbol('KmsSigncryptedShares.token');
+
+const GET_METADATA_FUNC = Symbol('KmsSigncryptedShares.getMetadata');
+const GET_SHARES_FUNC = Symbol('KmsSigncryptedShares.getShares');
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Validated collection of KMS signcrypted shares.
+ *
+ * Construction guarantees:
+ * - Contains at least one share.
+ * - All shares have identical `extraData` values.
+ * - The shared `extraData` matches the `extraData` derived from the associated {@link KmsSignersContext}.
+ *
+ * @internal
+ */
+class KmsSigncryptedSharesImpl implements KmsSigncryptedShares {
+  declare readonly [KmsSigncryptedSharesBrand]: never;
+  readonly #metadata: KmsSigncryptedSharesMetadata;
+  readonly #shares: readonly KmsSigncryptedShare[];
+
+  constructor(metadata: KmsSigncryptedSharesMetadata, shares: readonly KmsSigncryptedShare[]) {
+    this.#metadata = {
+      kmsSignersContext: metadata.kmsSignersContext,
+      eip712Domain: metadata.eip712Domain,
+      eip712Signature: metadata.eip712Signature,
+      eip712SignerAddress: metadata.eip712SignerAddress,
+      handles: [...metadata.handles],
+    };
+    Object.freeze(this.#metadata);
+    Object.freeze(this.#metadata.handles);
+
+    this.#shares = [...shares];
+    Object.freeze(this.#shares);
+    this.#shares.forEach((share) => Object.freeze(share));
+  }
+
+  public [GET_SHARES_FUNC](token: symbol): readonly KmsSigncryptedShare[] {
+    if (token !== PRIVATE_KMS_SIGNCRYPTED_SHARES_TOKEN) {
+      throw new Error('Unauthorized');
+    }
+    return this.#shares;
+  }
+
+  public [GET_METADATA_FUNC](token: symbol): KmsSigncryptedSharesMetadata {
+    if (token !== PRIVATE_KMS_SIGNCRYPTED_SHARES_TOKEN) {
+      throw new Error('Unauthorized');
+    }
+    return this.#metadata;
+  }
+}
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly chain: FhevmChain;
+  readonly client: NonNullable<object>;
+  readonly options: { readonly batchRpcCalls: boolean };
+};
+
+/**
+ * Asserts that at least one share exists and that all shares carry the same
+ * `extraData`. Returns the common `extraData` value.
+ */
+function assertUniformExtraData(shares: readonly KmsSigncryptedShare[]): BytesHexNo0x {
+  const firstShare = shares[0];
+  if (firstShare === undefined) {
+    throw new Error('Expected at least one signcrypted share.');
+  }
+
+  const firstExtraData = firstShare.extraData;
+  for (let i = 1; i < shares.length; i++) {
+    const share = shares[i];
+    if (share !== undefined && share.extraData !== firstExtraData) {
+      throw new Error(
+        `Mismatched extraData across shares: share[0]="${firstExtraData}" vs share[${i}]="${share.extraData}".`,
+      );
+    }
+  }
+
+  return firstExtraData;
+}
+
+/**
+ * Creates a validated {@link KmsSigncryptedShares} instance.
+ *
+ * Enforces all invariants documented on {@link KmsSigncryptedSharesImpl}:
+ * at least one share, uniform `extraData`, and consistency with the
+ * {@link KmsSignersContext}.
+ *
+ * @throws If validation fails.
+ * @internal
+ */
+export async function createKmsSigncryptedShares(
+  context: Context,
+  parameters: {
+    readonly metadata: KmsSigncryptedSharesMetadata;
+    readonly shares: readonly KmsSigncryptedShare[];
+  },
+): Promise<KmsSigncryptedShares> {
+  const { metadata, shares } = parameters;
+  /*
+    TODO: add an optional signature verification pass. 
+    (13 signatures verifications. Could be CPU costly)
+
+    See: in KMS (eip712Domain)
+    json.response[i].signature is an eip712 sig potentially on this message:
+
+    struct UserDecryptResponseVerification {
+        bytes publicKey;
+        bytes32[] ctHandles;
+        bytes userDecryptedShare;
+        bytes extraData;
+    }
+  */
+
+  // Assert context first — extraData comparison depends on a valid KmsSignersContext.
+  assertIsKmsSignersContext(metadata.kmsSignersContext, {});
+
+  // Extract the common extraData from all shares and validate its format.
+  const relayerExtraData: BytesHex = ensure0x(assertUniformExtraData(shares));
+  assertIsKmsExtraData(relayerExtraData, {});
+
+  // Reconcile KMS signer context using 'loose' mode.
+  const reconciledKmsSignersContext: KmsSignersContext = await reconcileKmsSignersContext(context, {
+    address: context.chain.fhevm.contracts.kmsVerifier.address as ChecksummedAddress,
+    relayerExtraData,
+    requestedKmsSignersContext: metadata.kmsSignersContext,
+    mode: 'loose',
+  });
+
+  return new KmsSigncryptedSharesImpl({ ...metadata, kmsSignersContext: reconciledKmsSignersContext }, shares);
+}
+
+/**
+ * Returns the validated shares. No additional verification is needed —
+ * all invariants are enforced at {@link KmsSigncryptedSharesImpl} construction time.
+ *
+ * @internal
+ */
+export function getShares(signcryptedShares: KmsSigncryptedShares): readonly KmsSigncryptedShare[] {
+  if (!(signcryptedShares instanceof KmsSigncryptedSharesImpl)) {
+    throw new Error('Invalid KmsSigncryptedShares');
+  }
+  return signcryptedShares[GET_SHARES_FUNC](PRIVATE_KMS_SIGNCRYPTED_SHARES_TOKEN);
+}
+
+/**
+ * @internal
+ */
+export function getMetadata(signcryptedShares: KmsSigncryptedShares): KmsSigncryptedSharesMetadata {
+  if (!(signcryptedShares instanceof KmsSigncryptedSharesImpl)) {
+    throw new Error('Invalid KmsSigncryptedShares');
+  }
+  return signcryptedShares[GET_METADATA_FUNC](PRIVATE_KMS_SIGNCRYPTED_SHARES_TOKEN);
+}