网络配置 - OpenZeppelin 文档

本文档详细介绍了 OpenZeppelin Relayer 的网络配置系统,支持通过 JSON 文件配置多种区块链网络,包括EVM兼容网络、Solana 和 Stellar。文档涵盖了网络类型、配置方法(包括分离 JSON 文件和直接配置)、网络字段参考、特殊网络标签的用法、各种网络的配置示例、网络继承以及最佳实践,同时提供了故障排除的指导。

网络配置

OpenZeppelin Relayer 通过灵活的基于 JSON 的配置系统支持多个区块链网络。本指南涵盖了配置 relayer 实例网络所需的一切。

概述

网络在 JSON 配置文件中定义,允许你:

  • 配置任何兼容 EVM 的网络(Ethereum、Polygon、BSC、Arbitrum、Optimism 等)

  • 设置 Solana 网络 (mainnet-beta, devnet, testnet, 自定义 RPC 终端)

  • 配置 Stellar 网络 (Pubnet, Testnet, 自定义网络)

  • 创建具有特定 RPC 终端,链 ID 和网络参数的自定义网络配置

  • 使用继承来创建网络变体,而无需复制配置

网络类型

网络类型 描述
evm 以太坊虚拟机兼容网络。通过配置链 ID、RPC URL 和特定于网络的参数来支持任何 EVM 链。
solana Solana 区块链网络。 支持所有 Solana 集群和自定义 RPC 终端。
stellar Stellar 区块链网络。支持 Stellar 公共网络和测试网。

配置方法

默认网络配置

如果在你的 config.json 中未指定 networks 字段,则 relayer 将自动从 ./config/networks 目录加载网络配置。 这是默认行为。

{
  "relayers": [...],
  "notifications": [...],
  "signers": [...]
  // 没有 "networks" 字段 - 默认为 "./config/networks"
}
一旦你在配置中指定了 networks 字段,默认的 ./config/networks 目录将不会自动加载。 如果你想使用该目录中的文件,你必须显式指定路径 "./config/networks"

你可以通过两种方式配置网络:

方法 1:单独的 JSON 文件

在你的主 config.json 中指定网络配置文件的路径:

{
  "relayers": [...],
  "notifications": [...],
  "signers": [...],
  "networks": "./config/networks"  // 指向目录或文件的路径
}
这与默认行为相同,但已明确指定。 你也可以指向不同的目录或文件路径。

每个 JSON 文件 必须 包含一个顶级 networks 数组:

{
  "networks": [\
    // ... 网络定义 ...\
  ]
}

当使用目录结构时:

networks/
├── evm.json        # {"networks": [...]}
├── solana.json     # {"networks": [...]}
└── stellar.json    # {"networks": [...]}

方法 2:直接配置

直接在你的主 config.json 中定义网络,而不是使用单独的文件:

{
  "relayers": [...],
  "notifications": [...],
  "signers": [...],
  "networks": [\
    {\
      "type": "evm",\
      "network": "ethereum-mainnet",\
      "chain_id": 1,\
      // ... 其他字段\
    }\
  ]
}

当使用此方法时,将忽略默认的 ./config/networks 目录,并且只有在此数组中定义的网络可用。

网络字段参考

常用字段

所有网络类型都支持以下配置字段:

字段 类型 必需 描述
type string 网络类型:"evm""solana""stellar"
network string 唯一的网络标识符(例如,“ethereum-mainnet”,“polygon-mumbai”)
from string 要从中继承的父网络的名称(仅限相同类型)
rpc_urls array[string] 是* RPC 终端 URL 列表(*基础网络必需,继承网络可选)
explorer_urls array[string] 区块链浏览器 URL 列表
average_blocktime_ms number 估计的块之间平均时间(以毫秒为单位)
is_testnet boolean 这是否为测试网(影响行为和验证)
tags array[string] 用于分类和过滤的任意标签

特殊网络标签

某些标签具有特殊含义并影响 relayer 行为:

标签 描述和行为
rollup 识别Layer2 Rollup 网络(例如,Arbitrum、Optimism、Base)
optimism 识别使用 OP Stack 的基于 Optimism 的网络(例如,Optimism、Base、World Chain)
no-mempool 指示缺少传统 mempool 的网络(例如,Arbitrum)
deprecated 标记已弃用且将来版本中可能会删除的网络
示例:使用特殊标签

这是一个示例,展示了如何在实践中使用特殊标签:

{
  "type": "evm",
  "network": "arbitrum-one",
  "chain_id": 42161,
  "required_confirmations": 1,
  "symbol": "ETH",
  "rpc_urls": ["https://arb1.arbitrum.io/rpc"],
  "tags": ["rollup", "no-mempool"],  // Arbitrum 是一个没有 mempool 的 rollup
  "is_testnet": false
}

这些标签帮助 relayer:

  • Rollup 应用特定的交易处理

  • 对 OP Stack 链使用优化的费用计算

  • 跳过没有 mempool 的网络的与 mempool 相关的操作

  • 警告用户有关已弃用的网络

EVM 特定字段

字段 类型 必需 描述
chain_id number 是* 唯一的链标识符(例如,以太坊主网为 1,Polygon 为 137)(*基础网络必需,继承网络可选)
required_confirmations number 是* 在认为交易最终确定之前需要的区块确认数(*基础网络必需,继承网络可选)
symbol string 是* 原生货币符号(例如,“ETH”,“MATIC”,“BNB”)(*基础网络必需,继承网络可选)
features array[string] 支持的功能(例如,["eip1559", "london"])
示例:EVM 网络配置

这是一个展示 EVM 网络配置的示例:

{
  "type": "evm",
  "network": "ethereum-mainnet",
  "chain_id": 1,                    // 以太坊主网链 ID
  "required_confirmations": 12,     // 高安全性:12 个确认
  "symbol": "ETH",                  // 原生货币符号
  "features": ["eip1559"],          // 支持 EIP-1559 费用市场
  "rpc_urls": ["https://mainnet.infura.io/v3/YOUR_KEY"],
  "is_testnet": false
}

Solana 特定字段

目前,Solana 网络仅使用常用字段。 将来版本中可能会添加其他 Solana 特定的配置选项。

Stellar 特定字段

字段 类型 必需 描述
passphrase string 用于交易签名和网络识别的网络口令短语(对于所有网络(包括基础网络)都是可选的)
示例:Stellar 网络配置

这是一个展示带有口令短语的 Stellar 网络配置的示例:

{
  "type": "stellar",
  "network": "pubnet",
  "rpc_urls": ["https://horizon.stellar.org"],
  "explorer_urls": ["https://stellar.expert/explorer/public"],
  "passphrase": "Public Global Stellar Network ; September 2015",  // 官方主网口令短语
  "average_blocktime_ms": 5000,
  "is_testnet": false
}

配置示例

基本 EVM 网络

{
  "type": "evm",
  "network": "ethereum-mainnet",
  "chain_id": 1,
  "required_confirmations": 12,
  "symbol": "ETH",
  "rpc_urls": ["https://mainnet.infura.io/v3/YOUR_KEY"],
  "explorer_urls": ["https://etherscan.io"],
  "average_blocktime_ms": 12000,
  "is_testnet": false,
  "tags": ["mainnet", "ethereum"]
}

带有标签的Layer2 EVM 网络

{
  "type": "evm",
  "network": "optimism",
  "chain_id": 10,
  "required_confirmations": 1,
  "symbol": "ETH",
  "rpc_urls": [\
    "https://mainnet.optimism.io",\
    "https://optimism.drpc.org"\
  ],
  "features": ["eip1559"],
  "tags": ["rollup", "optimism"],
  "average_blocktime_ms": 2000,
  "is_testnet": false
}

Solana 网络

