jam-types.asn

--------------------------------------------
-- JAM Protocol Types
--------------------------------------------

JamTypes DEFINITIONS ::= BEGIN

IMPORTS
    -- Constants
    validators-count, epoch-length, cores-count,
    validators-super-majority, avail-bitfield-bytes,
    max-blocks-history, max-tickets-per-block,
    auth-pool-max-size, auth-queue-size
        FROM Constants;

--------------------------------------------
-- Simple
--------------------------------------------

U8 ::= INTEGER (0..255)
U16 ::= INTEGER (0..65535)
U32 ::= INTEGER (0..4294967295)
U64 ::= INTEGER (0..18446744073709551615)

ByteSequence ::= OCTET STRING
ByteArray32 ::= OCTET STRING (SIZE(32))

--------------------------------------------
-- Crypto
--------------------------------------------

BandersnatchPublic ::= OCTET STRING (SIZE(32))
Ed25519Public ::= OCTET STRING (SIZE(32))
BlsPublic ::= OCTET STRING (SIZE(144))

BandersnatchVrfSignature ::= OCTET STRING (SIZE(96))
BandersnatchRingVrfSignature ::= OCTET STRING (SIZE(784))
Ed25519Signature ::= OCTET STRING (SIZE(64))

BandersnatchRingCommitment ::= OCTET STRING (SIZE(144))

--------------------------------------------
-- Application Specific Core
--------------------------------------------

OpaqueHash ::= ByteArray32

TimeSlot ::= U32
ValidatorIndex ::= U16
CoreIndex ::= U16

HeaderHash ::= OpaqueHash
StateRoot ::= OpaqueHash
BeefyRoot ::= OpaqueHash
WorkPackageHash ::= OpaqueHash
WorkReportHash ::= OpaqueHash
ExportsRoot ::= OpaqueHash
ErasureRoot ::= OpaqueHash

Gas ::= U64

Entropy ::= OpaqueHash
EntropyBuffer ::= SEQUENCE (SIZE(4)) OF Entropy

ValidatorMetadata ::= OCTET STRING (SIZE(128))

ValidatorData ::= SEQUENCE {
    bandersnatch BandersnatchPublic,
    ed25519 Ed25519Public,
    bls BlsPublic,
    metadata ValidatorMetadata
}

ValidatorsData ::= SEQUENCE (SIZE(validators-count)) OF ValidatorData

--------------------------------------------
-- Service
--------------------------------------------

ServiceId ::= U32

ServiceInfo ::= SEQUENCE {
    code-hash      OpaqueHash,
    balance        U64,
    min-item-gas   Gas,
    min-memo-gas   Gas,
    bytes          U64,
    items          U32
}

--------------------------------------------
-- Availability Assignments
--------------------------------------------

AvailabilityAssignment ::= SEQUENCE {
    report WorkReport,
    timeout U32
}

AvailabilityAssignmentsItem ::= CHOICE {
    none [0] NULL,
    some [1] AvailabilityAssignment
}

AvailabilityAssignments ::= SEQUENCE SIZE(cores-count) OF AvailabilityAssignmentsItem

--------------------------------------------
-- Refine Context
--------------------------------------------

RefineContext ::= SEQUENCE {
	anchor HeaderHash,
	state-root StateRoot,
	beefy-root BeefyRoot,
	lookup-anchor HeaderHash,
	lookup-anchor-slot TimeSlot,
	prerequisites SEQUENCE OF OpaqueHash
}

--------------------------------------------
-- Authorizations
--------------------------------------------

Authorizer ::= SEQUENCE {
    code-hash OpaqueHash,
    params ByteSequence
}

-- Hash of encoded Authorizer
AuthorizerHash ::= OpaqueHash

AuthPool ::= SEQUENCE (SIZE(0..auth-pool-max-size)) OF AuthorizerHash
AuthPools ::= SEQUENCE (SIZE(cores-count)) OF AuthPool

