# @fhevm/hardhat-plugin-v3 中文文档

规范地址：https://npmcn.com/package/%40fhevm/hardhat-plugin-v3/

版本：0\.13\.1
npm 元数据更新时间：2026-10-23T16:18:20.025Z
中文译文更新时间：2026-11-14T16:36:10.899Z
软件包许可：BSD-3-Clause-Clear

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fhevm/hardhat-plugin-v3
原文对照：https://npmcn.com/package/%40fhevm/hardhat-plugin-v3/?lang=original
项目主页：https://github.com/zama-ai/fhevm-mocks#readme
源码仓库：https://github.com/zama-ai/fhevm-mocks

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：654 kB，228 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.23\.4
- 运行依赖：1 个
- peer 依赖：viem ^2\.55\.19，hardhat ^3\.0\.0，@fhevm/sdk ^0\.13\.8
- 首次发布：2026-09-09T08:05:02.961Z
- 最新版本发布：2026-10-23T16:18:19.349Z
- 近 30 天下载量：3176（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

Hardhat 3的FHEVM插件:一个清晰文本的FHEVM堆栈,关于每个开发连接,加密,公开和用户解密,错误诊断,HCU会计和fhevm任务.

## 安装

```sh
npm install @fhevm/hardhat-plugin-v3
```

也可以使用：`pnpm add @fhevm/hardhat-plugin-v3`、`yarn add @fhevm/hardhat-plugin-v3`、`bun add @fhevm/hardhat-plugin-v3`

## README

