# @0xbow/privacy-pools-core-sdk 中文文档

规范地址：https://npmcn.com/package/%400xbow/privacy-pools-core-sdk/

版本：1\.5\.0
npm 元数据更新时间：2026-08-31T17:38:06.684Z
中文译文更新时间：2026-11-06T01:00:20.519Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%400xbow/privacy-pools-core-sdk
原文对照：https://npmcn.com/package/%400xbow/privacy-pools-core-sdk/?lang=original
项目主页：https://github.com/0xbow-io/privacy-pools-core#readme
源码仓库：https://github.com/0xbow-io/privacy-pools-core

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

- 包体积（解压后）：22.5 MB，117 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2025-02-18T17:31:29.625Z
- 最新版本发布：2026-08-31T17:38:05.938Z
- 近 30 天下载量：7583（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 16 个）

## 中文简介

隐私池协议的打字符 SDK

## 安装

```sh
npm install @0xbow/privacy-pools-core-sdk
```

也可以使用：`pnpm add @0xbow/privacy-pools-core-sdk`、`yarn add @0xbow/privacy-pools-core-sdk`、`bun add @0xbow/privacy-pools-core-sdk`

## README

# 隐私池核心SDK

用于与隐私池协议互动的 TypeScript SDK. 这个SDK为隐私池集成提供了加密功能、校对、账户管理和合同互动.

## 安装

```bash
npm install @0xbow/privacy-pools-core-sdk
# or
yarn add @0xbow/privacy-pools-core-sdk
# or
pnpm add @0xbow/privacy-pools-core-sdk
```

## 设置

1.  通过运行安装依赖性 `pnpm install`
2.  通过运行构建 SDK `pnpm build`

## 可用的脚本

| 脚本 | 说明 |
| --- | --- |
| `build` | 使用滚动构建 SDK |
| `build:bundle` | 构建 SDK 并设置电路 |
| `check-types` | 检查类型脚本类型问题 |
| `clean` | 删除建筑文物 |
| `lint` | 运行 ESLint 以检查代码质量 |
| `lint:fix` | 自动解决嵌入问题 |
| `format` | 使用 Pretier 检查代码格式 |
| `format:fix` | 自动解决格式化问题 |
| `test` | 使用 Vitest 运行测试 |
| `test:cov` | 生成测试覆盖报告 |

## 使用量

### 初始化

```typescript
import { PrivacyPoolSDK, Circuits } from '@0xbow/privacy-pools-core-sdk';

// In Node.js — set browser: false to load artifacts from the filesystem
const circuits = new Circuits({ browser: false });

// In the browser — the default (browser: true) uses fetch
// const circuits = new Circuits();

const sdk = new PrivacyPoolSDK(circuits);
```

### 承诺证明

```typescript
const commitmentProof = await sdk.proveCommitment(value, label, nullifier, secret);
const isValid = await sdk.verifyCommitment(commitmentProof);
```

### 退出证明

```typescript
const withdrawalProof = await sdk.proveWithdrawal(commitment, withdrawalInput);
const isValid = await sdk.verifyWithdrawal(withdrawalProof);
```

### 密钥衍生

SDK 从一个使用 BIP- 39 的元音短语中得出决定性主键 `generateMasterKeys`。这些密钥用于生成每个存款和每个撤回的无效者和秘密.

```typescript
import { generateMasterKeys, generateDepositSecrets, generateWithdrawalSecrets } from '@0xbow/privacy-pools-core-sdk';

const { masterNullifier, masterSecret } = generateMasterKeys(mnemonic);

const depositSecrets = generateDepositSecrets(
  { masterNullifier, masterSecret },
  scope,
  index,
);

const withdrawalSecrets = generateWithdrawalSecrets(
  { masterNullifier, masterSecret },
  label,
  index,
);
```

### 账户回收

这个 `AccountService` 通过扫描存款、提取和愤怒事件,重建链上账户状态.

```typescript
import { AccountService, DataService } from '@0xbow/privacy-pools-core-sdk';

const { account, legacyAccount, errors } = await AccountService.initializeWithEvents(
  dataService,
  { mnemonic },
  pools,
);
```

#### 范围不完整

无空 `errors` 数组表示一个或多个池无法装入 。 已重建 这些范围的状态是 **缺席, 不为空** 账户可能记有: 不可见,因此,将范围视为没有账户将低估 下个存款指数,产生一个以后重建找不到的存款.

在瞄准镜前检查状态 :

```typescript
account.getScopeStatus(scope); // 'complete' | 'incomplete' | 'not-loaded'
account.isScopeComplete(scope); // true only for 'complete'
account.getIncompleteScopes(); // scopes whose last load failed
```

不属于任何范围的区块存款和提款 `complete`。 。 。 . `createDepositSecrets(scope)` 没有针对此范围的明确索引 而不是猜测;只在恢复流量中通过明确的指数。 状态为 所以它能活下来 并恢复它.

