Skip to content

Commit

Permalink
inline local agent instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@paulbalaji
paulbalaji committed Jan 16, 2024
1 parent 7391954 commit 3392b28
Showing 1 changed file with 331 additions and 12 deletions.
343 changes: 331 additions & 12 deletions docs/guides/deploy-hyperlane-local-agents.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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-<your_chain_name>

# 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-<your_chain_name>

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

<Tabs groupId="docker">
<TabItem value="docker" label="Using Docker">

**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_<your_chain_name>,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 <your_chain_name> \
--checkpointSyncer.type localStorage \
--checkpointSyncer.path /tmp/validator-signatures \
--validator.key <your_validator_key>
...
```

</TabItem>
<TabItem value="from-source" label="Building from source">

**Clone and setup**

First, clone the Hyperlane monorepo:

```sh
git clone [email protected]: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
```

</TabItem>
</Tabs>

### Run

<Tabs groupId="docker">
<TabItem value="docker" label="Using Docker">
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_<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:main \
./validator \
--db /hyperlane_db \
--originChainName <your_chain_name> \
--checkpointSyncer.type localStorage \
--checkpointSyncer.path /tmp/validator-signatures \
--validator.key <your_validator_key>
```

</TabItem>

<TabItem value="from-source" label="Building from source">

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_<your_chain_name> \
--originChainName <your_chain_name> \
--checkpointSyncer.type localStorage \
--checkpointSyncer.path $VALIDATOR_SIGNATURES_DIR \
--validator.key <your_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_<your_chain_name> \
--originChainName <your_chain_name> \
--checkpointSyncer.type localStorage \
--checkpointSyncer.path $VALIDATOR_SIGNATURES_DIR \
--validator.key <your_validator_key>
```

:::

</TabItem>
</Tabs>

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

<Tabs groupId="docker">
<TabItem value="docker" label="Using Docker">

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

</TabItem>
<TabItem value="from-source" label="Building from source">

**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 [email protected]: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
```

</TabItem>
</Tabs>

### Run

<Tabs groupId="docker">
<TabItem value="docker" label="Using Docker">

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 <your_chain_name>,<remote_chain_name> \
--allowLocalCheckpointSyncers true \
--defaultSigner.key <your_validator_key>
```

</TabItem>
<TabItem value="from-source" label="Building from source">

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 <your_chain_name>,<remote_chain_name> \
--allowLocalCheckpointSyncers true \
--defaultSigner.key <your_validator_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 <your_chain_name>,<remote_chain_name> \
--allowLocalCheckpointSyncers true \
--defaultSigner.key <your_validator_key> \
--metrics-port 9091
```

:::

</TabItem>
</Tabs>

For further information, check out the [Relayer guide](/docs/operate/relayer/run-relayer).

## 5. Send test messages

Expand Down

0 comments on commit 3392b28

Please sign in to comment.