Getting Started

@cofhe/hardhat-3-plugin runs the CoFHE mock contracts inside Hardhat 3’s simulated network and attaches a cofhe object to every network connection. Use it to compile, test, and debug FHE contracts locally without the offchain CoFHE services.

This plugin is for Hardhat 3. For a Hardhat 2 project, use @cofhe/hardhat-plugin. The two are not interchangeable.

What the plugin provides

Mock contracts deployed on every new connection to the simulated network, standing in for the CoFHE coprocessor.
cofhe on the connection object, next to the viem object from @nomicfoundation/hardhat-viem.
cofhe.createClientWithBatteries(), which returns a connected SDK client with a self ACP (Access Control Permission) already signed.
Mock helpers for reading plaintext values, toggling operation logs, and calling the mock contracts directly with viem.
Network presets for localcofhe, eth-sepolia, and arb-sepolia.

Install the plugin

These steps assume a Hardhat 3 project that already uses @nomicfoundation/hardhat-viem and @nomicfoundation/hardhat-node-test-runner.

Add the dependency overrides

@cofhe/sdk pins viem to an exact version and declares an optional peer dependency on Hardhat 2. Both collide with a Hardhat 3 project. Add these entries to package.json before you install:

{
  "overrides": {
    "@cofhe/sdk": {
      "hardhat": "$hardhat",
      "viem": "$viem"
    },
    "@cofhe/hardhat-3-plugin": {
      "viem": "$viem"
    }
  }
}

overrides:
  viem: 2.57.1

{
  "resolutions": {
    "viem": "2.57.1"
  }
}

For pnpm and yarn, use the viem version your project already declares.

Install the packages

npm install --save-dev @cofhe/hardhat-3-plugin@^0.7.1 @cofhe/sdk@^0.7.1 @fhenixprotocol/cofhe-contracts@^0.2.0

pnpm add -D @cofhe/hardhat-3-plugin@^0.7.1 @cofhe/sdk@^0.7.1 @fhenixprotocol/cofhe-contracts@^0.2.0

yarn add -D @cofhe/hardhat-3-plugin@^0.7.1 @cofhe/sdk@^0.7.1 @fhenixprotocol/cofhe-contracts@^0.2.0

Add the plugin to the plugins array, and list the mock contract sources in npmFilesToBuild:

hardhat.config.ts

import { defineConfig } from 'hardhat/config';
import cofhePlugin from '@cofhe/hardhat-3-plugin';
import hardhatViem from '@nomicfoundation/hardhat-viem';
import hardhatNodeTestRunner from '@nomicfoundation/hardhat-node-test-runner';

export default defineConfig({
  plugins: [cofhePlugin, hardhatViem, hardhatNodeTestRunner],
  solidity: {
    version: '0.8.28',
    npmFilesToBuild: [
      '@cofhe/mock-contracts/contracts/MockTaskManager.sol',
      '@cofhe/mock-contracts/contracts/MockACL.sol',
      '@cofhe/mock-contracts/contracts/ACPTimestampRevoker.sol',
      '@cofhe/mock-contracts/contracts/ACPShareRegistry.sol',
      '@cofhe/mock-contracts/contracts/MockZkVerifier.sol',
      '@cofhe/mock-contracts/contracts/MockThresholdNetwork.sol',
    ],
  },
});

The plugin reads the mock bytecode from your project’s build artifacts. npmFilesToBuild makes the mocks part of that build, so the compile step of npx hardhat test keeps their artifacts in place.

Run npx hardhat test. The output prints cofhe-hardhat-3-plugin :: mocks deployed once for each connection your tests open.

Why the overrides are needed

Each entry fixes a specific failure:

hardhat (npm only): @cofhe/sdk declares hardhat@^2 as an optional peer, so npm refuses the install with ERESOLVE once Hardhat 3 is in the tree. pnpm and yarn warn and continue.
viem: @cofhe/sdk and the plugin pin viem 2.38.6, while @nomicfoundation/hardhat-viem requires 2.47.6 or later. Without the override, two copies of viem are installed. Tests still run, but TypeScript rejects every hardhat-viem client you pass to the plugin with error TS2345.

Without npmFilesToBuild, @nomicfoundation/hardhat-node-test-runner 3.0.17 and later remove the mock artifacts before the tests start. Every network.create() then fails with HHE1000: Artifact for contract "MockTaskManager" not found.

