# @gearbox-protocol/testnets-sdk 中文文档

规范地址：https://npmcn.com/package/%40gearbox-protocol/testnets-sdk/

版本：11\.43\.7
npm 元数据更新时间：2026-11-15T20:21:28.478Z
中文译文更新时间：2026-11-16T01:35:51.429Z
软件包许可：BUSL-1\.1

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

原始 npm 页面：https://www.npmjs.com/package/%40gearbox-protocol/testnets-sdk
原文对照：https://npmcn.com/package/%40gearbox-protocol/testnets-sdk/?lang=original
项目主页：https://gearbox.fi/
源码仓库：https://github.com/Gearbox-protocol/anvil-manager

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

- 包体积（解压后）：78.5 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：4 个
- peer 依赖：viem ^2，@gearbox-protocol/sdk \>=18
- 首次发布：2026-11-09T16:00:43.518Z
- 最新版本发布：2026-11-15T20:21:28.298Z
- 近 30 天下载量：2528（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

Gearbox 测试网( anvil- manager) API 的打入客户端

## 安装

```sh
npm install @gearbox-protocol/testnets-sdk
```

也可以使用：`pnpm add @gearbox-protocol/testnets-sdk`、`yarn add @gearbox-protocol/testnets-sdk`、`bun add @gearbox-protocol/testnets-sdk`

## README

# @gearbox-protocol/testnets-sdk (英语)

