Skip to content
fastroll-jamPublic

About

Join-Accumulate Machine Rust Client

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Latest commit

 

History

807 Commits

Folders and files

Repository files navigation

FastRoll: JAM validator client

License CI codecov

About

FastRoll is a Rust implementation of a validator node for JAM (Join-Accumulate Machine), formally specified in the Graypaper.

Status

  • [2026-09-27] 🏆 Awarded JAM Prize Milestone 1 (IMPORTER).
  • [2026-05-25] 🎉 Passed Milestone 1 fuzzing, successfully importing 1.3 million blocks generated by the fuzzer.
  • Successfully imports blocks and yields valid post-states as specified in the Graypaper (supported version).
  • WIP: Block authoring, auditing, networking, and performance optimization.

Build and Run

The fastroll binary currently runs as a fuzz target of the fuzz protocol. The JAM node runner is under active development and requires dev accounts.

Building requires the stable Rust toolchain and Clang.

# Build
cargo build --features "tiny,fuzz"

# Run the fuzz target on its default socket
cargo run --features "tiny,fuzz" -- fuzz --socket "/tmp/jam_target.sock"
Feature Purpose
tiny Selects the tiny chain spec.
full Selects the full chain spec, also used when tiny is off.
fuzz Skips timeslot validation against the wall clock.

Run the Docker image

Each release publishes an image with the tiny and full fuzz targets for linux/amd64:

docker run --rm \
  -v /tmp/fastroll:/fastroll \
  -e JAM_FUZZ=1 \
  -e JAM_FUZZ_SPEC=tiny \
  -e JAM_FUZZ_DATA_PATH=/fastroll/data \
  -e JAM_FUZZ_SOCK_PATH=/fastroll/jam_target.sock \
  ghcr.io/fastroll-jam/fastroll:latest
Variable Description
JAM_FUZZ Runs the fuzz target when defined. Otherwise the container passes its arguments to the tiny binary.
JAM_FUZZ_SPEC Chain spec, tiny or full.
JAM_FUZZ_DATA_PATH Data directory, created at startup.
JAM_FUZZ_SOCK_PATH Unix socket path for the fuzzer. Mount its directory to reach it from the host.
JAM_FUZZ_LOG_LEVEL Optional log level, error, warn, info, debug or trace. An explicit RUST_LOG takes precedence.

Conformance Testing

Test vectors

Test vectors take about 2 GiB and are pinned as Git submodules under integration/. Set them up before running the tests:

./scripts/setup-test-vectors.sh
Option Purpose
--verify Checks an existing checkout without downloading anything.
--force Recreates all vector submodules, discarding their local changes.

Avoid git submodule update --remote, because upstream branches may target newer Graypaper versions.

Test suites

Suite Vectors Test cases Harness
STF jam-test-vectors stf stf stf_harness.rs
PVM jamtestvectors pvm/programs pvm.rs pvm_harness.rs
Block import jam-test-vectors traces block_importer.rs importer_harness.rs
Block import with simple forks jam-test-vectors traces/fuzzy*, jam-fuzzing fuzz-reports/<gp-version>/traces block_importer.rs fuzzer.rs
Codec, erasure, shuffle jam-test-vectors codec, erasure, shuffle codec.rs, erasure.rs, shuffle.rs
Ed25519 jam-crypto ed25519 ed25519_consensus.rs

integration/build.rs generates the PVM and block import test cases.

Running tests

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

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

# Block import tests of one group
cargo nextest run block_import_safrole_ --no-fail-fast --features "tiny,fuzz" --release
  • Block import groups: fallback, safrole, storage, storage_light, preimages, preimages_light, fuzzy, fuzzy_light, and conformance for the fuzzing traces.
  • Groups in IGNORED_TRACE_GROUPS of integration/build.rs only run with --run-ignored all.
  • Set RUST_LOG to filter logs, and add --no-capture to print them (e.g. RUST_LOG="fr_node=debug").

Benchmarking

Run a per-block import benchmark over a jam-test-vectors trace group, selected by TRACE_KIND:

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

Each run writes total_avg_ms and per_block_avg_ms to node-bench/reports/<trace_label>_<unix_timestamp>.log. The averages include warm-up iterations and exclude handshake and initialization time.

Fuzzing performance across implementations is available in the reports and on the dashboard.

Repository Map

fastroll/
├── block/                Block and extrinsic types, and block stores
├── cli/                  fastroll CLI binary
├── clock/                Time provider and clock utilities
├── codec/                Codec crates
│   ├── fr-codec/         JAM codec
│   └── fr-codec-derive/  Derive macro for the JAM codec
├── common/               Shared types, constants, logging and 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
├── docker/               Entrypoint of the published container image
├── extrinsics/           Extrinsic validation, pool and guarantor assignment
├── fuzz/                 Fuzz target and trace-replay fuzzer
├── 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 crates
│   ├── pvm-core/         VM architectural state, interpreter, program loader and instructions
│   ├── pvm-host/         Host functions and partial state
│   ├── pvm-interface/    Common PVM invocation (Ψ_M), program cache and host-call dispatch
│   ├── pvm-invocation/   PVM invocation entry points (is_authorized, refine, accumulate)
│   └── pvm-types/        Common PVM data types
├── scripts/              Flamegraph, test-vector setup and release-note scripts
├── state/                Global state types, stores, state cache, manager and merkle interfaces
│   └── state-merkle-v2/  Merkle trie and its store
├── storage/              Node storage over state, header, extrinsic and post-state-root stores
├── test-utils/           Test harnesses and helpers
│   └── asn-types/        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.

About

Join-Accumulate Machine Rust Client

Topics

Resources

Stars

9 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages