# @api3/airnode-protocol-v1 中文文档

规范地址：https://npmcn.com/package/%40api3/airnode-protocol-v1/

版本：3\.4\.0
npm 元数据更新时间：2026-04-07T10:33:15.546Z
中文译文更新时间：2026-11-06T20:06:12.061Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40api3/airnode-protocol-v1
原文对照：https://npmcn.com/package/%40api3/airnode-protocol-v1/?lang=original

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

- 包体积（解压后）：4.4 MB，787 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2022-04-12T15:07:45.583Z
- 最新版本发布：2024-03-18T11:35:51.036Z
- 近 30 天下载量：2404（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 0 个）

## 中文简介

这个包临时存放了Airnode v1协议合同. 随着Airnode v1的发布,这些合同将转移到 [单列空气节点](https://github.com/api3dao/airnode)。 。 。 .

## 安装

```sh
npm install @api3/airnode-protocol-v1
```

也可以使用：`pnpm add @api3/airnode-protocol-v1`、`yarn add @api3/airnode-protocol-v1`、`bun add @api3/airnode-protocol-v1`

## README

# Airnode 协议 v1

这个包临时存放了Airnode v1协议合同. 随着Airnode v1发布,这些合同将是 迁移到 [单列空气节点](https://github.com/api3dao/airnode)。 。 。 .

如果你正在寻找 Airnode v0 所使用的合同,请看 [@api3/airnode- protocol](https://github.com/api3dao/airnode/tree/master/packages/airnode-protocol)。如果你正在寻找 如何操作Airnode,请参看 [文档](https://docs.api3.org/airnode)。 。 。 .

## 说明

安装依赖关系并构建

```sh
yarn
yarn build
```

测试合同,测试覆盖面和气体报告

```sh
yarn test
# Runs exhaustive tests for Sort.sol
yarn test:extended
# Outputs to `./coverage`
yarn test:coverage
# Outputs to `.gas_report`
yarn test:gas
```

## 关于zk同步的重要注释

部署在zkSync网络上的代理Factory是一个被修改的版本([代理FactoryZk同步器](https://github.com/api3dao/airnode-protocol-v1/blob/deploy-zksync-reference/contracts/api3-server-v1/proxies/ProxyFactoryZkSync.sol))处理 CREATE2 地址计算中的差额. 此套件会以"ProxyFactory"为名导出这些部署的地址来保持接口的统一. 代理地址计算方法 `@api3/contracts` 也处理差异,所以如果使用 `@api3/contracts` 和代理Factory合同的代理地址计算方法,可以将zkSync作为任何其他网络处理. 然而,如果您有自己的代理地址衍生执行,请注意您需要为zkSync破例.

## 团结版本

用固态版本测试Repo的当前形式 `0.8.17`将部署的完整合同已锁定 在此版本中,其余部分(界面、分包合同、模拟合同)指定版本 `^0.8.0` 不限制他们的 用户。 有些模拟合同使用自定义错误,因此它们指定了版本 `^0.8.4`。 。 。 .

## 概览

-   `access-control-registry/`合同通常执行独立的出入控制计划,从继承到继承 `Ownable` 为定制的复杂模型。 因此很难追踪账户给予的特权, 它具有消极的可用性和安全影响。 这一问题在权力下放的治理中更为相关 例如,DAO需要将特权授予权力下放程度较低的代理人,审计其业绩,以及 取消被滥用的特权。 对于这种工作方式,给予的特权必须容易 可以发现. `AccessControlRegistry` 是一个共享的注册,账户可以创建树形的角色结构 其他合同可以提及.
    
-   `protocol/`:"Airnode协议"指两个协议:请求-响应协议(RRP)和发布-订阅 协议(PSP)。 RRP是拉力版本("比特币的价格是什么?"),而PSP是拉力版本("给我回电") 当比特币的价格是5万美元".). Airnode 通过收听来自 `AirnodeProtocol`, (中文(简体) ), 和 PSP 订阅,通过查询 `Allocator`s. 还有RRP和PSP的中继版本,其中 请求者指定一个中继器来发送由Airnode签名的响应.
    
-   `allocators/`:一个支持PSP的Airnode需要检测潜在的订阅服务. 为了避免不得不 手动配置 Airnode 以更新订阅, 节点操作员可以配置以参考特定 `Allocator` 合同。 这些合同执行关于如何更新订阅内容的习惯规则,哪些 可能涉及货币化.
    
-   `authorizers/`: 检测 RRP 请求或PSP 订阅的Airnode 需要知道其中哪些应该是 服务。 为了避免需要手动配置Airnode来维持白名单,节点操作员可以配置它 提及具体 `Authorizer` 合同。 这些合同执行关于下列事项的习惯规则: 应提供订阅服务,这可能涉及货币化.
    
-   `dapis/`编号: `DataFeedServer` 合同工具 _灯塔_,是单极数据输入。 灯塔可以 合并到创建 _灯塔_,是同步聚合的灯塔(我们指灯塔和灯塔) 设置为“数据种子”. _dAPIs 数据_,由 `DapiServer`是灯塔或灯塔上的名字, 数据输入. `BeaconUpdatesWithRrp` 财务报告和审定财务报表 `DataFeedUpdatesWithPsp` 使用 RRP 和 PSP 来 更新数据分别提供,这使得它们成为如何使用Airnode协议的很好的例子. 单位 添加, `BeaconUpdatesWithSignedData` 允许由相应的Airnodes签名的数据更新灯塔,它可以是 在协议之外交付。 最后,使用这些签名数据更新的特殊版本来获取 [甲骨文可提取值( OEV)](https://medium.com/api3/oracle-extractable-value-oev-13c1b6d53c5b) 内 `OevDataFeedServer`。 。 。 .
    
-   `utils/`: 如名称所示,其他合同可能需要的公用事业合同。 多点调用合同的目标是 尽量减少Airnode RPC的呼叫,并改进非议定书合同的UX. `OwnableCallForwarder` 启用角色树 内 `AccessControlRegistry` 可转移. `ExpiringMetaTxForwarder` 允许 Airnode 操作员或计数 他们授权签发签名,以拥有用户自白列表.
    

## 设计支柱

**协议化 :** API3旨在构建完全由一党甲骨文,即甲骨文提供动力的甲骨文服务 由API提供者操作. 这意味着我们不能把问题卸到节点操作员身上, 无论是节点还是协议 有必要 _设置和忘记_。这最好反映在PSP中,它允许人们建立数据输入(和许多其他类型) ,无需节点操作员作出任何努力.

应当指出的是,我们也认为甲骨文商业模式是协议的延伸,其目的也是: 一个设定和忘记的商业模式. `Allocator`s 和 `Authorizer`s是数据协议中用于 货币化也要被规范下来,我们将释放合同 在未来充分充实这一点.

**特性 :** 协议设计中一个常见的陷阱是过于笼统,试图涵盖所有潜在的 使用大小写。 这使得用户现在需要学习的许多抽象,同时不提供任何结构 用户可以工作了。 反之,我们采取了一种有意见的方法, 提供脚手架进入我们的方向 认为用户应该向前构建.

**不可用性 :** API3旨在建立不信任的甲骨文服务,这意味着人们只需要信任 数据来源(这是不可避免的),没有其他人。 即使由DAO进行治理也会污染这种信任最小化。 改为: 避免这种情况,我们做两件事:(1) 我们的合同不能升级,因为这不可避免地需要某种 (2) 定义的终点 [伊办](https://docs.api3.org/ois) 确定了(甲状腺整合规格) 以 [结束点 ID](https://docs.api3.org/airnode/latest/concepts/endpoint.html#endpointid)s,端点标识和 [Airnode ABI 编码参数](https://docs.api3.org/airnode/latest/reference/specifications/airnode-abi-specifications.html) 构成 [模板标识](https://docs.api3.org/airnode/latest/reference/specifications/airnode-abi-specifications.html)s, (中文(简体) ), [空气节点地址](https://docs.api3.org/airnode/latest/reference/specifications/airnode-abi-specifications.html) 财务报告和审定财务报表 模板ID构成灯塔ID,而灯塔ID构成灯塔设置ID. 因此,可以追踪 整个数据供应链从API开始,一直到汇总数据反馈,并做到信任最小化 就是这样.

**优化缩放 :** 我们的解决方案一般是乐观的, 一个防篡改的,高效的 以及一个信任最小且效率较低的解决方案。 第一个解决办法是防篡改,因为它取决于 airnode 的签名,但是它的交付是集中的性能。 只有这样的风险 解决办法是使其无法使用,在这种情况下,尽量减少信任的解决办法应该无缝地倒退 改为: 要将甲骨文服务最小化,它就必须与链条直接互动. 取决于第三方 中继,或要求通过区块链或状态通道与其他甲骨文节点进行交互 对尽量减少信任的解决办法来说是不可接受的,因为这增加了失败点.

这方面的一个例子可见于 `DapiServer`,通过从Airnodes收集签名数据来更新灯塔集 和电话 `updateBeaconWithSignedData()` 财务报告和审定财务报表 `updateBeaconSetWithBeacons()` 由一个集中的代理。 如果是这样的话 这个服务停止了,Airnodes可以通过呼叫更新各自的灯塔 `fulfillPspBeaconUpdate()` 如果他们有PSP 订阅或可以使用 `updateDataFeedWithSignedData()` 仅凭自己签名的数据更新 灯塔 [边框](https://byog.io/) ),之后,灯塔集可以由任何人打电话更新 `updateBeaconSetWithBeacons()` 或通过 PSP 订阅 `fulfillPspBeaconSetUpdate()` 基于 偏移条件。 后一种操作方法预计不会被使用,但是它作为故障安全装置存在 前一种方法是可以接受的.

## 执行详情

### `AccessControlRegistry` 和角色树

使用 `AccessControlRegistry` 在此重现( 即 `AccessControlRegistryAdminned` (合同)使用 接下来的公约,每个合同创建角色树.

```
Root
  └─── Admin (can grant and revoke the roles below)
        ├── Contract specific role #1
        ├── Contract specific role #2
        └── Contract specific role #3
```

在这方面,根本作用必然与一个账户联系在一起。 合同管理者的作用来自根本作用和 合同管理角色描述。 这意味着具有相同合同管理角色描述的合同将 共享角色树.

### `...WithManager` 对 `...WithAirnode`

有两种类型 `AccessControlRegistryAdminned` 合同中,以 `...WithManager` 财务报告和审定财务报表 结束于 `...WithAirnode`。这主要是指如果根角色属于管理器账户(例如: API3 DAO),或如果这是一个共享账户,每个Airnode管理自己的角色树和相关权限. 说明 当适用时,根角色与管理者账户是不可改变地联系在一起的,这意味着如果您希望管理者 可转让,请指定 `OwnableCallForwarder` (这是一个 `Ownable` 其所有权可以是 成为经理 并通过这个给你打电话.

### 中继RRP和PSP

RRP和PSP有中继版本,其中请求者指定了一个中继器来发送由各自签名的数据 空气节点。 请注意,我们的目标是以中继形式复制整个RRP和PSP功能,而不是 设计基于中继的甲骨文协议。 由于为 RRP 和 PSP 进行中继, 需要信任中继器, 而不是不信任 篡改数据,但不拒绝服务,在PSP案中,即使 条件不能满足 – 更适合指定信任的中继器 .

### 赞助商和赞助商钱包

我们已经确定甲骨文服务的天然气成本是商业模式中一个非常重要的摩擦点. 虽然 正如上文所讨论,我们发现,这里转发签名的数据是一个更好的选择,我们发现这远远没有通过信任最小化 自己来 作为一种解决办法,我们在协议中建立了一个方案,允许用户支付由他们造成的天然气成本 用途。 您可以为此参考 v0 文档, 因为这个概念从此没有改变 : [https://docs.api3.org/airnode/latest/concepters/赞助商.html](https://docs.api3.org/airnode/latest/concepts/sponsor.html)

赞助是按RRP的要求进行的,赞助是按PSP的要求进行的。 中继服务受到影响 与甲骨文服务相同的煤气成本问题 因为请求者事先知道并信任他们 只要他们从他们那里得到接力服务,我们期望同样的赞助计划也能适用。 发起人 协议的钱包及其中继版本单独保存,而赞助状态统一。 单位 换句话说,当赞助者赞助RRP请求者时,他们也赞助他们转发RRP. 然而,两个独立的 将为请求者保存赞助钱包,为RRP保存一个,为中继RRP保存一个.

### 不需要Airnode运营商交易

在第一部分甲骨文设定中,要求Airnode操作员进行任何交易,是一种重大的摩擦 点。 这就是为什么Airnode运营商不需要部署自己的合同(它们使用共享的) `AirnodeProtocol` 或进行交易以宣布任何情况。 选择加入或退出货币化计划 只需要更新配置文件即可添加或删除 `Allocator`s 和 `Authorizer`和重新部署,以及 通报他们通过非链路渠道这样做.

### 数据种子货币化

何况 [服务范围](https://github.com/api3dao/api3-whitepaper/blob/3f4a2e3a19b45bd1a6c26f7b6ab21861fc0373ef/api3-whitepaper.tex#L727), (中文(简体) ), 我们预计主要数据输入货币化模型将基于OEV(见图1) [平纸](https://raw.githubusercontent.com/api3dao/oev-litepaper/main/oev-litepaper.pdf)) (中文(简体) ). 落实到 最优化的方式,我们把它建 `Api3ServerV1`,但数据输入用户如果愿意可以选择退出.

### 数据种子代理

数据素材是受欢迎的甲骨文服务,主要是因为它们简单而高度标准化. 虽然如此,它是一个 要求用户正确执行集成,提供技术支持不是一个可扩展的解决方案. 我们的目标是使我们的用户登入过程完全自动化,我们拥有许多相同的数据输入的变体(是否) 用户想要读取 dAPI, 显示器设置为 dAPI 指向, OEV 启用或禁用, 无论是否安全 覆盖面等) 为了同时解决这两个问题,我们决定让用户能够使用 [API3 市场](https://market.api3.org/dapis) \* 部署实施所需一体化的代理 在方案方面。 因此,无论API3数据为用户提供何种使用,他们只需要调用 `read()` 函数.

为了尽量减少使用代理人的间接费用,我们更希望正常部署(而不是被克隆)。 改为: 减低这些代理的部署成本,我们把执行的同样多推进到DapiServer.

### 过期元交易

`AccessControlRegistry`, (中文(简体) ), `Allocator`s 和 `Authorizer`s 支持元交易。 这主要是考虑到事实 用户希望Airnode运营商进行交易,Airnode运营商不希望支付 这些交易的天然气成本。 考虑到我们的要求和预期的使用情况,我们最终定型了 元交易执行,我们完全同意不适合一般用途。 这里的要点 因为我们不想让元交易互相阻塞 并且我们还有期 时间戳来避免负债。 作为进一步防范,我们允许签名人取消元交易 (尚未执行) 与自己的交易.

## 常见问题

### @api3/airnode-protocol-v1 是什么？

这个包临时存放了Airnode v1协议合同\. 随着Airnode v1的发布,这些合同将转移到 单列空气节点。 。 。 \.

### 如何安装 @api3/airnode-protocol-v1？

在项目目录运行 npm install @api3/airnode-protocol-v1，或使用 pnpm add / yarn add / bun add。

### @api3/airnode-protocol-v1 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/api3\_\_airnode-protocol-v1 是否存在。

### @api3/airnode-protocol-v1 支持 ESM 还是 CommonJS？

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

### @api3/airnode-protocol-v1 可以商用吗？

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

### @api3/airnode-protocol-v1 的下载量有多少？

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

### @api3/airnode-protocol-v1 还在维护吗？

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