为avil-manager v1 API所打入的客户端,它运行有avilforks Gearbox调用测试网. 类型来自 Go 后端(`backend/manager/core`由 tygo; 运行 `pnpm generate:types` 内 `frontend` 在改变它们之后.

`@gearbox-protocol/sdk` 联合国 `viem` (^2) 是同行依赖关系.

## 使用量

有个客户寄了个信 创建一个 `forks:create` API 键,然后切换到创建的测试网 `accessToken`它提供 `forks:read` 财务报告和审定财务报表 `forks:write` 在测试网上,并随即失效:

```ts
import { TestnetsAPI } from "@gearbox-protocol/testnets-sdk";

const api = new TestnetsAPI({ token: process.env.ANVIL_MANAGER_TOKEN });

const created = await api.create({ network: "Mainnet", timeout: "2h" });
// or: await api.clone("mainnet-persistent", { description: "my clone" });

const fork = api.withToken(created.accessToken);
const status = await fork.waitUntilReady(created.executionId, { strict: true });
// ... use status.rpcUrl ...

const task = await fork.startTask(created.executionId, { id: "optimist" });
const done = await fork.waitForTask(created.executionId, task.id);
const result = await fork.getTaskResult<unknown>(created.executionId, done.id);
const faucet = await fork.getScriptResult<unknown>(
  created.executionId,
  "deploy-faucet",
);
const file = await fork.getArtifact(
  created.executionId,
  "deploy-faucet/output/addresses.json",
);

await fork.kill(created.executionId);
```

`getScriptResult` 财务报告和审定财务报表 `getTaskResult` 返回一个步骤 `output.json`,用 `json_parse`。需要脚本结果 `forks:read`;任务结果公开. 步骤书写不是秘密:输入、输出和共享目录被同步到S3.

## 写入一步

每个脚本和任务都得到相同的嵌入(`SHARED_DIR`, (中文(简体) ), `WORK_DIR`, (中文(简体) ), `INPUT_DIR`, (中文(简体) ), `OUTPUT_DIR`, (中文(简体) ), `OUTPUT_JSON`,以及 `INPUT_JSON` 当输入时, 键入为 `StepEnv`;路径常数是从根导出. [步骤( C) md](https://npmcn.com/STEP_CONVENTION.md) 有完整的布局。 节点步骤可以使用 `@gearbox-protocol/testnets-sdk/node`数字 :

```ts
import {
  assertWorkDir,
  readInputJson,
  writeOutputJson,
} from "@gearbox-protocol/testnets-sdk/node";

assertWorkDir();
const input = await readInputJson<MyInput>(); // undefined when the step has no input
await writeOutputJson(result); // json_stringify to $OUTPUT_JSON
```

## 网络呼号

`waitUntilReady` 财务报告和审定财务报表 `waitForTask` 民意调查最长10分1小时. 如果一个过程不能活那么长,比如在一个没有服务器的函数中,则让avil-manager回电:

```ts
const created = await api.create({
  network: "Mainnet",
  webhook: "https://hooks.gearbox.fi/fork?secret=...",
});
// later, in the handler of fork:ready:
await fork.startTask(created.executionId, {
  id: "optimist",
  webhook: "https://hooks.gearbox.fi/task?secret=...",
});
```

`clone` 带 `webhook` 我也一样 `PermissionlessTestnetsAPI` 预设。 一个叉子被网球击中 `fork:ready`最终 `fork:failed` 或者说 `fork:terminated`。一个任务 Webhook 得到 `task:finished`每一个身体都是 `WebhookEvent`。 。 。 .

一个webhook从未被存储,因此其URL可能携带一个秘密. 它必须去一个东道主 avil -manager允许。 事情可能丢失,所以保持一个最后期限 并回到一个 `get` 或者说 `getTask` 电话 这个 [后端读取器](https://npmcn.com/backend/README.md#webhooks) 记录每起事件何时起火和如何交付.

## 错误

每一次失败都是 `TestnetsError` 子类 : `TestnetStatusError` (非-2xx,与 `TestnetNotFoundError` (单位:千美元), `TestnetRequestFailedError`, (中文(简体) ), `TestnetFailedError`, (中文(简体) ), `TestnetWaitTimeoutError` 财务报告和审定财务报表 `IpfsDownloadError`。 。 。 .

## 无权限测试网

`@gearbox-protocol/testnets-sdk/permissionless` 添加 `PermissionlessTestnetsAPI`页:1 `TestnetsAPI` 它有一些测试网预设:

```ts
import { PermissionlessTestnetsAPI } from "@gearbox-protocol/testnets-sdk/permissionless";

const api = new PermissionlessTestnetsAPI({
  token: process.env.ANVIL_MANAGER_TOKEN,
});

// the input is any JSON with a chainId and, optionally, a marketConfigurator
const created = await api.createPermissionless({ input: timelockTxs });
// or from IPFS, on top of a persistent testnet:
// await api.createPermissionless({ cid }, { cloneFrom: "mainnet-persistent", scriptVersion: "staging" });

const fork = api.withToken(created.accessToken);
await fork.waitUntilReady(created.executionId);
const state = await fork.getState(created.executionId); // GearboxState
```

输入作为输入发送 `execute_txs` 脚本( e)`EXECUTE_SCRIPT_ID`),以及 `getState` 实值 `getScriptResult` 剧本.

## 手工测试

```bash
ANVIL_MANAGER_TOKEN=... pnpm create-testnet
# against a local backend
ANVIL_MANAGER_URL=http://localhost:8080 ANVIL_MANAGER_TOKEN=... pnpm create-testnet
```

## 出版

软件包是用手工出版的 `next` 频道. 版本起伏未出出 git :

```bash
cd frontend/packages/testnets-sdk && pnpm build
npm version 0.1.0-next.0 --no-git-tag-version
pnpm publish --tag next --no-git-checks && git checkout package.json
```

## 常见问题

### @gearbox-protocol/testnets-sdk 是什么？

Gearbox 测试网\( anvil- manager\) API 的打入客户端

### 如何安装 @gearbox-protocol/testnets-sdk？

在项目目录运行 npm install @gearbox-protocol/testnets-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2）、@gearbox-protocol/sdk（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gearbox-protocol/testnets-sdk 支持 TypeScript 吗？

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

### @gearbox-protocol/testnets-sdk 支持 ESM 还是 CommonJS？

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

### @gearbox-protocol/testnets-sdk 需要什么版本的 Node\.js？

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

### @gearbox-protocol/testnets-sdk 可以商用吗？

@gearbox-protocol/testnets-sdk 使用 BUSL-1\.1 许可。声明的许可为 BUSL-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @gearbox-protocol/testnets-sdk 的下载量有多少？

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

### @gearbox-protocol/testnets-sdk 还在维护吗？

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

