sdk/js-sdk/docs/api-reference.md
This is the complete reference for every function the SDK exports. For guided usage, see Getting started, Encryption, or Decryption instead.
Client factories and runtime config are importable from @fhevm/sdk/ethers or @fhevm/sdk/viem (identical APIs). Standalone action functions are available from their respective entry points under @fhevm/sdk/actions/*.
setFhevmRuntimeConfig(config)Configures the global runtime. Must be called before creating any clients.
setFhevmRuntimeConfig(config: FhevmRuntimeConfig): void
| Parameter | Type | Description |
|---|---|---|
config.locateFile | (file: string) => URL | Custom WASM file locator |
config.logger | Logger | Logger instance { debug, error } |
config.singleThread | boolean | Force single-threaded WASM |
config.numberOfThreads | number | Number of WASM worker threads |
createFhevmClient(parameters)Full client with encrypt, decrypt, and base modules.
createFhevmClient<chain, provider>(parameters: {
readonly provider: provider;
readonly chain: chain;
readonly options?: FhevmOptions;
}): FhevmClient<chain, WithAll, provider>
createFhevmEncryptClient(parameters)Encrypt-only client (no TKMS WASM loaded).
createFhevmEncryptClient<chain, provider>(parameters: {
readonly provider: provider;
readonly chain: chain;
readonly options?: FhevmOptions;
}): FhevmEncryptClient<chain, WithEncrypt, provider>
createFhevmDecryptClient(parameters)Decrypt-only client (no TFHE WASM loaded).
createFhevmDecryptClient<chain, provider>(parameters: {
readonly provider: provider;
readonly chain: chain;
readonly options?: FhevmOptions;
}): FhevmDecryptClient<chain, WithDecrypt, provider>
createFhevmBaseClient(parameters)Empty base client — extend with encryptActions, decryptActions, or both.
createFhevmBaseClient<chain, provider>(parameters: {
readonly provider: provider;
readonly chain: chain;
readonly options?: FhevmOptions;
}): FhevmBaseClient<chain, FhevmRuntime, provider>
Import from @fhevm/sdk/actions/encrypt.
encrypt(fhevm, parameters)Encrypts values and returns encrypted handles with a verified input proof. The FHE public encryption key is automatically fetched and cached on first use.
// Single value
encrypt(fhevm, parameters: EncryptSingleParameters): Promise<EncryptSingleReturnType>
// Multiple values
encrypt(fhevm, parameters: EncryptMultipleParameters): Promise<EncryptMultipleReturnType>
| Parameter | Type | Description |
|---|---|---|
contractAddress | string | Target contract address |
userAddress | string | User's Ethereum address |
values | TypedValueLike | readonly TypedValueLike[] | Values to encrypt (single or array) |
options? | RelayerInputProofOptions | Optional relayer options |
Single value return (EncryptSingleReturnType):
| Field | Type | Description |
|---|---|---|
externalEncryptedValue | ExternalEncryptedValue | The encrypted handle |
inputProof | BytesHex | Proof bytes to pass to contract |
Multiple values return (EncryptMultipleReturnType):
| Field | Type | Description |
|---|---|---|
externalEncryptedValues | readonly ExternalEncryptedValue[] | Encrypted handles in input order |
inputProof | BytesHex | Shared proof bytes for all values |
generateZkProof(fhevm, parameters)Generates a ZK proof of correct encryption (CPU-intensive TFHE WASM).
generateZkProof(fhevm, parameters: GenerateZkProofParameters): Promise<ZkProof>
Import from @fhevm/sdk/actions/base. Also available as client methods on all client types.
publicDecrypt(fhevm, parameters) / client.publicDecrypt(parameters)Decrypts encrypted values that are publicly decryptable on-chain.
publicDecrypt(fhevm, parameters: PublicDecryptParameters): Promise<PublicDecryptionProof>
| Parameter | Type | Description |
|---|---|---|
encryptedValues | readonly EncryptedValueLike[] | Encrypted values to decrypt (min 1, max 2048 bits) |
options? | RelayerPublicDecryptOptions | Optional relayer options |
fetchVerifiedInputProof(fhevm, parameters)Sends a ZK proof to the relayer, returns a verified input proof with coprocessor signatures.
fetchVerifiedInputProof(fhevm, parameters: FetchVerifiedInputProofParameters): Promise<VerifiedInputProof>
fetchKmsSignedcryptedShares(fhevm, parameters)Fetches KMS signcrypted shares for decryption.
fetchKmsSignedcryptedShares(fhevm, parameters: FetchKmsSignedcryptedSharesParameters): Promise<KmsSigncryptedShares>
isAllowedForDecryption(fhevm, parameters)Checks if encrypted values are allowed for decryption on the ACL contract.
isAllowedForDecryption(fhevm, parameters): Promise<boolean | boolean[]>
checkAllowedForDecryption(fhevm, parameters)Same as isAllowedForDecryption, but throws if any value is not allowed.
checkAllowedForDecryption(fhevm, parameters: CheckAllowedForDecryptionParameters): Promise<void>
Import from @fhevm/sdk/actions/decrypt.
decrypt(fhevm, parameters) / client.decrypt(parameters)Decrypts encrypted values using a transport key pair and signed permit.
decrypt(fhevm, parameters: DecryptParameters): Promise<readonly ClearValue[]>
| Parameter | Type | Description |
|---|---|---|
encryptedValues | EncryptedValueEntry | readonly EncryptedValueEntry[] | Encrypted values with their contract addresses |
signedPermit | SignedSelfDecryptionPermit | SignedDelegatedDecryptionPermit | Signed permit from signDecryptionPermit() |
e2eTransportKeypair | E2eTransportKeypair | E2E transport key pair from generateE2eTransportKeypair() |
options? | RelayerUserDecryptOptions | RelayerDelegatedUserDecryptOptions | Optional relayer options |
Each EncryptedValueEntry has { encryptedValue: EncryptedValueLike, contractAddress: ChecksummedAddress }.
generateE2eTransportKeypair(fhevm) / client.generateE2eTransportKeypair()Generates a new E2E transport key pair for decryption.
generateE2eTransportKeypair(fhevm): Promise<E2eTransportKeypair>
decryptKmsSignedcryptedShares(fhevm, parameters)Lower-level: decrypts KMS signcrypted shares locally using TKMS WASM.
decryptKmsSignedcryptedShares(fhevm, parameters: DecryptKmsSignedcryptedSharesParameters): Promise<ClearValue[]>
Import from @fhevm/sdk/actions/chain. These act on the chain definition alone — no provider needed.
signDecryptionPermit(fhevm, parameters) / client.signDecryptionPermit(parameters)Creates and signs a decryption permit in a single step. Constructs the EIP-712 typed data internally and signs it with the provided signer.
// Self decryption
signDecryptionPermit(fhevm, parameters: SignSelfDecryptionPermitParameters): Promise<SignedSelfDecryptionPermit>
// Delegated decryption (onBehalfOf)
signDecryptionPermit(fhevm, parameters: SignDelegatedDecryptionPermitParameters): Promise<SignedDelegatedDecryptionPermit>
| Parameter | Type | Description |
|---|---|---|
contractAddresses | readonly string[] | Allowed contracts (max 10) |
startTimestamp | number | Unix timestamp (seconds) |
durationDays | number | Validity period (max 365) |
signerAddress | string | Address of the signer |
signer | NativeSigner | Ethers Signer or viem WalletClient |
e2eTransportKeypair | E2eTransportKeypair | Transport key pair |
onBehalfOf? | string | Optional — address to decrypt on behalf of |
createKmsUserDecryptEIP712(fhevm, parameters) / client.createUserDecryptEIP712(parameters)Lower-level: constructs EIP-712 typed data for a decrypt permit without signing. Use signDecryptionPermit for the common case.
createKmsUserDecryptEIP712(fhevm, parameters: CreateKmsUserDecryptEIP712Parameters): Promise<CreateKmsUserDecryptEIP712ReturnType>
createKmsDelegatedUserDecryptEIP712(fhevm, parameters) / client.createDelegatedUserDecryptEIP712(parameters)Lower-level: constructs EIP-712 typed data for a delegated decrypt permit without signing.
createKmsDelegatedUserDecryptEIP712(fhevm, parameters: CreateKmsDelegatedUserDecryptEIP712Parameters): Promise<CreateKmsDelegatedUserDecryptEIP712ReturnType>
verifyKmsUserDecryptEIP712(fhevm, parameters)Verifies a decrypt permit EIP-712 signature. Throws on invalid signature.
verifyKmsUserDecryptEIP712(fhevm, parameters: VerifyKmsUserDecryptEIP712Parameters): Promise<void>
parseE2eTransportKeypair(fhevm, parameters) / client.parseE2eTransportKeypair(parameters)Restores a key pair from serialized bytes.
parseE2eTransportKeypair(fhevm, parameters: ParseE2eTransportKeypairParameters): Promise<E2eTransportKeypair>
serializeE2eTransportKeypair(fhevm, parameters) / client.serializeE2eTransportKeypair(parameters)Serializes a key pair for storage/persistence.
serializeE2eTransportKeypair(fhevm, parameters: SerializeE2eTransportKeypairParameters): SerializeE2eTransportKeypairReturnType
fetchFheEncryptionKeyBytes(fhevm, parameters?) / client.fetchFheEncryptionKeyBytes(parameters?)Fetches the ~50MB FHE public encryption key from the relayer and caches it.
fetchFheEncryptionKeyBytes(fhevm, parameters?: FetchFheEncryptionKeyBytesParameters): Promise<FetchFheEncryptionKeyBytesReturnType>
createKmsEIP712Domain(fhevm)Creates the EIP-712 domain for KMS operations.
createKmsEIP712Domain(fhevm): Promise<CreateKmsEIP712DomainReturnType>
createCoprocessorEIP712Domain(fhevm)Creates the EIP-712 domain for coprocessor operations.
createCoprocessorEIP712Domain(fhevm): Promise<CreateCoprocessorEIP712DomainReturnType>
Import from @fhevm/sdk/actions/host. These read on-chain contract data. They take any Fhevm instance — no FhevmChain required.
resolveFhevmConfig(fhevm, parameters)Resolves complete FHEVM configuration by reading multiple host contracts.
resolveFhevmConfig(fhevm, parameters: ResolveFhevmConfigParameters): Promise<ResolveFhevmConfigReturnType>
readFhevmExecutorContractData(fhevm, parameters)readFhevmExecutorContractData(fhevm, parameters: ReadFhevmExecutorContractDataParameters): Promise<ReadFhevmExecutorContractDataReturnType>
readInputVerifierContractData(fhevm, parameters)readInputVerifierContractData(fhevm, parameters: ReadInputVerifierContractDataParameters): Promise<ReadInputVerifierContractDataReturnType>
readKmsVerifierContractData(fhevm, parameters)readKmsVerifierContractData(fhevm, parameters: ReadKmsVerifierContractDataParameters): Promise<ReadKmsVerifierContractDataReturnType>
| Function | Description |
|---|---|
getACLAddress(fhevm, params) | Gets the ACL contract address |
getFHEVMExecutorAddress(fhevm, params) | Gets the FhevmExecutor contract address |
getInputVerifierAddress(fhevm, params) | Gets the InputVerifier contract address |
getKmsSigners(fhevm, params) | Gets KMS signer addresses |
getCoprocessorSigners(fhevm, params) | Gets coprocessor signer addresses |
getThreshold(fhevm, params) | Gets the signature threshold |
getHandleVersion(fhevm, params) | Gets the handle version |
resolveChainId(fhevm, params) | Resolves the chain ID |
isAllowedForDecryption(fhevm, params) | Checks ACL decryption permission |
persistAllowed(fhevm, params) | Checks persisted ACL permissions |
eip712Domain(fhevm, params) | Reads EIP-712 domain from contract |
Client: FhevmClient, FhevmEncryptClient, FhevmDecryptClient, FhevmBaseClient, Fhevm, FhevmRuntime, FhevmRuntimeConfig, FhevmOptions, WithEncrypt, WithDecrypt, WithAll
Encrypted values: EncryptedValue, ComputedEncryptedValue, ExternalEncryptedValue, EncryptedValueLike, Handle (alias), InputHandle (alias), Ebool, Euint8, Euint16, Euint32, Euint64, Euint128, Euint256, Eaddress, ExternalEbool, ExternalEuint8, ... ExternalEaddress
Clear values: ClearValue, ClearValueOfType, ClearBool, ClearUint8, ClearUint16, ClearUint32, ClearUint64, ClearUint128, ClearUint256, ClearAddress
FHE: FheType, FheTypeId
Primitives: ChecksummedAddress, Address, BytesHex, Bytes32Hex, Bytes65Hex, Uint8Number, Uint16Number, Uint32Number, Uint64BigInt, Uint128BigInt, Uint256BigInt, TypedValue, TypedValueLike
Proofs: VerifiedInputProof, InputProof, ZkProof, PublicDecryptionProof
Permits: SignedSelfDecryptionPermit, SignedDelegatedDecryptionPermit, SignedDecryptionPermit, KmsUserDecryptEIP712, KmsDelegatedUserDecryptEIP712, KmsEIP712Domain, E2eTransportKeypair
Chains: FhevmChain
Convention: Every action exports FunctionNameParameters and FunctionNameReturnType (e.g., EncryptParameters, EncryptReturnType).