Core Types

Core Types

JAM Forge defines all protocol types in the jam-core module, providing type-safe representations of JAM protocol entities.

Block Types

Block

Complete JAM block containing header and extrinsic.

case class Block(
  header: Header,
  extrinsic: Extrinsic
)

Package: io.forge.jam.core.types

Header

Block header with metadata and seal.

case class Header(
  parentHash: Hash,           // Hash of parent block
  priorStateRoot: Hash,       // State root before this block
  extrinsicHash: Hash,        // Hash of extrinsic data
  slot: TimeSlot,             // Time slot identifier
  epoch: EpochNumber,         // Current epoch
  winningTickets: Seq[Ticket],// Winning tickets for block production
  offenders: Seq[Offender],   // Validator offenders to punish
  seal: Seal                  // Block author's signature
)

Extrinsic

Block body containing transactions and data.

case class Extrinsic(
  tickets: Tickets,           // Safrole tickets
  preimages: Preimages,       // Preimage data
  assurances: Assurances,     // Availability assurances
  reports: Reports,           // Work reports
  disputes: Disputes,         // Dispute judgments
  authorizations: Authorizations // Service authorizations
)

State Types

FullJamState

Complete JAM state representation.

case class FullJamState(
  // Core chain state
  bestBlock: Hash,
  finalizedBlock: Hash,
  currentSlot: TimeSlot,
  currentEpoch: EpochNumber,

  // Validator state
  validators: Vector[ValidatorKey],
  validatorStats: ValidatorStatistics,

  // Service state
  services: Map[ServiceId, ServiceAccount],
  authPool: AuthorizationPool,

  // Data availability
  preimages: PreimageStore,
  availabilityQueue: AvailabilityQueue,

  // Pending work
  workReports: WorkReportQueue,
  disputes: DisputeState,

  // History
  mmrRoot: Hash,
  blockHistory: Vector[Hash]
)

Work Package Types

WorkPackage

Work to be executed by validators.

case class WorkPackage(
  authorizationToken: Hash,   // Authorization proof
  code: Bytes,                // PVM bytecode to execute
  items: Vector[WorkItem],    // Individual work items
  authorizationOutput: Hash   // Authorization for output
)

WorkItem

Individual computation task within a work package.

case class WorkItem(
  serviceId: ServiceId,       // Target service
  code: Bytes,                // Item-specific code
  gas: Gas,                   // Gas limit
  input: Bytes                // Input data
)

WorkReport

Result of work package execution.

case class WorkReport(
  packageHash: Hash,          // Hash of work package
  contextHash: Hash,          // Execution context
  coreIndex: CoreIndex,       // Core that executed
  authorizationOutput: Hash,  // Authorization output
  output: Bytes,              // Execution output
  results: Vector[WorkResult] // Per-item results
)

WorkResult

Result of individual work item execution.

case class WorkResult(
  serviceId: ServiceId,       // Service that processed
  output: Hash,               // Output hash
  gas: Gas,                   // Gas consumed
  payload: Bytes              // Result payload
)

Service Types

ServiceAccount

Service account state.

case class ServiceAccount(
  code: Hash,                 // Service code hash
  balance: Balance,           // Service balance
  storage: Hash,              // Storage root
  preimages: Set[Hash],       // Required preimages
  thresholds: Thresholds      // Gas thresholds
)

Thresholds

Gas limits for service operations.

case class Thresholds(
  gas: Gas,                   // Normal gas limit
  minGas: Gas                 // Minimum gas limit
)

Validator Types

ValidatorKey

Validator public key and metadata.

case class ValidatorKey(
  ed25519: Ed25519PublicKey,  // Ed25519 key for signing
  bandersnatch: BandersnatchPublicKey, // Bandersnatch key for VRF
  metadata: Bytes             // Additional metadata
)

ValidatorStatistics

Performance statistics for validators.

case class ValidatorStatistics(
  index: ValidatorIndex,      // Validator index
  reports: UInt,              // Work reports submitted
  preimages: UInt,            // Preimages provided
  availability: UInt,         // Availability assurances
  offenses: UInt              // Protocol violations
)

Cryptographic Types

Hash

32-byte hash value.

opaque type Hash = Array[Byte]

object Hash:
  def apply(bytes: Array[Byte]): Hash = bytes
  def fromHex(hex: String): Hash = // ...

  extension (h: Hash)
    def toHex: String = // ...
    def bytes: Array[Byte] = h

Ed25519PublicKey

Ed25519 public key (32 bytes).

opaque type Ed25519PublicKey = Array[Byte]

Ed25519Signature

Ed25519 signature (64 bytes).

opaque type Ed25519Signature = Array[Byte]

BandersnatchPublicKey

Bandersnatch public key for VRF.

opaque type BandersnatchPublicKey = Array[Byte]

Primitive Types

Balance

Token balance value.

opaque type Balance = UInt

object Balance:
  def apply(value: UInt): Balance = value
  val zero: Balance = UInt(0)

  extension (b: Balance)
    def +(other: Balance): Balance = // ...
    def -(other: Balance): Option[Balance] = // ...

Gas

Gas amount for execution metering.

opaque type Gas = ULong

object Gas:
  def apply(value: ULong): Gas = value
  val zero: Gas = ULong(0)

  extension (g: Gas)
    def +(other: Gas): Gas = // ...
    def -(other: Gas): Option[Gas] = // ...

ServiceId

Service identifier.

opaque type ServiceId = UInt

object ServiceId:
  def apply(value: UInt): ServiceId = value

TimeSlot

Time slot number.

opaque type TimeSlot = ULong

object TimeSlot:
  def apply(value: ULong): TimeSlot = value

  extension (t: TimeSlot)
    def +(slots: ULong): TimeSlot = // ...

EpochNumber

Epoch number.

opaque type EpochNumber = UInt

object EpochNumber:
  def apply(value: UInt): EpochNumber = value

Collection Types

Vector[A]

Immutable sequence, used throughout for ordered collections.

Map[K, V]

Immutable key-value mapping.

Set[A]

Immutable set of unique values.

Type Conversions

JAM Forge provides safe conversions between types:

// Hash from bytes
val hash: Hash = Hash(bytes)

// Balance arithmetic
val balance1 = Balance(1000)
val balance2 = Balance(500)
val total = balance1 + balance2

// Service ID from integer
val serviceId = ServiceId(UInt(42))

Next Steps

• See Codec System for serialization
• Explore State Transitions for type usage
• Check Architecture for module organization