@fhevm/sdk 0.0.1 → 1.0.0-alpha.1

package/ethers/internal/ethers-p.ts

@@ -0,0 +1,105 @@
+import type { ethers as EthersT } from 'ethers';
+import type { TrustedClient } from '../../core/modules/ethereum/types.js';
+import type { FhevmRuntime, FhevmRuntimeConfig } from '../../core/types/coreFhevmRuntime.js';
+import type { CreateFhevmRuntimeParameters } from '../../core/runtime/CoreFhevmRuntime-p.js';
+import { createFhevmRuntime as createFhevmRuntime_ } from '../../core/runtime/CoreFhevmRuntime-p.js';
+import { verifyTrustedValue } from '../../core/base/trustedValue.js';
+import { createTrustedClient } from '../../core/modules/ethereum/createTrustedClient.js';
+import { ethereumModule } from './ethereum.js';
+import { relayerModule } from '../../core/modules/relayer/module/index.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+// Will leak in js
+export const PRIVATE_ETHERS_TOKEN = Symbol('ethers.token');
+
+////////////////////////////////////////////////////////////////////////////////
+
+let ethersFhevmRuntime: FhevmRuntime | undefined;
+let ethersFhevmRuntimeConfig: FhevmRuntimeConfig | undefined;
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Sets the global {@link FhevmRuntimeConfig} used by the ethers adapter.
+ *
+ * Must be called before any runtime or client is created.
+ * May be called multiple times with identical parameters (idempotent).
+ * Throws if called again with different parameters.
+ *
+ * @param config - The runtime configuration.
+ * @throws If a different config has already been set.
+ */
+export function setFhevmRuntimeConfig(config: FhevmRuntimeConfig): void {
+  if (ethersFhevmRuntimeConfig === undefined) {
+    ethersFhevmRuntimeConfig = { ...config };
+    return;
+  }
+  if (
+    ethersFhevmRuntimeConfig.logger !== config.logger ||
+    ethersFhevmRuntimeConfig.locateFile !== config.locateFile ||
+    ethersFhevmRuntimeConfig.singleThread !== config.singleThread ||
+    ethersFhevmRuntimeConfig.numberOfThreads !== config.numberOfThreads
+  ) {
+    throw new Error(
+      'FhevmRuntime config has already been set and cannot be changed. ' +
+        'Ensure setFhevmRuntimeConfig is called only once, or with identical parameters.',
+    );
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function getEthersRuntime(): FhevmRuntime {
+  if (ethersFhevmRuntimeConfig === undefined) {
+    throw new Error('Call setFhevmRuntimeConfig first.');
+  }
+
+  const em = ethereumModule();
+  const rm = relayerModule();
+
+  ethersFhevmRuntime ??= createFhevmRuntime({
+    ethereum: em.ethereum,
+    relayer: rm.relayer,
+    config: ethersFhevmRuntimeConfig,
+  });
+  return ethersFhevmRuntime;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Seals an ethers `ContractRunner` into an opaque {@link TrustedClient}.
+ *
+ * The returned value can be passed through the core layer without exposing
+ * the underlying ethers instance. Only the ethers adapter can later recover
+ * the original runner via {@link trustedClientToEthersContractRunner}.
+ *
+ * @param runner - The ethers contract runner to seal.
+ * @returns An opaque {@link TrustedClient} bound to the ethers origin token.
+ */
+export function ethersContractRunnerToTrustedClient<client extends EthersT.ContractRunner>(
+  runner: client,
+): TrustedClient<client> {
+  return createTrustedClient(runner, PRIVATE_ETHERS_TOKEN);
+}
+
+/**
+ * Verifies that the {@link TrustedClient} was created by the ethers adapter
+ * and extracts the original `ContractRunner`.
+ *
+ * @param trustedClient - The host client to verify.
+ * @returns The original ethers `ContractRunner`.
+ * @throws {Error} If the client was not created by {@link ethersContractRunnerToTrustedClient}.
+ */
+export function trustedClientToEthersContractRunner<client extends EthersT.ContractRunner>(
+  trustedClient: TrustedClient<client>,
+): client {
+  return verifyTrustedValue(trustedClient, PRIVATE_ETHERS_TOKEN);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createFhevmRuntime(parameters: CreateFhevmRuntimeParameters): FhevmRuntime {
+  return createFhevmRuntime_(PRIVATE_ETHERS_TOKEN, parameters);
+}

package/ethers/internal/utils.ts

@@ -0,0 +1,41 @@
+import type { ethers as EthersT } from 'ethers';
+import type { ChecksummedAddress } from '../../core/types/primitives.js';
+import type { TrustedClient } from '../../core/modules/ethereum/types.js';
+import { Contract, Interface } from 'ethers';
+import { trustedClientToEthersContractRunner } from './ethers-p.js';
+
+/**
+ * Get ethers Network from an unknown client.
+ * Supports Provider (has getNetwork) and ContractRunner (via its provider).
+ */
+export async function getNetwork(hostPublicClient: TrustedClient<EthersT.ContractRunner>): Promise<EthersT.Network> {
+  const runner = trustedClientToEthersContractRunner(hostPublicClient);
+
+  if ((runner as unknown) === undefined || (runner as unknown) === null) {
+    throw new Error('Cannot get network: client is null or undefined.');
+  }
+
+  if (
+    typeof runner === 'object' &&
+    'getNetwork' in runner &&
+    typeof (runner as Record<string, unknown>).getNetwork === 'function'
+  ) {
+    return await (runner as unknown as EthersT.Provider).getNetwork();
+  }
+
+  if (runner.provider != null) {
+    return await runner.provider.getNetwork();
+  }
+
+  throw new Error('Cannot get network: client is neither a Provider nor a ContractRunner with a provider.');
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export function getEthersContract<C>(
+  hostPublicClient: TrustedClient<EthersT.ContractRunner>,
+  contractAddress: ChecksummedAddress,
+  abi: ReadonlyArray<Record<string, unknown>>,
+): C {
+  const runner = trustedClientToEthersContractRunner(hostPublicClient);
+  return new Contract(contractAddress, new Interface(abi), runner) as unknown as C;
+}

package/ethers/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../_types/ethers/index.d.ts",
+  "module": "../_esm/ethers/index.js",
+  "main": "../_cjs/ethers/index.js"
+}

package/ethers/runtime/initFhevmDecryptRuntime.ts

@@ -0,0 +1,8 @@
+import { getEthersRuntime, PRIVATE_ETHERS_TOKEN } from '../internal/ethers-p.js';
+import { initFhevmDecryptRuntime as initFhevmDecyptRuntime_ } from '../../core/runtime/initFhevmDecryptRuntime-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function initFhevmDecryptRuntime(): Promise<void> {
+  return initFhevmDecyptRuntime_(getEthersRuntime(), PRIVATE_ETHERS_TOKEN);
+}

package/ethers/runtime/initFhevmEncryptRuntime.ts

@@ -0,0 +1,8 @@
+import { getEthersRuntime, PRIVATE_ETHERS_TOKEN } from '../internal/ethers-p.js';
+import { initFhevmEncryptRuntime as initFhevmEncryptRuntime_ } from '../../core/runtime/initFhevmEncryptRuntime-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function initFhevmEncryptRuntime(): Promise<void> {
+  return initFhevmEncryptRuntime_(getEthersRuntime(), PRIVATE_ETHERS_TOKEN);
+}

package/ethers/runtime/initFhevmRuntime.ts

@@ -0,0 +1,8 @@
+import { getEthersRuntime, PRIVATE_ETHERS_TOKEN } from '../internal/ethers-p.js';
+import { initFhevmRuntime as initFhevmRuntime_ } from '../../core/runtime/initFhevmRuntime-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function initFhevmRuntime(): Promise<void> {
+  return initFhevmRuntime_(getEthersRuntime(), PRIVATE_ETHERS_TOKEN);
+}

package/package.json

@@ -1,9 +1,97 @@
 {
   "name": "@fhevm/sdk",
   "description": "TypeScript Interface for FHEVM",
-  "version": "0.0.1",
+  "version": "1.0.0-alpha.1",
   "type": "module",
-  "main": "index.js",
+  "main": "./_cjs/index.js",
+  "module": "./_esm/index.js",
+  "types": "./_types/index.d.ts",
+  "typings": "./_types/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "*",
+    "!**/*.test.ts",
+    "!**/*.tsbuildinfo",
+    "!tsconfig.build.json"
+  ],
+  "exports": {
+    ".": {
+      "types": "./_types/index.d.ts",
+      "import": "./_esm/index.js",
+      "default": "./_cjs/index.js"
+    },
+    "./base": {
+      "types": "./_types/core/base/index.d.ts",
+      "import": "./_esm/core/base/index.js",
+      "default": "./_cjs/core/base/index.js"
+    },
+    "./chains": {
+      "types": "./_types/core/chains/index.d.ts",
+      "import": "./_esm/core/chains/index.js",
+      "default": "./_cjs/core/chains/index.js"
+    },
+    "./ethers": {
+      "types": "./_types/ethers/index.d.ts",
+      "import": "./_esm/ethers/index.js",
+      "default": "./_cjs/ethers/index.js"
+    },
+    "./types": {
+      "types": "./_types/core/types/index.d.ts",
+      "import": "./_esm/core/types/index.js",
+      "default": "./_cjs/core/types/index.js"
+    },
+    "./viem": {
+      "types": "./_types/viem/index.d.ts",
+      "import": "./_esm/viem/index.js",
+      "default": "./_cjs/viem/index.js"
+    },
+    "./actions/base": {
+      "types": "./_types/core/actions/base/index.d.ts",
+      "import": "./_esm/core/actions/base/index.js",
+      "default": "./_cjs/core/actions/base/index.js"
+    },
+    "./actions/chain": {
+      "types": "./_types/core/actions/chain/index.d.ts",
+      "import": "./_esm/core/actions/chain/index.js",
+      "default": "./_cjs/core/actions/chain/index.js"
+    },
+    "./actions/decrypt": {
+      "types": "./_types/core/actions/decrypt/index.d.ts",
+      "import": "./_esm/core/actions/decrypt/index.js",
+      "default": "./_cjs/core/actions/decrypt/index.js"
+    },
+    "./actions/encrypt": {
+      "types": "./_types/core/actions/encrypt/index.d.ts",
+      "import": "./_esm/core/actions/encrypt/index.js",
+      "default": "./_cjs/core/actions/encrypt/index.js"
+    },
+    "./actions/host": {
+      "types": "./_types/core/actions/host/index.d.ts",
+      "import": "./_esm/core/actions/host/index.js",
+      "default": "./_cjs/core/actions/host/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "ethers": ">=6",
+    "typescript": ">=5.0.4",
+    "viem": ">=2"
+  },
+  "peerDependenciesMeta": {
+    "ethers": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@noble/hashes": "2.0.1",
+    "wasm-feature-detect": "^1.8.0"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zama-ai/fhevm.git"

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.base.json",
+  "include": ["./**/*.ts"],
+  "exclude": ["./**/*.test.ts", "./**/*.test-d.ts", "./**/*.bench.ts", "./**/*.bench-d.ts"],
+  "compilerOptions": {
+    "composite": true,
+    "noEmit": true
+  }
+}

package/viem/clients/createFhevmBaseClient.ts

@@ -0,0 +1,24 @@
+import type { PublicClient } from 'viem';
+import type { FhevmChain } from '../../core/types/fhevmChain.js';
+import type { FhevmRuntime } from '../../core/types/coreFhevmRuntime.js';
+import type { FhevmOptions } from '../../core/types/coreFhevmClient.js';
+import type { FhevmBaseClient } from '../../core/types/fhevmClient.js';
+import { getViemRuntime, PRIVATE_VIEM_TOKEN } from '../internal/viem-p.js';
+import { createCoreFhevm } from '../../core/runtime/CoreFhevm-p.js';
+import { baseActions } from '../../core/clients/decorators/base.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createFhevmBaseClient<chain extends FhevmChain, publicClient extends PublicClient>(parameters: {
+  readonly publicClient: publicClient;
+  readonly chain: chain;
+  readonly options?: FhevmOptions | undefined;
+}): FhevmBaseClient<chain, FhevmRuntime, publicClient> {
+  const c = createCoreFhevm(PRIVATE_VIEM_TOKEN, {
+    chain: parameters.chain,
+    runtime: getViemRuntime(),
+    client: parameters.publicClient,
+    options: parameters.options,
+  });
+  return c.extend(baseActions);
+}

package/viem/clients/createFhevmClient.ts

@@ -0,0 +1,20 @@
+import type { PublicClient } from 'viem';
+import type { FhevmChain } from '../../core/types/fhevmChain.js';
+import type { WithAll } from '../../core/types/coreFhevmRuntime.js';
+import type { FhevmOptions } from '../../core/types/coreFhevmClient.js';
+import type { FhevmClient } from '../../core/types/fhevmClient.js';
+import { createFhevmBaseClient } from './createFhevmBaseClient.js';
+import { encryptActions } from '../decorators/encrypt.js';
+import { decryptActions } from '../decorators/decrypt.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createFhevmClient<chain extends FhevmChain, publicClient extends PublicClient>(parameters: {
+  readonly publicClient: publicClient;
+  readonly chain: chain;
+  readonly options?: FhevmOptions | undefined;
+}): FhevmClient<chain, WithAll, publicClient> {
+  const c = createFhevmBaseClient(parameters);
+
+  return c.extend(decryptActions).extend(encryptActions);
+}

package/viem/clients/createFhevmDecryptClient.ts

@@ -0,0 +1,18 @@
+import type { PublicClient } from 'viem';
+import type { FhevmChain } from '../../core/types/fhevmChain.js';
+import type { WithDecrypt } from '../../core/types/coreFhevmRuntime.js';
+import type { FhevmOptions } from '../../core/types/coreFhevmClient.js';
+import type { FhevmDecryptClient } from '../../core/types/fhevmClient.js';
+import { createFhevmBaseClient } from './createFhevmBaseClient.js';
+import { decryptActions } from '../decorators/decrypt.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createFhevmDecryptClient<chain extends FhevmChain, publicClient extends PublicClient>(parameters: {
+  readonly publicClient: publicClient;
+  readonly chain: chain;
+  readonly options?: FhevmOptions | undefined;
+}): FhevmDecryptClient<chain, WithDecrypt, publicClient> {
+  const c = createFhevmBaseClient(parameters);
+  return c.extend(decryptActions);
+}

