使用本地代理部署Hyperlane

tip

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

如果尚未这样做，初学者应该从deploying Hyperlane with Kurtosis agents开始。

术语表

local chain：是您要部署Hyperlane的新链。

remote chain：是指已部署 Hyperlane 的链，您希望本地链与之收发信息。

概览

这个指南分为六个步骤：

1. Set up keys ：您将使用这些密钥部署合约并运行验证人和中继器。
2. Deploy contracts ：在本地链和与本地链能够发送和接收消息的每个远程链上部署合约。
3. Run a validator ：为您部署的互链安全模块提供所需的签名。
4. Run a relayer ：在您部署合约的链之间发送和接收消息。
5. Send a test message ：确认您的中继能够在每对链之间传递消息。
6. Deploy a Warp Route ：跨链发送令牌，而不仅仅是消息。

立即开始

1. 设置密钥

您必须设置三个密钥并为其提供资金。

tip

首先，您可以通过对所有三个角色使用相同的十六进制密钥来简化。

密钥角色	说明	资金需求
合约部署者	32字节十六进制私钥	在我们需要部署合约的所有链上提供资金。
验证者账户	将对本地链中的出站消息进行签名的验证器地址列表。只需一个验证器就可以快速启动。	只需少量，这样验证者就可以通过一次性交易在链上公布他们的签名位置
中继器账户	您将操作的单个中继器需要在它将发送消息的每个链上都有一个帐户	中继器必须在它所传递的所有链上持有余额。

有关如何生成密钥的说明，请参阅agent keys 部分。部署程序密钥必须是十六进制密钥，而验证器和中继程序密钥可以是十六进制或AWS KMS。

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

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

2. 部署合约

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

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

• 核心合约，包括可用于发送和接收信息的Mailbox。

我们在所有链将进行部署：

• 可用于验证来自其他本地和远程链的入站消息的 Multisig ISM。
• InterchainGasPaymaster可用于支付中继器传递链间消息的费用。
• TestRecipient我们将向其发送信息，以测试一切工作是否正常。

设置

首先，使用NPM安装Hyperlane CLI。需要Node 16 或以上版本。以下命令将在你的机器上全局安装。请参阅package page了解临时安装或从源代码构建等其他方法。

npm install -g @hyperlane-xyz/cli

接下来，确定本地链和远程链需要哪些自定义链配置。任何已经包含在Hyperlane SDK中的链都不需要链配置（但如果想覆盖默认设置，可以选择使用）。 运行以下命令查看默认SDK链：

hyperlane chains list

您可以按空格键选择链。对于需要自定义配置的链，可以使用JSON或YAML手动定义（请参阅 配置示例），或使用以下命令创建：

hyperlane config create chain

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

要创建多个ISM配置，您可以使用JSON或YAML手动定义它，请参阅此处example config here)，或使用以下命令创建它：

hyperlane config create ism

在被询问关于多重签名类型时，选择message id ism。在这个指南的背景下，我们将使用 1/1 多重签名，因此选择一个阈值为 1，并输入您的密钥地址。

部署

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

hyperlane deploy core \
    --targets chain1,chain2,... \ # all the chains you want to bridge between
    --chains $CHAIN_CONFIG_FILE \  # path to chains.yaml config e.g. ./configs/chains.yaml
    --ism $MULTISIG_CONFIG_FILE \ # path to ism.yaml config e.g. ./configs/ism.yaml
    --artifacts $PREDEPLOYED_ARTIFACT_FILE \ # (optional) in case you want to reuse contracts you've already predeployed
    --out $OUT_DIR \ # (optional) deployment contract artifacts
    --key $YOUR_DEPLOYER_PRIVATE_KEY

验证

部署合同构件默认将写入artifacts/文件夹。部署程序将创建两个带时间戳的文件，即agent-config-{timestamp}.json和core-deployment-{timestamp}.json core-deployment 文件包含按链排列的核心合约地址。 agent-config 文件包含下一步运行Hyperlane代理所需的数据。

3. 运行验证人

验证者为从您的链发送到远程链的消息提供安全性。仅在使用Multisig ISM时才需要它们。

设置目录

首先，将CONFIG_FILES环境变量设置为在deploy contracts步骤中生成的代理配置文件的路径。例如：

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

接下来，创建一个本地目录，用于让您的验证器将其签名写入其中。记住这个路径，因为在配置验证器时您将需要它。

danger

验证器签名路径将作为validator announcement transaction的一部分写入链上。请注意不要泄露任何安全敏感或个人信息！

# 选择一个具体到您正在验证的链的信息性名称
export VALIDATOR_SIGNATURES_DIR=/tmp/hyperlane-validator-signatures-<your_chain_name>

# 创建目录
mkdir -p $VALIDATOR_SIGNATURES_DIR

warning

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

# 创建一个本地的 tmp 目录，该目录可以被 Docker 访问。
mkdir tmp

# 选择一个具有特定信息的名称，该名称与您正在验证的链相关。
export VALIDATOR_SIGNATURES_DIR=tmp/hyperlane-validator-signatures-<your_chain_name>

# 创建目录
mkdir -p $VALIDATOR_SIGNATURES_DIR

配置

Validators可以配置许多参数。对于本指南，我们只关心其中的一小部分：

参数	说明
--db	持久化数据写入磁盘的路径。
--originChainName	正在验证的链的名称(例如:ethereum)。
--checkpointSyncer.type	本指南中设置为 localStorage。
--checkpointSyncer.path	写入验证程序签名的本地目录路径。与 $VALIDATOR_SIGNATURES_DIR相同。
--validator.key	验证器的十六进制私钥。

