Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 11 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.
The first character in a CESR text stream that determines which code table the parser should use for interpreting subsequent characters, serving dual purpose as both a table selector (for default vs. alternate code tables) and as a type code for the most popular primitives with pad size of 1 in the default table.
The code-table-selector is a fundamental structural element in CESR (Composable Event Streaming Representation) that appears as the first character in the text domain encoding of a CESR stream. This single character performs a critical dual function that enables CESR's efficient, self-describing encoding scheme.
The code-table-selector serves two essential purposes within CESR's architecture:
Table Selection Function: It determines which code table the parser should use to interpret subsequent characters in the stream. CESR supports multiple code tables optimized for different use cases, and the selector character indicates whether to use the default code table or switch to an alternate table.
Type Encoding Function: For the most frequently used primitives that have a pad size of 1, the selector character simultaneously serves as the type code itself within the default code table. This dual-purpose design maximizes encoding efficiency by eliminating redundant characters.
This dual-purpose constraint is explicitly stated in the specification: "the 1 character text code table must do double duty. It must provide selectors for the different text code tables and also provide type codes for the most popular primitives that have a pad size of 1 that appear in the default code table."
The code-table-selector is positioned at the stream boundary - it is always the first character a parser encounters when beginning to process a CESR stream or when transitioning between different encoding contexts. This positioning is critical for enabling cold start stream parsing, where a parser can begin processing a stream without prior context by examining the initial character.
Implementations MUST maintain a complete registry of code tables that maps selector characters to primitive specifications. The registry must include:
The registry must be version-aware to support multiple CESR versions. Different versions may assign different meanings to the same selector character.
Implementations MUST validate selector characters at multiple levels:
[A-Z, a-z, 0-9, -, _]Invalid selectors should trigger appropriate error handling, such as:
The selector must drive the core stream parsing logic:
def parse_primitive(stream: str, pos: int) -> tuple:
# Read selector
selector = stream[pos]
# Determine code table
if selector in DEFAULT_TABLE:
table = DEFAULT_TABLE
type_code = selector
elif selector in TABLE_SELECTORS:
# Switch to alternate table
table_name = TABLE_SELECTORS[selector]
table = CODE_TABLES[table_name]
# Read additional characters for type code
type_code = stream[pos+1:pos+1+table['code_length']]
else:
raise ValueError(f"Invalid selector: {selector}")
# Lookup primitive specification
spec = table[type_code]
# Extract primitive
prim_length = spec['length']
primitive = stream[pos:pos+prim_length]
return (primitive, pos + prim_length)
The selector character is drawn from the URL-safe Base64 character set defined in RFC-4648: [A-Z, a-z, 0-9, -, _]. This 64-character alphabet provides sufficient space to encode both table selection information and type codes for common primitives within a single character.
The code-table-selector integrates with several key CESR components:
Code Tables: The selector references specific code tables that define the mapping between character sequences and primitive types. Each code table is optimized for different primitive categories (e.g., cryptographic keys, digests, signatures).
Derivation Codes: The selector may itself be a derivation code for common primitives, encoding both the cryptographic algorithm and the expected length of the primitive.
Framing Codes: The selector is the first element of the framing code structure that enables self-framing primitives - primitives that contain all information needed to parse them without external delimiters.
The code-table-selector is encoded as a single Base64 URL-safe character, which represents 6 bits of information. This provides 64 possible values (2^6 = 64), allowing the selector to distinguish between:
The Base64 URL-safe character set ensures that CESR streams can be safely transmitted through text-based protocols (HTTP headers, JSON, URLs) without requiring additional escaping or encoding.
While the code-table-selector is a single character, it encodes multiple logical fields through its value:
Table Selection Field: Certain character values indicate that the parser should switch from the default code table to an alternate table. For example, specific characters might indicate:
Type Code Field: When the selector character indicates the default table, the character itself serves as the type code for primitives with pad size 1. This includes some of the most frequently used primitives in KERI applications, such as certain public key types and digest algorithms.
The code-table-selector has strict size constraints that derive from CESR's 24-bit alignment requirement:
The 24-bit alignment constraint is fundamental to CESR's composability property - the ability to convert concatenated primitives between text and binary domains without loss. Since Base64 characters encode 6 bits and bytes encode 8 bits, 24 bits (the least common multiple of 6 and 8) is the minimum alignment boundary that ensures clean conversion.
The code-table-selector participates in CESR's pre-padding encoding scheme. Unlike naive Base64 encoding that uses trailing = pad characters, CESR uses leading pad bytes ("lead bytes") prepended to raw binary values before Base64 conversion. The selector character is part of the encoded representation that results from this pre-padding process.
For primitives with pad size 1, the encoding process works as follows:
This encoding scheme ensures that the selector character is always present and always in the first position, enabling efficient stream parsing.
The code-table-selector is created during the primitive serialization process when converting from the Raw Domain (where cryptographic operations occur) to the Text Domain (where streaming and transmission occur).
Serialization Process:
Primitive Type Determination: The serializer determines the type of primitive being encoded (e.g., Ed25519 public key, Blake3-256 digest, Ed25519 signature)
Pad Size Calculation: The serializer calculates the pad size required for 24-bit alignment: ps = (3 - (N mod 3)) mod 3 where N is the raw binary length in bytes
Code Table Selection: Based on the primitive type and pad size, the serializer selects the appropriate code table and determines the selector character
Selector Assignment: For primitives with pad size 1 in the default table, the selector character is assigned as the type code. For other cases, the selector indicates which code table to use for interpreting subsequent characters.
Stream Composition: The selector character is prepended to the encoded primitive, forming the first character of the serialized representation
The code-table-selector is the first element examined during stream parsing, enabling the parser to determine how to process subsequent characters.
Parsing Process:
Character Extraction: The parser reads the first character from the CESR stream
Table Lookup: The parser uses the selector character to look up the appropriate code table. This lookup determines:
Primitive Extraction: Based on the code table information, the parser extracts the exact number of characters needed for the complete primitive
Domain Conversion: If needed, the parser converts the text domain representation to binary or raw domain for cryptographic verification
Stream Advancement: The parser advances to the next primitive in the stream, which begins with its own code-table-selector
This parsing process enables self-framing - each primitive contains all information needed to parse it without external delimiters or length fields.
The code-table-selector participates in several verification processes:
Stream Integrity Verification:
Type Validation:
Composability Verification:
The code-table-selector is used throughout the KERI protocol stack and related technologies:
KERI Key Event Logs (KEL):
ACDC Credentials (ACDC):
OOBI Discovery (OOBI):
Transaction Event Logs (TEL):
The code-table-selector has a simple lifecycle tied to the primitive it prefixes:
Creation: The selector is assigned during primitive serialization based on the primitive type and pad size
Transmission: The selector is transmitted as the first character of the primitive in CESR streams
Storage: The selector is stored as part of the primitive representation in databases, files, and logs
Parsing: The selector is read and interpreted during stream parsing to determine primitive boundaries
Verification: The selector is validated during cryptographic verification to ensure proper primitive typing
Archival: The selector remains part of the primitive representation in long-term storage, ensuring future parseability
The selector does not have independent lifecycle events - it is always part of a larger primitive and shares that primitive's lifecycle.
The code-table-selector interacts with several related CESR structures:
Derivation Codes: The selector may itself be a derivation code that indicates the cryptographic algorithm used to derive a key or digest. For example, a selector character might indicate "Ed25519 public key" or "Blake3-256 digest."
Count Codes: For group framing, the selector may indicate a count code table that provides information about the number of primitives in a group. This enables efficient parsing of primitive groups without scanning the entire group.
Framing Codes: The selector is the first component of a framing code - a code that delineates the number of characters or bytes that can be extracted atomically from a stream.
Code Tables: The selector references specific code tables that define the mapping between character sequences and primitive types. CESR maintains multiple code tables optimized for different primitive categories.
Primitives: The selector prefixes primitives - serialized values associated with cryptographic operations including digests, salts, seeds, private keys, public keys, and signatures.
The code-table-selector enables several critical stream processing capabilities:
Cold Start Parsing: A parser can begin processing a CESR stream at any primitive boundary by reading the selector character. This enables efficient stream processing without requiring the parser to scan from the beginning of the stream.
Multiplexing: Multiple CESR streams can be multiplexed into a single stream, with each primitive maintaining its selector. Demultiplexing is straightforward because each primitive is self-framing.
Pipelining: CESR streams can be processed in a pipelined fashion, with different stages operating on different primitives concurrently. The selector enables each stage to quickly determine primitive boundaries.
Partial Parsing: Applications can parse only the primitives they need from a stream by examining selectors and skipping primitives that are not relevant. This enables efficient filtering and routing of CESR streams.
Error Recovery: If a parser encounters an invalid primitive, it can attempt to resynchronize by scanning for the next valid selector character. This provides some resilience to stream corruption.
The code-table-selector participates in CESR's version management through the CESR-version mechanism:
Version Specification: A special count code can specify the version of all CESR code tables in a given stream or stream section. This version information affects how selectors are interpreted.
Backward Compatibility: New versions of CESR may introduce new selector characters or redefine existing ones. The version specification ensures that parsers interpret selectors according to the correct version.
Forward Compatibility: Reserved selector values enable future extensions without breaking existing parsers. Parsers encountering unknown selectors can skip the primitive or signal an error.
The code-table-selector design has significant performance implications:
Single-Character Lookup: The selector enables primitive type determination with a single character lookup, minimizing parsing overhead.
No Scanning Required: Unlike delimited formats that require scanning for delimiters, the selector provides immediate information about primitive boundaries.
Cache-Friendly: The selector enables predictable memory access patterns, improving CPU cache utilization during stream processing.
Minimal Overhead: The selector adds only 1 character (6 bits) of overhead per primitive, which is minimal compared to alternative framing schemes.
Efficient Conversion: The selector participates in CESR's efficient text-binary conversion, which operates on 24-bit aligned blocks without bit-level manipulation.
These performance characteristics make CESR suitable for high-throughput applications such as witness pools processing thousands of key events per second or watcher networks synchronizing large KERLs.
Implementing code-table-selector support requires careful attention to several technical details:
Code Table Registry: Implementations must maintain a registry of code tables that maps selector characters to primitive types and lengths. This registry must be version-aware to support multiple CESR versions.
Selector Validation: Implementations must validate that selector characters are valid Base64 URL-safe characters and map to defined code table entries. Invalid selectors should trigger appropriate error handling.
Alignment Verification: Implementations must verify that primitives maintain 24-bit alignment. The selector contributes to this alignment, and implementations must ensure that the complete primitive (selector + value) has a length that is an integer multiple of 4 characters.
Domain Conversion: Implementations must correctly handle selector characters during text-binary domain conversion. The selector must be preserved during round-trip conversion to maintain primitive parseability.
Stream Parsing: Implementations must use the selector to drive stream parsing logic, extracting the correct number of characters for each primitive based on the selector's code table entry.
Error Recovery: Implementations should provide mechanisms for recovering from invalid selectors, such as scanning for the next valid selector character or signaling a stream error.
These implementation considerations are critical for ensuring interoperability between different CESR implementations and maintaining the protocol's security and reliability properties.
When converting between text and binary domains, the selector must be preserved:
Text to Binary: The selector character (6 bits) becomes part of the first byte in binary representation. Implementations must correctly pack the selector bits with subsequent value bits.
Binary to Text: The first byte (containing selector bits) must be correctly unpacked to reconstruct the selector character.
Round-trip conversion (text → binary → text) MUST preserve the selector character exactly. This is critical for maintaining CESR's composability property.
For high-performance implementations:
Implementations should provide mechanisms for recovering from invalid selectors:
def parse_with_recovery(stream: str) -> list:
primitives = []
pos = 0
while pos < len(stream):
try:
prim, new_pos = parse_primitive(stream, pos)
primitives.append(prim)
pos = new_pos
except ValueError as e:
# Log error
logger.warning(f"Invalid primitive at {pos}: {e}")
# Attempt to find next valid selector
pos = find_next_selector(stream, pos + 1)
if pos == -1:
break # No more valid selectors
return primitives
Implementations must test:
The selector is part of the security-critical parsing path: