Installation

Overview

This guide covers building the Avail Node from source. Building from source gives you access to the latest features and allows you to customize the build for your specific needs.

System requirements

Before installing, ensure your system meets these requirements:

Hardware requirements

CPU: 4+ cores (8+ recommended for validators)
RAM: 8GB minimum (16GB+ recommended)
Storage: 200GB+ SSD (NVMe recommended for validators)
Network: Stable broadband connection (100Mbps+ for validators)

Supported operating systems

Ubuntu 20.04 LTS or newer
Debian 11 or newer
Fedora 35 or newer
macOS 11 (Big Sur) or newer
Other Linux distributions with equivalent package versions

Rust installation

Avail Node requires Rust version 1.82.0 as specified in rust-toolchain.toml.

Install Rust toolchain

Download and install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the prompts to complete installation. When asked, choose the default installation.

Configure your shell

Add Rust to your system PATH:

source $HOME/.cargo/env

Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent:

echo 'source $HOME/.cargo/env' >> ~/.bashrc

Verify installation

Confirm Rust is installed correctly:

rustc --version
cargo --version

The Avail repository includes a rust-toolchain.toml file that automatically installs the correct Rust version (1.82.0) and required components.

Substrate dependencies

Avail is built with Substrate, which requires additional system dependencies.

Ubuntu / Debian

Update package index

sudo apt update

Install dependencies

sudo apt install -y \
  build-essential \
  git \
  clang \
  curl \
  libssl-dev \
  llvm \
  libudev-dev \
  make \
  cmake \
  protobuf-compiler

Fedora / RHEL / CentOS

Install dependencies

sudo dnf install -y \
  gcc \
  gcc-c++ \
  make \
  git \
  clang \
  curl \
  openssl-devel \
  llvm \
  systemd-devel \
  cmake \
  protobuf-compiler

macOS

Install Homebrew

If you don’t have Homebrew installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install dependencies

brew install cmake protobuf llvm

Building Avail Node

Now you’re ready to build the Avail Node from source.

Clone the repository

git clone https://github.com/availproject/avail.git
cd avail

To build a specific version, checkout a release tag:

git checkout v2.3.4.0

Build the release binary

Build the optimized release binary:

cargo build --locked --release

The first build typically takes 20-30 minutes depending on your hardware. Subsequent builds will be much faster.

The --locked flag ensures dependencies match Cargo.lock exactly, and --release enables optimizations.

Verify the build

Check that the binary was created successfully:

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

You should see output like:

avail-node 2.3.0-6c6b8912fd3

Installing the binary

Optionally, install the binary to your system path:

sudo cp target/release/avail-node /usr/local/bin/

Now you can run avail-node from anywhere:

avail-node --version

Understanding the build process

The Avail workspace consists of multiple components defined in Cargo.toml:

base - Core Avail types and utilities
runtime - Blockchain runtime logic
node - Node implementation (produces the avail-node binary)
pallets/ - Custom pallets:
- dactr - Data availability control
- mandate - Governance mandates
- system - Custom frame-system fork
- vector - Vector commitment functionality
client/basic-authorship - Custom block authorship
rpc/ - RPC implementations including Kate RPC
patricia-merkle-trie - Merkle trie implementation

Build optimizations

The workspace Cargo.toml includes optimizations for cryptographic operations even in dev builds:

[profile.dev.package]
blake2 = { opt-level = 3 }
curve25519-dalek = { opt-level = 3 }
ed25519-dalek = { opt-level = 3 }
keccak = { opt-level = 3 }
sha2 = { opt-level = 3 }
# ... and more

This ensures reasonable performance during development.

Advanced build options

Build with specific features

Build only what you need:

# Build with runtime benchmarking
cargo build --locked --release --features runtime-benchmarks

# Build with try-runtime for testing migrations
cargo build --locked --release --features try-runtime

Cross-compilation

Build for different architectures:

# Add target
rustup target add aarch64-unknown-linux-gnu

# Build for ARM64
cargo build --locked --release --target aarch64-unknown-linux-gnu

Environment variables

Control build behavior with these environment variables:

Variable	Description	Default
`WASM_BUILD_TYPE`	WebAssembly build type	`release`
`SKIP_WASM_BUILD`	Skip WASM runtime build	`false`
`CARGO_PROFILE_RELEASE_LTO`	Enable link-time optimization	Disabled

Example:

export CARGO_PROFILE_RELEASE_LTO=fat
cargo build --locked --release

Enabling LTO significantly increases build time but may improve runtime performance by 5-10%.

Verifying dependencies

The project uses specific versions of key dependencies:

Polkadot SDK: v1.7.1-patch-13 (forked version)
Avail Core: core-node-12 tag
Rust: 1.82.0 (enforced by rust-toolchain.toml)

When you build, Rust automatically:

Reads rust-toolchain.toml
Installs Rust 1.82.0 if needed
Installs required components: rustfmt, clippy, rust-src
Adds WASM target: wasm32-unknown-unknown

Building with Docker

If you prefer containerized builds, use the provided Dockerfile:

docker build -t avail-builder -f Dockerfile .

This uses a multi-stage build process:

Builder stage: Debian 12.12-slim with full build toolchain
Runtime stage: Minimal Debian image with only the binary

The resulting image is optimized for size (< 200MB vs ~5GB build environment).

Development build

For development, use a debug build which compiles much faster:

cargo build
./target/debug/avail-node --dev

Debug builds run 10-100x slower than release builds. Only use for rapid development iteration.

Building specific packages

Build individual workspace members:

# Build only the runtime
cargo build -p da-runtime --release

# Build Kate RPC
cargo build -p kate-rpc --release

Running tests

Verify your build with the test suite:

# Run all tests
cargo test --workspace

# Run tests for specific package
cargo test -p da-runtime

# Run with release optimizations (slower build, faster execution)
cargo test --workspace --release

Benchmarking

The project includes comprehensive benchmarking tools:

Runtime benchmarks

cargo bench --bench header_kate_commitment_cri
cargo bench --bench header_kate_commitment_divan

Instruction-level analysis

cargo bench --bench header_kate_commitment_iai_callgrind
cargo bench --bench header_kate_commitment_iai

These benchmarks use iai and iai-callgrind for detailed performance profiling including cache hits and instruction counts.

Troubleshooting

Build fails with linker errors

Ensure all system dependencies are installed:

# Ubuntu/Debian
sudo apt install -y build-essential clang libssl-dev

# Fedora
sudo dnf install -y gcc gcc-c++ clang openssl-devel

WASM build fails

Add the WASM target explicitly:

rustup target add wasm32-unknown-unknown --toolchain 1.82.0

Out of memory during build

Reduce parallel compilation:

cargo build --locked --release -j 2

Or limit memory per job:

export CARGO_BUILD_JOBS=2
cargo build --locked --release

Protobuf compiler not found

Install the protobuf compiler:

# Ubuntu/Debian
sudo apt install -y protobuf-compiler

# macOS
brew install protobuf

# Fedora
sudo dnf install -y protobuf-compiler

Keeping your installation updated

Update to the latest version:

cd avail
git fetch --all --tags
git checkout <latest-tag>
cargo build --locked --release

Always check the release notes before upgrading. Some releases may require chain data migration or configuration changes.

Next steps

Quick start

Run your newly built node

Configuration

Learn about node configuration options

Validator setup

Configure your node as a validator

CLI reference

Complete command-line reference

Additional resources

Substrate Documentation - Detailed Substrate dependency guide
Rust Installation - Official Rust installation guide
Avail Wiki - Advanced topics and build configurations

Getting Started

Running a Node

Architecture

Pallets

Operations

Development

​Overview

​System requirements

​Hardware requirements

​Supported operating systems

​Rust installation

​Substrate dependencies

​Ubuntu / Debian

​Fedora / RHEL / CentOS

​macOS

​Building Avail Node

​Installing the binary

​Understanding the build process

​Build optimizations

​Advanced build options

​Build with specific features

​Cross-compilation

​Environment variables

​Verifying dependencies

​Building with Docker

​Development build

​Building specific packages

​Running tests

​Benchmarking

​Runtime benchmarks

​Instruction-level analysis

​Troubleshooting

​Build fails with linker errors

​WASM build fails

​Out of memory during build

​Protobuf compiler not found

​Keeping your installation updated

​Next steps

Quick start

Configuration

Validator setup

CLI reference

​Additional resources

Build docs developers (and LLMs) love

Overview

System requirements

Hardware requirements

Supported operating systems

Rust installation

Substrate dependencies

Ubuntu / Debian

Fedora / RHEL / CentOS

macOS

Building Avail Node

Installing the binary

Understanding the build process

Build optimizations

Advanced build options

Build with specific features

Cross-compilation

Environment variables

Verifying dependencies

Building with Docker

Development build

Building specific packages

Running tests

Benchmarking

Runtime benchmarks

Instruction-level analysis

Troubleshooting

Build fails with linker errors

WASM build fails

Out of memory during build

Protobuf compiler not found

Keeping your installation updated

Next steps

Additional resources