info

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

要了解您可以更改的所有参数，请阅读agent configuration reference。

Using Docker

更新代理配置

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

要做到这一点，请转到$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进行验证。

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

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

...
-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 \
...

硬编码这些路径可以在运行验证器的不同源链的Docker实例之间去重配置。这样可以更轻松地在运行容器时传递正确的参数。请参阅下面的示例，其中唯一需要针对不同链进行不同配置的是链名称和验证器密钥。

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

Building from source

克隆并设置

首先，克隆Hyperlane monorepo：

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

然后按照rust目录中的setup instructions进行操作。这将设置rustup，如果你使用的是Apple Silicon，需要安装 Rosetta 2。

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

# (apple silicon only) install rosetta 2
softwareupdate --install-rosetta --agree-to-license

运行

Using Docker

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

docker pull gcr.io/abacus-labs-dev/hyperlane-agent:3adc0e9-20240319-152359

在运行之前，请确保所有需要挂载的目录都存在。这可能需要创建 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:3adc0e9-20240319-152359 \
  ./validator \
  --db /hyperlane_db \
  --originChainName <your_chain_name> \
  --checkpointSyncer.type localStorage \
  --checkpointSyncer.path /tmp/validator-signatures \
  --validator.key <your_validator_key>

Building from source

完成设置后，您现在应该能够使用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>

欲了解更多信息，请查阅Validators guide。

4. 运行中继器

Relayers负责传递在本地链和远程链之间发送的跨链消息。

如果还没有，请确保已将 CONFIG_FILES 环境变量设置为在deploy contracts步骤中生成的代理配置文件的路径。

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

配置

这个指南涉及到配置验证器的许多参数。对于这个指南，我们只关注其中的一小部分：

参数	说明
--db	将持久数据写入磁盘的路径。
--relayChains	用逗号分隔要中继的链的名称。如ethereum,polygon,avalanche。
--allowLocalCheckpointSyncers	允许中继器在本地文件系统上查找验证器签名。
--defaultSigner.key	用于为所有链签署事务的十六进制私钥。
--metrics-port	可选的。公开prometheus监控指标的端口默认为9090。

tip

您的中继链集应包括原始链和目标链。

要了解您可以更改的所有参数，请阅读agent configuration reference。

Using Docker

挂载目录 对于中继器（relayer），我们向Docker提供的参数几乎与验证器相同。

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

...
-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 \
...

硬编码这些路径可以消除在运行中维护不同链集的中继器的Docker实例之间的配置重复。这样可以在运行容器时更容易传递正确的参数。请参阅下面的示例，其中唯一需要针对不同链进行配置的项目是中继的链列表和中继器密钥。

Building from source

克隆并设置

如果还没有这样做，请克隆Hyperlane monorepo并按照 rust 目录中的setup instructions进行操作。

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

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

# (apple silicon only) install rosetta 2
softwareupdate --install-rosetta --agree-to-license

运行

Using Docker

如果您还没有拉取 Docker 镜像，请现在运行以下命令进行操作：

docker pull gcr.io/abacus-labs-dev/hyperlane-agent:3adc0e9-20240319-152359

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

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_relayer,target=/hyperlane_db \
  --mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures,readonly \
  gcr.io/abacus-labs-dev/hyperlane-agent:3adc0e9-20240319-152359 \
  ./relayer \
  --db /hyperlane_db \
  --relayChains <chain_1_name>,<chain_2_name> \
  --allowLocalCheckpointSyncers true \
  --defaultSigner.key <your_relayer_key> \

Building from source

在按照设置说明进行操作后，您现在应该可以使用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

为了避免与验证器发生冲突，metrics端口被覆盖。

（可选）：直接运行二进制文件

您也可以选择构建代理程序：

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

要获取更多信息，请查阅Relayer guide。

5. 发送测试信息

您可以在成对的链之间发送测试消息，检查一切工作是否正常。 使用CLI启动信息。它会要求提供一组要使用的核心部署构件。选择步骤2中的core-deploymentsJSON 文件。

hyperlane send message --key $PRIVATE_KEY

send message命令会在发送信息时通知您。短暂等待后，系统将显示发送确认。如果信息发送超时，很可能是上述步骤中的验证器或中继器设置出现了问题。要排除故障，请查看起源链中继器日志。如果您需要进一步帮助，请联系 Discord。

6. (可选) 部署一个Warp Route

一旦消息被传送，您可以选择部署一个Warp Route。Warp 是一个工具包，用于在任何链之间无需许可的桥接代币。路由可以使用本地货币（如 Eth）或 ERC20 代币（如 USDC）。

首先，创建一个新的路由配置：

hyperlane config create warp

接下来，就可以部署路由了。与之前一样，CLI 会提示您提供核心部署构件文件：

hyperlane deploy warp --key $PRIVATE_KEY

完成后，CLI将创建两个新的JSON构件文件：warp-deployment-{timestamp}.json和warp-ui-token-config-{timestamp}。第一个文件只包含新部署的Warp路由器合约的地址。第二个是Warp UI的配置文件，可用于下一个可选步骤。

tip

请参阅详细的Deploy Warp Guide了解更多基本概念以及如何设置Warp路由以传输令牌。

部署 Warp UI

Warp UI是用于与Warp Routes交互的DApp 模板。您可以克隆Warp UI repo 并按照 CUSTOMIZE.md 中的说明配置新实例。简而言之，使用前面步骤中的 chains.yaml 和 warp-ui-token-config.json 文件为用户界面提供所需的信息。有关分步说明，请参阅 Deploy Warp UI guide 。