hyperlane-monorepo/rust/README.md

## Hyperlane Rust implementations

### Setup

- install `rustup`
  - [link here](https://rustup.rs/)

Note: You should be running >= version `1.69.0` 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.69.0 (84c898d65 2023-04-16)`
```

### Running Locally

To run the validator, run:

```bash
cargo run --release --bin validator
```

Or build and then run the binary directly:

```bash
cargo build --release --bin validator
./target/release/validator
```

To run the relayer, run:

```bash
cargo run --release --bin relayer
```

Or build and then run the binary directly:

```bash
cargo build --release --bin relayer
./target/release/relayer
```

#### Automated E2E Test

To perform an automated e2e test of the agents locally, from within the `hyperlane-monorepo/rust` directory, run:

```bash
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`.

### Building Agent Docker Images

There exists a docker build for the agent binaries. These docker images are used for deploying the agents in a
production environment.

```bash
cd rust
./build.sh <image_tag>
```

### Deploy Procedure

The contract addresses of each deploy can be found in `rust/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.

### Useful cargo commands

- `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

### Useful cargo extensions

- 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]` and `macros!()`
  - install: `cargo install cargo-expand`
  - invoke `cargo expand path::to::module`

### Architecture

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](https://github.com/gakonst/ethers-rs). Please see the docs
[here](https://docs.rs/ethers/0.2.0/ethers/).

We use the tokio async runtime environment. Please see the docs
[here](https://docs.rs/tokio/1.1.0/tokio/).

### Repo layout

- `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