# @api3/contracts 中文文档

规范地址：https://npmcn.com/package/%40api3/contracts/

版本：42\.0\.1
npm 元数据更新时间：2026-10-06T15:33:30.227Z
中文译文更新时间：2026-11-06T09:57:59.892Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40api3/contracts
原文对照：https://npmcn.com/package/%40api3/contracts/?lang=original
项目主页：https://github.com/api3dao/contracts#readme
源码仓库：https://github.com/api3dao/contracts

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

- 包体积（解压后）：5.4 MB，1297 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：4 个
- 首次发布：2023-03-10T17:29:44.435Z
- 最新版本发布：2026-10-06T15:33:29.750Z
- 近 30 天下载量：4834（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：167（近 12 个月 31 个）

## 中文简介

API3服务通过的合同

## 安装

```sh
npm install @api3/contracts
```

也可以使用：`pnpm add @api3/contracts`、`yarn add @api3/contracts`、`bun add @api3/contracts`

## README

# @ api3/ 合同

[![npm version](https://img.shields.io/npm/v/%40api3%2Fcontracts)](https://www.npmjs.com/package/@api3/contracts) ![downloads per week](https://img.shields.io/npm/dw/%40api3%2Fcontracts) [![continuous-build](https://img.shields.io/github/actions/workflow/status/api3dao/contracts/continuous-build.yml?label=continuous-build)](https://github.com/api3dao/contracts/actions/workflows/continuous-build.yml) [![validate-verify](https://img.shields.io/github/actions/workflow/status/api3dao/contracts/validate-verify.yml?label=validate-verify)](https://github.com/api3dao/contracts/actions/workflows/validate-verify.yml) [![license](https://img.shields.io/npm/l/%40api3%2Fchains)](https://www.npmjs.com/package/@api3/contracts)

> 提供Api3服务的合同

这个软件包提供了集成数据源的工具,可以在 [Api3 市场](https://market.api3.org/). 典型的工作流程如下:

1.  在 Api3 市场购买数据输入订阅并获得相应的代理地址
2.  使用此软件包提供的代理地址计算工具功能( Name`computeCommunalApi3ReaderProxyV1Address()`)验证正在使用的代理地址
3.  使用阅读器合同中此套件提供的代理合同接口, 如 [https://github.com/api3dao/data-feed-reader-example 页面存档备份,存于互联网档案馆](https://github.com/api3dao/data-feed-reader-example)

一揽子计划包括的更为完整的清单如下:

-   所有便利Api3数据反馈服务的合同,包括OEV拍卖
-   `@typechain/ethers-v6` 这些合同的打字
-   这些合同的Api3部署地址
-   代理地址计算工具函数

## • 警卫

我们对合同及其离链部分进行了10+审计. 以下是与本回购合同直接相关的报告(或在某些情况下,其较早版本).

-   [2024-10-24 泉水图](https://npmcn.com/package/%40api3/contracts/audit-reports/2024-10-24%20Quantstamp.pdf) (参考: [这里](https://github.com/api3dao/contracts-qs/tree/final-report) (以散装方式)
-   [2024-02-20 u口通](https://npmcn.com/package/%40api3/contracts/audit-reports/2024-02-20%20Quantstamp.pdf)
-   [2023-12-20 问号标注](https://npmcn.com/package/%40api3/contracts/audit-reports/2023-12-20%20Quantstamp.pdf)
-   [2023-03-02 西格玛总理](https://npmcn.com/package/%40api3/contracts/audit-reports/2023-03-02%20Sigma%20Prime.pdf)
-   [2022-03-30 位数轨迹](https://npmcn.com/package/%40api3/contracts/audit-reports/2022-03-30%20Trail%20of%20Bits.pdf)
-   [2021-12-16 西格玛正统](https://npmcn.com/package/%40api3/contracts/audit-reports/2021-12-16%20Sigma%20Prime.pdf)

对于错误报告, 联系人 `security@api3.org`

## 发展

最常见的变化类型是增加或更新一个链条。 可以通过创建或编辑 `data/chains/` 目录.

如果对链作任何改变,你将需要"再生"链. 这将把所有的 JSON 文件汇编成一个单一的 TypeScript 文件, 以便导入项目 。 请检查一下 [开发者指令](https://npmcn.com/package/%40api3/contracts/#readme--developer-instructions) 关于如何做到这一点的更多信息.

TypeScript链的列表也针对所有JSON文件列表进行验证,以确保所有文件同步.

注:如果不重新生成 TypeScript 链, 您将无法将更改推向链条 .

## QQ 开发者指令

安装依赖关系并构建

```sh
pnpm i && pnpm build
```

测试合同,获得覆盖和天然气报告

```sh
pnpm test
pnpm test:extended
# Outputs to `./coverage`
pnpm test:coverage
# Outputs to `gas_report`
pnpm test:gas
```

生成最新的 `CHAINS` 矩阵和输出文件到 `src/generated/chains.ts`

```sh
pnpm generate:chains
```

生成最新的 `DAPPS` 矩阵和输出文件到 `src/generated/dapps.ts`

```sh
pnpm generate:dapps
```

生成所有链条的部署地址并输出文件到 `src/generated/deployments.ts`

```sh
pnpm generate:deployment-addresses
```

生成上述全部文件为一

```sh
pnpm generate
```

检查含有元数据的本地文件

```sh
pnpm check
```

核实供应商合同是否与各自包件合同相同.

```sh
pnpm verify-vendor-contracts
```

核查部署情况并验证其现状

```sh
# on all chains
pnpm verify-deployments
# or a single chain
NETWORK=ethereum pnpm verify-deployments
# on all chains
pnpm validate-deployments
# or a single chain
NETWORK=ethereum pnpm validate-deployments
```

## • API

从此软件包导出以下变量/功能

### 中国

支持链列表的单一真相来源 . 静态数组 `Chain` 对象.

```ts
import { CHAINS } from '@api3/contracts';
console.log(CHAINS);
/*
[
  {
    name: 'Arbitrum testnet',
    alias: 'arbitrum-sepolia-testnet',
    id: '421614',
    ...
  },
  ...
]
*/
```

### DAPPS 软件

支持 dApps 列表的单一真相来源 . 静态数组 `Dapp` 对象.

```ts
import { DAPPS } from '@api3/contracts';
console.log(DAPPS);
/*
[
  {
    aliases: {
      'compound-finance-usde': {
        chains: ['mantle'],
        title: '...',
        description: '...',
      },
    },
    homepageUrl: 'https://...',
  }
  ...
]
*/
```

### 部署 地址

包含所有链条上所有合同的部署地址的对象。 键是合同名,值是对象,其中键是链式ID,值是合同地址.

```ts
import { deploymentAddresses } from '@api3/contracts';
console.log(deploymentAddresses);
/*
{
  "GnosisSafeWithoutProxy": {
    "1": "0x...",
    "10": "0x...",
    "56": "0x...",
    ...
  },
  "OwnableCallForwarder": {
    "1": "0x...",
    "10": "0x...",
    "56": "0x...",
    ...
  },
  ...
}
*/
```

### 拍卖商Metadata

一个包含拍卖商元数据的对象.

```ts
import { auctioneerMetadata } from '@api3/contracts';
console.log(auctioneerMetadata);
/*
{
  "auction-resolvers": ["0x..."],
  "auction-cops": ["0x..."]
}
*/
```

### dapi 管理元数据

含有 merkle 树标的对象.

```ts
import { dapiManagementMetadata } from '@api3/contracts';
console.log(dapiManagementMetadata);
/*
{
  "dapiManagementMerkleRootSigners": [
    "0x...",
    "0x..."
  ],
  "dapiPricingMerkleRootSigners": [
    "0x...",
    "0x..."
  ],
  "signedApiUrlMerkleRootSigners": [
    "0x...",
    "0x..."
  ]
}
*/
```

### 不安全的计算DappId

为给定的dApp别名和链式ID计算dApp ID. 这个功能是不安全的,因为它不验证输入,所以它只应该在保证输入正确时使用.

```ts
import { unsafeComputeDappId } from '@api3/contracts';
const dappId = unsafeComputeDappId('dtrinity', '252');
console.log(dappId);
/*
16210721173577624589952893185091679941657223823840386808143855919126917477566n
*/
```

### 计算 Api3 读取器ProxyV1 地址

为给定的链式ID,dAPI名,dApp ID和元数据计算 Api3 ReaderProxyV1 地址.

```ts
import { computeApi3ReaderProxyV1Address } from '@api3/contracts';
const address = computeApi3ReaderProxyV1Address(
  '1',
  'ETH/USD',
  '16210721173577624589952893185091679941657223823840386808143855919126917477566',
  '0x'
);
console.log(address);
/*
0xC93Da088b0c78dE892f523db0eECb051Cb628991
*/
```

### 计算CommunalApi3读取器ProxyV1 地址

计算 Api3 Reader ProxyV1 地址被 Api3 市场用于给定的 dAPI 名称和链式ID .

```ts
import { computeCommunalApi3ReaderProxyV1Address } from '@api3/contracts';
const address = computeCommunalApi3ReaderProxyV1Address('1', 'ETH/USD');
console.log(address);
/*
0x5b0cf2b36a65a6BB085D501B971e4c102B9Cd473
*/
```

### 计算 DappSpecifical Api3 读取器ProxyV1 地址

计算 dApp 特定 Api3ReaderProxyV1 地址,用于给定 dApp 的别名,链式ID,和 dAPI 名. 此函数可用于检索特定链上特定 dApp 的代理地址 .

```ts
import { computeDappSpecificApi3ReaderProxyV1Address } from '@api3/contracts';
const address = computeDappSpecificApi3ReaderProxyV1Address('dtrinity', '252', 'BTC/USD');
console.log(address);
/*
0x781d431031Ffd5273585e65F663699Dcb74834E6
*/
```

### 硬汉 Config. blockscout ()

返回可用作 `blockscout` 领域 [`hardhat.config.js`](https://hardhat.org/hardhat-runner/docs/config) (要求 [`hardhat-etherscan` 插件](https://v2.hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify)) (中文(简体) ).

它包括一个 `customChains` 字段,包括所有支持Blockscout合同验证的链条 API.

```ts
import { hardhatConfig } from '@api3/contracts';
console.log(hardhatConfig.blockscout());
/*
{
  enabled: true,
  customChains: [
    ...
  ]
}
*/
```

### 硬汉网络

返回一个对象,其中密钥是每个链子的别名,而值是可以作为对象的对象 `networks` 领域 [`hardhat.config.js`](https://v2.hardhat.org/hardhat-runner/docs/config)。 。 。 .

默认 `url` 值可以被链式特定环境变量所压倒. 这些环境变量的形式是: `HARDHAT_HTTP_RPC_URL_${toUpperSnakeCase(chain.alias)}`例如. `HARDHAT_HTTP_RPC_URL_ARBITRUM_SEPOLIA_TESTNET`。 。 。 .

```ts
import { hardhatConfig } from '@api3/contracts';
console.log(hardhatConfig.networks());
/*
{
  "arbitrum-sepolia-testnet": {
      accounts: { mnemonic: '' },
      chainId: '421614',
      url: 'https://...',
  },
  ...
}
*/
```

### 硬汉 Config.etherscan ()

返回可用作 `etherscan` 领域 [`hardhat.config.js`](https://v2.hardhat.org/hardhat-runner/docs/config) (要求 [`hardhat-etherscan` 插件](https://v2.hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify)) (中文(简体) ).

它包括一个 `apiKey` 字段可以设置 `ETHERSCAN_API_KEY` 环境变量。 还有 `customChains` 字段,其中包含所有支持以太子V2合同验证的链条 API.

```ts
import { hardhatConfig } from '@api3/contracts';
console.log(hardhatConfig.etherscan());
/*
{
  apiKey: someApiKey,
  customChains: [
    ...
  ]
}
*/
```

### 硬汉 Config. get Envariable Names ()

返回预计为 Hardhat 配置设定的环境变量名称 .

```ts
import { hardhatConfig } from '@api3/contracts';
console.log(hardhatConfig.getEnvVariableNames());
/*
[
  'MNEMONIC',
  'KEYCARD_ACCOUNT',
  'ETHERSCAN_API_KEY',
  'HARDHAT_HTTP_RPC_URL_APECHAIN_ARBITRUM_SEPOLIA_TESTNET',
  ...
]
*/
```

### 双链链( )

返回格式中的链条数组 [维埃姆](https://viem.sh/docs/chains/introduction) 期待着 每个链对象都可以用来 [创建 Viem 公共客户端](https://viem.sh/docs/clients/public#usage)。 。 。 .

额外 `rpcUrls` 通过使用环境变量可以(可选择)添加数值。 这些环境变量的形式是: `API3_CHAINS_HTTP_RPC_URL_${toUpperSnakeCase(chain.alias)}`。如果检测到某一链的匹配环境变量,则该变量将被添加到 `http` 数组 `rpcUrls.environment` 对象。 如果没有检测到匹配的环境变量, 那么 `http` 数组为空.

```ts
import { viemConfig } from '@api3/contracts';
console.log(viemConfig.chains());
/*
[
  {
    id: 421613,
    name: 'arbitrum-sepolia-testnet',
    network: 'arbitrum-sepolia-testnet',
    rpcUrls: { default: ..., public: ..., environment: ... }
    ...
  },
  ...
]
*/
```

### 类型

导出类型 `src/types.ts` 从 [佐德语](https://github.com/colinhacks/zod) schemas,也用于验证每个链. 由TypeChain生成的与合同有关的类型可见于 `typechain-types` 工程建成后.

## \*

此 CLI 为计算 dApp ID 和检索代理地址等重要链上信息提供功能命令 .

### 打印- api3reader proxyv1- 地址

打印 dApp 特定 Api3ReaderProxyV1 地址,用于给定 dApp 的别名和链式ID.

```sh
npx @api3/contracts print-api3readerproxyv1-address --dapp-alias lendle --chain-id 5000 --dapi-name ETH/USD
```

### 计算dapp-id

为给定的dApp别名和链式ID计算dApp ID.

```sh
npx @api3/contracts compute-dapp-id --dapp-alias mach-finance --chain-id 146
```

## · 释出

自动处理新版本 [变化](https://github.com/changesets/changesets)。在合并前,拉动请求应当包括更改器文件. 这些可以通过运行生成 `pnpm changeset` 并遵循指示。 一旦新版本准备发布, 只需合并 `main` 输入 `production` 树枝。 更改集文件将合并为一个新版本,该版本将发布到npm.

更多信息载于本报告 [Api3 准则](https://github.com/api3dao/tasks/blob/main/API3%20Packages/changeset.md)。 。 。 .

## 常见问题

### @api3/contracts 是什么？

API3服务通过的合同

### 如何安装 @api3/contracts？

在项目目录运行 npm install @api3/contracts，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 api3-contracts，可以用 npx api3-contracts 直接运行。

### @api3/contracts 支持 TypeScript 吗？

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

### @api3/contracts 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @api3/contracts 需要什么版本的 Node\.js？

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

### @api3/contracts 可以商用吗？

@api3/contracts 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @api3/contracts 的下载量有多少？

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

### @api3/contracts 还在维护吗？

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