JAM Implementation in Java

A Java implementation of the JAM (Join-Accumulate Machine) blockchain protocol for the JAM Prize Competition.

Competition Disclosure

Third-Party Libraries Used (Allowed per Rule 1):

• SCALE Codec (io.jam.scale) - For SCALE serialization (vendored from PolkaJ)
  • Note: Vendored (copied) into src/main/java/io/jam/scale/ because not published to Maven Central
  • Source: https://github.com/emeraldpay/polkaj (Apache 2.0 License)
  • See src/main/java/io/emeraldpay/NOTICE.txt for full attribution
• Standard Testing (JUnit 5, AssertJ) - For unit testing
• Standard Logging (SLF4J, Logback) - For logging

All JAM-specific business logic is implemented from scratch per competition rules.

Current Status

Milestone 1 (M1 - IMPORTER) - In Progress

• ✅ Phase 1: Foundation (Project structure, data structures)
• 🚧 Phase 2: Serialization (SCALE codec)
• ⏳ Phase 3: Cryptography (Ed25519, Blake2b, Bandersnatch)

Prerequisites

• Java 17 or higher (Java 21 recommended)
• Maven 3.8+

Building

# Build the project
mvn clean install

# Run tests
mvn test

# Run specific test
mvn test -Dtest=CodecRoundTripTest

# Run with verbose output
mvn test -X

# Package as JAR
mvn package

Compiling

# Clean and compile the project
mvn clean compile

# Just compile (faster if you haven't cleaned)
mvn compile

Linting and Formatting

# Run linting
mvn spotless:check

# Run formatting
mvn spotless:apply

Running Tests

The test suite includes various test categories, including heavy conformance tests that require significant memory. You can control which tests run using Maven profiles or command-line options.

Using Maven Profiles

# Run all tests (default, requires 4GB heap)
mvn test

# Run only conformance tests
mvn test -Pconformance-only

# Run fast tests (excludes heavy AllTraceConformanceTest, requires 2GB heap)
mvn test -Pfast

# Run all tests except conformance tests (requires 2GB heap)
mvn test -Pno-conformance

# Run all tests including heavy conformance tests
mvn test -Pall

Including/Excluding Specific Test Classes

# Run only conformance tests (using includes)
mvn test -Dtest.includes="**/conformance/**/*Test.java"

# Exclude specific test class from command line
mvn test -Dtest.excludes="**/AllTraceConformanceTest.java"

# Exclude multiple test classes (comma-separated)
mvn test -Dtest.excludes="**/AllTraceConformanceTest.java,**/SafroleTransitionRealVrfTest.java"

# Exclude entire package
mvn test -Dtest.excludes="**/conformance/**/*Test.java"

Running Specific Tests

# Run a specific test class
mvn test -Dtest=HashTest

# Run multiple specific test classes
mvn test -Dtest=HashTest,BlockTest

# Run tests matching a pattern
mvn test -Dtest="**/storage/*Test"

Test Configuration

• Default: All tests run with 4GB heap (-Xmx4g)
• Fast profile: Excludes AllTraceConformanceTest (1000+ test cases), uses 2GB heap
• No-conformance profile: Excludes all conformance tests, uses 2GB heap

The heavy AllTraceConformanceTest processes 1000+ trace test vectors and requires significant memory. Use the fast profile for quicker test runs during development.

Quick Start

# Install Java 21 and Maven (Windows with Chocolatey)
choco install openjdk21 maven -y

# Build and test
cd jam
mvn clean test

Project Structure

jam/
├── src/main/java/io/jam/
│   ├── core/
│   │   ├── types/      # Primitive types (Hash, BlockNumber, etc.)
│   │   ├── block/      # Block structures (Header, Block, Extrinsic)
│   │   ├── state/      # State structures (ServiceAccount, ValidatorState)
│   │   └── codec/      # SCALE codec implementations
│   └── Main.java       # Entry point
└── src/test/java/io/jam/
    └── core/           # Unit tests

Architecture

This implementation follows the JAM specification (Graypaper v0.7.2):

• Immutable Data Structures: Using Java records for safety
• SCALE Codec: Polkadot-compatible serialization
• Clean Separation: Core types, serialization, and business logic decoupled

License

MIT License - See LICENSE file

References

• JAM Specification (Graypaper)
• JAM Prize Competition
• SCALE Codec Specification