Skip to main content

Welcome to Tessera JAM Documentation

Tessera is a clean-room Python implementation of the JAM protocol, a coherent blockchain protocol developed as the next evolution of Polkadot.

What is JAM?​

JAM (from the collect/refine/Join/Accumulate/Marshall model) is a complete blockchain protocol that unifies computation, state transition, and consensus. Unlike traditional smart contract platforms, JAM introduces a novel computational model that achieves scalability while maintaining coherence.

Key Characteristics​

  • Resilient: Highly resistant to being stopped, corrupted, or censored
  • General-Purpose: Turing-complete computation via the Polkadot Virtual Machine (PVM)
  • Scalable: Pipeline architecture separating in-core (parallel) and on-chain (coherent) computation
  • Coherent: Deterministic state transitions with bounded asynchrony

Quick Start​

New to Tessera? Start here:

  • Getting Started - Install and run Tessera Node
  • Download pre-built binaries or build from source
  • Configure your node and connect to the network

The JAM Model​

JAM's architecture centers on three key components:

1. Computation Pipeline​

JAM separates computation into two stages:

In-Core (Off-Chain):

  • Validators execute work-packages in parallel
  • High scalability through sharding across 341 cores
  • Results guaranteed by assigned validators

On-Chain (Accumulation):

  • Sequential integration of work-results into service state
  • Fully synchronous and coherent
  • PVM execution of service accumulation logic

2. State Structure​

JAM state is partitioned into focused components:

  • δ (Services): Service accounts and their state (analogous to smart contracts)
  • γ (SAFROLE): Block production consensus state
  • κ, λ, ι: Current, previous, and pending validator sets
  • ρ (Reports): Pending work-reports awaiting availability
  • α (Authorization): Core authorization pools
  • ψ (Disputes): Judgments and offender records
  • β (Recent History): Block history and state commitments
  • ω (Ready Queue): Work-reports ready for accumulation

3. Dual Consensus​

SAFROLE (Block Production):

  • Ticket-based validator selection using Ring-VRF
  • Anonymous block authoring
  • Deterministic seal keys per timeslot (6-second slots)
  • Entropy generation for protocol randomness

GRANDPA (Finality):

  • Byzantine fault-tolerant finality gadget
  • Finalizes blocks with high confidence
  • Prevents long-range attacks
  • Separate from block production

Core Protocol Flow​

  1. Work-Package Submission: Services submit work-packages to cores
  2. Guaranteeing: Assigned validators execute work, create work-reports
  3. Availability: Validators erasure-code and distribute data, submit assurances
  4. Auditing: Other validators verify work-reports (off-chain)
  5. Accumulation: Available work-reports integrated into service state on-chain
  6. Finality: GRANDPA finalizes blocks

Documentation Structure​

This documentation is organized into six main sections:

1. Block​

Block handling, import validation, production mechanics, fork management, and GRANDPA finality integration.

Topics: Block structure, header validation, extrinsics, best-chain selection, fork resolution

2. State Transitions​

All state transition functions (ζ) following the Gray Paper specification.

Topics: SAFROLE, recent history, authorization, assurances, disputes, reports, accumulation, preimages, statistics

3. PVM​

Polkadot Virtual Machine integration and host call implementations.

Topics: Host calls, instruction sets, gas metering, memory management, recompilation

4. Storage​

Data availability, erasure coding, and chunk distribution.

Topics: Sharding across validators, segment distribution, network storage patterns

5. Networking​

JAM Simple Networking Protocol (JAMNP-S) and P2P communication.

Topics: Protocol specification, QUIC implementation, peer management, message propagation

6. Auditing​

Off-chain validation engine, judgment creation, and audit assignment.

Topics: Audit engine, tranche management, work-report verification, judgment signatures

Tessera Implementation​

Tessera is built in Python 3.12 with a focus on correctness and clarity:

Architecture:

  • Clean-room implementation from Gray Paper specification
  • Modular design mirroring protocol structure
  • Comprehensive test coverage including W3F test vectors

Components:

  • State transition functions (ζ)
  • Block import and validation
  • SAFROLE and GRANDPA consensus
  • PVM integration (via tsrkit-pvm)
  • Networking layer (JAMNP-S over QUIC)
  • Auditing engine
  • RPC API for external interactions

Modes:

  • Validator Node: Full participation (block production, auditing, guaranteeing)
  • Builder Node: Block building without validator keys
  • RPC Node: JSON-RPC interface for queries

State Transition Function​

At its core, JAM is defined by the state-transition function:

σ' = ζ(σ, B)

Where:

  • σ is the prior state
  • σ' is the posterior state
  • B is a valid block
  • ζ is the block-level state-transition function

The block B consists of:

  • Header (H): Metadata, cryptographic commitments, seal
  • Extrinsic (E): External data (tickets, guarantees, assurances, disputes, preimages)

Time Model​

JAM uses a common clock assumption with 6-second timeslots:

  • JAM Common Era: Begins at 1200 UTC on January 1, 2025
  • Epoch: 600 timeslots (1 hour)
  • Slot: Minimum time between blocks (6 seconds)

Validators are rotated per epoch, and seal keys are determined per slot.

Next Steps​

References​

  • Gray Paper: https://graypaper.com - Complete JAM protocol specification
  • Tessera Repository: github.com/Chainscore/tessera
  • W3F Test Vectors: Protocol conformance test suite
  • RFC 31 (CoreJam): Original proposal for the collect/refine/join/accumulate model

Welcome to Tessera JAM Documentation

Tessera is a performant, open-source, clean-room implementation of the JAM protocol as defined in the Gray Paper.

Quick Start​

New to Tessera? Start here:

  • Getting Started - Install and run Tessera Node
  • Installation Guide - Download binaries, extract, and run your first node
  • Basic Configuration - Environment setup and command-line options

Next Steps​

Architecture Overview​

Tessera is designed with modularity in mind:

  • Core Protocol: JAM specification implementation
  • PVM: Polkadot Virtual Machine integration
  • Networking: P2P communication layer
  • Consensus: GRANDPA and SAFROLE support

Quick navigation​