Skip to main content
This guide covers building the Avail blockchain node from source code using Rust and Cargo.

​
Prerequisites

​
System Dependencies

Before building Avail, ensure you have the required system packages installed: 
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev \
  git clang curl protobuf-compiler

​
Rust Toolchain

Avail requires a specific Rust version as defined in rust-toolchain.toml.
1

Install Rust

Install Rust using rustup:
curl https://sh.rustup.rs -sSf | sh -s -- -y
source "$HOME/.cargo/env"
2

Verify Installation

The project uses Rust 1.82.0 with the following components:
  • rustfmt - Code formatting
  • clippy - Linting
  • rust-src - Source code for the standard library
  • wasm32-unknown-unknown target - WebAssembly compilation
When you run cargo commands, rustup will automatically install the correct toolchain based on rust-toolchain.toml:
rustup show
Avail is built on the Substrate framework and uses Polkadot SDK version polkadot-1.7.1-patch-13.

​
Building the Node

​
Development Build

For development and testing, build without optimizations: 
cargo build
The binary will be located at target/debug/avail-node.

​
Release Build

Release builds take significantly longer but produce optimized binaries for production use.
Build an optimized production binary: 
cargo build --release --locked
The --locked flag ensures dependencies match Cargo.lock exactly. The binary will be at target/release/avail-node.
1

Start the Build

cargo build --release --locked
This process typically takes 20-40 minutes depending on your hardware.
2

Verify the Binary

./target/release/avail-node --version
3

Run the Node

mkdir -p output
./target/release/avail-node --chain mainnet -d ./output

​
Building Specific Packages

Build only the node binary without workspace dependencies: 
cargo build --release -p avail-node

​
Build Features

Avail supports several conditional compilation features:

​
Runtime Benchmarks

Enable runtime benchmarking capabilities: 
cargo build --release --features runtime-benchmarks

​
Try Runtime

Enable the try-runtime feature for testing runtime migrations: 
cargo build --release --features try-runtime

​
Fast Runtime

For development and testing, use a faster block time: 
cargo build --release --features fast-runtime
The fast-runtime feature is required when running E2E tests.

​
Combined Features

Build with multiple features: 
cargo build --release --features "runtime-benchmarks try-runtime"

​
Build Optimization

​
Using sccache

Speed up rebuilds by caching compilation artifacts with sccache: 
cargo install sccache
export RUSTC_WRAPPER=sccache
cargo build --release
Check cache statistics: 
sccache --show-stats

​
Skipping WASM Build

For faster iteration during development, skip WebAssembly runtime compilation: 
export SKIP_WASM_BUILD=true
cargo build
Skipping WASM build creates an incomplete binary. Only use this for compilation checks, not for running the node.

​
Workspace Structure

The Avail repository is organized as a Cargo workspace with these key members:
  • node/ - Node implementation and CLI
  • runtime/ - Blockchain runtime logic
  • pallets/ - Custom pallets (dactr, mandate, system, vector)
  • base/ - Core primitives and utilities
  • client/basic-authorship/ - Block authorship
  • rpc/ - RPC implementations (kate-rpc, testing-rpc)
  • e2e/ - End-to-end tests

​
Build Profiles

​
Development Profile

The development profile includes optimizations for cryptographic dependencies: 
[profile.dev.package]
blake2 = { opt-level = 3 }
ed25519-dalek = { opt-level = 3 }
# ... and many more crypto libraries
This significantly improves development build performance.

​
Release Profile

Release builds use:
  • Panic strategy: unwind (required by Substrate runtime)
  • Optimization level: 3 (maximum)
  • LTO: Disabled by default (can be enabled for smaller binaries)

​
Troubleshooting

​
Linker Errors

If you encounter linker errors, ensure you have the required development packages: 
# Ubuntu/Debian
sudo apt-get install build-essential

# macOS - install Xcode Command Line Tools
xcode-select --install

​
Out of Memory

If compilation fails due to memory constraints, limit parallel jobs: 
cargo build --release -j 2

​
Protobuf Errors

Ensure protobuf compiler is installed: 
protoc --version
If missing, install it as shown in the prerequisites.

​
OpenSSL Errors

On some systems, you may need to explicitly set OpenSSL paths: 
export OPENSSL_DIR=/usr/local/opt/openssl
export PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig
cargo build --release

​
Next Steps

Running Tests

Learn how to run unit, integration, and E2E tests

Contributing

Guidelines for contributing to Avail

Build docs developers (and LLMs) love

Get started for freeTalk to us