{
  "type": "solana",
  "network": "mainnet-beta",
  "rpc_urls": ["https://api.mainnet-beta.solana.com"],
  "explorer_urls": ["https://explorer.solana.com"],
  "average_blocktime_ms": 400,
  "is_testnet": false,
  "tags": ["mainnet", "solana"]
}

Stellar 网络

{
  "type": "stellar",
  "network": "pubnet",
  "rpc_urls": ["https://horizon.stellar.org"],
  "passphrase": "Public Global Stellar Network ; September 2015",
  "explorer_urls": ["https://stellar.expert/explorer/public"],
  "average_blocktime_ms": 5000,
  "is_testnet": false,
  "tags": ["mainnet", "stellar"]
}

网络继承

网络可以从相同类型的其他网络继承,从而允许你创建变体而无需复制配置:

{
  "networks": [\
    {\
      "type": "evm",\
      "network": "ethereum-base",\
      "chain_id": 1,\
      "required_confirmations": 12,\
      "symbol": "ETH",\
      "rpc_urls": ["https://mainnet.infura.io/v3/YOUR_KEY"]\
    },\
    {\
      "from": "ethereum-base",\
      "type": "evm",\
      "network": "ethereum-sepolia",\
      "chain_id": 11155111,\
      "required_confirmations": 3,\
      "rpc_urls": ["https://sepolia.infura.io/v3/YOUR_KEY"],\
      "is_testnet": true\
    }\
  ]
}

当使用继承时:

  • 子网络从父网络继承所有字段

  • 在子网络中指定的字段将覆盖父网络的值

  • from 字段必须引用相同类型的网络

在 Relayer 配置中使用网络

定义网络后,在你的 Relayer 配置中引用它们:

{
  "relayers": [\
    {\
      "id": "my-evm-relayer",\
      "name": "My EVM Relayer",\
      "network": "ethereum-mainnet",  // 引用网络 ID\
      "network_type": "evm",\
      "signer_id": "my-signer"\
    }\
  ]
}

最佳实践

1. 网络组织

  • 将相关网络分组到单独的文件中(例如,ethereum.jsonpolygon.json

  • 对网络标识符使用一致的命名约定

  • 包括主网和测试网配置

2. RPC URL

  • 始终配置多个 RPC URL 以实现冗余

  • 对生产使用私有/专用 RPC 终端

  • 确保通过公共网络访问时 URL 是安全的 (HTTPS)

3. 确认要求

  • 根据网络安全性设置适当的 required_confirmations

  • 主网的值较高,测试网的值较低

  • 考虑特定于网络的最终确定特征

4. 标签和功能

  • 使用标签对网络进行分类(例如,“mainnet”,“testnet”,“rollup”)

  • 启用适当的功能(例如,对支持的网络启用“eip1559”)

  • 记录在你的组织中使用的自定义标签

5. 继承

  • 为常用设置创建基本配置

  • 使用继承来减少重复

  • 仅覆盖子网络中必要的字段

故障排除

常见问题

找不到网络:

  • 确保 Relayer 配置中的网络标识符完全匹配

  • 检查网络配置文件是否位于正确的位置

  • 验证 JSON 语法是否有效

RPC 连接失败:

  • 在配置之前独立测试 RPC URL

  • 确保防火墙/网络允许出站HTTPS连接

  • 检查 API 密钥是否包含在 RPC URL 中(如果需要)

配置无效:

  • 验证网络类型是否存在必需字段

  • 确保数字字段(chain_id,confirmations)是数字,而不是字符串

  • 检查继承的网络是否引用了现有的父网络

参见

← 签名者

项目结构 →

  • 原文链接: docs.openzeppelin.com/re...
  • 登链社区 AI 助手,为大家转译优秀英文文章,如有翻译不通的地方,还请包涵~
点赞 0
收藏 0
分享
本文参与登链社区写作激励计划 ,好文好收益,欢迎正在阅读的你也加入。

0 条评论

请先 登录 后评论
OpenZeppelin
OpenZeppelin
江湖只有他的大名,没有他的介绍。