Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 15 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.
A serialization technique where CESR-encoded cryptographic primitives are combined with other serialization formats (JSON, CBOR, MessagePack) within a single stream using special count codes that enable parsers to distinguish between different encoding types while maintaining composability and self-framing properties.
Interleaved serialization is a fundamental capability of CESR (Composable Event Streaming Representation) that enables multiple serialization formats to coexist within a single data stream. Rather than requiring a uniform encoding throughout, interleaved serialization allows CESR primitives (cryptographic keys, signatures, digests) to be mixed with standard data serialization formats like JSON, CBOR, and MessagePack (MGPK) in a way that maintains the critical properties of composability and self-framing.
The core innovation lies in CESR's use of special count codes that act as format delimiters and type indicators. These count codes enable parsers to:
This capability is particularly valuable for applications that need to combine cryptographic material (naturally suited to CESR encoding) with flexible data structures (naturally suited to JSON/CBOR/MGPK field maps). The interleaving approach avoids the need to convert all data to a single format, allowing each type of content to use its most appropriate encoding.
Traditional cryptographic protocols typically faced a binary choice: either encode everything in a human-readable text format (sacrificing compactness) or encode everything in binary (sacrificing readability and debuggability). This forced compromise affected:
Implementations must support:
Count Code Recognition: Parsers must recognize and interpret count codes that indicate:
Multi-Format Libraries: Integration with:
Stream State Management: Maintain parser state across format transitions:
Recovery Mechanisms: Implement cold start recovery:
The problem became more acute with the rise of verifiable credentials and decentralized identity systems, which needed to:
Earlier attempts at mixed serialization typically used wrapper envelopes - outer structures that contained both data and cryptographic material as separate sections. However, this approach:
KERI's solution through CESR interleaved serialization represents a fundamental architectural shift. Rather than wrapping different formats in containers, CESR enables direct concatenation of different serialization types within a single stream, using count codes as intelligent boundaries.
CESR defines special group framing codes (count codes) that serve multiple purposes:
These count codes maintain CESR's critical 24-bit alignment constraint - all primitives and groups align on boundaries that are integer multiples of both 4 Base64 characters (text domain) and 3 bytes (binary domain). This alignment ensures composability is preserved even when interleaving different formats.
A typical interleaved CESR stream might contain:
[CESR Count Code for JSON][JSON field map with data][CESR Count Code for primitives][CESR-encoded signatures][CESR Count Code for CBOR][CBOR-encoded metadata]
Each section is independently parseable, yet the entire stream maintains CESR's composability property - it can be converted between text and binary domains en masse without losing the ability to separate individual sections.
The interleaving capability is particularly powerful for field maps (dictionaries/hash tables) that contain both:
Rather than forcing all content into CESR encoding (which would be inefficient for structured data) or forcing cryptographic material into JSON strings (which loses type information and compactness), interleaved serialization allows each to use its optimal format.
A critical advantage of interleaved serialization is support for cold start stream parsing. When a parser encounters errors or needs to resynchronize:
This robustness is essential for distributed systems where network interruptions, partial transmissions, or corrupted data may occur.
In ACDC (Authentic Chained Data Container) credentials, interleaved serialization enables:
The entire ACDC can be transmitted as a single interleaved stream, with each component using its most appropriate encoding, yet the whole structure remains verifiable and composable.
Verifiable Credentials: ACDCs use interleaved serialization to combine human-readable claims (JSON) with cryptographic proofs (CESR). A credential might contain:
Key Event Logs: KELs can include:
Streaming Protocols: Network protocols benefit from:
Format Optimization: Each type of content uses its most appropriate encoding:
Tooling Compatibility: Applications can:
Stream Processing Efficiency: Parsers can:
Human Readability: When using text domain encoding:
Parser Complexity: Implementations must:
Format Proliferation: Systems must decide:
Alignment Overhead: Count codes add:
However, these trade-offs are generally favorable compared to alternatives:
Interleaved serialization maintains CESR's security properties:
The ability to skip malformed sections also provides resilience against malicious inputs - a corrupted JSON section doesn't prevent processing of valid CESR primitives that follow.
Interleaved serialization represents a sophisticated solution to the multi-format encoding challenge in cryptographic protocols. By enabling different serialization types to coexist within a single composable stream, CESR provides the flexibility needed for modern verifiable data structures while maintaining the efficiency and security properties required for production systems. This capability is fundamental to KERI's architecture and enables the practical implementation of ACDCs, KELs, and other verifiable data structures that combine human-readable content with cryptographic commitments.