parside — Rust CESR Stream Parser

Overview

parside is a Rust library for parsing CESR (Composable Event Streaming Representation) byte streams into structured types. It sits one layer above cesride in the KERI stack: where cesride handles individual cryptographic primitives (Verfer, Diger, Siger, etc.), parside handles stream-level framing — detecting serialization format via cold start, dispatching counter-coded groups, and parsing interleaved JSON/CBOR/MGPK payloads.

parside is a structural decoder only. It does not validate KELs, verify signatures, or track key state. It answers "what CESR groups are in this byte stream?" — protocol semantics are the responsibility of higher layers (keriox, keripy).

Key design: all parsing is synchronous, stateless, and uses nom combinators. Every parsed group supports round-trip serialization via qb64() / qb2() .

Quick Reference

Type Purpose

Message

Sum type: Custom { CustomPayload } or Group { CesrGroup }

MessageList

Parse multiple messages from a byte stream

CustomPayload

JSON/CBOR/MGPK payload as serde_json::Value

CesrGroup

Enum of 12 CESR group variants

Group<T>

Trait: CODE , new() , value() , qb64() , qb2() , full_size()

GroupItem

Trait: qb64() , qb64b() , qb2() , full_size()

ControllerIdxSigs

-A counter: indexed controller signatures

WitnessIdxSigs

-B counter: indexed witness signatures

NonTransReceiptCouples

-C counter: non-transferable receipt couples (Verfer+Cigar)

TransReceiptQuadruples

-D counter: transferable receipt quadruples

FirstSeenReplayCouples

-E counter: first-seen replay couples (Seqner+Dater)

TransIdxSigGroups

-F counter: transferable indexed sig groups (nested)

SealSourceCouples

-G counter: seal source couples (Seqner+Saider)

TransLastIdxSigGroups

-H counter: transferable last idx sig groups (nested)

SadPathSigs

-J counter: SAD path signatures (deeply nested)

SadPathSigGroups

-K counter: SAD path sig groups (doubly nested)

PathedMaterialQuadlets

-L counter: raw unparsed CESR material

AttachedMaterialQuadlets

-V counter: recursive container of CesrGroups

ParsideError

Error enum: 6 variants

Import Guide

// Top-level types (re-exported from lib.rs) use parside::{Message, MessageList, CesrGroup, CustomPayload, Group};

// Group types (re-exported via groups::*) use parside::{ ControllerIdxSigs, ControllerIdxSig, WitnessIdxSigs, WitnessIdxSig, NonTransReceiptCouples, NonTransReceiptCouple, TransReceiptQuadruples, TransReceiptQuadruple, FirstSeenReplayCouples, FirstSeenReplayCouple, TransIdxSigGroups, TransIdxSigGroup, SealSourceCouples, SealSourceCouple, TransLastIdxSigGroups, TransLastIdxSigGroup, SadPathSigs, SadPathSig, SadPathSigGroups, SadPathSigGroup, PathedMaterialQuadlets, PathedMaterialQuadlet, AttachedMaterialQuadlets, GroupItem, };

// Errors use parside::error::{ParsideError, ParsideResult};

// cesride primitives (used within group items) use cesride::{Siger, Cigar, Verfer, Prefixer, Seqner, Saider, Dater, Pather, Counter}; use cesride::{Matter, Indexer}; // traits for .code(), .qb64(), .raw(), etc.

Reference Files

File Contents Size

references/architecture.md

KERI stack position, boundaries, companion skills ~2KB

references/api.md

Parsing mental model, Message/MessageList/CesrGroup API, Group/GroupItem traits, invariants ~4KB

references/types.md

Counter code mapping table, nesting hierarchy, all 12 group structs with fields ~5KB

references/stream.md

Cold start tritet dispatch, ColdCode routing, CustomPayload deserialization, KERI version compat ~3KB

references/primitives.md

Parsers factory methods, qb64/qb2 size math, nomify! macro, special cases (Cigar, siger_list) ~3KB

references/errors.md

ParsideError variants, error origin mapping, recoverability, From conversions ~2KB

Usage Patterns

Parse a KERI message stream

let (rest, list) = MessageList::from_stream_bytes(stream_bytes)?; for msg in &list.messages { match msg { Message::Custom { value } => { // JSON/CBOR/MGPK payload let v_field = value.value["v"].as_str(); } Message::Group { value } => { // CESR attachment group match value { CesrGroup::ControllerIdxSigsVariant { value: sigs } => { for sig in &sigs.value { let idx = sig.siger.index(); } } // ... other variants } } } }

Construct and serialize a group

let sigs = ControllerIdxSigs::new(vec![ ControllerIdxSig::new(siger), ]); let qb64_string = sigs.qb64()?; // includes "-AAB" counter prefix let qb64_bytes = sigs.qb64b()?;

Round-trip parse and serialize

let (rest, group) = CesrGroup::from_stream_bytes(original)?; let reserialized = group.qb64()?; assert_eq!(reserialized.as_bytes(), original);

Extract typed KERI event

let (_, msg) = Message::from_stream_bytes(json_bytes)?; let event: MyKeriEvent = msg.typed_payload()?;

Anti-Patterns

DON'T assume count() returns item count for AttachedMaterialQuadlets. DO use value().len() for item count. AMQ's count() returns quadlet count.

DON'T call payload() or cesr_group() without checking the variant. DO pattern match on Message::Custom / Message::Group .

DON'T expect error details from nom-path failures. DO know that nomify! erases all error detail to ErrorKind::IsNot .

DON'T assume PathedMaterialQuadlets parses its internal structure. DO treat PathedMaterialQuadlet.raw as opaque bytes for application-level parsing.

DON'T forget that Cigar parsing consumes a Verfer first. DO account for verfer.full_size() + cigar.full_size() total bytes.