要重试失败的池, 请通过 **两者** 原电话返回的服务 :

```typescript
const retry = await AccountService.initializeWithEvents(
  dataService,
  { service: account, legacyService: legacyAccount },
  pools,
);
```

选择 `legacyService` 重建没有迁移的重试范围 它默默地省略了移徙来源的账户.

#### 空节点

`account.getSpendableCommitments()` 返回每个账户的最新解密承诺。 默认`includeEmptyNodes: true`)结果包括: **空( 零值) 、 迁移和愤怒** 节点与可花节相并列,因此呼叫者可以看到完整的解密状态.

恢复仅能支出的行为——只归还账户没有暴躁或迁移的非零值承付款——设定 `includeEmptyNodes: false`数字 :

```typescript
const { account } = await AccountService.initializeWithEvents(
  dataService,
  { mnemonic },
  pools,
  { includeEmptyNodes: false },
);
```

在构建一个 `AccountService` 直接 :

```typescript
const account = new AccountService(dataService, { mnemonic, includeEmptyNodes: false });
```

> 注:何时 `includeEmptyNodes` 实值 `true`, (中文(简体) ), `getSpendableCommitments()` 可能归还实际上无法用上的承诺(零价值、迁移或愤怒)。 打开过滤器 `value` 在试图花费前先挂帐号.

### 合同互动

```typescript
const contracts = sdk.createContractInstance(rpcUrl, chain, entrypointAddress, privateKey);
```

## 机械安全

SDK会的 **没有** 提供 `generateMnemonic` 函数。 使用一个可信赖的BIP-39库(例如. `@scure/bip39` 或者说 `viem/accounts`)在外部生成元音短语.

-   **从不硬码** 源代码或配置文件中的mnemonics.
-   **永不日志或发送** 明正文中释相.
-   **存储模式** 使用OS级安全存储器(如OS密钥链,加密金库)——在浏览器localStorage或未加密文件中从不使用.
-   **不重复使用** 跨越不相干应用的单元。 失密的记忆暴露了所有衍生的钥匙和他们控制的资金.
-   记忆是 **所有衍生密钥的唯一根**货币损失是指永久丧失获得所有相关承诺和资金的机会.

## 电路艺术完整性

SDK验证 **每个** 下载的电路文物(wasm,vkey,zkey)与预期的SHA-256文摘相对. 未经注册散列的艺术品在载货时被拒绝.

| 艺术 | SHA-256 (英语) |
| --- | --- |
| `commitment.wasm` | `254d2130607182fd6fd1aee67971526b13cfe178c88e360da96dce92663828d8` |
| `commitment.vkey` | `7d48b4eb3dedc12fb774348287b587f0c18c3c7254cd60e9cf0f8b3636a570d8` |
| `commitment.zkey` | `494ae92d64098fda2a5649690ddc5821fcd7449ca5fe8ef99ee7447544d7e1f3` |
| `withdraw.wasm` | `36cda22791def3d520a55c0fc808369cd5849532a75fab65686e666ed3d55c10` |
| `withdraw.vkey` | `666bd0983b20c1611543b04f7712e067fbe8cad69f07ada8a310837ff398d21e` |
| `withdraw.zkey` | `2a893b42174c813566e5c40c715a8b90cd49fc4ecf384e3a6024158c3d6de677` |

您可以根据承诺的文物独立核实:

```bash
shasum -a 256 packages/circuits/trusted-setup/final-keys/*.{vkey,zkey}
shasum -a 256 packages/circuits/build/*/*_js/*.wasm
```

## 特征

-   零知识证明的生成和核查(承诺和撤回)
-   BIP- 39 演示产生的决定性密钥
-   账户状态从链上事件恢复
-   承诺和默克勒证明公用事业
-   合同互动助手
-   类型安全 API

## 捐款

欢迎捐款! 请随意提交拉力请求.

## 许可证

阿帕奇 - 2.0 驾照 - 看 [自由主义](https://npmcn.com/package/%400xbow/privacy-pools-core-sdk/LICENSE) 详细文件.

## 常见问题

### @0xbow/privacy-pools-core-sdk 是什么？

隐私池协议的打字符 SDK

### 如何安装 @0xbow/privacy-pools-core-sdk？

在项目目录运行 npm install @0xbow/privacy-pools-core-sdk，或使用 pnpm add / yarn add / bun add。

### @0xbow/privacy-pools-core-sdk 支持 TypeScript 吗？

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

### @0xbow/privacy-pools-core-sdk 支持 ESM 还是 CommonJS？

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

### @0xbow/privacy-pools-core-sdk 可以商用吗？

@0xbow/privacy-pools-core-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @0xbow/privacy-pools-core-sdk 的下载量有多少？

根据 npm 官方下载统计，@0xbow/privacy-pools-core-sdk 在 2026/10/04 – 2026/11/02 这 30 天内被下载 7,583 次，日均约 253 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @0xbow/privacy-pools-core-sdk 还在维护吗？

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