package/viem/clients/createFhevmEncryptClient.ts

@@ -0,0 +1,21 @@
+import type { PublicClient } from 'viem';
+import type { FhevmChain } from '../../core/types/fhevmChain.js';
+import type { WithEncrypt } from '../../core/types/coreFhevmRuntime.js';
+import type { FhevmOptions } from '../../core/types/coreFhevmClient.js';
+import type { FhevmEncryptClient } from '../../core/types/fhevmClient.js';
+import { createFhevmBaseClient } from './createFhevmBaseClient.js';
+import { encryptActions } from '../decorators/encrypt.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function createFhevmEncryptClient<chain extends FhevmChain, publicClient extends PublicClient>(parameters: {
+  readonly publicClient: publicClient;
+  readonly chain: chain;
+  readonly options?: FhevmOptions | undefined;
+}): FhevmEncryptClient<chain, WithEncrypt, publicClient> {
+  const c = createFhevmBaseClient(parameters);
+
+  return c.extend(encryptActions);
+}
+
+////////////////////////////////////////////////////////////////////////////////

package/viem/decorators/decrypt.ts

@@ -0,0 +1,12 @@
+import type { FhevmChain } from '../../core/types/fhevmChain.js';
+import type { WithDecrypt } from '../../core/types/coreFhevmRuntime.js';
+import type { FhevmBase, FhevmExtension } from '../../core/types/coreFhevmClient.js';
+import type { DecryptActions } from '../../core/clients/decorators/decrypt.js';
+import { decryptModule } from '../../core/modules/decrypt/module/index.js';
+import { decryptActionsWithModule } from '../../core/clients/decorators/decrypt.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function decryptActions(fhevm: FhevmBase<FhevmChain>): FhevmExtension<DecryptActions, WithDecrypt> {
+  return decryptActionsWithModule(fhevm, decryptModule);
+}

package/viem/decorators/encrypt.ts

@@ -0,0 +1,12 @@
+import type { FhevmChain } from '../../core/types/fhevmChain.js';
+import type { WithEncrypt } from '../../core/types/coreFhevmRuntime.js';
+import type { FhevmBase, FhevmExtension } from '../../core/types/coreFhevmClient.js';
+import type { EncryptActions } from '../../core/clients/decorators/encrypt.js';
+import { encryptModule } from '../../core/modules/encrypt/module/index.js';
+import { encryptActionsWithModule } from '../../core/clients/decorators/encrypt.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function encryptActions(fhevm: FhevmBase<FhevmChain>): FhevmExtension<EncryptActions, WithEncrypt> {
+  return encryptActionsWithModule(fhevm, encryptModule);
+}

package/viem/index.ts

@@ -0,0 +1,10 @@
+export { setFhevmRuntimeConfig } from './internal/viem-p.js';
+
+export { createFhevmBaseClient } from './clients/createFhevmBaseClient.js';
+export { createFhevmClient } from './clients/createFhevmClient.js';
+export { createFhevmDecryptClient } from './clients/createFhevmDecryptClient.js';
+export { createFhevmEncryptClient } from './clients/createFhevmEncryptClient.js';
+
+export { initFhevmRuntime } from './runtime/initFhevmRuntime.js';
+export { initFhevmEncryptRuntime } from './runtime/initFhevmEncryptRuntime.js';
+export { initFhevmDecryptRuntime } from './runtime/initFhevmDecryptRuntime.js';

package/viem/internal/ethereum.ts

@@ -0,0 +1,145 @@
+import type { PublicClient, WalletClient } from 'viem';
+import type {
+  DecodeParameters,
+  DecodeReturnType,
+  EncodePackedParameters,
+  EncodePackedReturnType,
+  EncodeParameters,
+  EncodeReturnType,
+  EthereumModuleFactory,
+  GetChainIdReturnType,
+  TrustedClient,
+  ReadContractParameters,
+  RecoverTypedDataAddressParameters,
+  RecoverTypedDataAddressReturnType,
+  SignTypedDataParameters,
+  SignTypedDataReturnType,
+  NativeSigner,
+} from '../../core/modules/ethereum/types.js';
+import type { BytesHex } from '../../core/types/primitives.js';
+import { recoverTypedDataAddress as viemRecoverTypedDataAddress } from 'viem';
+import { encodePacked as viemEncodePacked, encodeAbiParameters, decodeAbiParameters } from 'viem';
+import { asChecksummedAddress } from '../../core/base/address.js';
+import { trustedClientToViemPublicClient } from './viem-p.js';
+
+////////////////////////////////////////////////////////////////////////////////
+// recoverTypedDataAddress
+////////////////////////////////////////////////////////////////////////////////
+
+export async function recoverTypedDataAddress(
+  parameters: RecoverTypedDataAddressParameters,
+): Promise<RecoverTypedDataAddressReturnType> {
+  const recoveredAddress = await viemRecoverTypedDataAddress(parameters);
+  return asChecksummedAddress(recoveredAddress);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// encodePacked
+////////////////////////////////////////////////////////////////////////////////
+
+export function encodePacked(parameters: EncodePackedParameters): EncodePackedReturnType {
+  return viemEncodePacked(parameters.types, parameters.values) as BytesHex;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// encode
+////////////////////////////////////////////////////////////////////////////////
+
+export function encode(parameters: EncodeParameters): EncodeReturnType {
+  const abiParameters = parameters.types.map((type) => ({ type }));
+  return encodeAbiParameters(abiParameters, parameters.values) as BytesHex;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// decode
+////////////////////////////////////////////////////////////////////////////////
+
+export function decode(parameters: DecodeParameters): DecodeReturnType {
+  const abiParameters = parameters.types.map((type) => ({ type }));
+  return [...decodeAbiParameters(abiParameters, parameters.encodedData as `0x${string}`)];
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// readContract
+////////////////////////////////////////////////////////////////////////////////
+
+export async function readContract(
+  hostPublicClient: TrustedClient<PublicClient>,
+  parameters: ReadContractParameters,
+): Promise<unknown> {
+  const publicClient = trustedClientToViemPublicClient(hostPublicClient);
+  return publicClient.readContract(parameters);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// getChainId
+////////////////////////////////////////////////////////////////////////////////
+
+export async function getChainId(hostPublicClient: TrustedClient<PublicClient>): Promise<GetChainIdReturnType> {
+  const publicClient = trustedClientToViemPublicClient(hostPublicClient);
+  const chainId = await publicClient.getChainId();
+  return BigInt(chainId);
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// signTypedData
+////////////////////////////////////////////////////////////////////////////////
+
+export async function signTypedData(
+  signer: NativeSigner,
+  parameters: SignTypedDataParameters,
+): Promise<SignTypedDataReturnType> {
+  const { account, primaryType, types, domain, message } = parameters;
+
+  const walletClient = signer as WalletClient;
+  if (typeof walletClient.signTypedData !== 'function') {
+    throw new Error('signer does not support signTypedData');
+  }
+
+  // Skipped: viem delegates account selection to the wallet/RPC node.
+  // Adding a getAddresses() guard here would add an extra RPC call
+  // on every sign for little benefit.
+  // Keep code if needed
+  /*
+
+      const walletAddresses = await walletClient.getAddresses();
+      if (walletAddresses.length === 0) {
+        throw new Error("No account found in wallet client");
+      }
+      const accountLower = account.toLowerCase();
+      if (!walletAddresses.some((addr) => addr.toLowerCase() === accountLower)) {
+        throw new Error(
+          `Signer address mismatch: expected ${account} but wallet contains [${walletAddresses.join(", ")}]`,
+        );
+      }
+        
+  */
+
+  const signature = await walletClient.signTypedData({
+    account,
+    domain,
+    types,
+    primaryType,
+    message,
+  });
+
+  return signature as SignTypedDataReturnType;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// ethereumModule
+////////////////////////////////////////////////////////////////////////////////
+
+export const ethereumModule: EthereumModuleFactory = () => {
+  return Object.freeze({
+    ethereum: Object.freeze({
+      decode,
+      encode,
+      encodePacked,
+      recoverTypedDataAddress,
+      signTypedData,
+      getChainId,
+      readContract,
+    }),
+  });
+};