Configuration

The plugin adds an optional cofhe key to the Hardhat config. Every option has a default, so you can leave the key out.

hardhat.config.ts

export default defineConfig({
  plugins: [cofhePlugin, hardhatViem, hardhatNodeTestRunner],
  cofhe: {
    gasWarning: true,
    mocksDeployVerbosity: 'vv',
  },
});

Option	Type	Default	Effect
`gasWarning`	`boolean`	`false`	Prints a note after each mock deployment that mock FHE operations cost more gas than they do on a live network.
`mocksDeployVerbosity`	`'' \| 'v' \| 'vv'`	`'v'`	Output while the mocks deploy. `''` prints nothing, `'v'` prints one summary line, `'vv'` prints each contract and its address.

The config type also accepts cofhe.logMocks, but no plugin code reads it. Setting it has no effect on FHE operation logs. Use the helpers on the Logging page instead.

When the mocks deploy

The plugin hooks into Hardhat’s connection lifecycle. Every call to network.create() returns a new simulated chain, and the plugin deploys the full mock stack on it before your code gets the connection.

test/Counter.test.ts

import { describe, it } from 'node:test';
import { network } from 'hardhat';

describe('Counter', async () => {
  const { viem, cofhe } = await network.create();

  it('has the mocks deployed', async () => {
    console.log(cofhe.mocks.MockTaskManager.address);
  });
});

network.connect() behaves the same way, but Hardhat 3.4.0 deprecated it in favor of network.create(). network.getOrCreate() reuses an existing connection, and its mocks, when one is open. The plugin checks whether the network answers Hardhat’s hardhat_metadata RPC method before it deploys anything. On a testnet it skips the deployment, so the same connection code works against a live network. There is no environment variable to turn deployment off.

Pre-configured networks

The plugin adds these networks unless your config already defines a network with the same name.

Network	URL	Chain ID
`localcofhe`	`http://127.0.0.1:42069`	`420105`
`eth-sepolia`	`SEPOLIA_RPC_URL`, or the public Ethereum Sepolia RPC	`11155111`
`arb-sepolia`	`ARBITRUM_SEPOLIA_RPC_URL`, or the public Arbitrum Sepolia RPC	`421614`

The testnet presets sign with the key in the PRIVATE_KEY environment variable.

Differences from the Hardhat 2 plugin

	`@cofhe/hardhat-plugin` (Hardhat 2)	`@cofhe/hardhat-3-plugin`
Entry point	`hre.cofhe`	`cofhe` on each network connection
Mocks deploy	Before `npx hardhat test` and `npx hardhat node`	On every new network connection
Test runner	Mocha	Node.js `node:test`
Signers	ethers `HardhatEthersSigner`	viem `WalletClient`
Registration	Side-effect `import`	`plugins` array
Mock contract access	Typed ethers contracts from `getMockTaskManager()` and similar	viem `{ address, abi }` descriptors
Skip mock deployment	`COFHE_SKIP_MOCKS_DEPLOY=1`	Automatic on networks that are not Hardhat
Tasks	`task:cofhe-mocks:deploy`, `task:cofhe-mocks:setlogops`, `task:cofhe:usefaucet`	`cofhe:set-log-ops`, `cofhe:faucet`

The mock contracts themselves are the same package, @cofhe/mock-contracts, in both plugins.

Next steps

Client: create and connect an SDK client in a test.
Mock contracts: read plaintext values and call the mocks directly.
Logging: print the FHE operations your contracts perform.
Testing: a complete test file and the patterns around it.

Introduction

Quick Start

Guides

Hardhat Plugin

Hardhat 3 Plugin

Foundry Plugin

Examples

Reference

What the plugin provides

Install the plugin

Why the overrides are needed

Configuration

When the mocks deploy

Pre-configured networks

Differences from the Hardhat 2 plugin

Next steps

​What the plugin provides

​Install the plugin

​Why the overrides are needed

​Configuration

​When the mocks deploy

​Pre-configured networks

​Differences from the Hardhat 2 plugin

​Next steps

What the plugin provides

Install the plugin

Why the overrides are needed

Configuration

When the mocks deploy

Pre-configured networks

Differences from the Hardhat 2 plugin

Next steps