@ api3/ 合同

提供Api3服务的合同

这个软件包提供了集成数据源的工具,可以在 Api3 市场. 典型的工作流程如下:

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

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

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

• 警卫

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

• 2024-10-24 泉水图 (参考: 这里 (以散装方式)
• 2024-02-20 u口通
• 2023-12-20 问号标注
• 2023-03-02 西格玛总理
• 2022-03-30 位数轨迹
• 2021-12-16 西格玛正统

对于错误报告, 联系人 [email protected]

发展

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

如果对链作任何改变,你将需要"再生"链. 这将把所有的 JSON 文件汇编成一个单一的 TypeScript 文件, 以便导入项目 。 请检查一下 开发者指令 关于如何做到这一点的更多信息.

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

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

QQ 开发者指令

安装依赖关系并构建

pnpm i && pnpm build

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

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

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

pnpm generate:chains

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

pnpm generate:dapps

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

pnpm generate:deployment-addresses

生成上述全部文件为一

pnpm generate

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

pnpm check

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

pnpm verify-vendor-contracts

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

# 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 对象.

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

DAPPS 软件

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

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

部署 地址

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

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

拍卖商Metadata

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

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

dapi 管理元数据

含有 merkle 树标的对象.

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

不安全的计算DappId

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

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

计算 Api3 读取器ProxyV1 地址

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

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 .

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

计算 DappSpecifical Api3 读取器ProxyV1 地址

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

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

硬汉 Config. blockscout ()

返回可用作 blockscout 领域 hardhat.config.js (要求 hardhat-etherscan 插件) (中文(简体) ).

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

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

硬汉网络

返回一个对象,其中密钥是每个链子的别名,而值是可以作为对象的对象 networks 领域 hardhat.config.js。 。 。 .

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

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

硬汉 Config.etherscan ()

返回可用作 etherscan 领域 hardhat.config.js (要求 hardhat-etherscan 插件) (中文(简体) ).

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

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

硬汉 Config. get Envariable Names ()

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

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

双链链( )

返回格式中的链条数组 维埃姆 期待着 每个链对象都可以用来 创建 Viem 公共客户端。 。 。 .

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

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 从 佐德语 schemas,也用于验证每个链. 由TypeChain生成的与合同有关的类型可见于 typechain-types 工程建成后.

*

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

打印- api3reader proxyv1- 地址

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

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

计算dapp-id

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

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

· 释出

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

更多信息载于本报告 Api3 准则。 。 。 .