@gearbox-protocol/testnets-sdk

中文文档
11.43.7发布于 2026/11/16BUSL-1.1TypeScriptES Module近 30 天下载 2528

Typed client for the Gearbox testnets (anvil-manager) API

原始使用文档
文档目录7 节
  1. Usage
  2. Writing a step
  3. Webhooks
  4. Errors
  5. Permissionless testnets
  6. Manual testing
  7. Publishing

@gearbox-protocol/testnets-sdk

Typed client for the anvil-manager v1 API, which runs the anvil forks Gearbox calls testnets. The types are generated from the Go backend (backend/manager/core) by tygo; run pnpm generate:types in frontend after changing them.

@gearbox-protocol/sdk (>=18) and viem (^2) are peer dependencies.

Usage

One client sends one token. Create with a forks:create API key, then switch to the created testnet's accessToken. It grants forks:read and forks:write on that testnet only, and expires with it:

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 and getTaskResult return a step's output.json, parsed with json_parse. A script result needs forks:read; a task result is public. Nothing a step writes is secret: inputs, outputs and the shared dir are synced to S3.

Writing a step

Every script and task gets the same env (SHARED_DIR, WORK_DIR, INPUT_DIR, OUTPUT_DIR, OUTPUT_JSON, and INPUT_JSON when it has an input), typed as StepEnv; the path constants are exported from the root. STEP_CONVENTION.md has the full layout. Node steps can use @gearbox-protocol/testnets-sdk/node:

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

Webhooks

waitUntilReady and waitForTask poll for up to 10 minutes and 1 hour. Where a process cannot live that long, e.g. in a serverless function, let anvil-manager call back instead:

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 takes webhook too, and so do the PermissionlessTestnetsAPI presets. A fork webhook gets fork:ready, and finally fork:failed or fork:terminated. A task webhook gets task:finished. Every body is a WebhookEvent.

A webhook is never stored, so its URL may carry a secret. It must go to a host anvil-manager allows. Events can be lost, so keep a deadline and fall back to one get or getTask call. The backend README documents when each event fires and how it is delivered.

Errors

Every failure is a TestnetsError subclass: TestnetStatusError (non-2xx, with TestnetNotFoundError for 404), TestnetRequestFailedError, TestnetFailedError, TestnetWaitTimeoutError and IpfsDownloadError.

Permissionless testnets

@gearbox-protocol/testnets-sdk/permissionless adds PermissionlessTestnetsAPI, a TestnetsAPI that has some testnet presets:

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

The input is sent as the input of the execute_txs script (EXECUTE_SCRIPT_ID), and getState is getScriptResult of that script.

Manual testing

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

Publishing

The package is published by hand to the next channel. The version bump stays out of git:

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 共发布 17 个版本,首次发布于 2026/11/10;过去 12 个月发布了 17 个版本。

版本发布日期距今
11.43.7latest2026/11/16今天
11.43.62026/11/123 天前
11.43.52026/11/123 天前
11.43.42026/11/123 天前
11.43.32026/11/123 天前
11.43.22026/11/123 天前

其他发布通道:bootstrap → 0.0.0-bootstrap.0,next → 11.41.0-next.6。

关于 @gearbox-protocol/testnets-sdk 的常见问题

@gearbox-protocol/testnets-sdk 是什么?

Typed client for the Gearbox testnets (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 和提交记录判断。