![FHEVM](https://raw.githubusercontent.com/zama-ai/fhevm/main/docs/.gitbook/assets/fhevm-header-light.png)

* * *

[读取白纸](https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper.pdf) | [页:1](https://docs.zama.ai/) | [社区支助](https://zama.ai/community) | [扎玛的FHE资源](https://github.com/zama-ai/awesome-zama)

# FHEVM Hardhat 3 插件

[![NPM Version](https://img.shields.io/npm/v/%40fhevm%2Fhardhat-plugin-v3)](https://www.npmjs.com/package/@fhevm/hardhat-plugin-v3) [![hardhat](https://hardhat.org/buidler-plugin-badge.svg?1)](https://hardhat.org/)

Hardhat 3 用于开发和测试 FHEVM 合同的插件.

文件和资源:

-   [建立哈达特](https://docs.zama.ai/protocol/solidity-guides/getting-started/setup)
-   [FHEVM 实例](https://docs.zama.ai/protocol/examples)
-   [Hardhat 3 实例项目](https://github.com/zama-ai/fhevm-mocks/tree/release/0.13.x/hardhat/v3/fhevm-hardhat-template/pkg): 不是一个随时可用的模板,而是一个工作项目文件夹,您可以用作自己设置的模型

## 同行依赖关系列表

此 Hardhat 插件依赖于以下对等依赖来正确运行 .

-   `@fhevm/sdk`
-   `hardhat`
-   `viem`

如果您的软件包管理器没有自动安装端点依赖性( pnpm 或 npm < 7) , 请将它们添加到您的软件包中 手动.

## 安装

```sh
npm install --save-dev @fhevm/hardhat-plugin-v3
```

将插件注册到您的 [`hardhat.config.ts`](https://hardhat.org/config/)数字 :

```ts
import fhevmPlugin from '@fhevm/hardhat-plugin-v3';
import { defineConfig } from 'hardhat/config';

export default defineConfig({
  plugins: [fhevmPlugin],
});
```

# QQ快起步:有FHEVM的"你好世界"

最小工程:一个存储两个加密值,添加这些值的合同,以及解密总和的测试.

### 1\. 安装

```sh
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox-mocha-ethers @fhevm/hardhat-plugin-v3 @fhevm/sdk viem
npm install @fhevm/solidity
```

### 2\. 创建 `contracts/APlusB.sol`

```solidity
// SPDX-License-Identifier: BSD-3-Clause-Clear
pragma solidity ^0.8.24;

import { FHE, euint8, externalEuint8 } from "@fhevm/solidity/lib/FHE.sol";
import { ZamaEthereumConfig } from "@fhevm/solidity/config/ZamaConfig.sol";

contract APlusB is ZamaEthereumConfig {
  euint8 private _a;
  euint8 private _b;
  euint8 private _aplusb;

  function setA(externalEuint8 inputA, bytes calldata inputProof) external {
    _a = FHE.fromExternal(inputA, inputProof);
    FHE.allowThis(_a);
  }

  function setB(externalEuint8 inputB, bytes calldata inputProof) external {
    _b = FHE.fromExternal(inputB, inputProof);
    FHE.allowThis(_b);
  }

  function computeAPlusB() external {
    _aplusb = FHE.add(_a, _b);
    FHE.allowThis(_aplusb);
    FHE.allow(_aplusb, msg.sender);
  }

  function aplusb() public view returns (euint8) {
    return _aplusb;
  }
}
```

### 3\. 创建 `hardhat.config.ts`

见 [Hardhat 3 配置指南](https://hardhat.org/docs/reference/configuration) 详细参考.

```ts
import fhevmPlugin from '@fhevm/hardhat-plugin-v3';
import hardhatToolboxMochaEthers from '@nomicfoundation/hardhat-toolbox-mocha-ethers';
import { defineConfig } from 'hardhat/config';

export default defineConfig({
  plugins: [hardhatToolboxMochaEthers, fhevmPlugin],
  solidity: {
    version: '0.8.27',
    // ⚠️ FHEVM requires at least the "cancun" EVM version
    settings: { evmVersion: 'cancun' },
  },
});
```

### 4\. 创建 `test/APlusB.ts`

在Hardhat 3中,FHEVM API住在网络连接上,而不是在 `hre`。 。 。 .

```ts
import { expect } from 'chai';
import { network } from 'hardhat';

const { ethers, fhevm } = await network.connect();

describe('APlusB', function () {
  it('uint8: add 80 to 123 should equal 203', async function () {
    const [alice] = await ethers.getSigners();
    const contract = await ethers.deployContract('APlusB');
    const contractAddress = await contract.getAddress();

    // 1. Encrypt and store `a`
    const a = await fhevm.helpers.encryptUint8({ value: 80, contractAddress, userAddress: alice.address });
    await (await contract.setA(a.externalEuint8, a.inputProof)).wait();

    // 2. Encrypt and store `b`
    const b = await fhevm.helpers.encryptUint8({ value: 123, contractAddress, userAddress: alice.address });
    await (await contract.setB(b.externalEuint8, b.inputProof)).wait();

    // 3. Compute the FHE sum on chain
    await (await contract.computeAPlusB()).wait();

    // 4. Decrypt the result as alice
    const clear = await fhevm.helpers.decryptUint8({
      euint8: await contract.aplusb(),
      contractAddress,
      userAddress: alice.address,
    });

    expect(clear).to.eq(203n);
  });
});
```

### 5\. 运行

```sh
npx hardhat test
```

# 插件 API 欺骗表

所有帮助者都住在连接处 `fhevm` 对象 : `const { fhevm } = await network.connect();`

### `fhevm.helpers` - 加密

每一个都要 `{ value, contractAddress, userAddress }` 返回时 `{ external<Type>, inputProof }`。 。 。 .

| 函数 | `value` |
| --- | --- |
| `encryptBool` | `boolean` |
| `encryptUint8` | `number | bigint` |
| `encryptUint16` | `number | bigint` |
| `encryptUint32` | `number | bigint` |
| `encryptUint64` | `number | bigint` |
| `encryptUint128` | `number | bigint` |
| `encryptUint256` | `number | bigint` |
| `encryptAddress` | `string` |

### `fhevm.helpers` ——解密(用户解密,需要ACL允许+许可)

每一个都要 `{ <handle>, contractAddress, userAddress, options? }`。 。 。 .

| 函数 | 处理参数 | 回返 |
| --- | --- | --- |
| `decryptBool` | `ebool` | `boolean` |
| `decryptUint8` | `euint8` | `number` |
| `decryptUint16` | `euint16` | `number` |
| `decryptUint32` | `euint32` | `number` |
| `decryptUint64` | `euint64` | `bigint` |
| `decryptUint128` | `euint128` | `bigint` |
| `decryptUint256` | `euint256` | `bigint` |
| `decryptAddress` | `eaddress` | `` `0x${string}` `` |

### `fhevm.helpers` ——公开解密(要求) `FHE.makePubliclyDecryptable`(中文(简体) )

每一个都要 `{ <handle> }` 只有这个.

| 函数 | 处理参数 | 回返 |
| --- | --- | --- |
| `decryptPublicBool` | `ebool` | `boolean` |
| `decryptPublicUint8` | `euint8` | `number` |
| `decryptPublicUint16` | `euint16` | `number` |
| `decryptPublicUint32` | `euint32` | `number` |
| `decryptPublicUint64` | `euint64` | `bigint` |
| `decryptPublicUint128` | `euint128` | `bigint` |
| `decryptPublicUint256` | `euint256` | `bigint` |
| `decryptPublicAddress` | `eaddress` | `` `0x${string}` `` |

每个 `decryptPublic*` 有一个 `decryptPublic*WithSignatures` 双胞胎返回 `{ clearValue, checkSignaturesArgs }`,用于 测试链上签名验证.

### `fhevm.cleartextDb` ——直接读取清晰文本(仅测试,绕行ACL)

每一个都要 `{ <handle> }` 即使没有人能看到价值 也只能回答.

| 函数 | 处理参数 | 回返 |
| --- | --- | --- |
| `readBool` | `ebool` | `boolean` |
| `readUint8` | `euint8` | `number` |
| `readUint16` | `euint16` | `number` |
| `readUint32` | `euint32` | `number` |
| `readUint64` | `euint64` | `bigint` |
| `readUint128` | `euint128` | `bigint` |
| `readUint256` | `euint256` | `bigint` |
| `readAddress` | `eaddress` | `` `0x${string}` `` |

### `fhevm.client` - 生下来的 `@fhevm/sdk` 客户端

以上帮手为便利包装. 当你需要的东西 他们不覆盖 - 或者当你想要测试 `@fhevm/sdk` API本身——达到 `fhevm.client`,基础 `FhevmClient` 从 `@fhevm/sdk`,并称其行动 直接说.

```ts
const { fhevm } = await network.connect();
const { encryptedValues, inputProof } = await fhevm.client.encryptValues({
  values: [{ type: 'euint8', value: 80 }],
  contractAddress,
  userAddress,
});
```

# FHEVM 文件和实例

欲了解更多FHEVM实例和详细文件,请前往 [这里](https://docs.zama.ai/protocol)

## 常见问题

### @fhevm/hardhat-plugin-v3 是什么？

Hardhat 3的FHEVM插件:一个清晰文本的FHEVM堆栈,关于每个开发连接,加密,公开和用户解密,错误诊断,HCU会计和fhevm任务\.

### 如何安装 @fhevm/hardhat-plugin-v3？

在项目目录运行 npm install @fhevm/hardhat-plugin-v3，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2\.55\.19）、hardhat（^3\.0\.0）、@fhevm/sdk（^0\.13\.8）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fhevm/hardhat-plugin-v3 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fhevm/hardhat-plugin-v3 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fhevm/hardhat-plugin-v3 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.23\.4。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fhevm/hardhat-plugin-v3 可以商用吗？

@fhevm/hardhat-plugin-v3 使用 BSD-3-Clause-Clear 许可。声明的许可为 BSD-3-Clause-Clear，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @fhevm/hardhat-plugin-v3 的下载量有多少？

根据 npm 官方下载统计，@fhevm/hardhat-plugin-v3 在 2026/10/15 – 2026/11/13 这 30 天内被下载 3,176 次，日均约 106 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fhevm/hardhat-plugin-v3 还在维护吗？

最新版本 0\.13\.1 发布于 2026/10/24（22 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/09/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。