Skip to content
JAM Forge

JAM Protocol Specification

JAM Protocol Specification

Section titled “JAM Protocol Specification”

The JAM (Join-Accumulate Machine) protocol is defined in the Gray Paper, a comprehensive technical specification authored by Dr. Gavin Wood. JAM Forge implements this specification in Scala 3.

Gray Paper

Section titled “Gray Paper”

The official JAM Gray Paper can be found at graypaper.com.

Key Sections

Section titled “Key Sections”

The Gray Paper is organized into the following major sections:

  1. Introduction - Overview of JAM and its design goals
  2. State Model - JAM state representation and components
  3. State Transition Functions - Core protocol logic
  4. Work Packages - Computation execution model
  5. Block Structure - Block format and validation
  6. Consensus - Safrole consensus mechanism
  7. Cryptography - Cryptographic primitives used
  8. Networking - P2P communication protocol

State Transition Functions

Section titled “State Transition Functions”

JAM Forge implements all nine state transition functions specified in the Gray Paper:

1. Safrole

Section titled “1. Safrole”
  • Purpose: Block production and validator rotation
  • Implementation: io.forge.jam.protocol.safrole.SafroleTransition
  • Key Features:
    • Ticket accumulation and distribution
    • Epoch transitions
    • VRF-based block slot selection

2. Disputes

Section titled “2. Disputes”
  • Purpose: Handle validator disagreements
  • Implementation: io.forge.jam.protocol.disputes.DisputesTransition
  • Key Features:
    • Dispute creation and resolution
    • Validator punishment
    • Work report invalidation

3. Assurances

Section titled “3. Assurances”
  • Purpose: Data availability attestations
  • Implementation: io.forge.jam.protocol.assurances.AssurancesTransition
  • Key Features:
    • Availability announcements
    • Erasure coding verification
    • Chunk distribution tracking

4. Reports

Section titled “4. Reports”
  • Purpose: Work report processing
  • Implementation: io.forge.jam.protocol.reports.ReportsTransition
  • Key Features:
    • Work report validation
    • Guarantor signature verification
    • Report queue management

5. Accumulation

Section titled “5. Accumulation”
  • Purpose: Finalize work results
  • Implementation: io.forge.jam.protocol.accumulation.AccumulationTransition
  • Key Features:
    • Service state updates
    • Work result merging
    • Balance transfers

6. History

Section titled “6. History”
  • Purpose: Block ancestry tracking
  • Implementation: io.forge.jam.protocol.history.HistoryTransition
  • Key Features:
    • MMR (Merkle Mountain Range) updates
    • Historical block roots
    • Ancestor verification

7. Authorizations

Section titled “7. Authorizations”
  • Purpose: Service authorization management
  • Implementation: io.forge.jam.protocol.authorizations.AuthorizationsTransition
  • Key Features:
    • Authorization pool updates
    • Service permission grants
    • Authorization expiry

8. Preimages

Section titled “8. Preimages”
  • Purpose: Data storage and retrieval
  • Implementation: io.forge.jam.protocol.preimages.PreimagesTransition
  • Key Features:
    • Preimage registration
    • Data availability guarantees
    • Storage fee accounting

9. Statistics

Section titled “9. Statistics”
  • Purpose: Validator performance metrics
  • Implementation: io.forge.jam.protocol.statistics.StatisticsTransition
  • Key Features:
    • Validator statistics updates
    • Performance tracking
    • Reward calculations

Block Structure

Section titled “Block Structure”

JAM blocks consist of:

Section titled “Header”
  • Parent Hash: Hash of the previous block
  • Prior State Root: Root hash of state before block execution
  • Extrinsic Hash: Hash of the extrinsic data
  • Slot: Time slot identifier
  • Epoch: Current epoch number
  • Seal: Block author’s signature

Extrinsic

Section titled “Extrinsic”
  • Tickets: Safrole tickets for next epoch
  • Preimages: New preimage data
  • Assurances: Availability assurances
  • Reports: Work reports from guarantors
  • Disputes: Dispute judgments and culprits
  • Authorizations: Service authorizations

Conformance

Section titled “Conformance”

JAM Forge maintains strict conformance with the Gray Paper through:

  1. Test Vectors: Official test vectors from jamtestvectors repository
  2. Conformance Server: Unix socket server for cross-implementation validation
  3. Fuzzing: Automated fuzzing with jam-conformance tools
  4. Continuous Testing: CI/CD pipeline running conformance tests

See Conformance Testing for details.

Implementation Notes

Section titled “Implementation Notes”

Scala-Specific Adaptations

Section titled “Scala-Specific Adaptations”

While JAM Forge strictly follows the Gray Paper specification, some Scala-specific adaptations are made:

  • Type Classes: Used for encoding/decoding instead of explicit functions
  • Opaque Types: Zero-cost wrappers for domain primitives
  • GADTs: Type-safe instruction encoding in PVM
  • Lenses: Monocle lenses for state updates

Native Library Integration

Section titled “Native Library Integration”

JAM Forge uses native Rust libraries for performance-critical operations:

  • Bandersnatch VRF: Ring VRF signatures
  • Ed25519: Signature verification
  • Erasure Coding: Reed-Solomon encoding/decoding

This approach:

  • Avoids reimplementation bugs in complex cryptography
  • Leverages audited Rust implementations
  • Provides near-native performance

Resources

Section titled “Resources”

Differences from Other Implementations

Section titled “Differences from Other Implementations”

JAM Forge differs from other JAM implementations in:

  1. Language: Scala 3 vs. Rust/C++/Go
  2. Paradigm: Functional-first vs. imperative
  3. Type System: Advanced type-level programming
  4. Code Size: ~70% fewer lines through FP abstractions

However, all implementations must conform to the same Gray Paper specification and pass the same test vectors.