The dual text-binary encoding format maintains cryptographic integrity through several mechanisms:

Derivation Code Binding: Each primitive includes a prepended derivation code that specifies the cryptographic algorithm used. This code is preserved across domain transformations, ensuring that a digest computed in one domain can be verified in the other domain. For example, a Blake3-256 digest with derivation code E in text domain (EABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop) converts to binary domain while maintaining the same cryptographic commitment.

24-Bit Boundary Alignment: The encoding achieves composability through strict alignment to 24-bit boundaries—the least common multiple of 6 bits (Base64 character width) and 8 bits (byte width). Every primitive in the text domain must be an integer multiple of 4 Base64 characters (24 bits), and every primitive in the binary domain must be an integer multiple of 3 bytes (24 bits). This alignment ensures that concatenated primitives can be converted en masse without crossing primitive boundaries.

Self-Framing Structure: Each primitive is self-framing, embedding type, size, and value information. This structure enables parsers to extract primitives from streams without external delimiters, and the self-framing property is preserved across domain transformations. A parser can determine primitive boundaries in either domain without needing to parse the entire primitive content.

Security Guarantees

The dual format provides several security guarantees:

Non-Repudiation: Digital signatures created in one domain remain verifiable in the other domain. A signature computed over text-domain data can be verified against binary-domain data after proper transformation, maintaining non-repudiation properties.

Tamper Evidence: Any modification to a primitive in either domain will be detected upon verification. The cryptographic binding between derivation codes and primitive values ensures that tampering is evident regardless of which domain is used for storage or transmission.

Algorithm Agility: The derivation code system supports multiple cryptographic algorithms within the same encoding framework. This enables post-quantum algorithm migration without breaking the dual format property—new algorithms can be added with new derivation codes while maintaining backward compatibility.

Data Format & Encoding

Text Domain Representation

The text domain uses Base64 URL-safe encoding with the character set A-Z, a-z, 0-9, -, _. This 64-character alphabet avoids problematic characters for URLs and file systems. Each Base64 character represents 6 bits of information.

A typical text-domain primitive structure:

[Derivation Code][Base64 Encoded Value]

For example, a Blake3-256 digest:

EABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop

• E: Derivation code indicating Blake3-256
• Remaining 43 characters: Base64-encoded 32-byte digest
• Total length: 44 characters (264 bits, divisible by 24)

Binary Domain Representation

The binary domain represents the same information in compact byte form. The derivation code is encoded in the first byte(s), followed by the raw cryptographic material.

For the same Blake3-256 digest:

[0x1C][32 bytes of digest]

• 0x1C: Binary derivation code for Blake3-256
• Following 32 bytes: Raw digest value
• Total length: 33 bytes (264 bits, divisible by 24)

Derivation Codes and Padding

CESR uses prepended derivation codes rather than traditional pad characters. In standard Base64, the = character pads strings to 4-character boundaries. CESR eliminates this by:

1. Pre-padding: Adding leading bytes before encoding to achieve 24-bit alignment
2. Code replacement: Using the derivation code itself to indicate padding requirements
3. Lead bytes: For primitives that don't naturally align, prepending bytes that are later replaced by the derivation code

This approach ensures that:

• No = pad characters appear in CESR streams
• Derivation codes encode both algorithm type and padding information
• Primitives remain self-framing in both domains

Transformation Algorithms

Text-to-Binary Transformation (T2B):

1. Parse derivation code from text primitive
2. Determine primitive length from code table
3. Extract Base64 characters
4. Decode Base64 to raw bytes
5. Prepend binary derivation code
6. Output binary primitive

Binary-to-Text Transformation (B2T):

1. Parse binary derivation code
2. Determine primitive length from code table
3. Extract raw bytes
4. Encode bytes to Base64
5. Prepend text derivation code
6. Output text primitive

These transformations are lossless and reversible, satisfying the composability property for concatenated primitives.

Usage in KERI/ACDC

Key Event Logs (KELs)

Key Event Logs leverage dual format encoding extensively:

Inception Events: The inception event contains the initial public key(s) and configuration. In text domain, this enables human-readable audit logs and debugging. In binary domain, it provides compact storage and efficient transmission to witnesses.

Rotation Events: Key rotation events include current keys, next key digests, and signatures. The dual format allows developers to inspect rotation logic in text form while production systems use binary for performance.

Interaction Events: Interaction events anchor external data through seals. These seals are CESR-encoded digests that benefit from dual format—text for human verification of anchored data, binary for efficient event log storage.

ACDC Credentials

ACDCs (Authentic Chained Data Containers) use dual format for:

