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.

Key Features & Capabilities

Version-Aware Parsing

Parside operates with a default CESR version at initialization. When encountering a version count code:

1. The parser switches to the specified version context
2. Elevates processing to the top level (version count codes must appear at top level)
3. The version count code determines which CESR code table to load for subsequent parsing

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.

Multi-Format Stream Detection

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:

• CESR binary - Binary-encoded CESR primitives
• CESR text - Text-encoded CESR primitives
• JSON - JavaScript Object Notation
• CBOR - Concise Binary Object Representation
• MGPK - MessagePack binary serialization

For non-CESR formats (JSON, CBOR, MessagePack), Parside employs a specialized extraction process:

1. Regex Matching - Applies regular expressions to locate the version string embedded within serialized data
2. Length Extraction - Extracts character count (text) or byte count (binary) defining the structure's total length
3. Boundary Detection - Uses length information to determine exactly where the data structure ends
4. Resume Sniffing - After processing the bounded structure, resumes operation on remaining stream

This multi-format capability is critical for KERI's ability to handle heterogeneous streaming data while maintaining cryptographic verifiability.

Hierarchical Group Parsing

When the sniffer identifies CESR format, Parside implements recursive descent parsing:

• Parser looks for CESR version count codes or other count codes at the top level
• Upon encountering a group count code, the parser descends into nested group parsing
• This recursive descent can nest arbitrarily deep, following the hierarchical structure
• Each level maintains its own parsing context and version state

As described in Document 1, this hierarchical composition enables "management at scale for high-bandwidth applications" through efficient pipelining and multiplexing of complex streams.

Cold Start Handling

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:

• The stream does not begin with an explicit version code
• Processing resumes after a cold restart
• Count code interpretation must proceed without explicit version context

This design ensures robust stream processing even in adverse network conditions or after system restarts.

Self-Framing Stream Processing

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:

• Parse streams without external framing information
• Support composability between text and binary domains
• Enable pipelining of complex event streams
• Maintain separability of individual primitives within groups

Unlike JSON (which is not self-framing), CESR's self-framing property allows Parside to process streams incrementally without buffering entire structures.

Architecture & Design Principles

Generator-Based Architecture

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:

• Lazy evaluation - Parse only what's needed when it's needed
• Memory efficiency - Avoid loading entire streams into memory
• Streaming processing - Handle arbitrarily large streams
• Backpressure handling - Natural flow control in processing pipelines

Modular Parsing Dispatch

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:

• Different parsers for different primitive types
• Extensibility through parser registration
• Optimization of parsing strategies per primitive type
• Clear separation of concerns between parsing layers

Dynamic Code Table Loading

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:

• Runtime extension of supported primitive types
• Version-specific table loading based on version codes
• Protocol evolution without parser recompilation
• Support for experimental or domain-specific primitives

Integration with KERI Ecosystem

Relationship to KEL Processing

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:

• Extract inception events
• Process rotation events
• Handle interaction events
• Verify witness receipts

The hierarchical parsing capabilities enable efficient processing of complex KEL structures with nested seals and attachments.

ACDC Credential Processing

For ACDC (Authentic Chained Data Container) credentials, Parside handles:

• Parsing of SAID-based field maps
• Extraction of nested credential chains
• Processing of selective disclosure structures
• Handling of compact disclosure formats

The ability to handle mixed JSON and CESR formats is particularly important for ACDC processing, as credentials may embed JSON schemas within CESR streams.

OOBI Discovery Protocol

Parside supports OOBI (Out-Of-Band Introduction) processing by:

• Parsing OOBI URLs and endpoint information
• Extracting AID identifiers from OOBI structures
• Processing witness and watcher endpoint lists
• Handling blind OOBI formats

This integration enables KERI's discovery mechanisms to function efficiently across heterogeneous network environments.

Technical Significance

Parside represents a critical architectural component enabling KERI's ability to handle heterogeneous streaming data with mixed serialization formats while maintaining:

1. Cryptographic Verifiability - All parsed primitives retain their cryptographic properties
2. Efficient Processing - Generator-based architecture enables streaming at scale
3. Protocol Composability - Support for multiple formats enables ecosystem interoperability
4. Forward Compatibility - Version-aware parsing supports protocol evolution

As noted in Document 1, the modular design "supports KERI's composability goals and enables pipelined processing of complex event streams at scale."

Implementation Status

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:

• Exact generator/iterator return patterns
• Dynamic code table loading mechanisms
• Optimal separation of responsibilities with Cesride
• Version count code handling at stream boundaries

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.

Performance Considerations

The chunk-based parsing approach (parsing by count code boundaries rather than iterating entire streams) provides several performance benefits:

• Reduced Memory Footprint - Only active chunks need to be in memory
• Parallel Processing Potential - Independent chunks can be processed concurrently
• Early Error Detection - Malformed chunks can be rejected without processing entire streams
• Efficient Pipelining - Chunks can flow through processing stages independently

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.

Performance Optimization

For high-throughput applications:

• Parse by count code boundaries to enable chunked processing
• Consider parallel processing of independent chunks
• Minimize buffering by leveraging self-framing properties
• Use lazy evaluation to avoid unnecessary parsing

Mixed Format Stream Handling

When processing streams with multiple serialization formats:

• Use regex patterns to locate version strings in non-CESR formats
• Extract length information to determine message boundaries
• Resume sniffing after processing each bounded structure
• Maintain parsing context across format transitions

Integration with KERI Components

Parside must integrate correctly with:

• KEL processing: Extract events, seals, and attachments
• ACDC parsing: Handle nested credentials and selective disclosure
• OOBI discovery: Parse endpoint information and AID identifiers
• Witness receipts: Process multi-signature attachments

Test integration points thoroughly to ensure correct end-to-end functionality.