name: fix-merkle-root-mismatch description: 应用修复relayer数据库中默克尔根不匹配问题的措施。在运行/investigate-merkle-root-mismatch调查并识别出不匹配条目后使用。在数据库修改前需要用户确认。

修复默克尔根不匹配

何时使用

在运行/investigate-merkle-root-mismatch调查问题后使用此技能。

用户请求触发：
- “修复[链]上的默克尔根不匹配”
- “应用默克尔树修复”
- “使用正确的消息ID更新relayer数据库”

输入参数

参数	必需	默认值	描述
`origin`	是	-	要修复的源链（例如，`polygonzkevm`、`ethereum`）
`domain_id`	是	-	链的域名ID
`environment`	否	`mainnet3`	`mainnet3`或`testnet4`
`merkle_tree_insertions`	是	-	修正列表：`[{leaf_index, message_id, block_number}]`

先决条件

调查已完成 - 先运行/investigate-merkle-root-mismatch以识别不匹配条目
对relayer pods具有kubectl访问权限
已建立到relayer的端口转发（端口9090）

修复工作流

步骤0：查找Monorepo根目录

MONOREPO_ROOT=$(git rev-parse --show-toplevel)

步骤1：验证端口转发已激活

检查端口9090是否已在使用中：

lsof -i :9090

如果未使用，在后台启动端口转发：

kubectl port-forward omniscient-relayer-hyperlane-agent-relayer-0 9090:9090 -n [environment] &

等待几秒，然后验证是否工作：

curl -s "localhost:9090/merkle_tree_insertions?domain_id=[domain_id]&leaf_index_start=0&leaf_index_end=1"

步骤2：呈现更改以供确认

重要：执行前需要用户确认。

在修改relayer数据库之前，您必须：

以清晰的表格格式呈现所有要做的更改摘要：

叶子索引	正确的消息ID	区块号
1477	0x4bb3e20db45366a6a360ad2639c5421ea622a69b89b2edb045aa97e2051529b7	9891832
1478	0xa66dbdc1874acfddf14e75e6a20dd1632e9e3206c5f5855884da0d26d8ca12fa	9891872

使用AskUserQuestion获取明确确认：
- 问题：“您是否要将这些默克尔树修复应用到relayer数据库？”
- 选项：“是，应用修复” / “否，取消”
仅当用户明确确认后才能继续。

步骤3：应用默克尔树修复

确认后，通过relayer API插入正确的默克尔树插入项：

curl -X POST \
    -H 'Content-type: application/json' \
    'localhost:9090/merkle_tree_insertions' \
    -d '{
    "merkle_tree_insertions": [
        {
            "chain": [domain_id],
            "insertion_block_number": [block_number],
            "leaf_index": [index],
            "message_id": "0x..."
        }
    ]
}'

请求模式：

{
  "merkle_tree_insertions": [
    {
      "chain": "<域名ID作为数字>",
      "insertion_block_number": "<区块号作为数字>",
      "leaf_index": "<叶子索引作为数字>",
      "message_id": "<0x前缀的H256哈希>"
    }
  ]
}

验证响应： API应返回成功响应，包含插入条目数。

步骤4：重启Relayer

重要：执行前需要用户确认。

使用AskUserQuestion确认：

问题：“您是否要重启relayer以应用数据库修复？”
选项：“是，重启relayer” / “否，稍后手动重启”

仅当用户明确确认后才能继续。

确认后，重启relayer以重建其内存中的默克尔树：

pnpm --dir typescript/infra exec tsx ./scripts/agents/restart-agents.ts -e [environment] --context hyperlane --role relayer

步骤5：验证修复

relayer重启后，验证修复：

5.1：获取最新索引

查询Grafana获取当前树大小：

使用mcp__grafana__query_prometheus：
- datasourceUid: grafanacloud-prom
- expr: hyperlane_latest_tree_insertion_index{origin="[origin]", hyperlane_deployment="[environment]"}
- startTime: now-1h
- queryType: instant

5.2：在关键索引处抽查根

比较验证者和relayer根在三个点：第一个修复索引、中间和最新。

index=[INDEX]
validator_root=$(curl -s "https://hyperlane-[environment]-[origin]-validator-0.s3.us-east-1.amazonaws.com/checkpoint_${index}_with_id.json" | jq -r '.value.checkpoint.root')
relayer_root=$(curl -s "localhost:9090/merkle_proofs?domain_id=[domain_id]&leaf_index=${index}&root_index=${index}" | jq -r '.root')
echo "索引 $index："
echo "  验证者：$validator_root"
echo "  Relayer：0x$relayer_root"
if [ "$validator_root" = "0x$relayer_root" ]; then echo "  ✓ 匹配"; else echo "  ❌ 不匹配"; fi

运行此命令用于：

第一个修复索引（例如，37352）
中间索引（例如，39000）
最新索引（例如，41172）

5.3：验证不匹配指标已清除

使用mcp__grafana__query_prometheus：
- datasourceUid: grafanacloud-prom
- expr: hyperlane_merkle_root_mismatch{origin="[origin]"}
- startTime: now-1h
- queryType: instant

预期结果： 空结果或值为0。

5.4：报告结果

以表格形式呈现验证结果：

索引	位置	结果
37352	第一个修复	✓ 匹配
39000	中间	✓ 匹配
41172	最新	✓ 匹配

如果仍不匹配：

通知用户可能还需要修复其他条目
建议重新运行/investigate-merkle-root-mismatch进行进一步调查

API参考

Relayer端点

端点	方法	描述
`/merkle_tree_insertions`	GET	列出数据库中的默克尔树插入项
`/merkle_tree_insertions`	POST	插入/更新默克尔树条目

请求/响应示例

POST /merkle_tree_insertions

请求：

{
  "merkle_tree_insertions": [
    {
      "chain": 1101,
      "insertion_block_number": 9891832,
      "leaf_index": 1477,
      "message_id": "0x4bb3e20db45366a6a360ad2639c5421ea622a69b89b2edb045aa97e2051529b7"
    }
  ]
}

响应（成功）：

{
  "status": "success",
  "data": {
    "count": 1
  }
}

常见问题

端口转发断开： 在应用修复前重新建立
API返回错误： 检查错误消息，验证域名ID和消息ID格式
Relayer重启失败： 检查kubectl访问权限和pod状态
修复无效： 可能漏掉了一些不匹配索引，重新调查

运行手册参考

完整运行手册：https://www.notion.so/hyperlanexyz/Merkle-Root-Mismatch-26a6d35200d680a2857dcd0b228d4ab7