SAIDs: Self-Addressing Identifiers are CESR-encoded digests that identify credential blocks. Text format enables URL-based credential references, while binary format supports compact credential chains.

Attribute Commitments: Selectively disclosable attributes use CESR-encoded digests as commitments. The dual format allows:

• Text domain: Human-readable credential schemas and disclosure policies
• Binary domain: Efficient credential presentation and verification

Edge References: ACDC edges that link credentials use CESR-encoded AIDs and SAIDs. Dual format enables both human-readable credential graphs and efficient graph traversal algorithms.

Witness Receipts

Witness receipts are CESR-encoded signatures attached to key events. The dual format provides:

Development: Text-domain receipts in log files for debugging witness consensus issues Production: Binary-domain receipts for efficient network transmission and storage Verification: Format-agnostic verification—receipts can be verified regardless of storage format

OOBI Resolution

Out-of-Band Introductions use dual format for:

URL Encoding: Text-domain AIDs in OOBI URLs for web-based identifier discovery Response Payloads: Binary-domain KEL transmission for efficient bootstrap Caching: Format conversion based on cache requirements (text for debugging, binary for production)

Related Primitives

Composability Property

The dual format is fundamentally enabled by composability—the mathematical property that concatenated primitive transformations preserve primitive boundaries. Without composability, dual format would require primitive-by-primitive conversion, losing the efficiency advantages.

Self-Framing

Self-framing primitives embed type, size, and value information, enabling parsers to extract primitives without external delimiters. This property is essential for dual format because it ensures primitives remain parseable in both domains without requiring format-specific delimiters.

Count Codes

CESR count codes enable grouping of primitives for efficient stream processing. Count codes themselves are dual-format primitives that specify how many subsequent primitives belong to a group, enabling pipelined parsing in both text and binary domains.

Qualified Primitives

Qualified primitives include prepended derivation codes that specify cryptographic algorithms. This qualification is preserved across domain transformations, ensuring that algorithm information travels with the primitive regardless of format.

Implementation Considerations

Performance Optimization

Lazy Conversion: Implementations should avoid unnecessary format conversions. Store primitives in the format most appropriate for the use case and convert only when required by protocol or API boundaries.

Batch Processing: When converting multiple primitives, leverage composability to perform en-masse conversion rather than primitive-by-primitive transformation. This reduces overhead and improves throughput.

Code Table Caching: Derivation code tables should be cached in memory to avoid repeated lookups during parsing. The code table maps derivation codes to primitive types, lengths, and padding requirements.

Error Handling

Invalid Derivation Codes: Parsers must reject primitives with unrecognized derivation codes rather than attempting to guess the format. This prevents security vulnerabilities from malformed primitives.

Boundary Violations: Verify that all primitives align to 24-bit boundaries. Primitives that violate this constraint indicate either corruption or malicious tampering.

Incomplete Streams: When parsing concatenated primitives, detect incomplete primitives at stream boundaries and buffer them for completion rather than treating them as errors.

Testing Strategies

Round-Trip Testing: Verify that B(T(b)) = b and T(B(t)) = t for all primitive types. This ensures lossless conversion.

Concatenation Testing: Test that T(cat(b[k])) = cat(T(b[k])) for various primitive combinations to verify composability.

Boundary Testing: Test primitives at 24-bit boundaries and verify that padding is correctly handled in both domains.

Interoperability

Protocol Negotiation: Systems should negotiate format preference during connection establishment. Text format for debugging/development, binary for production.

Format Detection: Implement sniffable stream detection that can identify whether a CESR stream is in text or binary format by examining the first few bytes/characters.

Hybrid Streams: Support streams that contain both text and binary primitives by using format-specific group codes that indicate domain transitions.

Architectural Significance

The dual text-binary encoding format represents a significant innovation in protocol design, solving the traditional trade-off between developer experience and production performance. By providing mathematically guaranteed composability across domains, CESR enables KERI to achieve:

• Zero-cost abstraction: Format choice becomes a deployment decision rather than a protocol constraint
• Universal tooling: The same parsing logic works in both domains with minimal adaptation
• Cryptographic agility: New algorithms can be added without breaking the dual format property
• Scalable verification: Verifiers can process streams in whichever format is most efficient for their context

This architectural approach has influenced the design of other cryptographic protocols and demonstrates that careful attention to encoding fundamentals can eliminate false dichotomies in protocol design.

Concatenation Composability: Test that concatenated primitives convert correctly as a group, verifying that primitive boundaries are preserved.

Boundary Alignment: Verify that all primitives align to 24-bit boundaries in both domains, and that padding is correctly handled.

Performance Benchmarking: Measure conversion overhead for different primitive types and stream sizes to identify optimization opportunities.