ash-rs

This project provides Rust crates to interact with:

Avalanche nodes, Subnets, and blockchains;
other Ash tools.

Crates

ash_sdk: Ash Rust SDK
ash_cli: Ash CLI

Ash CLI Installation

See the Installation section of the documentation.

Configuration

See the Custom Configuration tutorial section of the documentation.

Development

git clone https://github.com/AshAvalanche/ash-rs.git
cd ash-rs

# Run the library tests
cargo test

# Run the CLI
## Debug mode
cargo run -- --help
## Release mode
cargo run --release -- --help

Releasing

Use the build*.sh scripts to build the CLI binary. The binary will be archived to ash-${PLATFORM}-${ARCH}-v${VERSION}.tar.gz where PLATFORM is linux or macos, ARCH is amd64 or arm64, and VERSION is the version of the crate. A SHA512 checksum file will also be generated.

For MacOS builds, osxcross is used to cross-compile the binary. See scripts/osxcross_setup.sh for the setup script.

# Build a release for Linux only
./scripts/build_linux.sh --release
# Build a release for Mac only
OSXCROSS_PATH=/full/path/to/osxcross ./scripts/build_macos.sh --release
# Build a release for both Mac and Linux
# Requires osxcross to be installed. See ./scripts/osxcross_setup.sh
OSXCROSS_PATH=/full/path/to/osxcross ./sripts/build.sh --release

Advanced testing

Local Avalanche network

Some tests (e.g. avalanche::nodes::tests) require a local Avalanche network and are ignored by default. They are configured to work with avalanche-network-runner. The easiest way to bootstrap a network is using avalanche-cli:

# Install avalanche-cli
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s
export PATH=~/bin:$PATH

# Start the local network
avalanche network start

# Run all tests
cargo test -- --include-ignored

RPC endpoint configuration for tests

The Avalanche public APIs (provided by Ava Labs, Ankr, Blast, etc.) have rate limits that can impact testing. It is necessary to use a private RPC endpoint to have a reproducible testing behaviour.

A custom configuration file can be provided through the ASH_TEST_AVAX_CONFIG environment variable (defaults to crates/ash/tests/conf/default.yml). Tests are performed on the fuji network in this configuration file. See Configuration to see how to generate a sample file.

Ash QuickNode endpoint

The PR GitHub Actions workflow run tests on the Ash team's QuickNode RCP endpoint.

To run tests locally using this endpoint, you need a local copy of the ash-infra repo (private). Generate the tests configuration file before running the tests:

# Set ASH_INFRA_PATH
ASH_INFRA_PATH=path/to/ash-infra
# Source the tests .env file
source crates/ash/tests/.env
# Generate the tests configuration file
envsubst < crates/ash_sdk/tests/conf/quicknode.yml > target/ash-test-avax-conf.yml
# Run the tests
ASH_TEST_AVAX_CONFIG="$PWD/target/ash-test-avax-conf.yml" cargo test

Roadmap

CLI
Get Subnets and blockchains information from the Avalanche P-Chain
Get nodes information from the Avalanche P-Chain
Get Subnet validators information from the Avalanche P-Chain
Subnet creation
Blockchain creation
WASM integration (to allow the library to be used from JavaScript)

AshAvalanche / ash-rs