AuthQueue ::= SEQUENCE (SIZE(auth-queue-size)) OF AuthorizerHash
AuthQueues ::= SEQUENCE (SIZE(cores-count)) OF AuthQueue

--------------------------------------------
-- Work Package
--------------------------------------------

ImportSpec ::= SEQUENCE {
    tree-root OpaqueHash,
    index U16
}

ExtrinsicSpec ::= SEQUENCE {
    hash OpaqueHash,
    len U32
}

WorkItem ::= SEQUENCE {
    service ServiceId,
    code-hash OpaqueHash,
    payload ByteSequence,
    refine-gas-limit Gas,
    accumulate-gas-limit Gas,
    import-segments SEQUENCE OF ImportSpec,
    extrinsic SEQUENCE OF ExtrinsicSpec,
    export-count U16
}

WorkPackage ::= SEQUENCE {
    authorization ByteSequence,
    auth-code-host ServiceId,
    authorizer Authorizer,
    context RefineContext,
    items SEQUENCE (SIZE(1..16)) OF WorkItem
}

--------------------------------------------
-- Work Report
--------------------------------------------

WorkExecResult ::= CHOICE {
    ok [0] ByteSequence,
    out-of-gas [1] NULL,
    panic [2] NULL,
    bad-exports [3] NULL,
    bad-code [4] NULL,
    code-oversize [5] NULL
}

RefineLoad ::= SEQUENCE {
    gas-used Gas,
    imports U16,
    extrinsic-count U16,
    extrinsic-size U32,
    exports U16
}

WorkResult ::= SEQUENCE {
    service-id ServiceId,
    code-hash OpaqueHash,
    payload-hash OpaqueHash,
    accumulate-gas Gas,
    result WorkExecResult,
    refine-load RefineLoad
}

WorkPackageSpec ::= SEQUENCE {
    hash WorkPackageHash,
    length U32,
    erasure-root ErasureRoot,
    exports-root ExportsRoot,
    exports-count U16
}

SegmentRootLookupItem ::= SEQUENCE {
    work-package-hash WorkPackageHash,
    segment-tree-root OpaqueHash
}

SegmentRootLookup ::= SEQUENCE OF SegmentRootLookupItem

WorkReport ::= SEQUENCE {
    package-spec WorkPackageSpec,
    context RefineContext,
    core-index CoreIndex,
    authorizer-hash OpaqueHash,
    auth-output ByteSequence,
    segment-root-lookup SegmentRootLookup,
    results SEQUENCE (SIZE(1..16)) OF WorkResult,
    auth-gas-used Gas
}

--------------------------------------------
-- Block History
--------------------------------------------

MmrPeak ::= CHOICE {
    none [0] NULL,
    some [1] OpaqueHash
}

Mmr ::= SEQUENCE {
    peaks  SEQUENCE OF MmrPeak
}

ReportedWorkPackage ::= SEQUENCE {
    hash            WorkReportHash,
    exports-root    ExportsRoot
}

BlockInfo ::= SEQUENCE {
    header-hash    HeaderHash,
    mmr            Mmr,
    state-root     StateRoot,
    reported       SEQUENCE OF ReportedWorkPackage
}
 
BlocksHistory ::= SEQUENCE (SIZE(0..max-blocks-history)) OF BlockInfo

--------------------------------------------
-- Statistics
--------------------------------------------

ActivityRecord ::= SEQUENCE {
    blocks      U32,
    tickets     U32,
    pre-images  U32,
    pre-images-size U32,
    guarantees  U32,
    assurances  U32
}

ActivityRecords ::= SEQUENCE (SIZE(validators-count)) OF ActivityRecord

