@fhevm/sdk 0.0.1 → 1.0.0-alpha.1

package/core/host-contracts/checkPersistAllowed.ts

@@ -0,0 +1,115 @@
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import type { Handle } from '../types/encryptedTypes-p.js';
+import type { ChecksummedAddress } from '../types/primitives.js';
+import type { HandleAccountPair } from '../types/other-p.js';
+import { AclUserDecryptionError } from '../errors/AclError.js';
+import { persistAllowed } from './persistAllowed.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+  readonly options: { readonly batchRpcCalls: boolean };
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+  readonly userAddress: ChecksummedAddress;
+  readonly handleContractPairs: ReadonlyArray<{
+    readonly handle: Handle;
+    readonly contractAddress: ChecksummedAddress;
+  }>;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+export async function checkPersistAllowed(context: Context, parameters: Parameters): Promise<void> {
+  const { address, userAddress, handleContractPairs } = parameters;
+
+  if (handleContractPairs.length === 0) {
+    throw new Error('checkPersistAllowed requires at least one (handle, contractAddress) pair');
+  }
+
+  // runtime defensive check, use lowercase
+  function getKey(addr: string, handleBytes32Hex: string): string {
+    return `${addr}:${handleBytes32Hex}`.toLowerCase();
+  }
+
+  // 1. Verify rule: userAddress !== contractAddress
+  for (const pair of handleContractPairs) {
+    if (parameters.userAddress.toLowerCase() === pair.contractAddress.toLowerCase()) {
+      throw new AclUserDecryptionError({
+        contractAddress: address,
+        message: `userAddress ${userAddress} should not be equal to contractAddress when requesting user decryption!`,
+      });
+    }
+  }
+
+  // 2. Collect all unique (address, handle) pairs to avoid duplicate RPC calls
+  const allChecks: HandleAccountPair[] = [];
+  const seenKeys = new Set<string>();
+
+  for (const pair of handleContractPairs) {
+    // User check (runtime defensive check, use lowercase)
+    const userKey = getKey(parameters.userAddress, pair.handle.bytes32Hex);
+    if (!seenKeys.has(userKey)) {
+      seenKeys.add(userKey);
+      allChecks.push({
+        handle: pair.handle,
+        account: parameters.userAddress,
+      });
+    }
+    // Contract check (runtime defensive check, use lowercase)
+    const contractKey = getKey(pair.contractAddress, pair.handle.bytes32Hex);
+    if (!seenKeys.has(contractKey)) {
+      seenKeys.add(contractKey);
+      allChecks.push({
+        handle: pair.handle,
+        account: pair.contractAddress,
+      });
+    }
+  }
+
+  if (allChecks.length === 0) {
+    throw new Error('checkPersistAllowed: no ACL checks to perform (unexpected empty dedup result)');
+  }
+
+  // 3. Single batched RPC call for all unique checks
+  const allResults = await persistAllowed(context, {
+    address,
+    pairs: allChecks,
+  });
+
+  // 4. Build result map for lookup
+  const resultMap = new Map<string, boolean>();
+  for (const [i, check] of allChecks.entries()) {
+    const result = allResults[i];
+    // tsc: noUncheckedIndexedAccess
+    if (result === undefined) {
+      throw new Error(`Missing result at index ${i}`);
+    }
+    const key = getKey(check.account, check.handle.bytes32Hex);
+    resultMap.set(key, result);
+  }
+
+  for (const pair of handleContractPairs) {
+    // 5. Verify user permissions
+    const userKey = getKey(parameters.userAddress, pair.handle.bytes32Hex);
+    if (resultMap.get(userKey) !== true) {
+      throw new AclUserDecryptionError({
+        contractAddress: address,
+        message: `User ${parameters.userAddress} is not authorized to decrypt handle ${pair.handle.bytes32Hex}!`,
+      });
+    }
+
+    // 6. Verify contract permissions
+    const contractKey = getKey(pair.contractAddress, pair.handle.bytes32Hex);
+    if (resultMap.get(contractKey) !== true) {
+      throw new AclUserDecryptionError({
+        contractAddress: address,
+        message: `Dapp contract ${pair.contractAddress} is not authorized to user decrypt handle ${pair.handle.bytes32Hex}!`,
+      });
+    }
+  }
+}

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

@@ -0,0 +1,47 @@
+import type { Bytes32Hex, ChecksummedAddress } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { assertIsBytes32Hex } from '../base/bytes.js';
+import { decryptionResultTypehashAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+};
+
+type ReturnType = Bytes32Hex;
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @internal
+ * Reads the decryption result typehash from the given contract.
+ * The result is not cached; each call performs a fresh on-chain read.
+ */
+export async function decryptionResultTypehash(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: decryptionResultTypehashAbi,
+    args: [],
+    functionName: decryptionResultTypehashAbi[0].name,
+  });
+
+  try {
+    assertIsBytes32Hex(res, {});
+  } catch (e) {
+    throw new Error(`Invalid decryption result typehash.`, {
+      cause: e,
+    });
+  }
+
+  return res;
+}

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

@@ -0,0 +1,75 @@
+import type { ChecksummedAddress, Uint64BigInt } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { isChecksummedAddress } from '../base/address.js';
+import { isUint64BigInt } from '../base/uint.js';
+import { eip712DomainAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+};
+
+export type Eip712DomainReturnType = {
+  name: string;
+  version: string;
+  chainId: Uint64BigInt;
+  verifyingContract: ChecksummedAddress;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @internal
+ * Reads the EIP-712 domain from the given contract.
+ * The result is not cached; each call performs a fresh on-chain read.
+ */
+export async function eip712Domain(context: Context, parameters: Parameters): Promise<Eip712DomainReturnType> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: eip712DomainAbi,
+    args: [],
+    functionName: eip712DomainAbi[0].name,
+  });
+
+  if (!Array.isArray(res) || res.length < 5) {
+    throw new Error(`Invalid eip712Domain result.`);
+  }
+
+  const unknownName = res[1] as unknown;
+  const unknownVersion = res[2] as unknown;
+  const unknownChainId = res[3] as unknown;
+  const unknownVerifyingContract = res[4] as unknown;
+
+  if (typeof unknownName !== 'string') {
+    throw new Error('Invalid EIP-712 name version.');
+  }
+
+  if (typeof unknownVersion !== 'string') {
+    throw new Error('Invalid EIP-712 domain version.');
+  }
+
+  if (!isUint64BigInt(unknownChainId)) {
+    throw new Error('Invalid EIP-712 domain chainId.');
+  }
+
+  if (!isChecksummedAddress(unknownVerifyingContract)) {
+    throw new Error('Invalid EIP-712 domain chainId.');
+  }
+
+  return {
+    name: unknownName,
+    version: unknownVersion,
+    chainId: unknownChainId,
+    verifyingContract: unknownVerifyingContract,
+  };
+}

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

@@ -0,0 +1,47 @@
+import type { Bytes32Hex, ChecksummedAddress } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { assertIsBytes32Hex } from '../base/bytes.js';
+import { eip712InputVerificationTypehashAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+};
+
+type ReturnType = Bytes32Hex;
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @internal
+ * Reads the EIP-712 input verification typehash from the given contract.
+ * The result is not cached; each call performs a fresh on-chain read.
+ */
+export async function eip712InputVerificationTypehash(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: eip712InputVerificationTypehashAbi,
+    args: [],
+    functionName: eip712InputVerificationTypehashAbi[0].name,
+  });
+
+  try {
+    assertIsBytes32Hex(res, {});
+  } catch (e) {
+    throw new Error(`Invalid eip712 input verification typehash.`, {
+      cause: e,
+    });
+  }
+
+  return res;
+}

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

@@ -0,0 +1,47 @@
+import type { ChecksummedAddress } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { assertIsChecksummedAddress } from '../base/address.js';
+import { getACLAddressAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+};
+
+type ReturnType = ChecksummedAddress;
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @internal
+ * Reads the ACL contract address from the given contract.
+ * The result is not cached; each call performs a fresh on-chain read.
+ */
+export async function getAclAddress(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: getACLAddressAbi,
+    args: [],
+    functionName: getACLAddressAbi[0].name,
+  });
+
+  try {
+    assertIsChecksummedAddress(res, {});
+  } catch (e) {
+    throw new Error(`Invalid ACL address.`, {
+      cause: e,
+    });
+  }
+
+  return res;
+}

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

