使用本地代理部署 Hyperlane

提示

本指南适用于高级用户，他们可能最终打算在类似生产的环境中运行 Hyperlane 代理。它将涵盖如何手动配置和运行代理的基础知识，但这不是生产设置指南。

术语

“本地链”是您希望在其上部署 Hyperlane 的新链。

“远程链”是已经存在 Hyperlane 部署的链，您希望您的本地链能够发送和接收消息。

概述

本指南分为六个步骤：

设置密钥 以便您可以部署合约并运行验证者和中继器。
部署合约 到本地链以及每个远程链，以便本地链能够发送和接收消息。
运行验证者 以提供您部署的跨链安全模块所需的签名。
运行中继器 以在您部署合约的链之间发送和接收消息。
发送测试消息 以确认您的中继器能够在每对链之间传递消息。
部署 Warp 路由 以便在链之间发送代币价值，而不仅仅是消息。

开始

1. 设置密钥

您必须设置和资助三个密钥。

提示

要开始，您可以通过为所有三个角色使用相同的十六进制密钥来简化操作。

密钥角色	描述	资金需求
合约部署者	32字节十六进制私钥	在我们需要部署合约的所有链上都需要资助。
验证者账户	一组验证者地址，将签署来自您本地链的出站消息。快速入门时只需一个验证者即可。	一小笔资金，以便验证者可以通过一次性交易在链上宣布其签名的位置。
中继账户	您将操作的单个中继器需要在每个它将传递消息的链上都有一个账户。	中继器必须在它所中继的所有链上都有余额。

有关如何生成密钥的说明，请参见代理密钥部分。您的部署者密钥必须是十六进制密钥，而验证者和中继器密钥可以是十六进制或AWS KMS。

如果在使用Foundry的Anvil的本地网络上进行部署，请使用以下命令为您新生成的账户提供资金。它使用一个预先资助的私钥将1 ETH转移到环境变量中的$YOUR_TARGET_ADDRESS地址。

cast send $YOUR_TARGET_ADDRESS \
--private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
--value $(cast tw 1)

2. 部署合约

一旦您设置了部署者、验证者和中继器密钥，就可以使用 Hyperlane CLI 将智能合约部署到本地和远程链上。

在本地链上，我们将部署：

核心合约，包括一个 Mailbox，可以用来发送和接收消息。

在所有链上，我们将部署：

一个多重签名 ISM，用于验证来自其他本地和远程链的入站消息。
一个 InterchainGasPaymaster，用于支付我们的中继器以交付跨链消息。
一个 TestRecipient，我们将向其发送消息，以测试一切是否正常工作。

设置

首先，安装 Hyperlane CLI。

npm install -g @hyperlane-xyz/cli

链

部署将需要关于任何将要交互的链的基本信息。如果目标链尚未在 Hyperlane 注册表中，您必须为它们指定链元数据。有关详细信息，请参见 CLI 参考。

要查看当前已知的链，请运行以下命令：

hyperlane registry list

要为其他链创建链元数据配置，请运行以下命令：

hyperlane registry init

或者，您可以手动定义配置。有关其架构，请参见 ChainMetadata 类型。有关示例，请参见 chain-config.yaml。

使用多重签名 ISM 的核心部署

现在 CLI 将知道如何与您的所有链进行交互，但它还需要知道如何配置您的跨链安全模块（ISM）。

要使用多重签名 ISM 配置初始化核心配置，您可以使用 JSON 或 YAML 手动定义它（请参见示例配置），或使用以下命令创建它：

hyperlane core init --advanced

当被问及 ISM 类型时，选择 messageIdMultisigIsm。在本指南的上下文中，我们将使用 1/1 多重签名，因此选择阈值为 1 并输入您的密钥地址。

当被问及默认钩子类型和所需钩子类型时，选择 merkleTreeHook。

干运行核心部署

备注

为了执行干运行，您需要在单独的终端实例中运行 Anvil 节点。要启动 Anvil 节点，请运行 anvil。有关 Anvil 和安装的更多信息，请查看 Foundry 的 Anvil 文档。

在执行部署之前，您可以通过 --dry-run <CHAIN_NAME> 或 -d <CHAIN_NAME> 执行干运行，以确保部署成功并提供部署的 Gas 成本分析。这不会触发任何真实交易，而是模拟部署以显示所需合约及其各自的 Gas 成本列表。

