Skip to content
Ashen Docs

Local Devnet

Overview

Section titled “Overview”

Ashen provides three ways to run a local development environment:

  1. Single node — one validator with RPC, fastest iteration loop
  2. Multi-node testnet — multiple validators with P2P, tests consensus
  3. Deterministic simulation — in-memory consensus sim, no network needed

Quick Start (Single Node)

Section titled “Quick Start (Single Node)”
Terminal window
# Generate a keypair
just ed25519-keygen > dev.key.json


# Initialize with a pre-funded account
just node init --data-dir ./node-data \
  --alloc "493615aa1e16a24f618d3ab6dd93a9250ca76e19996e46493a372c5994862e8c=13370000000000"


# Start the node (RPC on port 3030)
just node run --data-dir ./node-data --block-time-ms 1000

Verify it’s running:

Terminal window
just rpc-status

Key Generation

Section titled “Key Generation”
Terminal window
# Random key
just ed25519-keygen


# Deterministic key (reproducible)
just ed25519-keygen --seed 12345

Output:

{
  "seed": 12345,
  "secret_key": "0x...",
  "public_key": "0x...",
  "address": "0x493615aa..."
}

Use --seed for reproducible test accounts across runs.

Genesis Configuration

Section titled “Genesis Configuration”

Genesis is created during node init. Pre-fund accounts with --alloc:

Terminal window
# Multiple accounts
just node init --data-dir ./node-data \
  --alloc "ADDR1=1000000" \
  --alloc "ADDR2=2000000"


# Auto-generate N seed accounts
just node init --data-dir ./node-data \
  --seed 42 --seed-count 10 --seed-balance 1000000000

The resulting genesis.json:

{
  "allocations": [
    { "address": "493615aa...", "balance": 13370000000000 }
  ]
}

Multi-Node Testnet

Section titled “Multi-Node Testnet”

Generate and run a local validator set:

Terminal window
# Generate configs for 3 validators
just testnet-local-generate N_VALIDATORS=3 TESTNET_DIR=./testnet-local


# Start all validators + archive node with RPC
just testnet-local-run N_VALIDATORS=3 TESTNET_DIR=./testnet-local

Or use the setup binary for more control:

Terminal window
cargo run --bin setup -- local \
  --validators 4 \
  --seed 12345 \
  --initial-balance 1000000000 \
  --output ./testnet

This creates: validator keys, BLS shares, peers.yaml, genesis.json, and a start-validators.sh script.

Deterministic Simulation

Section titled “Deterministic Simulation”

The devnet binary runs an in-memory consensus simulation — no network, fully deterministic:

Terminal window
# Default: 4 nodes, 200 steps
just devnet-small


# Chaos: 7 nodes, packet loss, latency
just devnet-chaos

Custom Parameters

Section titled “Custom Parameters”
Terminal window
cargo run --bin devnet -- \
  --nodes 4 \
  --steps 500 \
  --step-ms 10 \
  --link-latency-ms 5 \
  --link-jitter-ms 2 \
  --success-rate 1.0 \
  --state-backend cached-journal
ParameterEnv VarDefaultDescription
--nodesDEVNET_N4Number of validators
--stepsDEVNET_STEPS200Simulation steps
--step-msDEVNET_STEP_MS10Milliseconds per step
--link-latency-msDEVNET_LINK_LATENCY_MS5Baseline link latency
--link-jitter-msDEVNET_LINK_JITTER_MS2Latency jitter
--success-rateDEVNET_SUCCESS_RATE1.0Packet delivery rate (0.0-1.0)
--state-backendDEVNET_STATE_BACKENDcached-journalState backend
--report-every-stepsDEVNET_REPORT_EVERY_STEPS50Report interval

Chaos Testing

Section titled “Chaos Testing”

Simulate degraded network conditions:

Terminal window
DEVNET_SUCCESS_RATE=0.9 \
DEVNET_LINK_LATENCY_MS=25 \
DEVNET_LINK_JITTER_MS=10 \
cargo run --bin devnet -- --nodes 7 --steps 500

This tests consensus resilience under 10% packet loss and variable latency.

Interacting with a Running Node

Section titled “Interacting with a Running Node”

RPC Commands

Section titled “RPC Commands”
Terminal window
just rpc-status                          # Chain status
just rpc-manifest                        # Method IDL (JSON)
just rpc-idl                             # Raw IDL text
just rpc-account ADDR                    # Account balance/nonce
just rpc-predict-address DEPLOYER OFFSET # Predict deploy address
just rpc-tx-submit TX_HEX               # Submit signed transaction
just rpc-tx HASH                         # Look up transaction
just rpc-view CONTRACT CALLDATA GAS      # Read-only contract call
just rpc-call METHOD PARAMS              # Arbitrary RPC call

Direct curl

Section titled “Direct curl”
Terminal window
curl -s http://127.0.0.1:3030/v2/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"status","params":{}}' | jq .result

Smoke Tests

Section titled “Smoke Tests”
Terminal window
just agent-smoke   # Quick consensus + application tests
just agent-report  # Bundle metrics, health, and logs

Node Modes

Section titled “Node Modes”
ModeCommandDescription
Validatornode runFull consensus + RPC
RPC-onlynode rpcServes RPC from shared data-dir
Followernode followerP2P sync, no consensus participation

Useful Flags

Section titled “Useful Flags”
FlagDefaultDescription
--block-time-ms1000Block production interval
--archive-modeoffRetain all historical state
--prune-keep-epochs10Epochs to keep when pruning
--checkpoint-interval—Emit snapshots every N blocks
--produce-emptytrueProduce blocks with empty mempool

ashen-dev Tool

Section titled “ashen-dev Tool”

Thin wrapper for common dev workflows:

Terminal window
ashen-dev build [args]                   # Build contracts
ashen-dev test [args]                    # Run vm-runtime tests (default)
ashen-dev simulate --tx "0x..." --pretty # Simulate transaction via RPC

Environment Variables

Section titled “Environment Variables”
Terminal window
# RPC connection
NODE_RPC_URL=http://127.0.0.1:3030
NODE_AUTH_TOKEN=optional_bearer_token


# Node configuration
NODE_DATA_DIR=./node-data
NODE_LISTEN=127.0.0.1:3030
NODE_BLOCK_TIME_MS=1000


# Trace output (debugging)
ASHEN_TRACE_OUTPUT=1
ASHEN_TRACE_OUTPUT_DIR=target/feedback
Section titled “Related”