@@ -0,0 +1,136 @@
+import type { ChecksummedAddress, Uint8Number } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { assertIsChecksummedAddressArray } from '../base/address.js';
+import { asUint8Number, isUint8 } from '../base/uint.js';
+import { executeWithBatching } from '../base/promise.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+import { getCoprocessorSignersAbi, getThresholdAbi } from './abi-fragments/fragments.js';
+import { CACHE_TTL_24H, createCachedFetch } from '../base/cachedFetch.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+  readonly options: { readonly batchRpcCalls: boolean };
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+};
+
+type ReturnType = {
+  readonly threshold: Uint8Number;
+  readonly signers: readonly ChecksummedAddress[];
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+const cachedGetCoprocessorContextSignersAndThreshold = createCachedFetch<Context, Parameters, ReturnType>({
+  executeFn: _getCoprocessorContextSignersAndThreshold,
+  cacheKeyFn: (context, params) => `${context.runtime.uid.toLowerCase()}:${params.address.toLowerCase()}`,
+  // Signers are not Use long TTL
+  ttlMs: CACHE_TTL_24H,
+});
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Reads the global Coprocessor signers and threshold.
+ *
+ * @param parameters.address - The checksummed address of the InputVerifier 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.
+ */
+export function getCoprocessorContextSignersAndThreshold(
+  context: Context,
+  parameters: Parameters & { readonly forceRefresh?: boolean },
+): Promise<ReturnType> {
+  return cachedGetCoprocessorContextSignersAndThreshold.execute(context, parameters);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+async function _getCoprocessorContextSignersAndThreshold(
+  context: Context,
+  parameters: Parameters,
+): Promise<ReturnType> {
+  ////////////////////////////////////////////////////////////////////////////
+  //
+  // Important remark:
+  // =================
+  // Do NOTE USE `Promise.all` here!
+  // You may get a server response 500 Internal Server Error
+  // "Batch of more than 3 requests are not allowed on free tier, to use this
+  // feature register paid account at drpc.org"
+  //
+  ////////////////////////////////////////////////////////////////////////////
+
+  const rpcCalls = [() => _getThreshold(context, parameters), () => _getCoprocessorSigners(context, parameters)];
+
+  const res = await executeWithBatching<unknown>(rpcCalls, context.options.batchRpcCalls);
+
+  const threshold = res[0];
+  const coprocessorSigners = res[1];
+
+  if (!isUint8(threshold)) {
+    throw new Error(`Invalid InputVerifier coprocessor signers threshold.`);
+  }
+
+  try {
+    assertIsChecksummedAddressArray(coprocessorSigners, {});
+  } catch (e) {
+    throw new Error(`Invalid InputVerifier coprocessor signers addresses.`, {
+      cause: e,
+    });
+  }
+
+  return Object.freeze({
+    threshold: asUint8Number(Number(threshold)),
+    signers: coprocessorSigners,
+  });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+async function _getThreshold(context: Context, parameters: Parameters): Promise<Uint8Number> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: getThresholdAbi,
+    args: [],
+    functionName: getThresholdAbi[0].name,
+  });
+
+  if (!isUint8(res)) {
+    throw new Error(`Invalid threshold.`);
+  }
+
+  return Number(res) as Uint8Number;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+async function _getCoprocessorSigners(context: Context, parameters: Parameters): Promise<ChecksummedAddress[]> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: getCoprocessorSignersAbi,
+    args: [],
+    functionName: getCoprocessorSignersAbi[0].name,
+  });
+
+  try {
+    assertIsChecksummedAddressArray(res, {});
+  } catch (e) {
+    throw new Error(`Invalid coprocessor signers addresses.`, {
+      cause: e,
+    });
+  }
+
+  return res;
+}

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

@@ -0,0 +1,47 @@
+import type { ChecksummedAddress } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { assertIsChecksummedAddressArray } from '../base/address.js';
+import { getCoprocessorSignersAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+};
+
+type ReturnType = ChecksummedAddress[];
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @internal
+ * Reads the coprocessor signers addresses from the given contract.
+ * The result is not cached; each call performs a fresh on-chain read.
+ */
+export async function getCoprocessorSigners(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: getCoprocessorSignersAbi,
+    args: [],
+    functionName: getCoprocessorSignersAbi[0].name,
+  });
+
+  try {
+    assertIsChecksummedAddressArray(res, {});
+  } catch (e) {
+    throw new Error(`Invalid coprocessor signers addresses.`, {
+      cause: e,
+    });
+  }
+
+  return res;
+}

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

@@ -0,0 +1,74 @@
+import type { ChecksummedAddress, Uint256BigInt } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { getCurrentKmsContextIdAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+import { getVersion, isVersionStrictlyBefore } from './HostContractVersion-p.js';
+import { assertIsUint256 } 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 = Uint256BigInt;
+
+////////////////////////////////////////////////////////////////////////////////
+
+const cachedGetCurrentKmsContextId = createCachedFetch<Context, Parameters, ReturnType>({
+  executeFn: _getCurrentKmsContextId,
+  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 current KMS context ID for a KMSVerifier contract.
+ *
+ * Results are cached per (runtime, address) with a 24-hour TTL.
+ * Concurrent callers share a single in-flight RPC request (deduplication).
+ *
+ * @param parameters.address - The checksummed address of the KMSVerifier 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.
+ */
+export function getCurrentKmsContextId(
+  context: Context,
+  parameters: Parameters & { readonly forceRefresh?: boolean | undefined },
+): Promise<ReturnType> {
+  return cachedGetCurrentKmsContextId.execute(context, parameters);
+}
+
+async function _getCurrentKmsContextId(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const version = await getVersion(context, parameters);
+  // getCurrentKmsContextId has been introduced in KMSVerifier.sol v0.2.0
+  if (isVersionStrictlyBefore(version, { major: 0, minor: 2 })) {
+    return 0n as Uint256BigInt;
+  }
+
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: getCurrentKmsContextIdAbi,
+    args: [],
+    functionName: getCurrentKmsContextIdAbi[0].name,
+  });
+
+  try {
+    assertIsUint256(res, {});
+  } catch (e) {
+    throw new Error(`Invalid KMS Context Id.`, {
+      cause: e,
+    });
+  }
+
+  return BigInt(res) as Uint256BigInt;
+}

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

@@ -0,0 +1,47 @@
+import type { ChecksummedAddress } from '../types/primitives.js';
+import type { FhevmRuntime } from '../types/coreFhevmRuntime.js';
+import { assertIsChecksummedAddress } from '../base/address.js';
+import { getFHEVMExecutorAddressAbi } from './abi-fragments/fragments.js';
+import { getTrustedClient } from '../runtime/CoreFhevm-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+type Context = {
+  readonly runtime: FhevmRuntime;
+  readonly client: NonNullable<object>;
+};
+
+type Parameters = {
+  readonly address: ChecksummedAddress;
+};
+
+type ReturnType = ChecksummedAddress;
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * @internal
+ * Reads the FHEVMExecutor contract address from the given contract.
+ * The result is not cached; each call performs a fresh on-chain read.
+ */
+export async function getFhevmExecutorAddress(context: Context, parameters: Parameters): Promise<ReturnType> {
+  const trustedClient = getTrustedClient(context);
+  const address = parameters.address;
+
+  const res = await context.runtime.ethereum.readContract(trustedClient, {
+    address: address,
+    abi: getFHEVMExecutorAddressAbi,
+    args: [],
+    functionName: getFHEVMExecutorAddressAbi[0].name,
+  });
+
+  try {
+    assertIsChecksummedAddress(res, {});
+  } catch (e) {
+    throw new Error(`Invalid FHEVMExecutor address.`, {
+      cause: e,
+    });
+  }
+
+  return res;
+}