> ## Documentation Index
> Fetch the complete documentation index at: https://cofhe-docs.fhenix.zone/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install and configure @cofhe/hardhat-3-plugin for local FHE contract development with Hardhat 3

`@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.

<Note>
  This plugin is for Hardhat 3. For a Hardhat 2 project, use [`@cofhe/hardhat-plugin`](/client-sdk/hardhat-plugin/getting-started). The two are not interchangeable.
</Note>

## 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`.

<Steps>
  <Step title="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:

    <CodeGroup>
      ```json npm (package.json) theme={null}
      {
        "overrides": {
          "@cofhe/sdk": {
            "hardhat": "$hardhat",
            "viem": "$viem"
          },
          "@cofhe/hardhat-3-plugin": {
            "viem": "$viem"
          }
        }
      }
      ```

      ```yaml pnpm (pnpm-workspace.yaml) theme={null}
      overrides:
        viem: 2.57.1
      ```

      ```json yarn (package.json) theme={null}
      {
        "resolutions": {
          "viem": "2.57.1"
        }
      }
      ```
    </CodeGroup>

    For pnpm and yarn, use the `viem` version your project already declares.
  </Step>

  <Step title="Install the packages">
    <CodeGroup>
      ```bash npm theme={null}
      npm install --save-dev @cofhe/hardhat-3-plugin@^0.7.1 @cofhe/sdk@^0.7.1 @fhenixprotocol/cofhe-contracts@^0.2.0
      ```

      ```bash pnpm theme={null}
      pnpm add -D @cofhe/hardhat-3-plugin@^0.7.1 @cofhe/sdk@^0.7.1 @fhenixprotocol/cofhe-contracts@^0.2.0
      ```

      ```bash yarn theme={null}
      yarn add -D @cofhe/hardhat-3-plugin@^0.7.1 @cofhe/sdk@^0.7.1 @fhenixprotocol/cofhe-contracts@^0.2.0
      ```
    </CodeGroup>
  </Step>

  <Step title="Register the plugin">
    Add the plugin to the `plugins` array, and list the mock contract sources in `npmFilesToBuild`:

    ```typescript hardhat.config.ts theme={null}
    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.
  </Step>
</Steps>

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

## 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`.

<Warning>
  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`.
</Warning>

## Configuration

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

```typescript hardhat.config.ts theme={null}
export default defineConfig({
  plugins: [cofhePlugin, hardhatViem, hardhatNodeTestRunner],
  cofhe: {
    gasWarning: true,
    mocksDeployVerbosity: 'vv',
  },
});
```

| Option | Type | Default | Effect |
| - | - | - | - |
| <code style={{ whiteSpace: "nowrap" }}>gasWarning</code> | `boolean` | `false` | Prints a note after each mock deployment that mock FHE operations cost more gas than they do on a live network. |
| <code style={{ whiteSpace: "nowrap" }}>mocksDeployVerbosity</code> | `'' \| 'v' \| 'vv'` | `'v'` | Output while the mocks deploy. `''` prints nothing, `'v'` prints one summary line, `'vv'` prints each contract and its address. |

<Warning>
  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](/client-sdk/hardhat-3-plugin/logging) page instead.
</Warning>

## 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.

```typescript test/Counter.test.ts theme={null}
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](/client-sdk/hardhat-3-plugin/client): create and connect an SDK client in a test.
* [Mock contracts](/client-sdk/hardhat-3-plugin/mock-contracts): read plaintext values and call the mocks directly.
* [Logging](/client-sdk/hardhat-3-plugin/logging): print the FHE operations your contracts perform.
* [Testing](/client-sdk/hardhat-3-plugin/testing): a complete test file and the patterns around it.