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.
CESR-version is a special Count Code within the Composable Event Streaming Representation (CESR) protocol that specifies which version of the CESR code tables should be used when parsing a given stream or stream section. According to the canonical glossary, "the CESR Version is provided by a special Count Code that specifies the Version of all the CESR code tables in a given Stream or Stream section."
This version indicator serves as a critical parsing directive that determines how subsequent cryptographic primitives, framing codes, and group codes should be interpreted within the stream.
The CESR-version mechanism addresses a fundamental challenge in protocol evolution: maintaining backward compatibility while supporting new features. As CESR specifications evolve to support new cryptographic algorithms, encoding optimizations, or additional primitive types, the version mechanism provides a structured approach to managing these changes.
According to the Parside documentation (the CESR stream parser component), "Parside must start with a default version for CESR." This default version enables parsing to begin even when streams don't explicitly declare a version, which is particularly important in several scenarios:
Default Version Handling: Parsers MUST initialize with a default CESR version to handle streams that don't begin with explicit version codes or when resuming after cold restarts. The default version should correspond to the most widely deployed stable specification.
Version State Management: The parser must maintain version state throughout stream processing, as different sections may declare different versions. Version changes affect the interpretation of all subsequent primitives until another version code is encountered.
Top-Level Elevation: CESR-version codes must be processed at the top level of the parsing hierarchy. When encountered within nested structures, the parser should elevate processing to handle the version change before continuing with nested content.
Table Loading Strategy: Implementations should support dynamic loading of code tables corresponding to different CESR versions. This may involve lazy loading, pre-loading common versions, or runtime table generation based on version specifications.
Version Validation: Parsers should validate that declared CESR-versions correspond to known specifications and handle unknown versions gracefully (either by rejecting the stream or attempting best-effort parsing with warnings).
The default version represents a baseline CESR specification that the parser can use as a starting point before encountering explicit version codes.
When the parser encounters a CESR-version count code in a stream, it triggers a table loading operation. The Parside documentation states that the parser "changes version when it encounters a version count code" and "uses the version count code to determine which CESR code table to load when parsing the stream."
This dynamic loading capability is crucial for several reasons:
The Parside documentation explicitly states that version count codes "must appear at the top level" and that Parside "elevates version count codes to top level." This architectural requirement ensures that:
The term "elevates" suggests that if version count codes appear within nested structures during parsing, they are promoted to affect the top-level parsing context, ensuring consistent version application across the stream.
The CESR-version concept is fundamentally linked to the broader concept of code tables within CESR. According to the glossary definition of version-code: "tells you which set of tables to load, it tells the table state. It's a unique code. what version of the table is going to load."
Code tables define the mapping between encoded values and their semantic meanings. Different CESR versions may:
The version-code serves as the selector that determines which specific code table mappings apply to subsequent stream elements.
The CESR-version works in conjunction with the code-table-selector, which the glossary defines as "the first character in the text code of CESR stream that determines which code table to use, either a default code table or a code table selector character when not the default code table."
This creates a two-level versioning hierarchy:
This layered approach allows for both coarse-grained version management (entire specification versions) and fine-grained table selection (specific encoding variants within a version).
The Parside documentation notes that "count code interpretation depends on the active version code." This means that the same encoded count code value may have different interpretations depending on which CESR-version is active:
0x42 in CESR v1.0 might indicate one primitive type0x42 in CESR v2.0 might indicate a different primitive type or encoding variantThis version-dependent interpretation requires parsers to maintain version state and apply the appropriate code table for each section of the stream.
CESR-version can appear multiple times within a single stream, enabling stream segmentation where different sections use different encoding versions. This capability supports several important use cases:
Organizations upgrading from one CESR version to another can produce streams containing both legacy and modern encodings:
[CESR-version: 1.0] → [legacy primitives]
[CESR-version: 2.0] → [modern primitives]
[CESR-version: 1.0] → [more legacy primitives]
This allows systems to handle both old and new data formats during transition periods.
When aggregating streams from multiple sources that may use different CESR versions, the version codes provide clear segmentation:
The aggregated stream contains version codes that allow parsers to correctly interpret each segment according to its source's CESR version.
Different portions of a stream may require different CESR features:
The CESR ecosystem supports multiple serialization formats beyond pure CESR encoding. According to the sniffer documentation, the parser can detect and handle:
For non-CESR formats (JSON, CBOR, MGPK), the sniffer component "uses regex to locate the version string within the serialized data." The version string serves a similar version-declaration purpose for these formats, though it uses a different encoding approach than CESR-version count codes.
The glossary distinguishes between:
Both serve version declaration purposes but for different serialization contexts:
"v": "KERI10JSON" in event messages)The sniffer component bridges these two approaches by detecting the format and applying the appropriate version extraction mechanism.
Implementing CESR-version support requires parsers to maintain version state:
ParserState {
currentVersion: CESRVersion,
defaultVersion: CESRVersion,
loadedTables: Map<CESRVersion, CodeTable>,
versionHistory: Array<VersionChange>
}
The Parside architecture uses a "generator-based" approach where "Parside is fundamentally 'a bunch of generators' responsible for 'pulling out a stream of bits from a CESR stream and parse it.'" This generator pattern facilitates state management by allowing parsers to yield control when version changes occur, reload appropriate tables, and resume parsing with the new context.
The Parside documentation emphasizes that the parser should "not iterate stuff, only parse chunks delimited by the count code." This chunk-based approach aligns with CESR's self-framing property:
This design enables efficient stream processing where the parser can quickly skip or process chunks based on version compatibility without examining individual primitive contents.
While CESR-version controls stream encoding, KERI events have their own versioning mechanism through version strings. The glossary defines version (in KEL context) as "an instance of a KEL for an AID in which at least one event is unique between two instances of the KEL."
The two versioning systems serve different purposes:
Both must be managed correctly for proper system operation. For example, a KERI event with version string "KERI10JSON" might be encoded in a CESR v2.0 stream, requiring the parser to:
The CESR-version mechanism provides a foundation for future protocol evolution. The CESR specification (v0.9 Draft) emphasizes composability as a core property: "An encoding has Composability when any set of Self-Framing concatenated Primitives expressed in either the Text domain or Binary domain may be converted as a group to the other Domain and back again without loss."
Future CESR versions can:
The version mechanism ensures that:
Within the broader KERI ecosystem, CESR-version affects multiple infrastructure components:
KEL files may contain CESR-version codes that control how the encoded key events are parsed. The document "100_kel.txt" shows KELs with version strings like "v":"KERI10JSON" embedded in events, which work in conjunction with the CESR encoding version.
Similar to KELs, TELs may use CESR-version codes to manage credential issuance and revocation event encoding, ensuring that credential state changes are recorded in version-appropriate formats.
Witness receipts and watcher event confirmations are encoded using CESR, requiring consistent version management to ensure that receipts can be validated regardless of which witness or watcher version produced them.
Consider a practical scenario where a KERI system upgrades from CESR v1.0 to v2.0:
Phase 1: Initial State
Phase 2: Transition Period
Phase 3: Full Migration
This phased approach, enabled by CESR-version, allows non-disruptive protocol evolution.
CESR-version represents a foundational versioning mechanism that enables CESR's long-term evolution while maintaining the protocol's core properties of composability, self-framing, and efficient stream processing. By providing explicit version control through count codes, CESR ensures that parsers can correctly interpret streams regardless of when they were created or which CESR specification version was used to encode them. This version management capability is essential for KERI's goal of creating a future-proof, extensible protocol that can evolve cryptographic capabilities while maintaining verifiability of historical data encoded under earlier specifications.