除了验证即将进行的部署外，您还可以选择通过 --from-address 或 -f 提供您打算使用的 EOA 地址。这将确保您有足够的资金完成部署。

hyperlane core deploy --dry-run chain1 \ 
    --from-address $YOUR_DEPLOYER_ADDRESS \ # (可选) 您的账户地址，将通过 Anvil 进行模拟；默认为 HYP_KEY 环境变量
    --registry \ # (可选) 您的主要注册表路径；默认为 Hyperlane github 注册表
    --overrides # (可选) 覆盖注册表的路径；默认为本地 ./ 路径

部署

我们现在准备使用 core deploy 命令来部署 Hyperlane 合约。为了支付交易，命令将需要步骤 1 中的合约部署者密钥，可以通过 HYP_KEY 环境变量或作为命令参数提供。

hyperlane core deploy

验证

部署合约的工件将写入配置的注册表。默认情况下，您将在运行命令的本地目录中找到新地址（例如 ./chains/chain1/addresses.yaml）。

代理配置

我们现在准备使用已部署的合约生成代理配置，这将被代理（验证者和中继器）在以下步骤中使用。

hyperlane registry agent-config --chains chain1

将 CONFIG_FILES 环境变量设置为生成的代理配置的路径。

export CONFIG_FILES=/full/path/to/configs/agent-config.json

3. 运行验证者

验证者为从您的链发送到远程链的消息提供安全性。只有在使用 Multisig ISM 时才需要它们。要了解验证者的作用，请点击这里。

设置目录

首先，将 CONFIG_FILES 环境变量设置为在部署合约步骤中生成的代理配置的路径。例如：

export CONFIG_FILES=/full/path/to/configs/agent-config-{timestamp}.json

接下来，为您的验证者创建一个本地目录，以便写入其签名。记住该路径，因为在配置验证者时需要使用它。

危险

验证者签名路径将在验证者公告交易中写入链上。请小心，不要泄露任何安全敏感或个人信息！

# 选择一个特定于您正在验证的链的有意义的名称
export VALIDATOR_SIGNATURES_DIR=/tmp/hyperlane-validator-signatures-<your_chain_name>

# 创建目录
mkdir -p $VALIDATOR_SIGNATURES_DIR

注意

在 Mac 上通过 Docker 运行代理时，您将无法在 /tmp 中挂载任何内容。为了解决这个问题，请创建一个本地 tmp 目录以进行挂载。

# 创建一个可以被 docker 访问的本地 tmp 目录
mkdir tmp

# 选择一个特定于您正在验证的链的有意义的名称
export VALIDATOR_SIGNATURES_DIR=tmp/hyperlane-validator-signatures-<your_chain_name>

# 创建目录
mkdir -p $VALIDATOR_SIGNATURES_DIR

配置

验证者可以配置许多参数。对于本指南，我们只关注少数几个：

参数	描述
`--db`	写入持久数据到磁盘的路径。
`--originChainName`	被验证的链的名称（例如 `ethereum`）。
`--checkpointSyncer.type`	本指南中设置为 `localStorage`。
`--checkpointSyncer.path`	写入验证者签名的本地目录的路径。与 `$VALIDATOR_SIGNATURES_DIR` 相同的路径。
`--validator.key`	您验证者的十六进制私钥。

信息

确保验证者密钥与设置 MultisigIsmConfig 时提供的地址相对应。否则，您在上一步中部署的 Multisig ISM 将无法验证从您的链发送的消息。

要了解您可以更改的所有参数，请阅读代理配置参考。

使用 Docker
从源构建

更新代理配置

除非您在 Linux 上运行 Docker，否则还需要更新网络的代理配置。这是因为 Docker 不支持 Mac、Windows 或 Windows Server 上的 host 网络模式。

为此，请导航到 $CONFIG_FILES 中的代理配置，并将所有 "localhost" 或 "127.0.0.1" 替换为 host.docker.internal。例如：

...
"localnet1": {
  ...
  "rpcUrls": [
    {
      // "http": "http://localhost:8545"
      // "http": "http://127.0.0.1:8545"
      "http": "http://host.docker.internal:8545"
    }
  ],
  ...
},
...

挂载目录

使用 Docker 运行增加了一层复杂性，因为配置文件需要从 Docker 容器内访问，而验证者签名需要从容器外部访问，以便中继器读取。这是为了让中继器构建成功验证 Multisig ISM 所需的消息元数据。

为了解决这个问题，您可以将文件系统上的目录挂载到容器中。在下面的参数中，我们：

将 $CONFIG_FILES 环境变量设置为容器内的固定路径。
将代理配置文件挂载到此固定路径并设置为只读。
将持久数据目录挂载到容器内的固定路径。
将验证者签名目录挂载到容器内的固定路径。

...
-e CONFIG_FILES=/config/agent-config.json \
--mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
--mount type=bind,source="$(pwd)"/hyperlane_db_validator_<your_chain_name>,target=/hyperlane_db \
--mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures \
...

硬编码这些路径消除了不同源链的验证者运行的配置重复。这使得在运行容器时更容易传递正确的参数。请参见下面的示例，其中唯一需要为不同链配置的项目是链名称和验证者密钥。

...
./validator \
--db /hyperlane_db \
--originChainName <your_chain_name> \
--checkpointSyncer.type localStorage \
--checkpointSyncer.path /tmp/validator-signatures \
--validator.key <your_validator_key>
...

克隆和设置

首先，克隆 Hyperlane 单体仓库：

git clone git@github.com:hyperlane-xyz/hyperlane-monorepo.git

然后按照 rust 目录中的设置说明进行操作。这应该会设置 rustup 以及如果您使用的是 Apple Silicon，则会安装 Rosetta 2。

# 安装 rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# （仅限 Apple Silicon）安装 rosetta 2
softwareupdate --install-rosetta --agree-to-license

运行

使用 Docker
从源构建

现在您对配置验证者参数有了更多了解，请拉取最新的 Docker 镜像：

docker pull --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.1.0

在运行之前，请确保您需要挂载的所有目录都存在。这可能涉及到创建 hyperlane_db_validator_<your_chain_name>，如果它尚不存在。

mkdir -p hyperlane_db_validator_<your_chain_name>

最后，运行验证者：

docker run \
  -it \
  -e CONFIG_FILES=/config/agent-config.json \
  --mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane_db_validator_<your_chain_name>,target=/hyperlane_db \
  --mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures \
  gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.1.0 \
  ./validator \
  --db /hyperlane_db \
  --originChainName <your_chain_name> \
  --checkpointSyncer.type localStorage \
  --checkpointSyncer.path /tmp/validator-signatures \
  --validator.key <your_validator_key>

在按照设置说明进行操作后，您现在应该能够使用 cargo 运行验证者：

cargo run --release --bin validator -- \
    --db ./hyperlane_db_validator_<your_chain_name> \
    --originChainName <your_chain_name> \
    --checkpointSyncer.type localStorage \
    --checkpointSyncer.path $VALIDATOR_SIGNATURES_DIR \
    --validator.key <your_validator_key>

(可选) 直接运行二进制文件

您还可以构建代理：

cargo build --release --bin validator

并直接运行二进制文件：

./target/release/validator \
    --db ./hyperlane_db_validator_<your_chain_name> \
    --originChainName <your_chain_name> \
    --checkpointSyncer.type localStorage \
    --checkpointSyncer.path $VALIDATOR_SIGNATURES_DIR \
    --validator.key <your_validator_key>

提示

有关更多信息，请查看验证者指南。要了解如何运行多个验证者，请参见本节。

4. 运行中继器

中继器传递在本地链和远程链之间发送的跨链消息。要了解中继器的作用，请点击这里。

您应该已经将 CONFIG_FILES 环境变量设置为在部署合约步骤中生成的代理配置的路径。如果没有，请现在设置。

export CONFIG_FILES=/full/path/to/configs/agent-config.json

配置

中继器可以配置许多参数。对于本指南，我们只关注少数几个：

参数	描述
`--db`	写入持久数据到磁盘的路径。
`--relayChains`	要中继的链的逗号分隔名称。例如 `ethereum,polygon,avalanche`。
`--allowLocalCheckpointSyncers`	允许中继器在本地文件系统上查找验证者签名。
`--defaultSigner.key`	用于为所有链签署交易的十六进制私钥。
`--metrics-port`	可选。暴露 prometheus 指标的端口，默认为 `9090`。