CoreActivityRecord ::= SEQUENCE {
	-- Amount of bytes which are placed into either Audits or Segments DA.
	-- This includes the work-bundle (including all extrinsics and imports) as well as all
	-- (exported) segments.
	da-load         U32,
	-- Number of validators which formed super-majority for assurance.
	popularity      U16,
	-- Number of segments imported from DA made by core for reported work.
	imports         U16,
	-- Number of segments exported into DA made by core for reported work.
	exports         U16,
	-- Total size of extrinsics used by core for reported work.
	extrinsic-size  U32,
	-- Total number of extrinsics used by core for reported work.
	extrinsic-count U16,
	-- The work-bundle size. This is the size of data being placed into Audits DA by the core.
	bundle-size     U32,
	-- Total gas consumed by core for reported work. Includes all refinement and authorizations.
	gas-used        Gas
}

CoresStatistics ::= SEQUENCE (SIZE(cores-count)) OF CoreActivityRecord

ServiceActivityRecord ::= SEQUENCE {
	-- Number of preimages provided to this service.
	provided-count        U16,
	-- Total size of preimages provided to this service.
	provided-size         U32,
	-- Number of work-items refined by service for reported work.
	refinement-count      U32,
	-- Amount of gas used for refinement by service for reported work.
	refinement-gas-used   Gas,
	-- Number of segments imported from the DL by service for reported work.
	imports               U32,
	-- Number of segments exported into the DL by service for reported work.
	exports               U32,
	-- Total size of extrinsics used by service for reported work.
	extrinsic-size        U32,
	-- Total number of extrinsics used by service for reported work.
	extrinsic-count       U32,
	-- Number of work-items accumulated by service.
	accumulate-count      U32,
	-- Amount of gas used for accumulation by service.
	accumulate-gas-used   Gas,
	-- Number of transfers processed by service.
	on-transfers-count    U32,
	-- Amount of gas used for processing transfers by service.
	on-transfers-gas-used Gas
}

ServicesStatisticsMapEntry ::= SEQUENCE {
    id ServiceId,
    record ServiceActivityRecord
}

ServicesStatistics ::= SEQUENCE OF ServicesStatisticsMapEntry

Statistics ::= SEQUENCE {
    vals-current ActivityRecords,
    vals-last    ActivityRecords,
    cores        CoresStatistics,
    services     ServicesStatistics
}

--------------------------------------------
-- Tickets
--------------------------------------------

TicketId ::= OpaqueHash
TicketAttempt ::= U8

TicketEnvelope ::= SEQUENCE {
    attempt   TicketAttempt,
    signature BandersnatchRingVrfSignature
}

TicketBody ::= SEQUENCE {
    id      TicketId,
    attempt TicketAttempt
}

TicketsAccumulator ::= SEQUENCE (SIZE(0..epoch-length)) OF TicketBody

TicketsOrKeys ::= CHOICE {
    tickets SEQUENCE (SIZE(epoch-length)) OF TicketBody,
    keys    SEQUENCE (SIZE(epoch-length)) OF BandersnatchPublic
}

TicketsExtrinsic ::= SEQUENCE (SIZE(0..max-tickets-per-block)) OF TicketEnvelope

--------------------------------------------
-- Disputes
--------------------------------------------

Judgement ::= SEQUENCE {
    vote BOOLEAN,
    index ValidatorIndex,
    signature Ed25519Signature
}

Verdict ::= SEQUENCE {
    target OpaqueHash,
    age U32,
    votes SEQUENCE (SIZE(validators-super-majority)) OF Judgement
}

Culprit ::= SEQUENCE {
    target WorkReportHash,
    key Ed25519Public,
    signature Ed25519Signature
}

Fault ::= SEQUENCE {
    target WorkReportHash,
    vote BOOLEAN,
    key Ed25519Public,
    signature Ed25519Signature
}

DisputesRecords ::= SEQUENCE {
    -- Good verdicts (psi_g)
    good      SEQUENCE OF WorkReportHash,
    -- Bad verdicts (psi_b)
    bad       SEQUENCE OF WorkReportHash,
    -- Wonky verdicts (psi_w)
    wonky     SEQUENCE OF WorkReportHash,
    -- Offenders (psi_o)
    offenders SEQUENCE OF Ed25519Public
}

