RFC003

@fhevm/sdk
├── @fhevm/sdk/ethers            ← Ethers.js v6 adapter: client factories, runtime config
├── @fhevm/sdk/viem              ← Viem adapter: client factories, runtime config
├── @fhevm/sdk/chains            ← FhevmChain definitions (framework-agnostic, no viem/ethers dep)
├── @fhevm/sdk/actions/base      ← Base actions (publicDecrypt, ACL checks, input proofs)
├── @fhevm/sdk/actions/encrypt   ← Encrypt actions (encrypt, generateZkProof)
├── @fhevm/sdk/actions/decrypt   ← Decrypt actions (decrypt, generateE2eTransportKeypair)
├── @fhevm/sdk/actions/chain     ← Chain utility actions (signDecryptionPermit, EIP-712, keypair ops)
├── @fhevm/sdk/actions/host      ← Host contract read actions (resolveFhevmConfig, contract data)

import { createPublicClient, createWalletClient, custom, http } from "viem";
import { sepolia as viemSepolia } from "viem/chains";
import {
  setFhevmRuntimeConfig,
  createFhevmClient,
} from "@fhevm/sdk/viem";
import { sepolia } from "@fhevm/sdk/chains";

// 1. Configure runtime (once)
setFhevmRuntimeConfig({ numberOfThreads: 4 });

// 2. Create viem provider
const provider = createPublicClient({
  chain: viemSepolia,
  transport: http(),
});

// 3. Create FHEVM client (full: encrypt + decrypt)
const client = createFhevmClient({ chain: sepolia, provider });

// Encrypt — FHE encryption key is auto-fetched and cached on first call
const encrypted = await client.encrypt({
  values: [{ type: "uint64", value: 1000n }],
  contractAddress: "0x...",
  userAddress: account.address,
});
// encrypted.externalEncryptedValues — array of ExternalEncryptedValue
// encrypted.inputProof — hex string to pass to contract

import { createFhevmEncryptClient } from "@fhevm/sdk/viem";

const client = createFhevmEncryptClient({ chain: sepolia, provider });
// client.encrypt() ✓
// client.decrypt() ✗ (type error)

import { createFhevmDecryptClient } from "@fhevm/sdk/viem";

const client = createFhevmDecryptClient({ chain: sepolia, provider });
// client.decrypt() ✓
// client.publicDecrypt() ✓
// client.encrypt() ✗ (type error)

const walletClient = createWalletClient({
  chain: viemSepolia,
  transport: custom(window.ethereum!),
  account,
});

const e2eTransportKeypair = await client.generateE2eTransportKeypair();

const signedPermit = await client.signDecryptionPermit({
  contractAddresses: ["0x..."],
  startTimestamp: Math.floor(Date.now() / 1000),
  durationDays: 365,
  signerAddress: account.address,
  signer: walletClient,
  e2eTransportKeypair,
});

const results = await client.decrypt({
  e2eTransportKeypair,
  encryptedValues: [
    { encryptedValue: "0x...", contractAddress: "0x..." },
  ],
  signedPermit,
});

import { ethers } from "ethers";
import {
  setFhevmRuntimeConfig,
  createFhevmClient,
} from "@fhevm/sdk/ethers";
import { sepolia } from "@fhevm/sdk/chains";

// 1. Configure runtime
setFhevmRuntimeConfig({ numberOfThreads: 4 });

// 2. Create ethers provider
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// 3. Create FHEVM client
const client = createFhevmClient({ chain: sepolia, provider });

// Encrypt — FHE encryption key auto-fetched and cached on first call
const encrypted = await client.encrypt({
  values: [{ type: "uint64", value: 1000n }],
  contractAddress: "0x...",
  userAddress: await signer.getAddress(),
});

// Decrypt — permit creation and signing in one step
const e2eTransportKeypair = await client.generateE2eTransportKeypair();

const signedPermit = await client.signDecryptionPermit({
  contractAddresses: ["0xContractA"],
  startTimestamp: Math.floor(Date.now() / 1000),
  durationDays: 365,
  signerAddress: await signer.getAddress(),
  signer,
  e2eTransportKeypair,
});

const results = await client.decrypt({
  e2eTransportKeypair,
  encryptedValues: [
    { encryptedValue: "0x...", contractAddress: "0xContractA" },
  ],
  signedPermit,
});

createCoreFhevm() → base client (chain, runtime, trustedClient)
  ↓ .extend() chains decorators:
  ├─ baseActions       → publicDecrypt, signDecryptionPermit, parseE2eTransportKeypair,
  │                      serializeE2eTransportKeypair, fetchFheEncryptionKeyBytes
  ├─ decryptActions    → decrypt, generateE2eTransportKeypair, createUserDecryptEIP712,
  │                      createDelegatedUserDecryptEIP712, publicDecrypt
  └─ encryptActions    → encrypt

const encrypted = await client.encrypt({
  values: [
    { type: "uint64", value: 1000n },
    { type: "bool", value: true },
    { type: "address", value: "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC" },
  ],
  contractAddress: "0x...",
  userAddress: "0x...",
});

// encrypted.externalEncryptedValues — array of ExternalEncryptedValue
// encrypted.inputProof — hex string to pass to contract

const result = await client.publicDecrypt({
  encryptedValues: [encryptedValue1, encryptedValue2],
});

// result.orderedClearValues — array of ClearValue
// result.orderedClearValues[0].value — the decrypted plaintext
// result.orderedClearValues[0].fheType — "euint32", "ebool", etc.

// 1. Generate an E2E transport key pair
const e2eTransportKeypair = await client.generateE2eTransportKeypair();

// 2. Create and sign a decrypt permit in one step
const signedPermit = await client.signDecryptionPermit({
  contractAddresses: ["0xContractA"],
  startTimestamp: Math.floor(Date.now() / 1000),
  durationDays: 365,
  signerAddress: account.address, // or await signer.getAddress() for ethers
  signer,                          // viem WalletClient or ethers Signer
  e2eTransportKeypair,
});

// 3. Decrypt
const results = await client.decrypt({
  e2eTransportKeypair,
  encryptedValues: [
    { encryptedValue: "0x...", contractAddress: "0xContractA" },
  ],
  signedPermit,
});

// results is ClearValue[] — typed based on FHE type
results[0].value;           // number, bigint, boolean, or string
results[0].fheType;         // "euint32", "ebool", "eaddress", etc.
results[0].encryptedValue;  // the original EncryptedValue

const signedPermit = await client.signDecryptionPermit({
  contractAddresses: ["0xContract..."],
  startTimestamp: Math.floor(Date.now() / 1000),
  durationDays: 1,
  signerAddress: await signer.getAddress(),
  signer,
  e2eTransportKeypair,
  onBehalfOf: "0xDataOwnerAddress...",
});

export type FhevmChain = {
  readonly id: number;
  readonly fhevm: {
    readonly contracts: FhevmChainContracts; // acl, inputVerifier, kmsVerifier
    readonly relayerUrl: string;
    readonly gateway: FhevmGatewayChain;     // decryption & inputVerification verifier addresses
  };
};

import { defineFhevmChain } from "@fhevm/sdk/chains";

const myChain = defineFhevmChain({
  id: 8453,
  fhevm: {
    contracts: {
      acl: { address: "0x..." },
      inputVerifier: { address: "0x..." },
      kmsVerifier: { address: "0x..." },
    },
    relayerUrl: "https://relayer.mychain.example.com",
    gateway: {
      id: 99999,
      contracts: {
        decryption: { address: "0x..." },
        inputVerification: { address: "0x..." },
      },
    },
  },
});

import {
  readFhevmExecutorContractData,
  readInputVerifierContractData,
  readKmsVerifierContractData,
  resolveFhevmConfig,
} from "@fhevm/sdk/actions/host";

type FhevmRuntimeConfig = {
  readonly locateFile?: (file: string) => URL;  // Custom WASM file location
  readonly logger?: Logger;                      // { debug, error } callbacks
  readonly singleThread?: boolean;               // Disable multi-threading
  readonly numberOfThreads?: number;             // Worker pool size
};

// Standalone function (tree-shakeable)
import { encrypt } from "@fhevm/sdk/actions/encrypt";
const result = await encrypt(fhevmClient, { ... });

// Client method (added by decorator)
const result = await fhevmClient.encrypt({ ... });

import { initSDK, createInstance, SepoliaConfig } from "@zama-fhe/relayer-sdk/web";

await initSDK();
const instance = await createInstance({ ...SepoliaConfig, network: "https://sepolia-rpc.com" });

const encrypted = instance.createEncryptedInput(contractAddr, userAddr);
encrypted.add32(42);
encrypted.add8(100);
const { handles, inputProof } = await encrypted.encrypt();

import { setFhevmRuntimeConfig, createFhevmClient } from "@fhevm/sdk/ethers";
import { sepolia } from "@fhevm/sdk/chains";

setFhevmRuntimeConfig({});
const client = createFhevmClient({ chain: sepolia, provider });

const encrypted = await client.encrypt({
  values: [{ type: "uint32", value: 42 }, { type: "uint8", value: 100 }],
  contractAddress: contractAddr,
  userAddress: await signer.getAddress(),
});
// encrypted.externalEncryptedValues — array of ExternalEncryptedValue
// encrypted.inputProof — hex string

import { createPublicClient, http } from "viem";
import { sepolia as viemSepolia } from "viem/chains";
import { setFhevmRuntimeConfig, createFhevmClient } from "@fhevm/sdk/viem";
import { sepolia } from "@fhevm/sdk/chains";

setFhevmRuntimeConfig({});
const provider = createPublicClient({ chain: viemSepolia, transport: http() });
const client = createFhevmClient({ chain: sepolia, provider });

const encrypted = await client.encrypt({
  values: [
    { type: "uint32", value: 42 },
    { type: "uint8", value: 100 },
  ],
  contractAddress: contractAddr,
  userAddress: account.address,
});