FastRoll: JAM validator client

About FastRoll

FastRoll is a Rust implementation of the JAM (Join-Accumulate Machine) validator client.

The primary goal is strict conformance with the Graypaper formal specification (supported version).

Status

• Successfully imports blocks and yields valid post-states as specified in Graypaper.
• Passes all public test vectors and available block fuzz traces. See below for details.
• Ready for JAM prize Milestone #1 evaluation:
  • Milestone #1 delivery
  • Conformance testing
• Block authoring, auditing, and networking are in progress.

Supported Chain Specs

• Tiny / Full

Build and Run

Currently, the FastRoll binary focuses exclusively on fuzz-target functionality as specified in the fuzz protocol.

The JAM node runner is under active development and currently requires dev accounts to run.

Prerequisites

• Rust toolchain (stable, edition 2021)
• Git submodules for test vectors (see below)

Rust features

• tiny feature selects tiny chain-spec parameters for conformance testing.
• fuzz feature skips timeslot index validation against wall clock time for fuzzing.

Build the CLI

cargo build --features "tiny,fuzz"

Run the CLI (fuzz target)

cargo run --features "tiny,fuzz" -- fuzz --socket "/tmp/jam_target.sock"

Defaults

• RocksDB path: ./.rocksdb
• Fuzzer socket: /tmp/jam_target.sock

Conformance Testing

Test vector submodules

FastRoll relies on external test-vector repos as Git submodules:

• integration/jamtestvectors: official W3F test vectors
• integration/jamtestvectors-polkajam: test vectors release candidate
• integration/jamtestvectors-pvm: PVM/RISC-V test vectors
• integration/jam-conformance: fuzzing traces

Initialize them with:

git submodule update --init --recursive

State Transition Function (STF) tests

• Vectors: integration/jamtestvectors/stf
• Harness: test-utils/src/stf_harness.rs
• Test Cases: integration/tests/stf

PVM/RISC-V tests

• Vectors: integration/jamtestvectors-pvm/pvm/programs
• Harness: test-utils/src/pvm_harness.rs
• Build Script: integration/build.rs
• Test Cases: integration/tests/pvm.rs

Block import tests

• Vectors: integration/jamtestvectors-polkajam/traces
• Harness: test-utils/src/importer_harness.rs
• Build Script: integration/build.rs
• Test Cases: integration/tests/block_importer.rs

Block import tests (simple forks)

• Vectors:
  • integration/jamtestvectors-polkajam/traces: fuzzy blocks
  • integration/jam-conformance/fuzz-reports/0.7.2/traces: fuzzing traces
• Harness: fuzz/src/fuzzer.rs
• Build Script: integration/build.rs
• Test Cases: integration/tests/block_importer.rs

Running tests

• Note: Git submodule initialization is required. See Test vector submodules section above.

# Run all tests:
cargo nextest run --workspace --no-fail-fast --features "tiny,fuzz" --release

# Run all block import tests:
cargo nextest run block_import_ --no-fail-fast --features "tiny,fuzz" --release

# Run block import tests for a specific group:
cargo nextest run block_import_storage_ --no-fail-fast --features "tiny,fuzz" --release

# Run block import tests for fuzzing traces:
cargo nextest run block_import_conformance_ --no-fail-fast --features "tiny,fuzz" --release

• fuzz feature is required for fuzzing trace block imports.
• Available block groups: fallback, safrole, storage, storage_light, preimages, preimages_light, fuzzy, fuzzy_light.
• RUST_LOG env variable can be used for tracing test run and filter logs.
  • e.g. RUST_LOG="fr_node=debug" cargo nextest run block_import_storage_00000001 --features "tiny,fuzz" --release --no-capture

Benchmarking

Block import benchmark

Run a per-block import benchmark over a trace directory:

TRACE_KIND=storage cargo bench -p fr-node-bench --bench block_importer --features tiny -- --sample-size 10 --measurement-time 10

• TRACE_KIND selects a directory under integration/jamtestvectors-polkajam/traces/ (e.g., storage).
• --sample-size sets the number of measurement samples.
• --measurement-time is the total target time for the measurement phase.
• A report file is written per run to node-bench/reports/<trace_label>_<unix_timestamp>.log.
• The report includes total_avg_ms (average per trace run, from per-block timings) and per_block_avg_ms; handshake/init time is not included in these averages.
• Warm-up iterations are included in the report aggregates; set --warm-up-time to adjust warm-up impact.

Fuzzing benchmark

Community fuzzing performance reports across implementations are available at:

• Performance Reports
• Performance Dashboard

Repository Map

Top-level directories and their roles:

• block/: Block common types and stores.
• cli/: fastroll CLI binary.
• clock/: Time provider and clock utilities.
• codec/: JAM codec (fr-codec) and derive macro (fr-codec-derive).
• common/: Shared types, constants, logging, utilities.
  • erasure-coding/: Reed-solomon erasure codec for data availability.
  • limited-vec/: Bounded vector types.
• config/: Configuration and defaults.
• crypto/: Hashing, signatures, VRF, and signing key utilities.
• db/: RocksDB-backed storage primitives.
• extrinsics/: Extrinsic types and validation.
• fuzz/: Fuzz harness and integration with the block importer.
• integration/: Integration test crate and test-vector submodules.
• merkle/: Common Merkle-related utilities.
• network/: QUIC-based networking stack.
• node/: Node runtime, block importer, and service wiring.
• node-bench/: Criterion benchmarks.
• pvm/: PVM sub-crates:
  • pvm-core/: VM execution primitives; architectural state, interpreter, program loader, instructions.
  • pvm-host/: Host functions, partial state.
  • pvm-interface/: Host/guest interface types.
  • pvm-invocation/: PVM invocation entry-points (is_authorized, refine, accumulate).
  • pvm-types/: Common PVM data types.
• scripts/: Utility scripts (e.g., flamegraph generation).
• state/: Global state types, stores, state cache, manager, and merkle interfaces.
  • state-merkle-v2/: Current merkle trie and store implementation.
  • state-merkle/: Deprecated merkle trie (kept for reference).
• storage/: Node storage layer wiring different store types: state, merkle, header, extrinsics, etc.
• test-utils/: Test harnesses and helpers.
  • asn-types/: Type conversion between Rust and ASN types for test vectors (JSON support)
• transition/: State transition functions (STFs) and state prediction helpers.

Team Account IDs

• Polkadot: 134xm7pSX5oWibyckm4a2FXFqPumE1kfwxZNVLTHN28RQVTP
• Kusama: HHwToJztPUFMp2qVerfbizz7wYSzu3q5HmSiCaq3AewmgUf

License

Apache-2.0. See LICENSE.