From 3392b28cb25c782ad707c119b05f8ad67f8ff8bc Mon Sep 17 00:00:00 2001 From: Paul Balaji Date: Mon, 15 Jan 2024 19:47:14 +0000 Subject: [PATCH] inline local agent instructions --- docs/guides/deploy-hyperlane-local-agents.mdx | 343 +++++++++++++++++- 1 file changed, 331 insertions(+), 12 deletions(-) diff --git a/docs/guides/deploy-hyperlane-local-agents.mdx b/docs/guides/deploy-hyperlane-local-agents.mdx index f4468633..4a42ce97 100644 --- a/docs/guides/deploy-hyperlane-local-agents.mdx +++ b/docs/guides/deploy-hyperlane-local-agents.mdx @@ -4,6 +4,9 @@ import DeployContractsPartial from "/docs/partials/deploy-hyperlane/_deploy-cont import SendTestMessagesPartial from "/docs/partials/deploy-hyperlane/_send-test-messages.mdx"; import DeployWarpRoutePartial from "/docs/partials/deploy-hyperlane/_deploy-warp-route.mdx"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + # Deploy Hyperlane with Local Agents :::tip @@ -39,35 +42,351 @@ There are six steps in this guide: ## 3. Run a validator -Follow the [Validators guide](/docs/operate/validators/run-validators) to run a validator for the Mailbox on your local chain. This validator will provide the security for messages sent _from_ your chain to remote chains. +Validators provide the security for messages sent _from_ your chain to remote chains. + +### Setup directories + +First, set the `CONFIG_FILES` environment variable to the path of the agent config generated in the [deploy contracts](#2-deploy-contracts) step. For example: + +```bash +export CONFIG_FILES=/full/path/to/configs/agent-config-{timestamp}.json +``` + +Next, create a local directory for your validator to write its signatures to. Remember the path, as you will need this when configuring your validator. + +```sh +# Pick an informative name specific to the chain you're validating +export VALIDATOR_SIGNATURES_DIR=/tmp/hyperlane-validator-signatures- + +# Create the directory +mkdir -p $VALIDATOR_SIGNATURES_DIR +``` + +:::warning + +You will not be able to mount anything in `/tmp` when running the agent via Docker on Mac. To counter this, create a local `tmp` directory to mount instead. + +```sh +# Create a local tmp directory that can be accessed by docker +mkdir tmp + +# Pick an informative name specific to the chain you're validating +export VALIDATOR_SIGNATURES_DIR=tmp/hyperlane-validator-signatures- -You should have already set up your validator keys in [step 1](#1-set-up-keys), so you can skip that part of the guide. +# Create the directory +mkdir -p $VALIDATOR_SIGNATURES_DIR +``` + +::: + +### Configure + +There are numerous parameters that validators can be configured with. For this guide, we are concerned with just a handful: + +| Parameter | Description | +| ------------------------- | ------------------------------------------------------------------- | +| `--db` | Path for writing persistent data to disk. | +| `--originChainName` | Name of the chain being validated (e.g. `ethereum`). | +| `--checkpointSyncer.type` | Set to `localStorage` for this guide. | +| `--checkpointSyncer.path` | Path to local directory where validator signatures will be written. | +| `--validator.key` | Your validator's hexadecimal private key. | :::info -Make sure your validator matches the address provided when setting up your MultisigIsmConfig. Otherwise, the Multisig ISM you deployed in the previous step will not be able to verify messages sent from your chain. +Make sure the validator key corresponds to the address provided when setting up your MultisigIsmConfig. Otherwise, the Multisig ISM you deployed in the previous step will not be able to verify messages sent from your chain. ::: -Set the `CONFIG_FILES` environment variable to the path of the agent config generated in the [deploy contracts](#2-deploy-contracts) step. For example: -```bash -export CONFIG_FILES=/path/to/configs/agent-config-{timestamp}.json +To learn more about all the parameters you can change, read the [agent configuration reference](/docs/operate/config-reference). + + + + +**Update agent config** + +Unless you are running Docker on Linux, you will also need to update the agent configuration for your network. This is because Docker does not support the [`host` network mode](https://docs.docker.com/network/drivers/host/) on Mac, Windows or Windows Server. + +To do this, navigate to the agent-configuration at `$CONFIG_FILES` and replace all instances of "localhost" or "127.0.0.1" in to `host.docker.internal`. For example: + +```json +... +"localnet1": { + ... + "rpcUrls": [ + { + // "http": "http://localhost:8545" + // "http": "http://127.0.0.1:8545" + "http": "http://host.docker.internal:8545" + } + ], + ... +}, +... ``` -If you are using Docker, you will need to mount the file into the container. +**Mounting directories** + +Running with Docker adds an extra layer of complexity because config files need to be accessible from within the Docker container, and validator signatures need to be accessible from outside of the container. This can be solved by mounting directories on your file system into the container. + +In the arguments below, we: + +1. Set the `$CONFIG_FILES` environment variable to a fixed path within the container. +1. Mount the agent config file to this fixed path and making it readonly. +1. Mount the persistent data directory at a fixed path within the container. +1. Mount the validator signatures directory to a fixed path within the container. + +```sh +... +-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_,target=/hyperlane_db \ +--mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures \ +... +``` + +Hardcoding these paths deduplucates the configuration, making it easier to pass the right arguments when running the container. See the example below, where that's left is for you to configure the chain name and validator key. + +```sh +... +./validator \ +--db /hyperlane_db \ +--originChainName \ +--checkpointSyncer.type localStorage \ +--checkpointSyncer.path /tmp/validator-signatures \ +--validator.key +... +``` + + + + +**Clone and setup** + +First, clone the Hyperlane monorepo: + +```sh +git clone git@github.com:hyperlane-xyz/hyperlane-monorepo.git +``` + +Then follow the [setup instructions](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/rust/README.md) in the `rust` directory. This should setup `rustup` as well as Rosetta 2 if you are on Apple Silicon. + +```sh +# 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 +``` + + + + +### Run + + + +Now that you understand more about configuring validator arguments, pull the latest docker image: + +```sh +docker pull gcr.io/abacus-labs-dev/hyperlane-agent:main +``` + +Finally, run the validator: + +```sh +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_,target=/hyperlane_db \ + --mount type=bind,source="$(pwd)"/$VALIDATOR_SIGNATURES_DIR,target=/tmp/validator-signatures \ + gcr.io/abacus-labs-dev/hyperlane-agent:main \ + ./validator \ + --db /hyperlane_db \ + --originChainName \ + --checkpointSyncer.type localStorage \ + --checkpointSyncer.path /tmp/validator-signatures \ + --validator.key +``` + + + + + +After following the setup instructions, you should now be able to use `cargo` to run the Validator: + +```sh +cargo run --bin validator -- \ + --db ./hyperlane_db_validator_ \ + --originChainName \ + --checkpointSyncer.type localStorage \ + --checkpointSyncer.path $VALIDATOR_SIGNATURES_DIR \ + --validator.key +``` + +:::note (optional) Run the binary directly + +You can alternatively build out the agent: + +```sh +cargo build --release bin validator +``` + +And run the binary directly: + +```sh +./target/release/validator \ + --db ./hyperlane_db_validator_ \ + --originChainName \ + --checkpointSyncer.type localStorage \ + --checkpointSyncer.path $VALIDATOR_SIGNATURES_DIR \ + --validator.key +``` + +::: + + + + +For further information, check out the [Validators guide](/docs/operate/validators/run-validators). ## 4. Run a relayer -Follow the [Relayer guide](/docs/operate/relayer/run-relayer) to run a relayer delivering interchain messages sent between the local and remote chains. You should have already set up your relayer keys in [step 1](#1-set-up-keys), so you can skip that part of the guide. +Relayers deliver interchain messages sent between the local and remote chains. -Remember to set the `--relayChains` argument or `HYP_RELAYCHAINS` environment variable appropriately. +You should already have set the `CONFIG_FILES` environment variable to the path of the agent config generated in the [deploy contracts](#2-deploy-contracts) step. If not, do so now. -Set the `CONFIG_FILES` environment variable to the path of the agent config generated in the [deploy contracts](#2-deploy-contracts) step. For example: ```bash -export CONFIG_FILES=/path/to/configs/agent-config-{timestamp}.json +export CONFIG_FILES=/full/path/to/configs/agent-config-{timestamp}.json +``` + +### Configure + +There are numerous parameters that validators can be configured with. For this guide, we are concerned with just a handful: + +| Parameter | Description | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `--db` | Path for writing persistent data to disk. | +| `--relayChains` | Comma separates names of the origin chain and destination chains to relay messages between. E.g. `ethereum,polygon,avalanche`. | +| `--allowLocalCheckpointSyncers` | Allows the relayer to look for validator signatures on the local filesystem. | +| `--defaultSigner.key` | A hexadecimal private key used to sign transactions for all chains. | +| `--metrics-port` | Optional. The port to expose prometheus metrics on, defaults to `9090`. | + +To learn more about all the parameters you can change, read the [agent configuration reference](/docs/operate/config-reference). + + + + +**Mounting directories** + +For the relayer, we provide almost the same arguments to Docker as the validator: + +1. Set the `$CONFIG_FILES` environment variable to a fixed path within the container. +1. Mount the agent config file to this fixed path and making it **readonly**. +1. Mount the persistent data directory at a fixed path within the container. +1. Mount the validator signatures directory to a fixed path within the container and making it **readonly**. + +```sh +... +-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 \ +... +``` + +Hardcoding these paths deduplucates the configuration, making it easier to pass the right arguments when running the container. + + + + +**Clone and setup** + +If you haven't already done so when setting up the validator, clone the Hyperlane monorepo and follow the [setup instructions](https://github.com/hyperlane-xyz/hyperlane-monorepo/blob/main/rust/README.md) in the `rust` directory. + +```sh +# 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 +``` + + + + +### Run + + + + +If you haven't already pulled the Docker image when setting up your validator, do this now by running: + +```sh +docker pull gcr.io/abacus-labs-dev/hyperlane-agent:main ``` -If you are using Docker, you will need to mount the file into the container. +Finally, run the relayer: + +```sh +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:main \ + ./relayer \ + --db /hyperlane_db \ + --relayChains , \ + --allowLocalCheckpointSyncers true \ + --defaultSigner.key +``` + + + + +After following the setup instructions, you should now be able to use `cargo` to run the Relayer: + +```sh +cargo run --bin relayer -- \ + --db ./hyperlane_db_relayer \ + --relayChains , \ + --allowLocalCheckpointSyncers true \ + --defaultSigner.key \ + --metrics-port 9091 +``` + +The metrics port is overriden to avoid clashing with the validator. + +:::note (optional) Run the binary directly + +You can alternatively build out the agent: + +```sh +cargo build --release bin relayer +``` + +And run the binary directly: + +```sh +./target/release/relayer \ + --db ./hyperlane_db_relayer \ + --relayChains , \ + --allowLocalCheckpointSyncers true \ + --defaultSigner.key \ + --metrics-port 9091 +``` + +::: + + + + +For further information, check out the [Relayer guide](/docs/operate/relayer/run-relayer). ## 5. Send test messages