Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 77 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 version-code is a unique identifier in CESR streams that specifies which version of the CESR code tables should be loaded for parsing, determining the table state and enabling version-specific interpretation of primitives and count codes.
The version-code is a fundamental component of the CESR (Composable Event Streaming Representation) protocol that enables version management and backward compatibility in KERI-based systems. According to the canonical glossary, a 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."
The version-code serves as a table state selector that determines which specific version of CESR encoding/decoding tables a parser should use when processing a stream. This mechanism is critical for protocol evolution, allowing new cryptographic primitives, count codes, and encoding schemes to be introduced without breaking existing implementations.
The version-code must be distinguished from the related but distinct concept of version-string. According to Document 3, the version-string is "the first field in any top-level KERI field map" and serves as a "workaround mechanism to enable self-framing behavior in serialization formats" like JSON, CBOR, and MGPK that don't natively support self-framing.
While version-strings appear in serialized KERI messages to enable format detection and boundary determination, version-codes operate at the CESR primitive level to control code table interpretation. The version-string contains metadata about the message format and size, whereas the version-code controls the cryptographic primitive encoding scheme.
The version-code concept is part of the broader CESR specification, which defines a dual text-binary encoding format for cryptographic primitives. Document 10 establishes that CESR operates across three domains:
Implementations should initialize parsers with a default CESR version that matches the expected stream format. This default version is used when streams do not contain explicit version count codes.
When processing CESR streams, parsers must:
Implementations should consider:
Robust implementations must handle:
Critical implementation detail from Document 4: "Count code interpretation depends on the active version code context." This means:
Implementations must handle cold start scenarios where:
The default version mechanism provides the fallback behavior for these scenarios.
When implementing hierarchical parsing with group codes:
The version-code enables parsers to correctly interpret primitives across these domains by specifying which encoding rules and derivation codes are active for a given stream section.
CESR employs a sophisticated code table architecture where different versions of the protocol may define different sets of:
Document 4 explains that the version-code determines "which CESR table to load for subsequent parsing." This table-switching mechanism enables:
The version-code integrates with the Parside parser component, which is responsible for extracting and parsing CESR streams. According to Document 4, Parside operates with a default CESR version at initialization, but when encountering a version count code:
Document 4 describes cold start scenarios where a stream does not begin with an explicit version code. In these cases, the parser maintains a default version count code to handle:
This default version mechanism ensures robust parsing even when version information is implicit rather than explicit.
While the provided documents do not specify the exact binary or text encoding of version count codes, Document 4 establishes that version count codes are a special type of count code that appears at the top level of CESR streams.
Count codes in CESR are framing codes that delineate the number of characters (text domain) or bytes (binary domain) that can be extracted atomically from a stream. Document 15 explains that count codes enable self-framing grouping, which is "one of the primary advantages of composable encoding."
The version count code likely follows the general CESR count code pattern:
In non-CESR serialization formats (JSON, CBOR, MGPK), the version-code concept is implemented through version strings. Document 4 describes how the sniffer component detects these formats:
This mechanism enables CESR streams to contain embedded JSON, CBOR, or MGPK sections with their own version information, while maintaining overall stream composability.
When the sniffer identifies CESR format at the top level (Document 5):
The version count code thus serves as a format selector that determines how subsequent stream content should be interpreted.
The version-code enables dynamic version switching within a single CESR stream. Document 4 describes the operational workflow:
Initial State:
Version Code Encounter:
Subsequent Processing:
Document 4 describes how version context interacts with hierarchical parsing:
This hierarchical approach enables complex nested structures while maintaining consistent version interpretation.
Document 4 explicitly states that "count code interpretation depends on the active version code context." This means:
This version-dependent interpretation enables protocol evolution without requiring new count code namespaces for each version.
The version-code mechanism provides several security properties:
Explicit Version Declaration: By requiring version codes at the top level, CESR ensures that parsers cannot be tricked into using incorrect table versions through nested or malformed structures.
Version Isolation: Each version's code tables are isolated, preventing cross-version confusion attacks where primitives from one version are misinterpreted using another version's tables.
Default Version Safety: The default version mechanism ensures that parsers have a well-defined fallback behavior, preventing undefined states when version information is missing.
Version Confusion Attacks: The requirement that version count codes appear at the top level prevents attackers from embedding version switches deep in nested structures to confuse parsers.
Table Substitution Attacks: By cryptographically binding version codes to specific table definitions, CESR prevents attackers from substituting malicious code tables.
Downgrade Attacks: Parsers can implement minimum version requirements, rejecting streams that attempt to use obsolete versions with known vulnerabilities.
The version-code mechanism is essential for cryptographic agility in KERI systems. Document 58 emphasizes that "truly secure protocols must be both cryptographically agile and cryptographically primitive-heavy."
Version codes enable:
The version-code mechanism integrates deeply with the broader KERI protocol stack:
Key Event Logs (KELs): Document 12 describes KELs as "append-only, cryptographically verifiable data structures" that use CESR encoding. Version codes enable KELs to evolve their encoding schemes while maintaining verifiability of historical events.
Autonomic Identifiers (AIDs): AIDs use CESR-encoded prefixes that include derivation codes. Version codes ensure that these prefixes can be correctly interpreted across different CESR versions.
Witnesses and Watchers: Document 14 describes witness and watcher infrastructure that exchanges CESR-encoded messages. Version codes enable these components to negotiate compatible encoding versions.
Document 13 describes ACDCs as "ordered nested field maps" that can be serialized in multiple formats including CESR. The version-code mechanism enables:
Document 16 describes the Issuance and Presentation Exchange protocol for ACDC credentials. Version codes enable:
Document 33 describes TELs as "hash-linked data structures that track issuance and revocation state." Version codes enable:
Implementers must carefully manage parser state related to version codes:
Default Version Initialization: Parsers should initialize with a well-defined default version that matches the expected stream format.
Version Stack Management: For nested structures, parsers may need to maintain a version stack to handle version changes at different nesting levels.
Version Validation: Parsers should validate that version codes reference known, supported table versions before attempting to load them.
Document 4 suggests that Parside could "load" the code tables it supports, potentially enabling dynamically loaded code tables. Implementers should consider:
Static Table Embedding: Embedding all supported table versions in the parser binary for maximum performance and security.
Dynamic Table Loading: Loading table definitions from external sources, enabling version support without recompilation (with appropriate security controls).
Lazy Table Loading: Loading table versions only when first encountered in a stream, reducing memory footprint.
Table Caching: Once a table version is loaded, it should be cached for reuse across multiple streams.
Version Prediction: For streams with predictable version patterns, parsers can pre-load expected table versions.
Fast Path for Default Version: The default version should have an optimized fast path since it will be used most frequently.
Unknown Version Codes: Parsers should have well-defined behavior when encountering unknown version codes (reject, skip, or request table definition).
Version Mismatch: When a stream's version requirements conflict with parser capabilities, clear error messages should guide resolution.
Partial Version Support: Parsers may support only a subset of primitives in a given version; this should be clearly documented.
Version Compatibility Testing: Test suites should verify correct parsing across all supported versions.
Version Switching Testing: Test streams that switch between versions to verify correct state management.
Backward Compatibility Testing: Verify that new parser versions can correctly process streams from older versions.
While the provided documents do not reference a formal IETF RFC or specification document specifically for version-codes, implementers should:
The version-code mechanism is a critical component of CESR's architecture, enabling protocol evolution while maintaining backward compatibility and security. By providing a well-defined mechanism for table version selection, version codes enable KERI-based systems to adapt to new cryptographic algorithms, encoding schemes, and protocol features without breaking existing implementations.
Implementers must carefully consider version management in their parser designs, ensuring robust handling of version switches, unknown versions, and nested structures. The version-code mechanism, combined with CESR's composability properties, provides a solid foundation for long-term protocol evolution in the KERI ecosystem.
Implementations should include: