The key architectural distinction is that Bexter treats its payload as text-domain data rather than arbitrary binary data, enabling optimizations specific to Base64-encoded content.

Key Components

Bexter's structure consists of:

• Text Code: Identifies this as a Bexter primitive in the CESR stream
• Leader Bytes: Contain framing information for variable-length parsing
• Base64 Text Value: The actual content, constrained to URL-safe Base64 characters (A-Z, a-z, 0-9, -, _)

Data Format

Field Definitions

Bexter inherits standard Matter properties and adds text-specific functionality:

Inherited from Matter:

• .pad: Number of pad characters given raw input
• .code: Derivation code indicating cipher suite
• .raw: Crypto material bytes without code
• .index: Count of attached crypto material by context
• .qb64: Fully qualified Base64 string with derivation code
• .qb64b: Fully qualified Base64 as bytes
• .qb2: Binary representation with derivation code
• .transferable: Boolean indicating transferable derivation code

Bexter-Specific:

• .text: The Base64 text value with the text code and leader removed from .qb64

Encoding Format

The encoding format follows CESR's variable-length primitive pattern. The documentation provides concrete examples showing the relationship between input text (bext) and encoded output (qb64):

• Empty string: bext = "" → qb64 = '4AAA'
• Single character: bext = "-" → qb64 = '6AABAAA-'
• Two characters: bext = "-A" → qb64 = '5AABAA-A'
• Three characters: bext = "-A-" → qb64 = '4AABA-A-'
• Four characters: bext = "-A-B" → qb64 = '4AAB-A-B'

These examples demonstrate how the leader portion (the characters before the actual text value) varies in length to maintain proper alignment and self-framing properties.

Size and Constraints

Character Set Constraint: Bexter is strictly limited to Base64 URL-safe characters:

• Uppercase letters: A-Z
• Lowercase letters: a-z
• Digits: 0-9
• Hyphen: -
• Underscore: _

Variable Length: Unlike fixed-length primitives, Bexter can represent strings of arbitrary length, with the length encoded in the leader bytes.

Critical Limitation - Leading 'A' Ambiguity: A significant constraint exists for strings beginning with the character 'A' whose length is a multiple of 3 or 4. Due to pre-padding mechanics in the encoding scheme:

• Bexter(bext='ABBB').bext == 'BBB' (leading 'A' is stripped)
• Bexter(bext='BBB').bext == 'BBB' (no leading 'A', preserved)
• Bexter(bext='ABBB').qb64 == '4AABABBB' == Bexter(bext='BBB').qb64 (identical encoding)

This ambiguity means that Bexter should only be used for Base64 strings that never start with 'A'. This is a documented design constraint rather than a bug, arising from the interaction between CESR's padding rules and Base64 encoding.

Operations

Creation and Initialization

Bexter instances are created by providing Base64 text through the bext parameter:

bexter_instance = Bexter(bext="-A-B")

The initialization process:

1. Validates that the input contains only Base64 URL-safe characters
2. Computes the appropriate leader bytes based on string length
3. Constructs the qb64 representation
4. Stores both the encoded form and provides access to the decoded text via .text

Updates and Modifications

As with other CESR primitives, Bexter instances are typically immutable once created. The design philosophy of CESR emphasizes creating new primitives rather than modifying existing ones, which supports:

• Cryptographic integrity: Immutable primitives can be reliably hashed and signed
• Stream processing: Parsers can process primitives atomically without tracking state changes
• Concurrent access: Immutability eliminates race conditions in multi-threaded environments

Verification and Validation

Validation operations for Bexter include:

1. Character Set Validation: Ensuring all characters are Base64 URL-safe
2. Length Consistency: Verifying that the leader bytes correctly encode the text length
3. Round-Trip Verification: Confirming that encoding and decoding preserve the original text (except for the documented leading 'A' edge case)
4. Framing Validation: Ensuring the primitive can be correctly extracted from a CESR stream

Usage Context

Primary Applications

The documentation identifies two specific use cases where Bexter is the optimal primitive choice:

1. CESR-Encoded Paths for Nested SADs and SAIDs

Bexter is used to encode paths that navigate through nested Self-Addressing Data (SAD) structures and Self-Addressing Identifiers (SAID). In ACDC credentials and other KERI data structures, complex nested hierarchies often require path expressions to reference specific fields or sub-structures.

For example, a path like "attributes/legalEntity/LEI" can be efficiently encoded as a Bexter primitive, allowing it to be embedded in CESR streams alongside other cryptographic material. The Base64-compatible path components ensure compact representation while maintaining human readability in the text domain.

2. CESR-Encoded Fractionally Weighted Threshold Expressions

In multi-signature schemes, KERI supports fractionally weighted thresholds where different keys can have different voting weights. These threshold expressions, when represented as Base64-compatible strings, can be efficiently encoded using Bexter.

For instance, a threshold expression might specify that signatures from keys with combined weight ≥ 2/3 are required. When such expressions are encoded in a Base64-compatible format, Bexter provides the optimal primitive for including them in establishment events or other KERI messages.

Protocol Integration

Bexter integrates into the broader KERI protocol stack:

In KEL Events: Bexter primitives may appear in key event logs when events include path references or threshold expressions.

In ACDC Credentials: Authentic Chained Data Containers may use Bexter for encoding paths in selective disclosure mechanisms or for referencing nested attributes.

In CESR Streams: Bexter primitives can be freely mixed with other primitive types in CESR streams, maintaining the composability property that allows seamless concatenation and parsing.

Lifecycle Management

The lifecycle of a Bexter primitive typically follows this pattern:

1. Creation: Instantiated with Base64 text when constructing a KERI message or data structure
2. Serialization: Encoded into qb64 format for inclusion in text-domain streams or qb2 format for binary streams
3. Transmission: Sent as part of a CESR stream over network protocols
4. Parsing: Extracted from the stream by a CESR parser using the self-framing properties
5. Validation: Character set and structural validation performed
6. Utilization: The .text property accessed to retrieve the original Base64 string for application logic

Related Structures

Bexter exists within an ecosystem of related CESR primitives:

Matter Class: The parent class providing core primitive functionality. All Bexter instances are Matter instances, inheriting standard properties and methods.

Other Variable-Length Primitives: CESR includes other variable-length primitive types for different data categories (raw bytes, numbers, etc.). Bexter is specifically optimized for Base64 text.

Fixed-Length Primitives: In contrast to Bexter's variable length, CESR also defines fixed-length primitives for common cryptographic outputs (256-bit hashes, Ed25519 signatures, etc.).

Count Codes and Group Codes: These CESR constructs enable grouping of primitives, including Bexter instances, for efficient stream processing and pipelining.

Implementation Considerations

Performance Characteristics

Bexter's design prioritizes:

• Compact Encoding: More efficient than treating Base64 text as raw bytes
• Fast Parsing: Self-framing enables single-pass stream parsing
• Minimal Overhead: Leader bytes add minimal size overhead while enabling variable length

Edge Cases and Limitations

Implementers must be aware of:

1. Leading 'A' Constraint: Applications must ensure Bexter is only used for strings that don't start with 'A' (or accept the documented ambiguity)
2. Character Set Enforcement: Validation must reject non-Base64 characters
3. Length Encoding Limits: While theoretically supporting very long strings, practical implementations may impose maximum length constraints

Interoperability

Bexter's role in CESR ensures interoperability:

• Cross-Language: The encoding specification enables consistent implementation across Python (keripy), Rust (keriox), TypeScript, and other languages
• Domain Conversion: Perfect round-trip conversion between text and binary domains (except documented edge case)
• Stream Mixing: Bexter primitives can be freely mixed with other primitive types in heterogeneous streams

Relationship to KERI Architecture

Bexter represents a specialized component in KERI's broader architecture:

Composability: By providing efficient Base64 text encoding, Bexter supports CESR's goal of composable streams where different primitive types can be seamlessly concatenated.

Self-Framing: The variable-length encoding with embedded length information enables parsers to extract Bexter primitives from streams without external context.

Dual-Domain Support: Bexter's ability to represent the same data in both text (qb64) and binary (qb2) domains supports KERI's goal of protocol flexibility across different transport mechanisms.

Cryptographic Integrity: While Bexter itself doesn't contain cryptographic material, it can be included in signed messages, with the signature covering the entire CESR stream including any Bexter primitives.

This primitive type exemplifies KERI's design philosophy of creating minimal, composable building blocks that can be combined to support complex protocols while maintaining verifiability and efficiency.

Interoperability testing should verify that Bexter primitives created in one language can be correctly parsed and decoded in all other language implementations.

Error Handling

Implementations should provide clear error messages for:

• Invalid characters in input text
• Malformed qb64/qb2 input during parsing
• Length mismatches between leader and actual content
• Attempts to create Bexter from non-Base64 content

Integration with Matter Class

Since Bexter is a Matter subclass, implementations must:

• Properly initialize all inherited properties
• Override methods as needed for text-specific behavior
• Maintain compatibility with generic Matter-handling code
• Support polymorphic use where Matter instances are expected