跳到主要内容

Hyperlane故障排除指南

一般故障排除

日志记录

可以使用以下两个环境变量配置Hyperlane工具的日志级别和格式:

  • LOG_LEVEL:要过滤的日志级别。默认为info。选项:debug | info | warn | error | off
  • LOG_FORMAT:日志输出的格式。默认为pretty。选项:pretty | json

Hyperlane CLI还允许通过--log--verbosity标志配置日志记录。

链配置

在您的工作目录中,您可能会找到按链名组织的chains/yaml文件。这些metadata.yaml文件描述了在Hyperlane部署和应用程序中使用链所需的信息。

您可以在此文件中为任何新链定义完整配置。可以配置的元数据在这个示例配置中定义。您还可以在chainMetadataTypes.ts找到链元数据模式。

以下是两个本地anvil链的配置示例:

示例:两个本地Anvil链
anvil1:
chainId: 31337
domainId: 31337
name: anvil1
protocol: ethereum
rpcUrls:
- http: http://localhost:8545
nativeToken:
name: Ether
symbol: ETH
decimals: 18
anvil2:
chainId: 31338
domainId: 31338
name: anvil2
protocol: ethereum
rpcUrls:
- http: http://localhost:8555

您还可以通过提供要覆盖的字段来扩展核心链配置:

sepolia:
blocks:
confirmations: 2

覆盖RPC URL

您可以通过扩展核心链配置来覆盖RPC URL。

示例:定义RPC URL数组并调整重试设置
demochain:
name: demochain
chainId: 123456
domainId: 123456
protocol: ethereum
rpcUrls:
- http: https://rpc-testnet.demochain.gg
sepolia:
rpcUrls:
- http: https://rpc2.sepolia.org
- http: https://some-other-sepolia-rpc.gg
retry:
maxRequests: 10

覆盖交易设置

交易覆盖是在形成交易请求时要包含的任何属性。例如:

  • gasPrice: number | string
  • maxFeePerGas: number | string
  • maxPriorityFeePerGas: number | string
  • nonce: number | string
  • type: number
  • ccipReadEnabled: boolean

在下面的示例中,我们使用7 gwei的gas价格,硬编码nonce,并为基础费用和优先费用设置最大值。

sepolia:
transactionOverrides:
gasPrice: 7000000000 # 7 gwei
maxFeePerGas: 150000000000 # 150 gwei
maxPriorityFeePerGas: 40000000000 # 40 gwei
nonce: 1337
注意

如果您在链配置中覆盖nonce,请确保在交易成功后更新该值。

消息传递问题

消息传递时间长或超时

消息传递延迟或超时通常是由RPC问题引起的,例如过载的端点,或者只在需要时产生区块的链。

要识别问题,请检查日志中是否有指示RPC相关问题的内容,例如:Deprioritizing an inner provider in FallbackProvider

要解决这些延迟:

  • 检查RPC健康状况: 确保RPC端点响应正常。
  • 配置按需生成区块的链: 对于这些链,将reorgPeriod设置为0。这确保代理始终查看链的顶端,避免由区块最终确认过程引起的延迟。

代理故障排除

验证器故障排除

  • Validator has not announced any storage locations 警告:

    • 原因:当中继器无法检索处理消息所需的验证器签名时,会发生这种情况。
    • 解决方案
      • 确保验证器已宣布其存储位置。检查验证器日志中是否有如下消息: Validator has announced signature storage location, locations: ["file:///tmp/hyperlane-validator-signatures-local"]
      • 验证每个验证器都有唯一的签名存储路径(--checkpointSyncer.path)以防止覆盖。
      • 确认中继器对存储路径有读取权限。
  • No ISM Found for Origin 错误

    • 原因:当链间安全模块(ISM)无法识别源链时,会发生这种情况。
    • 解决方案
      • 确保ISM配置包含源链的验证器。
      • 如果没有,请将源链的验证器添加到您的ISM中。
      • 更新ISM配置后重启中继器。

中继器故障排除

检查队列中的待处理消息

如果消息卡在中继器队列中或未被处理,请使用list_operations端点检查中继器的队列:

curl http://0.0.0.0:9090/list_operations?destination_domain=<destination_domain_id>

此端点提供队列中消息的状态,可以帮助识别它们未被传递的原因。

使用日志进行调试

要获取详细信息,请启用调试日志并监控中继器的活动:HYP_LOG_LEVEL=debug。捕获日志后,您可以使用它们来定位特定消息ID的问题。

重试消息

查看日志后,您可以使用message_retry端点触发所有待处理消息的立即重试:

curl --location 'http://127.0.0.1:9090/message_retry' \
--header 'Content-Type: application/json' \
--data '[{"messageid": "*", "origindomain": "*", "senderaddress": "*", "destinationdomain": "*", "recipientaddress": "*"}]'

确保使用最新版本的中继器并捕获所有日志以进行调试。

中继器选择错误的ISM

确保您链上的链间安全模块(ISM)配置正确。不正确的ISM可能导致消息无法处理。验证配置中的ISM地址并确保它与您的部署设置匹配。

高级故障排除

eth_getStorageAt() 兼容性

某些链不原生支持eth_getStorageAt() API。如果您在这些链上部署并遇到问题,请查看在这个提交中对Hyperlane代码库所做的更改。

要在这些链上部署Hyperlane,请按照以下步骤操作:

  1. 克隆仓库
  2. 应用提交中的更改。
  3. 从根目录构建项目:yarn build
  4. 从根目录运行Hyperlane CLI:yarn workspace @hyperlane-xyz/cli hyperlane