Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 20 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
Parside is a specialized parsing component within the KERI ecosystem implemented as part of the Python reference implementation (KERIpy). It serves as the higher-level stream parser for CESR (Composable Event Streaming Representation) encoded data, working in tandem with Cesride to provide complete CESR stream processing capabilities.
The implementation is designed around a generator-based architecture that pulls streams of bits from CESR-encoded data and parses them into structured components. According to Document 1, the fundamental design principle is that "Parside should parse chunks delimited by count codes rather than iterating through entire streams," enabling efficient modular parsing.
The CESR parsing architecture implements a clear separation of concerns between two complementary components:
Based on Document 7, the Parside design discussions from February 2023 represent preliminary design thinking marked as "TBW" (To Be Written). Implementers should:
The division between Parside and Cesride must be strictly maintained:
Violating this separation will break the modular parsing architecture and prevent proper strip parameter dispatch.
Version count codes must appear at top level in CESR streams. Implementers must:
For Parside to function correctly, streams must be sniffable by:
Non-sniffable streams will cause parsing failures and require alternative processing strategies.
The generator-based architecture requires careful handling of:
Implementers should follow Python generator best practices and consider using contextlib for resource management.
This separation leverages CESR's self-framing property, which allows modular parser construction where parsing responsibilities can be dispatched to specialized entities based on the strip parameter. The strip parameter determines which portion of the CESR stream will be processed by which code component.
Parside operates with a default CESR version at initialization. When encountering a version count code:
This version management capability enables forward compatibility and supports protocol evolution without breaking existing implementations. As noted in Document 1, count code interpretation depends on the active version code context.
Parside integrates with the sniffer component to detect and handle multiple serialization formats within a single stream. According to Document 5, the sniffer can identify:
For non-CESR formats (JSON, CBOR, MessagePack), Parside employs a specialized extraction process:
This multi-format capability is critical for KERI's ability to handle heterogeneous streaming data while maintaining cryptographic verifiability.
When the sniffer identifies CESR format, Parside implements recursive descent parsing:
As described in Document 1, this hierarchical composition enables "management at scale for high-bandwidth applications" through efficient pipelining and multiplexing of complex streams.
Parside addresses the cold start problem - the challenge of synchronizing with a stream without prior context. According to Document 3, a stream is sniffable when it starts with recognizable group codes or field maps.
The parser maintains a default version count code to handle scenarios where:
This design ensures robust stream processing even in adverse network conditions or after system restarts.
CESR primitives are self-framing, meaning each primitive contains sufficient information to determine its own boundaries. As noted in Document 7, this property is "relatively new" and enables modular parser construction.
Parside leverages self-framing to:
Unlike JSON (which is not self-framing), CESR's self-framing property allows Parside to process streams incrementally without buffering entire structures.
According to Document 7, Parside is described as "a bunch of generators" responsible for pulling streams of bits from CESR streams. The February 2023 design discussions explored whether Parside could "return an iterator/generator" for efficient stream processing.
This generator pattern enables:
The strip parameter mechanism enables dynamic parsing dispatch. As defined in Document 2, the strip parameter "tells which part of the CESR stream will be parsed by which code."
This modular approach allows:
The February 2023 design notes in Document 7 suggest Parside could "load the code tables it supports," potentially enabling dynamically loaded code tables. This capability would allow:
Parside plays a critical role in processing KEL (Key Event Log) streams. KERI event streams are CESR-encoded sequences of key events that must be parsed to:
The hierarchical parsing capabilities enable efficient processing of complex KEL structures with nested seals and attachments.
For ACDC (Authentic Chained Data Container) credentials, Parside handles:
The ability to handle mixed JSON and CESR formats is particularly important for ACDC processing, as credentials may embed JSON schemas within CESR streams.
Parside supports OOBI (Out-Of-Band Introduction) processing by:
This integration enables KERI's discovery mechanisms to function efficiently across heterogeneous network environments.
Parside represents a critical architectural component enabling KERI's ability to handle heterogeneous streaming data with mixed serialization formats while maintaining:
As noted in Document 1, the modular design "supports KERI's composability goals and enables pipelined processing of complex event streams at scale."
Based on Document 7, the Parside design discussions from February 2023 represent preliminary design thinking rather than finalized specification. The document explicitly marks sections as "TBW" (To Be Written) and characterizes the content as "meeting notes and preliminary design discussions."
Key design decisions still under consideration include:
Developers should consult the current KERIpy implementation for the most up-to-date architectural decisions, as the design has likely evolved since the February 2023 discussions documented in the source materials.
The chunk-based parsing approach (parsing by count code boundaries rather than iterating entire streams) provides several performance benefits:
These characteristics make Parside suitable for high-throughput KERI applications processing large volumes of event streams, such as witness pools handling events from thousands of identifiers.
For high-throughput applications:
When processing streams with multiple serialization formats:
Parside must integrate correctly with:
Test integration points thoroughly to ensure correct end-to-end functionality.