@fhevm/sdk 0.0.1 → 1.0.0-alpha.1

package/core/types/encryptedTypes-p.ts

@@ -0,0 +1,226 @@
+import type {
+  EncryptionBits,
+  FheType,
+  FheTypeId,
+  FheTypeToIdMap,
+  FheTypeToValueTypeNameMap,
+  SolidityPrimitiveTypeName,
+} from './fheType.js';
+import type {
+  Bytes21Hex,
+  Bytes32,
+  Bytes32Hex,
+  Bytes32HexNo0x,
+  TypedValueOfBase,
+  Uint64BigInt,
+  Uint8Number,
+  ValueTypeName,
+} from './primitives.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+// Brand
+declare const encryptedValueBrand: unique symbol;
+declare const inputBrand: unique symbol;
+declare const computedBrand: unique symbol;
+
+export type EncryptedValueBrand = { readonly [encryptedValueBrand]: never };
+export type InputBrand = { readonly [inputBrand]: never };
+export type ComputedBrand = { readonly [computedBrand]: never };
+
+////////////////////////////////////////////////////////////////////////////////
+
+export type InputHandleBytes32 = Bytes32 & EncryptedValueBrand & InputBrand;
+export type InputHandleBytes32Hex = Bytes32Hex & EncryptedValueBrand & InputBrand;
+export type InputHandleBytes32HexNo0x = Bytes32HexNo0x & EncryptedValueBrand & InputBrand;
+
+////////////////////////////////////////////////////////////////////////////////
+
+export type ComputedHandleBytes32 = Bytes32 & EncryptedValueBrand & ComputedBrand;
+export type ComputedHandleBytes32Hex = Bytes32Hex & EncryptedValueBrand & ComputedBrand;
+export type ComputedHandleBytes32HexNo0x = Bytes32HexNo0x & EncryptedValueBrand & ComputedBrand;
+
+////////////////////////////////////////////////////////////////////////////////
+
+// Branded bytes
+export type HandleBytes32 = ComputedHandleBytes32 | InputHandleBytes32;
+export type HandleBytes32Hex = ComputedHandleBytes32Hex | InputHandleBytes32Hex;
+export type HandleBytes32HexNo0x = ComputedHandleBytes32HexNo0x | InputHandleBytes32HexNo0x;
+
+////////////////////////////////////////////////////////////////////////////////
+
+// Base interface — class implements this
+export interface HandleBaseV0 {
+  readonly bytes32Hex: HandleBytes32Hex;
+  readonly bytes32: HandleBytes32;
+  readonly bytes32HexNo0x: HandleBytes32HexNo0x;
+  readonly hash21: Bytes21Hex;
+  readonly chainId: Uint64BigInt;
+  readonly fheTypeId: FheTypeId;
+  readonly fheType: FheType;
+  readonly clearType: ValueTypeName;
+  readonly version: Uint8Number;
+  readonly index: Uint8Number;
+  readonly encryptionBits: EncryptionBits;
+  readonly solidityPrimitiveTypeName: SolidityPrimitiveTypeName;
+  readonly isComputed: boolean;
+  readonly isExternal: boolean;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+// Typed base
+export interface HandleOfTypeBaseV0<etype extends FheType> extends HandleBaseV0 {
+  readonly fheTypeId: FheTypeToIdMap[etype];
+  readonly fheType: etype;
+}
+
+// Computed typed base
+export interface ComputedHandleOfTypeBaseV0<etype extends FheType> extends HandleOfTypeBaseV0<etype> {
+  readonly bytes32Hex: ComputedHandleBytes32Hex;
+  readonly bytes32: ComputedHandleBytes32;
+  readonly bytes32HexNo0x: ComputedHandleBytes32HexNo0x;
+  readonly isComputed: true;
+  readonly isExternal: false;
+}
+
+// External typed base
+export interface InputHandleOfTypeBaseV0<etype extends FheType> extends HandleOfTypeBaseV0<etype> {
+  readonly bytes32Hex: InputHandleBytes32Hex;
+  readonly bytes32: InputHandleBytes32;
+  readonly bytes32HexNo0x: InputHandleBytes32HexNo0x;
+  readonly index: Uint8Number;
+  readonly isComputed: false;
+  readonly isExternal: true;
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// Public types
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * An encrypted FHE value (`handle` in `FHE.sol` / FHEVM whitepaper).
+ * Either a {@link ComputedHandle} (verified, on-chain) or an
+ * {@link InputHandle} (unverified input). Narrowable via `isExternal`.
+ */
+export type Handle<etype extends FheType = FheType> = ComputedHandle<etype> | InputHandle<etype>;
+
+/** A computed encrypted value — verified on-chain, result of an FHE operation. */
+export type ComputedHandle<etype extends FheType = FheType> = {
+  [K in etype]: ComputedHandleOfTypeBaseV0<K>;
+}[etype];
+
+/** An unverified encrypted value (`inputHandle` in `FHE.sol`). */
+export type InputHandle<etype extends FheType = FheType> = {
+  [K in etype]: InputHandleOfTypeBaseV0<K>;
+}[etype];
+
+// /**
+//  * Alias for {@link EncryptedValuePipo} using `FHE.sol` terminology.
+//  * In `FHE.sol`, a `handle` is the `bytes32` reference to any encrypted value.
+//  */
+// export type HandlePipo<etype extends FheType = FheType> = EncryptedValuePipo<etype>;
+
+// /**
+//  * Alias for {@link ExternalEncryptedValuePipo} using `FHE.sol` terminology.
+//  * In `FHE.sol`, an `inputHandle` is an encrypted value that has not yet been
+//  * verified on-chain via `InputVerifier.sol`.
+//  */
+// export type InputHandlePipo<etype extends FheType = FheType> = ExternalEncryptedValuePipo<etype>;
+
+// /** Alias for {@link ComputedEncryptedValuePipo} using `FHE.sol` terminology. */
+// export type ComputedHandlePipo<etype extends FheType = FheType> = ComputedEncryptedValuePipo<etype>;
+
+// ////////////////////////////////////////////////////////////////////////////////
+// // Typed shortcuts
+// ////////////////////////////////////////////////////////////////////////////////
+
+// /** Encrypted boolean (`ebool` in Solidity). */
+// export type EboolPipo = EncryptedValuePipo<'ebool'>;
+// /** Encrypted unsigned 8-bit integer (`euint8` in Solidity). */
+// export type Euint8Pipo = EncryptedValuePipo<'euint8'>;
+// /** Encrypted unsigned 16-bit integer (`euint16` in Solidity). */
+// export type Euint16Pipo = EncryptedValuePipo<'euint16'>;
+// /** Encrypted unsigned 32-bit integer (`euint32` in Solidity). */
+// export type Euint32Pipo = EncryptedValuePipo<'euint32'>;
+// /** Encrypted unsigned 64-bit integer (`euint64` in Solidity). */
+// export type Euint64Pipo = EncryptedValuePipo<'euint64'>;
+// /** Encrypted unsigned 128-bit integer (`euint128` in Solidity). */
+// export type Euint128Pipo = EncryptedValuePipo<'euint128'>;
+// /** Encrypted unsigned 256-bit integer (`euint256` in Solidity). */
+// export type Euint256Pipo = EncryptedValuePipo<'euint256'>;
+// /** Encrypted address (`eaddress` in Solidity). */
+// export type EaddressPipo = EncryptedValuePipo<'eaddress'>;
+
+// /** Unverified encrypted boolean (`externalEbool` in Solidity). Requires on-chain verification before use. */
+// export type ExternalEboolPipo = ExternalEncryptedValuePipo<'ebool'>;
+// /** Unverified encrypted unsigned 8-bit integer (`externalEuint8` in Solidity). */
+// export type ExternalEuint8Pipo = ExternalEncryptedValuePipo<'euint8'>;
+// /** Unverified encrypted unsigned 16-bit integer (`externalEuint16` in Solidity). */
+// export type ExternalEuint16Pipo = ExternalEncryptedValuePipo<'euint16'>;
+// /** Unverified encrypted unsigned 32-bit integer (`externalEuint32` in Solidity). */
+// export type ExternalEuint32Pipo = ExternalEncryptedValuePipo<'euint32'>;
+// /** Unverified encrypted unsigned 64-bit integer (`externalEuint64` in Solidity). */
+// export type ExternalEuint64Pipo = ExternalEncryptedValuePipo<'euint64'>;
+// /** Unverified encrypted unsigned 128-bit integer (`externalEuint128` in Solidity). */
+// export type ExternalEuint128Pipo = ExternalEncryptedValuePipo<'euint128'>;
+// /** Unverified encrypted unsigned 256-bit integer (`externalEuint256` in Solidity). */
+// export type ExternalEuint256Pipo = ExternalEncryptedValuePipo<'euint256'>;
+// /** Unverified encrypted address (`externalEaddress` in Solidity). */
+// export type ExternalEaddressPipo = ExternalEncryptedValuePipo<'eaddress'>;
+
+// ////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Any value that can be interpreted as an encrypted value (bytes32 handle).
+ *
+ * - `Uint8Array` — raw 32-byte handle (`Bytes32`)
+ * - `string` — 0x-prefixed hex-encoded 32-byte handle (`Bytes32Hex`, e.g. `"0xabcd..."`)
+ * - `{ bytes32Hex: string }` — object with a hex-encoded handle property
+ * - `EncryptedValue` — an already-parsed encrypted value
+ */
+export type EncryptedValueLike = Uint8Array | string | { readonly bytes32Hex: string };
+
+// export type HandleLike = EncryptedValueLike;
+
+// /**
+//  * Any value that can be interpreted as an external encrypted value (bytes32 input handle).
+//  * An input handle is a user-encrypted value that has not yet been verified on-chain via `InputVerifier.sol`.
+//  *
+//  * - `Uint8Array` — raw 32-byte handle (`Bytes32`)
+//  * - `string` — 0x-prefixed hex-encoded 32-byte handle (`Bytes32Hex`, e.g. `"0xabcd..."`)
+//  * - `{ bytes32Hex: string }` — object with a hex-encoded handle property
+//  * - `ExternalEncryptedValue` — an already-parsed external encrypted value
+//  */
+// export type ExternalEncryptedValueLike =
+//   | Uint8Array
+//   | string
+//   | { readonly bytes32Hex: string }
+//   | ExternalEncryptedValuePipo;
+
+// export type InputHandleLike = ExternalEncryptedValueLike;
+
+// ////////////////////////////////////////////////////////////////////////////////
+
+export type ClearValueOfFheType<etype extends FheType> = TypedValueOfBase<ClearValueTypeName<etype>> & {
+  readonly handle: Handle<etype>;
+};
+
+/**
+ * The decrypted clear value of an FHE encrypted value.
+ * @typeParam T - The FHE type (e.g. `"euint8"`, `"ebool"`). Defaults to all types.
+ */
+export type ClearValue<etype extends FheType = FheType> = {
+  [K in etype]: ClearValueOfFheType<K>;
+}[etype];
+
+export type ClearValueTypeName<etype extends FheType = FheType> = FheTypeToValueTypeNameMap[etype];
+
+export type ClearBool = ClearValue<'ebool'>;
+export type ClearUint8 = ClearValue<'euint8'>;
+export type ClearUint16 = ClearValue<'euint16'>;
+export type ClearUint32 = ClearValue<'euint32'>;
+export type ClearUint64 = ClearValue<'euint64'>;
+export type ClearUint128 = ClearValue<'euint128'>;
+export type ClearUint256 = ClearValue<'euint256'>;
+export type ClearAddress = ClearValue<'eaddress'>;

package/core/types/encryptedTypes.ts

@@ -0,0 +1,41 @@
+import type { FheType } from './fheType.js';
+import type { Bytes32Hex } from './primitives.js';
+
+////////////////////////////////////////////////////////////////////////////////
+// Public types
+////////////////////////////////////////////////////////////////////////////////
+
+declare const etype: unique symbol;
+declare const eValueBrand: unique symbol;
+
+export type EValueBrand = { readonly [eValueBrand]: never };
+
+type EValue<T extends FheType> = Bytes32Hex &
+  EValueBrand & {
+    readonly [etype]: T;
+  };
+
+export type ETypedValue<T extends FheType = FheType> = {
+  [K in T]: EValue<K>;
+}[T];
+
+export type Ebool = ETypedValue<'ebool'>;
+export type Euint8 = ETypedValue<'euint8'>;
+export type Euint16 = ETypedValue<'euint16'>;
+export type Euint32 = ETypedValue<'euint32'>;
+export type Euint64 = ETypedValue<'euint64'>;
+export type Euint128 = ETypedValue<'euint128'>;
+export type Euint256 = ETypedValue<'euint256'>;
+export type Eaddress = ETypedValue<'eaddress'>;
+
+export type EncryptedValue = ETypedValue;
+
+/**
+ * Any value that can be interpreted as an encrypted value (bytes32 handle).
+ *
+ * - `Uint8Array` — raw 32-byte handle (`Bytes32`)
+ * - `string` — 0x-prefixed hex-encoded 32-byte handle (`Bytes32Hex`, e.g. `"0xabcd..."`)
+ * - `{ bytes32Hex: string }` — object with a hex-encoded handle property
+ * - `EncryptedValue` — an already-parsed encrypted value
+ */
+export type EncryptedValueLike = Uint8Array | string | { readonly bytes32Hex: string };

package/core/types/fheEncryptionKey.ts

@@ -0,0 +1,106 @@
+import type { Bytes, UintNumber } from './primitives.js';
+import type { Prettify } from './utils.js';
+
+/**
+ * Configuration for fetching a TFHE Public Key Encryption (PKE) Common Reference
+ * String (CRS) from a remote URL.
+ *
+ * Typically obtained from the <relayer-url>/keyurl response, which provides
+ * the URLs for fetching the data.
+ */
+export type FheEncryptionCrsSource = {
+  /** Unique identifier for the CRS provided by the relayer */
+  readonly id: string;
+  /** URL from which to fetch the CRS bytes */
+  readonly url: string;
+  /** The CRS capacity (always 2048 in the current configuration). */
+  readonly capacity: number;
+};
+
+/**
+ * Configuration for fetching a TFHE public key from a remote URL.
+ *
+ * Typically obtained from the <relayer-url>/keyurl response, which provides
+ * the URLs for fetching the data.
+ */
+export type FheEncryptionPublicKeySource = {
+  /** Unique identifier for the public key provided by the relayer */
+  readonly id: string;
+  /** URL from which to fetch the public key bytes */
+  readonly url: string;
+};
+
+/**
+ * URL configuration for fetching TFHE PKE (Public Key Encryption) parameters.
+ */
+export type FheEncryptionKeySource = {
+  /** URL configuration for the TFHE compact public key */
+  readonly publicKeySource: FheEncryptionPublicKeySource;
+  /** URL configuration for the PKE CRS (Common Reference String) */
+  readonly crsSource: FheEncryptionCrsSource;
+  /** Metadata about the key origin (relayer URL, chain ID) */
+  readonly metadata: FheEncryptionKeyMetadata;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+export declare const FheEncryptionPublicKeyBrand: unique symbol;
+export declare const FheEncryptionCrsBrand: unique symbol;
+
+////////////////////////////////////////////////////////////////////////////////
+
+export type FheEncryptionPublicKey = {
+  readonly [FheEncryptionPublicKeyBrand]: never;
+  readonly id: string;
+};
+
+export type FheEncryptionPublicKeyBytes = Prettify<
+  Omit<FheEncryptionPublicKey, typeof FheEncryptionPublicKeyBrand> & {
+    readonly bytes: Bytes;
+  }
+>;
+
+////////////////////////////////////////////////////////////////////////////////
+
+// Generated via a KMS ceremony
+// Defined by TFHE-rs
+export type FheEncryptionCrs = {
+  readonly [FheEncryptionCrsBrand]: never;
+  readonly id: string;
+  readonly capacity: UintNumber;
+};
+
+export type FheEncryptionCrsBytes = Prettify<
+  Omit<FheEncryptionCrs, typeof FheEncryptionCrsBrand> & {
+    readonly bytes: Bytes;
+  }
+>;
+
+////////////////////////////////////////////////////////////////////////////////
+
+export type FheEncryptionKeyMetadata = {
+  readonly relayerUrl: string;
+  readonly chainId: number;
+};
+
+export type FheEncryptionKeyWasm = {
+  readonly publicKey: FheEncryptionPublicKey;
+  readonly crs: FheEncryptionCrs;
+  readonly metadata: FheEncryptionKeyMetadata;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+export type FheEncryptionKeyBytes = {
+  readonly publicKeyBytes: FheEncryptionPublicKeyBytes;
+  readonly crsBytes: FheEncryptionCrsBytes;
+  readonly metadata: FheEncryptionKeyMetadata;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+export type FheEncryptionKeyUrls = {
+  readonly publicKeyUrl: string;
+  readonly crsUrl: string;
+  readonly metadata: FheEncryptionKeyMetadata;
+};

package/core/types/fheType.ts

@@ -0,0 +1,137 @@
+import type { UintNormalizedMap, UintValueTypeMap, ValueTypeBitsMap, ValueTypeMap } from './primitives.js';
+
+////////////////////////////////////////////////////////////////////////////////
+//
+// FheType
+//
+////////////////////////////////////////////////////////////////////////////////
+
+export type FheTypeToValueTypeMap = {
+  readonly ebool: 'bool';
+  //euint4 has been deprecated
+  readonly euint8: 'uint8';
+  readonly euint16: 'uint16';
+  readonly euint32: 'uint32';
+  readonly euint64: 'uint64';
+  readonly euint128: 'uint128';
+  readonly euint256: 'uint256';
+  readonly eaddress: 'address';
+};
+
+// Compile-time proof that keys match FheType exactly.
+// Missing or extra keys will cause a TS error.
+type AssertFheTypeKeys<T extends Readonly<Record<FheType, unknown>>> = T;
+
+export type FheTypeToIdMap = AssertFheTypeKeys<
+  Readonly<{
+    ebool: 0;
+    //euint4: 1; has been deprecated
+    euint8: 2;
+    euint16: 3;
+    euint32: 4;
+    euint64: 5;
+    euint128: 6;
+    eaddress: 7;
+    euint256: 8;
+  }>
+>;
+
+/**
+ * **FHE Type Mapping for Input Builders**
+ * * Maps the **number of encrypted bits** used by a FHEVM primary type
+ * to its corresponding **FheTypeId**. This constant is primarily used by
+ * `EncryptedInput` and `RelayerEncryptedInput` builders to determine the correct
+ * input type and calculate the total required bit-length.
+ *
+ * **Structure: \{ Encrypted Bit Length: FheTypeId \}**
+ *
+ * | Bits | FheTypeId | FHE Type Name | Note |
+ * | :--- | :-------- | :------------ | :--- |
+ * | 2    | 0         | `ebool`         | The boolean type. |
+ * | (N/A)| 1         | `euint4`        | **Deprecated** and omitted from this map. |
+ * | 8    | 2         | `euint8`        | |
+ * | 16   | 3         | `euint16`       | |
+ * | 32   | 4         | `euint32`       | |
+ * | 64   | 5         | `euint64`       | |
+ * | 128  | 6         | `euint128`      | |
+ * | 160  | 7         | `eaddress`      | Used for encrypted Ethereum addresses. |
+ * | 256  | 8         | `euint256`      | The maximum supported integer size. |
+ */
+// eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+export type FheType = keyof FheTypeToValueTypeMap & string;
+
+export type EuintType = keyof UintToEuintMap;
+export type FheTypeId = FheTypeToIdMap[keyof FheTypeToIdMap];
+
+// Reverse of FheTypeToValueTypeMap: "bool" → "ebool", "uint8" → "euint8", etc.
+export type ValueTypeNameToFheTypeMap = {
+  [etype in FheType as FheTypeToValueTypeMap[etype]]: etype;
+};
+
+/**
+ * The JavaScript type of the decrypted (clear) value for a given FHE type.
+ *
+ * | FheType      | ClearValueType   |
+ * | ------------ | ---------------- |
+ * | `"ebool"`    | `boolean`        |
+ * | `"euint8"`   | `Uint8Number`    |
+ * | `"euint16"`  | `Uint16Number`   |
+ * | `"euint32"`  | `Uint32Number`   |
+ * | `"euint64"`  | `Uint64BigInt`   |
+ * | `"euint128"` | `Uint128BigInt`  |
+ * | `"euint256"` | `Uint256BigInt`  |
+ * | `"eaddress"` | `Address`        |
+ *
+ * @typeParam T - The FHE type. Defaults to the union of all clear value types.
+ */
+export type ClearValueType<etype extends FheType = FheType> = ValueTypeMap[FheTypeToValueTypeMap[etype]];
+
+// Same as ClearValueType but as a full map: "ebool" → boolean, "euint8" → Uint8Number, etc.
+export type ClearValueTypeMap = {
+  [etype in FheType]: ValueTypeMap[FheTypeToValueTypeMap[etype]];
+};
+
+// Same as FheTypeToValueTypeMap (kept for backward compat)
+export type FheTypeToValueTypeNameMap = FheTypeToValueTypeMap;
+
+// Uint-only subset: "uint8" → "euint8", etc.
+export type UintToEuintMap = {
+  [etype in FheType as FheTypeToValueTypeMap[etype] extends keyof UintValueTypeMap
+    ? FheTypeToValueTypeMap[etype]
+    : never]: etype;
+};
+
+// Reverse: "euint8" → "uint8", etc.
+export type EuintToUintMap = {
+  [K in keyof UintToEuintMap as UintToEuintMap[K]]: K;
+};
+
+export type EuintToUintNormalizedMap = {
+  [K in keyof UintToEuintMap as UintToEuintMap[K]]: UintNormalizedMap[K];
+};
+
+export type FheTypeIdToNameMap = {
+  [etype in keyof FheTypeToIdMap as FheTypeToIdMap[etype]]: etype;
+};
+
+// ebool is encrypted on 2 bits (not 1)
+export type EncryptionBitsMap = Readonly<{
+  [etype in FheType]: etype extends 'ebool' ? 2 : ValueTypeBitsMap[FheTypeToValueTypeMap[etype]];
+}>;
+
+export type EncryptionBits = EncryptionBitsMap[keyof EncryptionBitsMap];
+export type EncryptionBitsOf<etype extends keyof EncryptionBitsMap> = EncryptionBitsMap[etype];
+
+export type FheTypeIdToEncryptionBitsMap = {
+  [etype in keyof FheTypeToIdMap as FheTypeToIdMap[etype]]: EncryptionBitsMap[etype];
+};
+
+export type EncryptionBitsToFheTypeIdMap = {
+  [etype in keyof EncryptionBitsMap as EncryptionBitsMap[etype]]: FheTypeToIdMap[etype];
+};
+
+export type EncryptionBitsToFheTypeMap = {
+  [etype in keyof EncryptionBitsMap as EncryptionBitsMap[etype]]: etype;
+};
+
+export type SolidityPrimitiveTypeName = 'bool' | 'uint256' | 'address';

package/core/types/fhevmChain.ts

@@ -0,0 +1,86 @@
+import type { ChecksummedAddress, Uint64BigInt } from './primitives.js';
+
+export type FhevmChain = {
+  readonly id: number;
+} & FhevmChainExtension;
+
+/**
+ * {
+ *   id: 1,
+ *   fhevm: {
+ *     contracts: {
+ *       acl: "0xdeadbeef..."
+ *       inputVerifier: "0xdeadbeef..."
+ *       kmsVerifier: "0xdeadbeef..."
+ *     },
+ *     relayerUrl: "http://foo",
+ *     gateway?: {
+ *       id: 1234,
+ *       contracts: {
+ *         decryption: ChecksummedAddress;
+ *         inputVerification: ChecksummedAddress;
+ *       }
+ *     }
+ *   }
+ * }
+ */
+
+export type FhevmChainExtension = {
+  readonly fhevm: {
+    readonly contracts: FhevmChainContracts;
+    readonly relayerUrl: string;
+    readonly gateway: FhevmGatewayChain;
+  };
+};
+
+type ChainContract = {
+  readonly address: `0x${string}`;
+  readonly blockCreated?: number | undefined;
+};
+
+export type FhevmChainContracts = {
+  readonly acl: ChainContract;
+  readonly inputVerifier: ChainContract;
+  readonly kmsVerifier: ChainContract;
+};
+
+export type FhevmGatewayChain = {
+  readonly id: number;
+  readonly contracts: {
+    readonly decryption: ChainContract;
+    readonly inputVerification: ChainContract;
+  };
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+export type ResolvedFhevmChain = {
+  readonly id: Uint64BigInt;
+} & ResolvedFhevmChainExtension;
+
+type ResolvedFhevmChainExtension = {
+  readonly fhevm: {
+    readonly contracts: ResolvedFhevmChainContracts;
+    readonly relayerUrl: string;
+    readonly gateway: ResolvedFhevmGatewayChain;
+  };
+};
+
+type ResolvedChainContract = {
+  readonly address: ChecksummedAddress;
+  readonly blockCreated?: number | undefined;
+};
+
+type ResolvedFhevmChainContracts = {
+  readonly acl: ResolvedChainContract;
+  readonly inputVerifier: ResolvedChainContract;
+  readonly kmsVerifier: ResolvedChainContract;
+};
+
+type ResolvedFhevmGatewayChain = {
+  readonly id: Uint64BigInt;
+  readonly contracts: {
+    readonly decryption: ResolvedChainContract;
+    readonly inputVerification: ResolvedChainContract;
+  };
+};

package/core/types/fhevmClient.ts

@@ -0,0 +1,30 @@
+import type { FhevmRuntime, WithAll, WithDecrypt, WithEncrypt } from './coreFhevmRuntime.js';
+import type { FhevmChain } from './fhevmChain.js';
+import type { BaseActions } from '../clients/decorators/base.js';
+import type { EncryptActions } from '../clients/decorators/encrypt.js';
+import type { DecryptActions } from '../clients/decorators/decrypt.js';
+import type { Fhevm, NativeClient } from '../types/coreFhevmClient.js';
+
+export type FhevmBaseClient<
+  chain extends FhevmChain = FhevmChain,
+  runtime extends FhevmRuntime = FhevmRuntime,
+  client extends NativeClient = NativeClient,
+> = Fhevm<chain, runtime, client> & BaseActions;
+
+export type FhevmClient<
+  chain extends FhevmChain = FhevmChain,
+  runtime extends WithAll = WithAll,
+  client extends NativeClient = NativeClient,
+> = Fhevm<chain, runtime, client> & BaseActions & DecryptActions & EncryptActions;
+
+export type FhevmDecryptClient<
+  chain extends FhevmChain = FhevmChain,
+  runtime extends WithDecrypt = WithDecrypt,
+  client extends NativeClient = NativeClient,
+> = Fhevm<chain, runtime, client> & BaseActions & DecryptActions;
+
+export type FhevmEncryptClient<
+  chain extends FhevmChain = FhevmChain,
+  runtime extends WithEncrypt = WithEncrypt,
+  client extends NativeClient = NativeClient,
+> = Fhevm<chain, runtime, client> & BaseActions & EncryptActions;

package/core/types/fhevmDecryptionKey.ts

@@ -0,0 +1,8 @@
+import type {
+  DecryptAndReconstructUserModuleFunction,
+  GetTkmsPublicKeyHexUserModuleFunction,
+} from '../modules/decrypt/types.js';
+
+// Use interface instead of type to keep the type name instead of its expansion
+export interface FhevmDecryptionKey
+  extends GetTkmsPublicKeyHexUserModuleFunction, DecryptAndReconstructUserModuleFunction {}

package/core/types/fhevmUser.ts

@@ -0,0 +1,7 @@
+import type { FhevmDecryptionKey } from './fhevmDecryptionKey.js';
+import type { ChecksummedAddress } from './primitives.js';
+
+export type FhevmUser = {
+  readonly address: ChecksummedAddress;
+  readonly decryptionKey: FhevmDecryptionKey;
+};