DisputesExtrinsic ::= SEQUENCE {
    verdicts SEQUENCE OF Verdict,
    culprits SEQUENCE OF Culprit,
    faults SEQUENCE OF Fault
}

--------------------------------------------
-- Preimages
--------------------------------------------

Preimage ::= SEQUENCE {
    requester ServiceId,
    blob ByteSequence
}

PreimagesExtrinsic ::= SEQUENCE OF Preimage

--------------------------------------------
-- Assurances
--------------------------------------------

AvailAssurance ::= SEQUENCE {
    anchor OpaqueHash,
    bitfield OCTET STRING (SIZE(avail-bitfield-bytes)),
    validator-index ValidatorIndex,
    signature Ed25519Signature
}

AssurancesExtrinsic ::= SEQUENCE (SIZE(0..validators-count)) OF AvailAssurance

--------------------------------------------
-- Guarantees
--------------------------------------------

ValidatorSignature ::= SEQUENCE {
    validator-index ValidatorIndex,
    signature Ed25519Signature
}

ReportGuarantee ::= SEQUENCE {
    report WorkReport,
    slot TimeSlot,
    signatures SEQUENCE OF ValidatorSignature
}

GuaranteesExtrinsic ::= SEQUENCE SIZE(0..cores-count) OF ReportGuarantee

--------------------------------------------
-- Accumulation
--------------------------------------------

ReadyRecord ::= SEQUENCE {
    report WorkReport,
    dependencies SEQUENCE OF WorkPackageHash
}

ReadyQueueItem ::= SEQUENCE OF ReadyRecord
ReadyQueue ::= SEQUENCE (SIZE(epoch-length)) OF ReadyQueueItem

AccumulatedQueueItem ::= SEQUENCE OF WorkPackageHash
AccumulatedQueue ::= SEQUENCE (SIZE(epoch-length)) OF AccumulatedQueueItem

AlwaysAccumulateMapEntry ::= SEQUENCE {
    id ServiceId,
    gas Gas
}

Privileges ::= SEQUENCE {
    bless ServiceId,
    assign ServiceId,
    designate ServiceId,
    always-acc SEQUENCE OF AlwaysAccumulateMapEntry
}

AccumulateRoot ::= OpaqueHash

--------------------------------------------
-- Header
--------------------------------------------

EpochMarkValidatorKeys ::= SEQUENCE {
    bandersnatch BandersnatchPublic,
    ed25519 Ed25519Public
}

EpochMark ::= SEQUENCE {
    entropy         Entropy,
    tickets-entropy Entropy,
    validators      SEQUENCE (SIZE(validators-count)) OF EpochMarkValidatorKeys
}

TicketsMark ::= SEQUENCE (SIZE(epoch-length)) OF TicketBody

OffendersMark ::= SEQUENCE OF Ed25519Public

Header ::= SEQUENCE {
    parent             HeaderHash,
    parent-state-root  StateRoot,
    extrinsic-hash     OpaqueHash,
    slot               TimeSlot,
    epoch-mark         EpochMark OPTIONAL,
    tickets-mark       TicketsMark OPTIONAL,
    offenders-mark     OffendersMark,
    author-index       ValidatorIndex,
    entropy-source     BandersnatchVrfSignature,
    seal               BandersnatchVrfSignature
}

--------------------------------------------
-- Block
--------------------------------------------

Extrinsic ::= SEQUENCE {
    tickets TicketsExtrinsic,
    preimages PreimagesExtrinsic,
    guarantees GuaranteesExtrinsic,
    assurances AssurancesExtrinsic,
    disputes DisputesExtrinsic
}

Block ::= SEQUENCE {
    header Header,
    extrinsic Extrinsic
}

END