FastRoll is a Rust implementation of a validator node for JAM (Join-Accumulate Machine), formally specified in the Graypaper.
- [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.
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. |
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. |
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.
| 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.
# 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, andconformancefor the fuzzing traces. - Groups in
IGNORED_TRACE_GROUPSof integration/build.rs only run with--run-ignored all. - Set
RUST_LOGto filter logs, and add--no-captureto print them (e.g.RUST_LOG="fr_node=debug").
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 10Each 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.
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
Polkadot: 134xm7pSX5oWibyckm4a2FXFqPumE1kfwxZNVLTHN28RQVTPKusama: HHwToJztPUFMp2qVerfbizz7wYSzu3q5HmSiCaq3AewmgUf
Apache-2.0. See LICENSE.