JAM Types

Python implementation of types and codecs for the JAM Protocol.

This package provides SCALE codec implementations for all JAM protocol data structures, including blocks, work packages, tickets, state transitions, and cryptographic primitives.

JAM Codec

The JAM codec is derived from SCALE (Simple Concatenated Aggregate Little-Endian) with one key difference: compact integer encoding. While SCALE uses a prefix-based compact encoding, JAM codec implements a different approach for compact integer representation as specified in the JAM protocol.

All other encoding rules (structs, enums, vectors, fixed arrays, etc.) remain compatible with SCALE.

Features

• Complete type definitions for JAM protocol structures
• JAM codec encoding/decoding support (SCALE-derived with custom compact integers)
• Multiple specification profiles (full/tiny)
• CLI tools for decoding and analyzing JAM data
• Fuzzer support for protocol testing
• Type introspection utilities

Installation

Direct Installation

Install from source:

pip install .

Or install in development mode:

pip install -e .

Using install.sh Script

Alternatively, use the provided installation script that automatically sets up a dedicated virtual environment:

./install.sh

The script will:

• Create a virtual environment in $HOME/.local/pip/jam-types (or $PIP_LOCAL_VENV/jam-types if set)
• Install the package and its dependencies in isolation
• Provide activation instructions for the environment

This approach differs from direct pip installation by automatically managing a separate virtual environment, preventing conflicts with system packages or other Python projects.

Usage

As a Library

from jam_types import Block, WorkReport, ScaleBytes
from jam_types.spec import set_spec

# Use tiny spec (6 validators, 12 epoch length)
set_spec('tiny')

# Decode a block from binary data
blob = open('block.bin', 'rb').read()
scale_bytes = ScaleBytes(blob)
block = Block(data=scale_bytes)
decoded = block.decode()

# Access block fields
print(decoded['header'])
print(decoded['extrinsic'])

CLI Tools

jam-decode

Decode binary JAM data to JSON:

# Decode from file (type inferred from filename)
jam-decode -f report.bin

# Decode with explicit type
jam-decode -f data.bin -t Block

# Decode hex string directly
jam-decode -d "0x1234567890abcdef" -t Header

# Use specific spec
jam-decode -f block.bin -t Block --spec tiny

Supported types include:

• Protocol types: Block, Header, WorkReport, WorkPackage, etc.
• Fuzzer types: Genesis, TraceStep, Report, Message, WireMessage
• Any type from jam_types modules (supports both CamelCase and snake_case)

jam-diff

Compare two decoded structures:

# Compare two files
jam-diff -f block1.bin -f block2.bin -t Block

# Compare hex data
jam-diff -d "0x1234" -d "0x5678" -t Header

# Mix files and hex data
jam-diff -f genesis.bin -d "0xabcd" -t genesis

# Verbose mode (show full content with inline markers)
jam-diff -f data1.bin -f data2.bin -t WorkReport -v

jam-types-info

Display type and spec information:

# Show current spec
jam-types-info

# List all available types
jam-types-info --types

# Show structure of specific type
jam-types-info --type Block

# Show spec details
jam-types-info --spec full

Specifications

JAM Types supports multiple protocol specifications:

Full Spec

• 1023 validators
• 600 epoch length
• 16 max tickets per block

Tiny Spec

• 6 validators
• 12 epoch length
• 3 max tickets per block

Set the spec programmatically or via environment variable:

from jam_types.spec import set_spec
set_spec('tiny')

export JAM_SPEC=full

Development

Dependencies

This package depends on a custom SCALE codec implementation:

• jam-codec-py

References

• JAM Protocol Specification