Is there a CommonJS-compatible entry point

aa2hr · October 5, 2025, 8:04pm

Hey Zama team

I’m currently working on a confidential voting dApp based on FHEVM, and I’m trying to deploy the FHEPrivateVoting contract using the Relayer SDK from a Hardhat script (Node.js).

However, I’m running into an issue with the SDK when used in a Node (CommonJS) context.

When I try importing the SDK like this:
import { createInstance, SepoliaConfig } from “@zama-fhe/relayer-sdk”;
or even
import { createInstance, SepoliaConfig } from “@zama-fhe/relayer-sdk/web”;

I get the following error:
ReferenceError: self is not defined
at @zama-fhe/relayer-sdk/lib/web.js:40:16

This happens because the web build expects a browser or WebWorker environment (where self is defined), but Hardhat uses Node.js runtime (CommonJS).

When I try using:
import { createInstance, SepoliaConfig } from “@zama-fhe/relayer-sdk/node”;

it only works under pure ESM projects — but Hardhat scripts use CommonJS, so it fails to import.

My question:
Is there a CommonJS-compatible entry point (like /lib/node.cjs) or a recommended way to use the relayer SDK from Hardhat or Node.js deployment scripts?

Environment:

Node.js v22
Hardhat 2.22.x
@zama-fhe/relayer-sdk 0.2.0
Target network: Sepolia (using relayer.testnet.zama.cloud)

AlexB · October 7, 2025, 8:13am

Hi @aa2hr !
Thank you for your interest in FHEVM. The problem you are facing most probably comes from a bad import. When using node, you should import the relayer-sdk as follow:
@zama-fhe/relayer-sdk/node
If you need to fix import/ESM/CJS issues, one possibility is to write the required wrapper (ESM → CJS) or (CJS->ESM) depending on your project configuration.
Concerning the use of the relayer-sdk directly into an Hardhat project, you can instead use the fhevm Hardhat plugin extension that provides access to the relayer-sdk under the hood when the targeted network is Sepolia.
See:

github.com

zama-ai/fhevm-hardhat-template/blob/main/tasks/FHECounter.ts

import { FhevmType } from "@fhevm/hardhat-plugin";
import { task } from "hardhat/config";
import type { TaskArguments } from "hardhat/types";

/**
 * Tutorial: Deploy and Interact Locally (--network localhost)
 * ===========================================================
 *
 * 1. From a separate terminal window:
 *
 *   npx hardhat node
 *
 * 2. Deploy the FHECounter contract
 *
 *   npx hardhat --network localhost deploy
 *
 * 3. Interact with the FHECounter contract
 *
 *   npx hardhat --network localhost task:decrypt-count
 *   npx hardhat --network localhost task:increment --value 2

This file has been truncated. show original

For a sample code illustrating the use of the fhevm Hardhat Plugin on Sepolia.
Don’t hesitate to get back to us if needed.

aa2hr · October 7, 2025, 4:40pm

Hi @AlexB ,

Thank you very much for the clarification! That makes total sense — the import issue came from mixing ESM and CJS in Hardhat, and your explanation about using @zama-fhe/relayer-sdk/node or the @fhevm/hardhat-plugin is perfectly clear.

I’ve already tried several approaches (including a CommonJS bridge and manual export patch) to make the SDK work smoothly inside a Hardhat environment, and things are now much clearer thanks to your guidance.

To speed up debugging and further collaboration, could you please manually grant me access to the Zama Developer Discord?

I’ve already applied through the Developer Program page, but the Discord role hasn’t been activated yet.

It would be really helpful to interact directly with the team there when testing relayer SDK builds or verifying environment setup.

Thank you again for your time, great documentation, and support!

alakazamzam · October 7, 2025, 6:29pm

@aa2hr If you’re referring to the Zama Protocol discord, if you’re having an issue with being added please email marketing at zama.ai with your rationale (you can link this thread)