Feature Flags

This document describes the compile-time feature flags available in the chain codebase, their behaviors, and valid combinations.

Feature Flag Matrix

Flag	Default	Purpose	Dependencies	Incompatible With
std	on	Enables prometheus metrics, QMDB state backend, persistent storage	dep:prometheus-client	(none)
tui	on	Enables interactive terminal UI explorer	ratatui, crossterm, directories, toml, flume	(none)
vm-tiering	off	Enables JIT/AOT execution tiers and persistent code cache	dep:vm-codecache	(none)
das	off	Enables Data Availability Sampling for light clients	(none)	(none)
qmdb-shadow	off	Enables shadow writes to QMDB for testing/migration	(none)	(none)

Feature Behaviors

std (default: on)

When enabled:

• Prometheus metrics are collected and exposed via /metrics endpoint
• QMDB state backend is available for persistent authenticated state
• Journal-backed storage backends are available

When disabled:

• In-memory state backend only
• No metrics collection
• Reduced binary size for embedded/wasm targets

tui (default: on)

When enabled:

• Interactive terminal UI via ashen tui command
• Block explorer, account viewer, transaction list
• Cost-aware query previews and filtering

When disabled:

• CLI-only operation via ashen commands
• Smaller binary size

vm-tiering (default: off)

When enabled:

• JIT tier: Basic-block predecode support with inline caches
• AOT tier: Eager predecode support when cached artifacts exist
• Tiered execution path with an in-memory code cache
• Pre-charge gas per basic block (faster than per-instruction)

When disabled:

• Interpreter-only execution (reference implementation)
• Per-instruction gas charging (authoritative for conformance)

Note: Interpreter is always available and serves as the semantic authority for VM conformance testing. The node does not currently wire automatic hot-code promotion or disk persistence.

das (default: off)

When enabled:

• Light clients perform Data Availability Sampling before accepting blocks
• Reed-Solomon erasure coding verification
• LightClientError::DataUnavailable and LightClientError::DasTimeout errors exposed
• ChunkGossip P2P integration for sample fetching

When disabled:

• Light clients trust block availability from finality proofs alone
• Smaller binary, lower verification overhead for non-validator nodes

qmdb-shadow (default: off)

When enabled:

• All state writes are shadowed to QMDB in addition to primary backend
• Useful for migration testing and correctness validation
• Additional I/O overhead

When disabled:

• Single state backend path

Build Profiles

Minimal (Interpreter-only)

Smallest binary, no optional features:

cargo build --no-default-features

Capabilities: Core consensus + execution with interpreter-only VM, in-memory state.

Standard (Default)

Balanced build for development and light operation:

cargo build
# Equivalent to: cargo build --features std,tui

Capabilities: Full node with TUI, metrics, QMDB storage.

Full Validator

All features for production validators:

cargo build --features std,tui,vm-tiering,das

Capabilities: JIT/AOT execution tiers, DAS verification, full observability.

Light Client

Minimal for light client verification with DAS:

cargo build --no-default-features --features das

Capabilities: Light client verification with data availability sampling.

Runtime Validation

The node binary validates feature flag combinations at startup. Incompatible configurations will produce clear error messages.

Current Validations

1. No incompatible flags: All flags are currently compatible with each other.

2. Feature-dependent functionality: Some functionality is only available when its flag is enabled:

   • vm-tiering: Code cache statistics, tier promotion, AOT compilation
   • das: Light client DAS verification
   • std: QMDB state backend, metrics endpoints

Planned Validations

Future versions may add startup checks for:

• Hardware requirements for vm-tiering (memory, CPU)
• Network requirements for das (sampling connectivity)

Conditional Compilation Patterns

Feature flags are used throughout the codebase via #[cfg(feature = "...")]:

// Conditional import
#[cfg(feature = "vm-tiering")]
use vm_codecache::{CodeCache, EvictionConfig};

// Conditional field
struct ExecutionEngine {
    #[cfg(feature = "vm-tiering")]
    pub vm_cache: CodeCache,
}

// Conditional code path
#[cfg(feature = "das")]
{
    verify_availability(&chunks, &config).await?;
}

Migration Guide

Enabling VM Tiering

1. Add --features vm-tiering to your build command
2. Set ASHEN_VM_TIERING=1 at runtime to activate the tiered execution path
3. Expect an interpreter-first warmup; JIT/AOT are only used when cached artifacts exist
4. Monitor cache metrics via /metrics (see code_cache_entries_by_tier)

Enabling DAS

1. Add --features das to your build command
2. Ensure P2P connectivity for chunk sampling
3. Configure sampling parameters in node config
4. Light clients will now verify data availability before accepting blocks

FAQ

Q: Do I need vm-tiering for production?

A: Not required. The interpreter is fully functional and serves as the semantic authority. Enable vm-tiering for better throughput on compute-heavy workloads.

Q: Can I run a validator without das?

A: Yes. DAS is primarily for light clients. Validators receive full blocks via consensus and don’t need DAS for their own verification.

Q: Why is std a default feature?

A: Most deployments want metrics and persistent storage. Disable it only for embedded/wasm targets or minimal testing.