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 | stringmaxFeePerGas
: number | stringmaxPriorityFeePerGas
: number | stringnonce
: number | stringtype
: numberccipReadEnabled
: 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,请按照以下步骤操作: