- install
rustup
Note: You should be running >= version 1.72.1
of the rustc compiler, you can see that version with this command and
should see similar output:
$ rustup --version
rustup 1.26.0 (5af9b9484 2023-04-05)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active `rustc` version is `rustc 1.72.1 (d5c2e9c34 2023-09-13)`
If your device has an Apple Silicon processor, you may need to install Rosetta 2:
softwareupdate --install-rosetta --agree-to-license
To run the validator, run:
cargo run --release --bin validator
Or build and then run the binary directly:
cargo build --release --bin validator
./target/release/validator
To run the relayer, run:
cargo run --release --bin relayer
Or build and then run the binary directly:
cargo build --release --bin relayer
./target/release/relayer
Building the docker image and upgrading the pod is a slow process. To speed up the development cycle, you can run a local binary against cloud resources. This workflow is useful for testing local changes against cloud resources. It is also useful for debugging issues in production.
Example of fetching env from pod:
kubectl exec fuji-hyperlane-agent-validator-0 --namespace testnet3 -c agent -- printenv > ./config/validator.fuji.env
Copy directory (rocks DB) from pod to local:
kubectl cp testnet3/fuji-hyperlane-agent-validator-0:/usr/share/hyperlane /tmp/fuji-validator-db
Configure additional env variables appropriately:
HYP_DB=/tmp/fuji-validator-db
CONFIG_FILES=./config/testnet_config.json
HYP_TRACING_FMT=pretty
GCS_USER_SECRET=./path/to/file
# or if service account used
GCS_SERVICE_ACCOUNT_KEY=./path/to/file
DATABASE_URL=<READ_REPLICA_POSTGRES_URL> # for scraper
Run binary with env copied from pod:
env $(cat ./config/validator.fuji.env | grep -v "#" | xargs) ./target/debug/validator
Clone hyperlane-registry
repo next to hyperlane-monorepo
repo.
To perform an automated e2e test of the agents locally, from within the hyperlane-monorepo/rust
directory, run:
cargo run --release --bin run-locally
This will automatically build the agents, start a local node, build and deploy the contracts, and run a relayer and
validator. By default, this test will run indefinitely, but can be stopped with ctrl-c
.
To run the tests for a specific VM, use the --features
flag.
cargo test --release --package run-locally --bin run-locally --features cosmos -- cosmos::test --nocapture
There exists a docker build for the agent binaries. These docker images are used for deploying the agents in a production environment.
cd rust
./build.sh <image_tag>
The contract addresses of each deploy can be found in rust/main/config
. The agents will
automatically pull in all configs in this directory.
When agents are deployed to point at a new environment, they cease to point at the old ones. We do not continue to operate off-chain agents on old contract deploys. Contracts not supported by the agents will cease to function (i.e. messages will not be relayed between chains).
Off-chain agents are not automatically re-deployed when new contract deploys are merged. Auto-redeploys will be implemented at some future date.
cargo doc --open
- generate documentation and open it in a web browser
cargo build
- compile the project
cargo run --example example
- run the default executable for the current project
cargo test
- run the tests
- tree
- show the dependency tree. Allows searching for specific packages
- install:
cargo install cargo-tree
- invoke:
cargo tree
- clippy
- search the codebase for a large number of lints and bad patterns
- install:
rustup component add clippy
- invoke:
cargo clippy
- expand
- expand macros and procedural macros. Show the code generated by the preprocessor
- useful for debugging
#[macros]
andmacros!()
- install:
cargo install cargo-expand
- invoke
cargo expand path::to::module
The on-chain portions of Hyperlane are written in Solidity. The rust portions are exclusively off-chain. Later, there may be on-chain rust for Near/Solana/ Polkadot.
Hyperlane will be managed by a number of small off-chain programs ("agents"). Each of these will have a specific role. We want these roles to be simple, and easily described. Each of these agents will connect to a home chain and any number of replicas. They need to be configured with chain connection details and have access to a reliable node for each chain.
For Ethereum and Celo connections we use ethers-rs. Please see the docs here.
We use the tokio async runtime environment. Please see the docs here.
hyperlane-base
- lowest dependency hyperlane utilities
- contains shared utilities for building off-chain agents
- this includes
- trait implementations for different chains
- shared configuration file formats
- basic setup for an off-chain agent
hyperlane-core
- depends on hyperlane-base
- contains implementations of core primitives
- this includes
- traits (interfaces) for the on-chain contracts
- model implementations of the contracts in rust
- merkle tree implementations (for provers)
chains/hyperlane-ethereum
- depends on hyperlane-core (and transitively hyperlane-base)
- interfaces to the ethereum contracts
chains/hyperlane-fuel
- depends on hyperlane-core
- interfaces to the fuel contracts
agents
- each of the off-chain agents implemented thus far