JAMZIG - M1 Release

JAMZIG is a Zig-based implementation of a JAM (Join-Accumulate Machine) node. JAM is a next-generation blockchain protocol designed as a potential successor to the Polkadot Relay Chain, introducing a novel computational model that addresses the size-coherency antagonism in distributed systems.

JamZig account: 14T1UcnoaMND24ubV86FCT4YxJ8q5CKVG7winwZ7umAit8g2

What is JAM?

JAM is a decentralized protocol that combines the best of both worlds:

1. Global singleton permissionless object environment (like Ethereum's smart contracts)
2. Secure sideband computation parallelized over a scalable node network (like Polkadot's approach)

The protocol uses a collect-refine-join-accumulate model that enables massive parallelization while maintaining state coherency. JAM's key innovation is solving the size-coherency antagonism through pipelined computation, separating scalable async work (Refine) from coherent sync work (Accumulate).

Project Architecture

Core Components

• src/pvm/ - Polka Virtual Machine (RISC-V based VM with gas metering)
• src/state_*/ - State management, encoding/decoding, and merklization
• src/safrole/ - Safrole consensus mechanism for block production
• src/net/ - QUIC-based networking with JAM Simple Networking Protocol (JAMSNP)
• src/crypto/ - Cryptographic primitives (Rust FFI bindings)

Development Tools

• src/repl/ - Interactive REPL for JAM system interaction
• src/jamtestvectors/ - Comprehensive test vectors against reference implementations
• src/pvm_fuzzer.zig - PVM fuzzing tool for testing
• src/jamtestnet_export.zig - Testnet data export utilities

Key Features

• 17-segment state partitioning for parallel computation (α, β, γ, δ, etc.)
• Service-based architecture replacing traditional account model
• Crypto-economic validation through guaranteeing, assuring, and auditing
• Bandersnatch Ring VRF for validator selection
• Erasure coding for data availability

Building and Running

Prerequisites

• Zig 0.14.0
• Rust toolchain (beta channel)
• Cargo for Rust FFI dependencies

Testing

JAMZIG includes comprehensive testing infrastructure:

• Unit Tests: Implementation-specific tests (zig build test)
• Test Vectors: Official JAM specification compliance tests (zig build test-vectors)
  • Validates against reference test vectors from the JAM community
  • Tests both tiny (test) and full (production) parameter sets
  • Covers all major components: accumulate, safrole, assurances, etc.
  • Includes W3F trace tests for block sequence validation
• JAM Conformance: Community-validated traces for cross-implementation compatibility
  • Tests against the jam-conformance/ archive of community-validated block traces
  • Ensures compatibility across different JAM implementations

The dedicated test-vectors command provides faster compilation by building only test vector code (~25 files) instead of the entire test suite, making it ideal for continuous compliance checking.

Test Runner Options

The test runner supports flags passed after --:

• --progress: Show colored progress output for each test as it runs
• --nocapture: Don't capture stderr - shows all debug output during test execution (essential for debugging failures)
• --exit-on-fail: Exit immediately on first test failure
• --log-progress: Log detailed test progress to test_progress.log file (includes timing, pass/fail status, summary stats)

Commands

# Build the project
zig build

# Run tests
zig build test

# Run specific test
zig build test -Dtest-filter=<test_name>

# Run tests with progress output
zig build test -Dtest-filter=<test_name> -- --progress

# Run JAM test vectors for specification compliance
zig build test-vectors

# Run only tiny parameter test vectors
zig build test-vectors -Dtest-filter="tiny"

# Run only full parameter test vectors
zig build test-vectors -Dtest-filter="full"

# Run W3F trace tests (block sequence validation)
zig build test-vectors -Dtest-filter="w3f:traces"

# JAM Conformance: View compliance summary
zig build test -Dtest-filter=jam-conformance:summary -- --nocapture

# JAM Conformance: Validate against specific archive
JAM_CONFORMANCE_ARCHIVE=<timestamp> zig build test -Dtest-filter="jam-conformance:archive" -- --nocapture

# Run the node
zig build run

# Run REPL
zig build run

# Run PVM fuzzer
zig build pvm_fuzz && zig build run -- pvm_fuzz

For more information about JAM and JAMZIG, visit: https://jamzig.dev or see the JAM Gray Paper: https://graypaper.com.