提示

您的中继链集合应包括源链和目标链。

要了解您可以更改的所有参数，请阅读代理配置参考。

使用 Docker
从源构建

挂载目录

对于中继器，我们提供几乎与验证者相同的参数给 Docker：

将 $CONFIG_FILES 环境变量设置为容器内的固定路径。
将代理配置文件挂载到此固定路径并设置为只读。
将持久数据目录挂载到容器内的固定路径。
将验证者签名目录挂载到容器内的固定路径并设置为只读。

...
-e CONFIG_FILES=/config/agent-config.json \
--mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
--mount type=bind,source="$(pwd)"/hyperlane_db_relayer,target=/hyperlane_db \
--mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures,readonly \
...

硬编码这些路径消除了不同链集的中继器运行的配置重复。这使得在运行容器时更容易传递正确的参数。请参见下面的示例，其中唯一需要为不同链配置的项目是要中继的链列表和中继器密钥。

克隆和设置

如果您还没有这样做，请克隆 Hyperlane 单体仓库并按照 rust 目录中的设置说明进行操作。

# 克隆 hyperlane 单体仓库
git clone git@github.com:hyperlane-xyz/hyperlane-monorepo.git

# 安装 rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# （仅限 Apple Silicon）安装 rosetta 2
softwareupdate --install-rosetta --agree-to-license

运行

使用 Docker
从源构建

如果您还没有拉取 Docker 镜像，请现在运行：

docker pull --platform linux/amd64 gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.1.0

在运行之前，请确保您需要挂载的所有目录都存在。这可能涉及到创建 hyperlane_db_relayer，如果它尚不存在。

mkdir -p hyperlane_db_relayer

最后，运行中继器：

docker run \
  -it \
  -e CONFIG_FILES=/config/agent-config.json \
  --mount type=bind,source=$CONFIG_FILES,target=/config/agent-config.json,readonly \
  --mount type=bind,source="$(pwd)"/hyperlane_db_relayer,target=/hyperlane_db \
  --mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures,readonly \
  gcr.io/abacus-labs-dev/hyperlane-agent:agents-v1.1.0 \
  ./relayer \
  --db /hyperlane_db \
  --relayChains <chain_1_name>,<chain_2_name> \
  --allowLocalCheckpointSyncers true \
  --defaultSigner.key <your_relayer_key> \

在按照设置说明进行操作后，您现在应该能够使用 cargo 运行中继器：

cargo run --release --bin relayer -- \
    --db ./hyperlane_db_relayer \
    --relayChains <chain_1_name>,<chain_2_name> \
    --allowLocalCheckpointSyncers true \
    --defaultSigner.key <your_relayer_key> \
    --metrics-port 9091

指标端口被重写以避免与验证者冲突。

(可选) 直接运行二进制文件

您还可以构建代理：

cargo build --release --bin relayer

并直接运行二进制文件：

./target/release/relayer \
    --db ./hyperlane_db_relayer \
    --relayChains <chain_1_name>,<chain_2_name> \
    --allowLocalCheckpointSyncers true \
    --defaultSigner.key <your_relayer_key> \
    --metrics-port 9091

提示

有关更多信息，请查看中继器指南。

5. 发送测试消息

您可以通过在链对之间发送测试消息来检查一切是否正常工作。使用 CLI 启动消息。

hyperlane send message --key $PRIVATE_KEY

send message 命令会在消息发送时通知您。稍等片刻后，将显示交付确认。如果消息交付超时，可能是上述步骤中验证者或中继器设置存在问题。要进行故障排除，请首先查看源链中继器的日志。如果您需要进一步的帮助，请在 Discord 上联系。

6. （可选）部署 Warp 路由

要使用您的新 Hyperlane 部署连接代币，请参见 Warp 路由部署指南。

术语​

概述​

开始​

1. 设置密钥​

2. 部署合约​

设置​

链​

使用多重签名 ISM 的核心部署​

干运行核心部署​

部署​

验证​

代理配置​

3. 运行验证者​

设置目录​

配置​

运行​

4. 运行中继器​

配置​

运行​

5. 发送测试消息​

6. （可选）部署 Warp 路由​

术语

概述

开始