Web3 应用中的区块链 API:工作方式与局限
区块链 API 在 Web3 应用中的作用:读取链上数据、发送交易、接收通知,以及智能合约为何需要预言机获取链外数据。文章区分了两个连接方向,说明何时使用 API 或预言机,并介绍 eth_getLogs 与 API 的局限。
审核: Maurice Sobiera
区块链 API 是一种网络接口,让应用无需运行自己的节点,即可读取区块链数据并提交交易。在 Web3 应用中,它位于用户界面与链之间。智能合约本身无法调用 Web API,链外的数据只能通过预言机(oracle)到达合约。
本文区分了 API 与区块链相连的两个方向,并说明各自的使用场景。
区块链 API 在 Web3 应用中做什么?
区块链 API 为应用提供三项能力:读取链上数据、提交交易,以及报告事件。没有它,你的后端就需要自己运行节点、保持同步并解析区块。
| 任务 | 示例 | 工作方式 |
|---|---|---|
| 读取 | 某个地址的余额、某个区块中的交易 | 向节点或 API 服务商发送请求 |
| 写入 | 发送一笔代币转账 | 用私钥签名交易,然后广播到网络 |
| 通知 | 告知后端已有一笔充值到账 | Webhook,或对节点进行轮询 |
Chaingateway 就是这样一种 API。其钱包、转账和 Webhook 端点列于 OpenAPI 文件中。Webhook 支持 Bitcoin、Ethereum、BNB Smart Chain、Polygon、Arbitrum 和 Tron。Solana 不提供 Webhook,因此 Solana 应用必须轮询。
为什么智能合约不能调用 Web API?
智能合约不能调用 Web API,因为每个节点都必须执行它并得到相同的结果。以太坊文档指出,引入外部数据会使确定性无法保证:价格 API 可能向不同节点返回不同的值,节点之间就无法再就链的状态达成一致(ethereum.org:预言机)。
这是设计本身的特性,与链所使用的语言或任何特定的 API 无关。其结果是:合约要使用某些数据,必须先通过一笔交易将这些数据写入链上。
链外数据如何到达智能合约?
链外数据通过预言机到达合约。预言机是一种应用,负责获取、验证外部信息,并将其传递给智能合约。需要某种资产价格的借贷协议,或依赖天气或航班数据的合约,都需要预言机。
以太坊文档描述了两种常见设计:
- 发布-订阅:预言机发布数据源,合约读取它。这适用于经常变化的数据,例如代币价格。
- 请求-响应:合约请求特定数据,预言机通过回调作出响应。这适用于数据集很大、而合约只需要其中一小部分的情形。发起请求的一方需要为查询及回调的 gas 付费。
由单一一方运营的预言机是单点故障。如果该方出现故障、被攻破或提供虚假数据,合约就会基于错误的数据执行操作。同一文档还描述了去中心化预言机服务,即在数据到达合约之前,多个参与者先就数据达成一致。去中心化是一个程度问题,你仍需判断所选预言机值得信任的程度。
不同任务需要哪种 API?
答案取决于数据流的方向。
| 方向 | 问题 | 工具 |
|---|---|---|
| 从链到应用 | 读取余额、发送转账、获取充值通知 | 区块链 API 或自己的节点 |
| 从外部世界到合约 | 为合约提供价格、评分或天气数值 | 预言机 |
| 从合约到外部世界 | 在链上事件发生后触发某项操作 | 由服务读取事件日志,或使用预言机 |
付款系统只使用第一行。用户向某个地址付款,Webhook 到达你的后端,然后你的后端在自己的数据库中为账户入账。整个过程不涉及预言机。关于如何在链与数据库之间划分工作,参见区块链与数据库。
应用如何从合约读取事件?
应用通过日志读取合约事件。合约发出事件后,节点会将其存入交易收据。遵循 JSON-RPC 2.0 规范的以太坊 JSON-RPC API 中的 eth_getLogs 方法,会返回与过滤条件匹配的日志。这是查找代币转账的常用方式。
针对某一代币在某个区块范围内的 ERC-20 Transfer 事件过滤器如下所示:
{ "jsonrpc": "2.0", "method": "eth_getLogs", "params": [{ "fromBlock": "0x10d4f00", "toBlock": "0x10d4f0a", "address": "0xTokenContract", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"] }], "id": 1}第一个 topic 是事件签名 Transfer(address,address,uint256) 的哈希。其他 topic 保存带索引的参数,此处为发送方和接收方。金额以十六进制数字的形式位于每条日志的 data 字段中。
区块范围很重要。许多服务商会限制单次 eth_getLogs 调用的区块范围或结果数量,因此扫描器必须分页遍历区块。能够为你解码这些日志或以 Webhook 推送它们的区块链 API,可以省去这部分代码。但它并不改变日志的含义:位于之后被重组的区块中的日志,会随该区块一起消失。
区块链 API 有哪些局限?
API 并不改变链的运作方式。只有当链本身确认时,交易才是最终的,而 API 可能比这更早地将其报告为待处理或已确认。只有在通过链的最终性规则之后,才应将充值视为已结算。
失败的 Webhook 投递不会自动重试。Chaingateway 会在每条链的失败通知端点中列出它们,例如 GET /api/v2/tron/webhooks/notifications/failed,你可以通过重试端点重新发送。处理 Webhook 的后端也应具有幂等性,以确保重新发送的通知不会导致账户被重复入账。
托管 API 还会增加对服务商的依赖。如果你需要直接访问协议,仍然可以运行节点,并通过 JSON-RPC与其通信。
准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。