@fhevm/sdk 0.0.1 → 1.0.0-alpha.1

package/core/host-contracts/CoprocessorSignersContext-p.ts

@@ -0,0 +1,167 @@
+import type { ChecksummedAddress, Uint8Number } from '../types/primitives.js';
+import type { coprocessorBrand } from '../types/coprocessor.js';
+import type { CoprocessorSignersContext, CoprocessorSignersContextJson } from '../types/coprocessorSignersContext.js';
+import type { ErrorMetadataParams } from '../base/errors/ErrorBase.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { DuplicateSignerError, ThresholdSignerError, UnknownSignerError } from '../errors/SignersError.js';
+import { InvalidTypeError } from '../base/errors/InvalidTypeError.js';
+import { assertOwnedBy } from '../runtime/CoreFhevmRuntime-p.js';
+
+const PRIVATE_TOKEN = Symbol('CoprocessorSignersContext.token');
+const VERIFY_FUNC = Symbol('CoprocessorSignersContext.verify');
+
+////////////////////////////////////////////////////////////////////////////////
+// CoprocessorSignersContext (private implementation)
+////////////////////////////////////////////////////////////////////////////////
+
+class CoprocessorSignersContextImpl implements CoprocessorSignersContext {
+  declare readonly [coprocessorBrand]: never;
+
+  readonly #owner: WeakRef<FhevmRuntime>;
+  readonly #address: ChecksummedAddress;
+  readonly #coprocessorSigners: ChecksummedAddress[];
+  readonly #coprocessorSignersSet: Set<string>;
+  readonly #coprocessorSignerThreshold: Uint8Number;
+
+  constructor(
+    privateToken: symbol,
+    owner: WeakRef<FhevmRuntime>,
+    parameters: {
+      readonly address: ChecksummedAddress;
+      readonly coprocessorSigners: readonly ChecksummedAddress[];
+      readonly coprocessorSignerThreshold: Uint8Number;
+    },
+  ) {
+    if (privateToken !== PRIVATE_TOKEN) {
+      throw new Error('Unauthorized');
+    }
+    this.#owner = owner;
+    this.#address = parameters.address;
+    this.#coprocessorSigners = [...parameters.coprocessorSigners];
+    this.#coprocessorSignerThreshold = parameters.coprocessorSignerThreshold;
+    this.#coprocessorSignersSet = new Set(this.#coprocessorSigners.map((addr) => addr.toLowerCase()));
+
+    Object.freeze(this.#coprocessorSigners);
+    Object.freeze(this);
+  }
+
+  public get address(): ChecksummedAddress {
+    return this.#address;
+  }
+
+  public get signers(): ChecksummedAddress[] {
+    return this.#coprocessorSigners;
+  }
+
+  public get threshold(): Uint8Number {
+    return this.#coprocessorSignerThreshold;
+  }
+
+  public has(signer: string): boolean {
+    return this.#coprocessorSignersSet.has(signer);
+  }
+
+  public static [VERIFY_FUNC](instance: unknown, owner: FhevmRuntime): void {
+    if (!(instance instanceof CoprocessorSignersContextImpl)) {
+      throw new Error('Invalid CoprocessorSignersContext instance');
+    }
+    assertOwnedBy({
+      actualOwner: instance.#owner,
+      expectedOwner: owner,
+      name: 'CoprocessorSignersContext',
+    });
+  }
+
+  public toJSON(): CoprocessorSignersContextJson {
+    return {
+      address: this.#address,
+      signers: this.#coprocessorSigners,
+      threshold: this.#coprocessorSignerThreshold,
+    };
+  }
+}
+
+// Prevent prototype pollution and constructor access
+Object.freeze(CoprocessorSignersContextImpl.prototype);
+Object.freeze(CoprocessorSignersContextImpl);
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createCoprocessorSignersContext(
+  owner: WeakRef<FhevmRuntime>,
+  parameters: {
+    readonly address: ChecksummedAddress;
+    readonly coprocessorSigners: readonly ChecksummedAddress[];
+    readonly coprocessorSignerThreshold: Uint8Number;
+  },
+): CoprocessorSignersContext {
+  return new CoprocessorSignersContextImpl(PRIVATE_TOKEN, owner, parameters);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Verifies that the given `CoprocessorSignersContext` instance was created
+ * by the given runtime. Throws if not.
+ */
+export function assertCoprocessorSignersContextOwnedBy(data: CoprocessorSignersContext, owner: FhevmRuntime): void {
+  CoprocessorSignersContextImpl[VERIFY_FUNC](data, owner);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function assertCoprocessorSignerThreshold(
+  coprocessorSignersContext: CoprocessorSignersContext,
+  recoveredAddresses: readonly string[],
+): void {
+  const type = 'coprocessor';
+  const addressMap = new Set<string>();
+  recoveredAddresses.forEach((address) => {
+    if (addressMap.has(address.toLowerCase())) {
+      throw new DuplicateSignerError({
+        duplicateAddress: address,
+        type,
+      });
+    }
+    addressMap.add(address.toLowerCase());
+  });
+
+  for (const address of recoveredAddresses) {
+    if (!coprocessorSignersContext.has(address.toLowerCase())) {
+      throw new UnknownSignerError({
+        unknownAddress: address,
+        type,
+      });
+    }
+  }
+
+  if (recoveredAddresses.length < coprocessorSignersContext.threshold) {
+    throw new ThresholdSignerError({
+      type,
+    });
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function isCoprocessorSignersContext(value: unknown): value is CoprocessorSignersContext {
+  return value instanceof CoprocessorSignersContextImpl;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function assertIsCoprocessorSignersContext(
+  value: unknown,
+  options: { readonly subject?: string } & ErrorMetadataParams,
+): asserts value is CoprocessorSignersContext {
+  if (!isCoprocessorSignersContext(value)) {
+    throw new InvalidTypeError(
+      {
+        subject: options.subject,
+        type: typeof value,
+        expectedType: 'CoprocessorSignersContext',
+      },
+      options,
+    );
+  }
+}

package/core/host-contracts/FhevmExecutorContractData-p.ts

@@ -0,0 +1,133 @@
+import type { ChecksummedAddress, Uint8Number } from '../types/primitives.js';
+import type { FhevmExecutorContractData } from '../types/coprocessor.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type { HostContractVersion } from '../types/hostContract.js';
+import { assertOwnedBy } from '../runtime/CoreFhevmRuntime-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+const PRIVATE_TOKEN = Symbol('FhevmExecutorContractData.token');
+const VERIFY_FUNC = Symbol('FhevmExecutorContractData.verify');
+
+////////////////////////////////////////////////////////////////////////////////
+// FHEVMExecutor (private implementation)
+////////////////////////////////////////////////////////////////////////////////
+
+class FhevmExecutorContractDataImpl implements FhevmExecutorContractData {
+  readonly #owner: WeakRef<FhevmRuntime>;
+  readonly #version: HostContractVersion<'FHEVMExecutor'>;
+  readonly #address: ChecksummedAddress;
+  readonly #handleVersion: Uint8Number;
+  readonly #aclContractAddress: ChecksummedAddress;
+  readonly #inputVerifierContractAddress: ChecksummedAddress;
+  readonly #hcuLimitContractAddress: ChecksummedAddress;
+
+  constructor(
+    privateToken: symbol,
+    owner: WeakRef<FhevmRuntime>,
+    parameters: {
+      readonly version: HostContractVersion<'FHEVMExecutor'>;
+      readonly address: ChecksummedAddress;
+      readonly handleVersion: Uint8Number;
+      readonly aclContractAddress: ChecksummedAddress;
+      readonly inputVerifierContractAddress: ChecksummedAddress;
+      readonly hcuLimitContractAddress: ChecksummedAddress;
+    },
+  ) {
+    if (privateToken !== PRIVATE_TOKEN) {
+      throw new Error('Unauthorized');
+    }
+    this.#version = Object.freeze({ ...parameters.version });
+    this.#owner = owner;
+    this.#address = parameters.address;
+    this.#handleVersion = parameters.handleVersion;
+    this.#aclContractAddress = parameters.aclContractAddress;
+    this.#inputVerifierContractAddress = parameters.inputVerifierContractAddress;
+    this.#hcuLimitContractAddress = parameters.hcuLimitContractAddress;
+    Object.freeze(this);
+  }
+
+  public get version(): HostContractVersion<'FHEVMExecutor'> {
+    return this.#version;
+  }
+
+  public get address(): ChecksummedAddress {
+    return this.#address;
+  }
+
+  public get aclContractAddress(): ChecksummedAddress {
+    return this.#aclContractAddress;
+  }
+
+  public get inputVerifierContractAddress(): ChecksummedAddress {
+    return this.#inputVerifierContractAddress;
+  }
+
+  public get hcuLimitContractAddress(): ChecksummedAddress {
+    return this.#hcuLimitContractAddress;
+  }
+
+  public get handleVersion(): Uint8Number {
+    return this.#handleVersion;
+  }
+
+  public static [VERIFY_FUNC](instance: unknown, owner: FhevmRuntime): void {
+    if (!(instance instanceof FhevmExecutorContractDataImpl)) {
+      throw new Error('Invalid FhevmExecutorContractData instance');
+    }
+    assertOwnedBy({
+      actualOwner: instance.#owner,
+      expectedOwner: owner,
+      name: 'FhevmExecutorContractData',
+    });
+  }
+
+  public toJSON(): Record<string, unknown> {
+    return {
+      version: this.#version,
+      address: this.#address,
+      aclContractAddress: this.#aclContractAddress,
+      inputVerifierContractAddress: this.#inputVerifierContractAddress,
+      hcuLimitContractAddress: this.#hcuLimitContractAddress,
+      handleVersion: this.#handleVersion,
+    };
+  }
+}
+
+// Prevent prototype pollution and constructor access
+Object.freeze(FhevmExecutorContractDataImpl.prototype);
+Object.freeze(FhevmExecutorContractDataImpl);
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createFhevmExecutorContractData(
+  owner: WeakRef<FhevmRuntime>,
+  parameters: {
+    readonly version: HostContractVersion<'FHEVMExecutor'>;
+    readonly address: ChecksummedAddress;
+    readonly aclContractAddress: ChecksummedAddress;
+    readonly inputVerifierContractAddress: ChecksummedAddress;
+    readonly hcuLimitContractAddress: ChecksummedAddress;
+    readonly handleVersion: Uint8Number;
+  },
+): FhevmExecutorContractData {
+  const { version, address, aclContractAddress, inputVerifierContractAddress, hcuLimitContractAddress, handleVersion } =
+    parameters;
+
+  return new FhevmExecutorContractDataImpl(PRIVATE_TOKEN, owner, {
+    version,
+    address,
+    aclContractAddress,
+    inputVerifierContractAddress,
+    hcuLimitContractAddress,
+    handleVersion,
+  });
+}
+
+/**
+ * Verifies that the given `FHEVMExecutorContractData` instance is owned
+ * by the given runtime. Throws if not.
+ */
+export function assertFHEVMExecutorContractDataOwnedBy(data: FhevmExecutorContractData, owner: FhevmRuntime): void {
+  FhevmExecutorContractDataImpl[VERIFY_FUNC](data, owner);
+}

package/core/host-contracts/HostContractVersion-p.ts

@@ -0,0 +1,155 @@
+import type { ChecksummedAddress } from '../types/primitives.js';
+import type { HostContractName, HostContractVersion, HostContractVersionString } from '../types/hostContract.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { assertIsNonEmptyString } from '../base/string.js';
+import { getVersionAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+import { assertIsUintNumber } from '../base/uint.js';
+import { CACHE_TTL_24H, createCachedFetch } from '../base/cachedFetch.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+};
+
+type ReturnType = HostContractVersion;
+
+////////////////////////////////////////////////////////////////////////////////
+
+const cachedGetVersion = createCachedFetch<Context, Parameters, ReturnType>({
+  executeFn: _getVersion,
+  cacheKeyFn: (context, params) => `${context.runtime.uid.toLowerCase()}:${params.address.toLowerCase()}`,
+  // Host contract versions are immutable per deployment, so a long TTL is safe.
+  ttlMs: CACHE_TTL_24H,
+});
+
+/**
+ * Reads the version of a host contract at the given address.
+ *
+ * Results are cached per address to avoid redundant RPC calls — concurrent
+ * callers share the same in-flight request (deduplication), and subsequent
+ * calls return the cached value instantly.
+ *
+ * Although host contract versions are generally immutable per deployment,
+ * upgrades can occur in rare cases (e.g. proxy re-pointing). To account for
+ * this, cached entries expire after 24 hours and are automatically refetched.
+ *
+ * @param parameters.address - The checksummed address of the host contract.
+ * @param parameters.forceRefresh - If `true`, invalidates the cached entry and
+ *   makes a fresh RPC call. The new result is stored back in the cache.
+ *   Use this after a known contract upgrade to ensure all subsequent callers
+ *   see the updated version.
+ */
+export function getVersion(
+  context: Context,
+  parameters: Parameters & { readonly forceRefresh?: boolean },
+): Promise<ReturnType> {
+  return cachedGetVersion.execute(context, parameters);
+}
+
+async function _getVersion(context: Context, parameters: Parameters): Promise<HostContractVersion> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: getVersionAbi,
+    args: [],
+    functionName: getVersionAbi[0].name,
+  });
+
+  try {
+    assertIsNonEmptyString(res);
+  } catch (e) {
+    throw new Error(`Invalid Version.`, {
+      cause: e,
+    });
+  }
+
+  return parseVersion(res);
+}
+
+/**
+ * Parses a version string with format: `<contractName> v<major>.<minor>.<patch>`
+ */
+function parseVersion(version: string): HostContractVersion {
+  const err = `Invalid version format: "${version}". Expected "<contractName> v<major>.<minor>.<patch>".`;
+
+  // Split on " v" to separate contract name from semver
+  const vIndex = version.lastIndexOf(' v');
+  if (vIndex < 1) {
+    throw new Error(err);
+  }
+
+  const contractName = version.slice(0, vIndex);
+  const semver = version.slice(vIndex + 2);
+
+  const parts = semver.split('.');
+  if (parts.length !== 3) {
+    throw new Error(err);
+  }
+
+  const [majorStr, minorStr, patchStr] = parts;
+  const major = Number(majorStr);
+  const minor = Number(minorStr);
+  const patch = Number(patchStr);
+
+  assertIsUintNumber(major, {});
+  assertIsUintNumber(minor, {});
+  assertIsUintNumber(patch, {});
+
+  if (
+    contractName !== 'ACL' &&
+    contractName !== 'FHEVMExecutor' &&
+    contractName !== 'InputVerifier' &&
+    contractName !== 'KMSVerifier' &&
+    contractName !== 'HCULimit'
+  ) {
+    throw new Error(err);
+  }
+
+  return Object.freeze({
+    version: version as HostContractVersionString,
+    contractName,
+    major,
+    minor,
+    patch,
+  });
+}
+
+/**
+ * Returns `true` if the version is strictly before `major.minor` (patch ignored).
+ */
+export function isVersionStrictlyBefore(
+  version: HostContractVersion,
+  before: { readonly major: number; readonly minor: number },
+): boolean {
+  if (version.major < before.major) {
+    return true;
+  }
+  if (version.major === before.major) {
+    return version.minor < before.minor;
+  }
+  return false;
+}
+
+/**
+ * Asserts that a {@link HostContractVersion} belongs to a specific contract.
+ * Narrows the type to `HostContractVersion<name>` on success.
+ *
+ * @throws If `v.contractName` does not match the expected name.
+ */
+export function assertIsHostContractVersionOf<hostContractName extends HostContractName>(
+  v: HostContractVersion,
+  hostContractName: hostContractName,
+): asserts v is HostContractVersion<hostContractName> {
+  if (v.contractName !== hostContractName) {
+    throw new Error(`Invalid contract name. Expecting '${hostContractName}', got ${v.contractName}.`);
+  }
+}

package/core/host-contracts/InputVerifierContractData-p.ts

@@ -0,0 +1,133 @@
+import type { ChecksummedAddress, Uint64BigInt, Uint8Number } from '../types/primitives.js';
+import type { CoprocessorEip712Domain, InputVerifierContractData } from '../types/coprocessor.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type { HostContractVersion } from '../types/hostContract.js';
+import { assertOwnedBy } from '../runtime/CoreFhevmRuntime-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+const PRIVATE_TOKEN = Symbol('InputVerifierContractData.token');
+const VERIFY_FUNC = Symbol('InputVerifierContractData.verify');
+
+////////////////////////////////////////////////////////////////////////////////
+// InputVerifier (private implementation)
+////////////////////////////////////////////////////////////////////////////////
+
+class InputVerifierContractDataImpl implements InputVerifierContractData {
+  readonly #owner: WeakRef<FhevmRuntime>;
+  readonly #version: HostContractVersion<'InputVerifier'>;
+  readonly #address: ChecksummedAddress;
+  readonly #eip712Domain: CoprocessorEip712Domain;
+  readonly #coprocessorSigners: ChecksummedAddress[];
+  readonly #coprocessorSignerThreshold: Uint8Number;
+  readonly #coprocessorSignersSet: Set<string>;
+
+  constructor(
+    privateToken: symbol,
+    owner: WeakRef<FhevmRuntime>,
+    parameters: {
+      readonly version: HostContractVersion<'InputVerifier'>;
+      readonly address: ChecksummedAddress;
+      readonly eip712Domain: CoprocessorEip712Domain;
+      readonly coprocessorSigners: readonly ChecksummedAddress[];
+      readonly coprocessorSignerThreshold: Uint8Number;
+    },
+  ) {
+    if (privateToken !== PRIVATE_TOKEN) {
+      throw new Error('Unauthorized');
+    }
+    this.#owner = owner;
+    this.#version = Object.freeze({ ...parameters.version });
+    this.#address = parameters.address;
+    this.#eip712Domain = { ...parameters.eip712Domain };
+    this.#coprocessorSigners = [...parameters.coprocessorSigners];
+    this.#coprocessorSignerThreshold = parameters.coprocessorSignerThreshold;
+    this.#coprocessorSignersSet = new Set(this.#coprocessorSigners.map((addr) => addr.toLowerCase()));
+
+    Object.freeze(this.#eip712Domain);
+    Object.freeze(this.#coprocessorSigners);
+    Object.freeze(this);
+  }
+
+  public get version(): HostContractVersion<'InputVerifier'> {
+    return this.#version;
+  }
+
+  public get address(): ChecksummedAddress {
+    return this.#address;
+  }
+
+  public get eip712Domain(): CoprocessorEip712Domain {
+    return this.#eip712Domain;
+  }
+
+  public get gatewayChainId(): Uint64BigInt {
+    return this.#eip712Domain.chainId;
+  }
+
+  public get coprocessorSigners(): ChecksummedAddress[] {
+    return this.#coprocessorSigners;
+  }
+
+  public get coprocessorSignerThreshold(): Uint8Number {
+    return this.#coprocessorSignerThreshold;
+  }
+
+  public get verifyingContractAddressInputVerification(): ChecksummedAddress {
+    return this.#eip712Domain.verifyingContract;
+  }
+
+  public has(signer: string): boolean {
+    return this.#coprocessorSignersSet.has(signer);
+  }
+
+  public static [VERIFY_FUNC](instance: unknown, owner: FhevmRuntime): void {
+    if (!(instance instanceof InputVerifierContractDataImpl)) {
+      throw new Error('Invalid InputVerifierContractData instance');
+    }
+    assertOwnedBy({
+      actualOwner: instance.#owner,
+      expectedOwner: owner,
+      name: 'InputVerifierContractData',
+    });
+  }
+
+  public toJSON(): Record<string, unknown> {
+    return {
+      version: this.#version,
+      address: this.#address,
+      eip712Domain: this.#eip712Domain,
+      coprocessorSigners: this.#coprocessorSigners,
+      coprocessorSignerThreshold: this.#coprocessorSignerThreshold,
+    };
+  }
+}
+
+// Prevent prototype pollution and constructor access
+Object.freeze(InputVerifierContractDataImpl.prototype);
+Object.freeze(InputVerifierContractDataImpl);
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createInputVerifierContractData(
+  owner: WeakRef<FhevmRuntime>,
+  parameters: {
+    readonly version: HostContractVersion<'InputVerifier'>;
+    readonly address: ChecksummedAddress;
+    readonly eip712Domain: CoprocessorEip712Domain;
+    readonly coprocessorSigners: readonly ChecksummedAddress[];
+    readonly coprocessorSignerThreshold: Uint8Number;
+  },
+): InputVerifierContractData {
+  return new InputVerifierContractDataImpl(PRIVATE_TOKEN, owner, parameters);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Verifies that the given `InputVerifierContractData` instance is owned
+ * by the given runtime. Throws if not.
+ */
+export function assertInputVerifierContractDataOwnedBy(data: InputVerifierContractData, owner: FhevmRuntime): void {
+  InputVerifierContractDataImpl[VERIFY_FUNC](data, owner);
+}