Installation

This guide covers building Ashen from source. There are two paths: devenv (recommended) for a reproducible Nix-based environment, or manual installation if you prefer managing dependencies yourself.

Quick Start (devenv)

The fastest way to get started is with devenv:

# Clone the repository
git clone https://github.com/ashen-sh/ashen.git
cd ashen

# Enter the dev environment (installs all dependencies)
devenv shell

# Build everything
just build

# Run tests
just test

---

Prerequisites

System Requirements

Component	Minimum	Recommended
CPU	4 cores	8+ cores
RAM	8 GB	16+ GB
Disk	20 GB free	50+ GB SSD
OS	Linux, macOS	Ubuntu 22.04+, macOS 13+

Required Tools

Tool	Version	Purpose
Rust	nightly-2025-11-05	Node and contract compilation
Zig	0.13+	Zig contract compilation
just	1.0+	Task runner
jq	1.6+	JSON processing (scripts)
curl	any	RPC testing

---

Option 1: devenv (Recommended)

devenv provides a reproducible development environment with all dependencies pinned.

Install devenv

# Install Nix (if not already installed)
sh <(curl -L https://nixos.org/nix/install) --daemon

# Install devenv
nix-env -iA devenv -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable

Enter the Environment

cd ashen
devenv shell

This automatically provides:

• Rust nightly (2025-11-05) with all components
• RISC-V cross-compilation target
• Miri for memory safety checks
• All required system tools (jq, curl, etc.)

Available Commands

Inside devenv shell, these scripts are available:

Command	Description
build	Build entire workspace
test	Run all tests
fmt	Format code
clippy	Run lints
ashen	Run the ashen CLI
devnet-node	Run a development node
contract-build	Build a contract
contract-deploy	Deploy a contract

---

Option 2: Manual Installation

If you prefer not to use Nix, install dependencies manually.

1. Install Rust

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

# Install the specific nightly toolchain
rustup toolchain install nightly-2025-11-05

# Set as default for this project
cd ashen
rustup override set nightly-2025-11-05

# Add required components
rustup component add rustc cargo clippy rustfmt rust-analyzer rust-src llvm-tools-preview

# Add RISC-V target for contracts
rustup target add riscv64imac-unknown-none-elf

2. Install Zig (for Zig contracts)

# Ubuntu/Debian
sudo apt install zig

# macOS
brew install zig

# Or download from https://ziglang.org/download/

3. Install just

# Ubuntu/Debian
sudo apt install just

# macOS
brew install just

# Or via cargo
cargo install just

4. Install System Tools

# Ubuntu/Debian
sudo apt install curl jq build-essential

# macOS
brew install curl jq

---

Building from Source

Build Everything

# Build the entire workspace (debug)
just build

# Or directly with cargo
cargo build --workspace --all-targets

# Release build (optimized)
cargo build --workspace --all-targets --release

Build Individual Components

# Build just the node
cargo build --bin node --release

# Build the CLI
cargo build --bin ashen --release

# Build the devnet simulator
cargo build --bin devnet

Build Contracts

Rust Contracts

# Build a specific Rust contract
just contract-build --manifest-path contracts/sft_v1/Cargo.toml

# With debug info (for debugging)
just contract-build-debug --manifest-path contracts/sft_v1/Cargo.toml

The contract is compiled to: target/riscv64imac-unknown-none-elf/release/<name>

Zig Contracts

# Build a specific Zig contract
cd contracts/amm_pool_v1
zig build -Doptimize=ReleaseSmall

# Build all contracts (Zig and Rust)
just contract-build-all

---

Verifying Installation

1. Check the Build

# Verify workspace compiles
cargo check --workspace --all-targets

2. Run Tests

# Run all tests
just test

# Or specific test suites
cargo test -p ashen                    # Core chain tests
cargo test -p vm-conformance           # VM conformance
cargo test -p vm-runtime               # Runtime tests

3. Run a Quick Smoke Test

# Fast verification of core functionality
just agent-smoke

This runs:

• Workspace compilation check
• 4-node consensus simulation (100 steps)
• Core application tests
• Execution unit tests

4. Start a Local Node

# Initialize node data with a funded account
just ed25519-keygen > ./target/dev.key.json
export ASHEN_PRIVATE_KEY=@./target/dev.key.json
ADDR=$(jq -r .address ./target/dev.key.json)

just devnet-node init --data-dir ./node-data --alloc "$ADDR=1000000000000"

# Run the node
just node

In another terminal:

# Check status
just rpc-status

# Check your account
just rpc-account $ADDR

---

Development Workflow

Useful just Commands

# List all available commands
just

# Format code
just fmt

# Run clippy lints
just clippy

# Run a single chain test (fast)
just ashen-single

# Run devnet simulation
just devnet-small      # 4 nodes, 200 steps
just devnet-chaos      # 7 nodes, lossy network

# Show verification guide
just robot

IDE Setup

VS Code

Install these extensions:

• rust-analyzer — Rust language support
• Even Better TOML — Cargo.toml editing
• Zig Language — Zig support (for contracts)

Add to .vscode/settings.json:

{
  "rust-analyzer.cargo.target": null,
  "rust-analyzer.check.command": "clippy",
  "rust-analyzer.check.extraArgs": [
    "--",
    "-D", "clippy::panic",
    "-D", "clippy::unwrap_used",
    "-D", "clippy::expect_used"
  ]
}

Neovim

Use nvim-lspconfig with rust-analyzer:

require('lspconfig').rust_analyzer.setup {
  settings = {
    ['rust-analyzer'] = {
      check = {
        command = 'clippy',
      },
    },
  },
}

---

Environment Variables

Set these in your shell or .env file:

Variable	Default	Description
NODE_RPC_URL	http://127.0.0.1:3030	RPC endpoint for CLI tools
NODE_AUTH_TOKEN	none	Bearer token for authenticated RPC
ASHEN_PRIVATE_KEY	none	Signing key for transactions
NODE_DATA_DIR	./node-data	Default data directory

Key Formats

The ASHEN_PRIVATE_KEY can be:

# Raw hex (64 chars)
export ASHEN_PRIVATE_KEY="abcd1234..."

# 0x-prefixed hex
export ASHEN_PRIVATE_KEY="0xabcd1234..."

# File reference (JSON with secret_key_hex field)
export ASHEN_PRIVATE_KEY="@./path/to/key.json"

# Keystore reference
export ASHEN_PRIVATE_KEY="keystore:my-key"

---

Troubleshooting

Rust Target Not Found

error: target 'riscv64imac-unknown-none-elf' not found

Fix: Install the RISC-V target:

rustup target add riscv64imac-unknown-none-elf

Linker Not Found

error: linker `cc` not found

Fix: Install a C toolchain:

# Ubuntu/Debian
sudo apt install build-essential

# macOS (Xcode command line tools)
xcode-select --install

Zig Not Found

zig: command not found

Fix: Install Zig or enter devenv shell:

devenv shell
# Or install Zig manually: https://ziglang.org/download/

Out of Memory During Build

Large workspaces can exhaust memory during parallel compilation.

Fix: Limit parallelism:

cargo build -j 4  # Limit to 4 parallel jobs

devenv Shell Fails

error: getting status of '/nix/store/...': No such file or directory

Fix: Rebuild the Nix store:

devenv gc    # Garbage collect
devenv shell # Re-enter

---

Next Steps

• Quickstart — Run a local node and deploy a contract
• Running a Node — Detailed node operation guide
• Deploying Contracts — Build and deploy smart contracts
• Using the CLI — Complete CLI reference