The home for Hyperlane core contracts, sdk packages, and other infrastructure
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
hyperlane-monorepo/rust/README.md

97 lines
3.0 KiB

## Abacus Rust implementations
### Setup
- install `rustup`
- [link here](https://rustup.rs/)
Note: You should be running >= version `1.63.0` of the rustc compiler, you can see that version with this command and should see similar output:
```
$ rustup --version
rustup 1.24.3 (ce5817a94 2021-05-31)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active `rustc` version is `rustc 1.63.0 (4b91a6ea7 2022-08-08)`
```
### 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 Abacus are written in Solidity. The rust portions are
exclusively off-chain. Later, there may be on-chain rust for Near/Solana/
Polkadot.
Abacus 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
- `abacus-base`
- lowest dependency abacus 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
- `abacus-core`
- depends on abacus-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/abacus-ethereum`
- depends on abacus-core (and transitively abacus-base)
- interfaces to the ethereum contracts
- `agents`
- each of the off-chain agents implemented thus far
### Running Locally
From within the `abacus-monorepo/rust` directory, run
```bash
cargo run -r -p run-locally
```
or (long-form)
```bash
cargo run --release --package run-locally
```