• Consists of exactly 3 bytes (a triplet)
• Encodes the same 24 bits of information (3 bytes × 8 bits/byte)
• Compact representation suitable for efficient transmission and storage
• Example: 0x300001 represents the same information as text MAAB

The critical property is that these representations are mathematically equivalent and bidirectionally convertible without information loss. This equivalence enables CESR's composability property, where concatenated primitives can be converted en masse between domains while maintaining individual primitive separability.

Key Components

A quadlet typically contains two logical components when used in variable-length encoding:

1. Length Information: Encoded in Base64 characters (represented abstractly as # in specifications), indicating the size of the associated variable-length value in quadlets (text domain) or triplets (binary domain)

2. Value Portion: The actual data being encoded, which may span multiple quadlets depending on the primitive's size

For example, in the CESR variable-length byte string codes:

• 4B## uses a 4-character code where the first 2 characters (4B) identify the code type and lead size, and the next 2 characters (##) encode the length
• The length value indicates how many quadlets follow to represent the actual data

Data Format

Field Definitions

Quadlets do not have traditional "fields" in the sense of structured data formats. Instead, they represent atomic encoding units whose interpretation depends on context within a CESR stream. The meaning of a quadlet is determined by:

Position in Stream: The first quadlet(s) of a primitive typically contain framing codes that specify the primitive type and size

Code Table Context: CESR uses multiple code tables, and the active table determines how quadlet contents are interpreted

Primitive Type: Different primitive types (digests, signatures, keys, etc.) use quadlets differently based on their encoding requirements

Encoding Format

The encoding format for quadlets follows strict rules to maintain composability:

Base64 URL-Safe Encoding (Text Domain):

• Uses the character set defined in RFC-4648 for URL-safe Base64
• Each character encodes 6 bits of information
• The = pad character is never used in CESR
• Instead, CESR uses pre-padding with lead bytes before Base64 conversion

Binary Encoding (Binary Domain):

• Raw bytes with no additional encoding
• Direct representation of the underlying binary data
• Maintains the same logical structure as text domain

Lead Padding Algorithm:

For variable-length values, CESR applies lead padding to ensure 24-bit alignment. The number of lead pad bytes (ps) is calculated as:

ps = (3 - (rs % 3)) % 3

Where rs is the raw size in bytes. This formula ensures:

• When rs % 3 = 0: No padding needed (ps = 0)
• When rs % 3 = 1: Two lead bytes added (ps = 2)
• When rs % 3 = 2: One lead byte added (ps = 1)

The lead bytes are prepended to the raw value before Base64 conversion, and the resulting Base64 characters corresponding to these lead bytes can be replaced with derivation codes without affecting the value encoding.

Size and Constraints

Fixed Size Constraint:

• Text domain: Always exactly 4 Base64 characters
• Binary domain: Always exactly 3 bytes
• This fixed size is fundamental to CESR's composability property

Variable-Length Primitive Support:

Quadlets enable variable-length primitives through length encoding. CESR defines two size ranges:

Small Codes (supporting up to 4,095 quadlets/triplets):

• Use 2-character length fields
• Can encode lengths from 0 to 4,095 (12 bits: 2 characters × 6 bits)
• Examples: 4B##, 5B##, 6B## for different lead sizes

Big Codes (supporting up to 16,777,215 quadlets/triplets):

• Use 4-character length fields
• Can encode lengths from 0 to 16,777,215 (24 bits: 4 characters × 6 bits)
• Examples: 7AAB####, 8AAB####, 9AAB#### for different lead sizes

Maximum Primitive Sizes:

• Small codes: 4,095 quadlets × 3 bytes/quadlet = 12,285 bytes maximum
• Big codes: 16,777,215 quadlets × 3 bytes/quadlet ≈ 50.3 MB maximum

These size limits accommodate virtually all cryptographic primitives used in practice, from small digests and signatures to large data structures like ACDCs.

Operations

Creation and Initialization

Encoding Process (Raw to Text Domain):

1. Calculate Pad Size: Determine lead padding needed using ps = (3 - (rs % 3)) % 3
2. Prepend Lead Bytes: Add ps zero bytes to the beginning of the raw value
3. Base64 Conversion: Convert the padded binary to Base64 URL-safe encoding
4. Replace Lead Characters: The first characters resulting from lead bytes can be replaced with derivation codes
5. Verify Alignment: Ensure the result is an integer multiple of 4 characters (quadlets)

Example Encoding:

For a 2-byte value 0x0001:

• Raw size: rs = 2
• Pad size: ps = (3 - (2 % 3)) % 3 = 1
• Padded value: 0x000001 (1 lead byte + 2 value bytes)
• Base64 result: AAAB (4 characters = 1 quadlet)
• The first character A (from lead byte) can be replaced with a type code

Decoding Process (Text to Raw Domain):

1. Extract Derivation Code: Read the leading characters to determine primitive type and lead size
2. Determine Value Length: Calculate how many quadlets contain the actual value
3. Base64 Decode: Convert the Base64 characters to binary
4. Remove Lead Bytes: Strip the ps leading bytes based on the derivation code
5. Extract Raw Value: The remaining bytes are the raw cryptographic material

Updates and Modifications

Quadlets themselves are immutable once created, as they represent atomic encoding units. However, primitives composed of multiple quadlets can be modified by:

Concatenation: Multiple quadlets can be concatenated to form longer primitives

Stream Assembly: Quadlets from different primitives can be concatenated in CESR streams, maintaining separability due to self-framing properties

Domain Conversion: Quadlets can be converted between text and binary domains:

• Text to Binary: T2B transformation converts 4 Base64 characters to 3 bytes
• Binary to Text: B2T transformation converts 3 bytes to 4 Base64 characters

Group Conversion: The composability property enables en masse conversion of concatenated quadlets:

T(cat(b[k])) = cat(T(b[k])) for all k
B(cat(t[k])) = cat(B(t[k])) for all k

This means converting a stream of concatenated primitives produces the same result as converting each primitive individually and then concatenating.

Verification and Validation

Alignment Verification:

All CESR primitives must verify 24-bit alignment:

• Text domain: Length must be divisible by 4 (integer number of quadlets)
• Binary domain: Length must be divisible by 3 (integer number of triplets)
• Misaligned primitives indicate parsing errors or corrupted streams

Code Table Validation:

The first quadlet(s) of a primitive contain derivation codes that must be validated against the active code table:

• Verify the code exists in the current table
• Confirm the code's lead size matches the primitive structure
• Validate that the indicated length is consistent with the available stream data

Composability Verification:

Round-trip conversion tests verify composability:

Original Text -> T2B -> Binary -> B2T -> Recovered Text

The recovered text must exactly match the original, confirming no information loss.

Stream Parsing Validation:

CESR parsers use quadlet boundaries to validate stream integrity:

• Extract the first quadlet(s) to determine primitive type and length
• Verify sufficient quadlets remain in the stream
• Parse the indicated number of quadlets
• Repeat for subsequent primitives

Any failure in this process indicates stream corruption or protocol violation.

Usage Context

In Which Protocols

Quadlets are fundamental to the entire KERI protocol suite:

KERI (Key Event Receipt Infrastructure):

• Key Event Logs (KELs) use quadlet-based encoding for all cryptographic primitives
• Witnesses and watchers exchange quadlet-encoded receipts
• Establishment events and interaction events are serialized using quadlet-aligned CESR

ACDC (Authentic Chained Data Containers):

• SAIDs (Self-Addressing Identifiers) are encoded as quadlet-aligned primitives
• Credential signatures and seals use quadlet encoding
• Selective disclosure mechanisms rely on quadlet-based compact disclosure

CESR-Proof Signatures:

• SAD Path Language uses Base64-compatible paths that align with quadlet boundaries
• Signature attachments are encoded as quadlet-aligned primitives
• Transposable signatures maintain quadlet alignment across envelope boundaries

TSP (Trust Spanning Protocol):

• VID (Verifiable Identifier) serialization uses quadlet-based variable-length encoding
• Open mode VIDs use codes like 4B##, 5B##, 6B## that specify length in quadlets
• Tunneled payloads maintain quadlet alignment for efficient parsing

OOBI (Out-Of-Band Introduction):

• OOBI URLs may contain quadlet-encoded AIDs
• Witness and watcher endpoint information uses quadlet encoding

Lifecycle Management

Stream Processing Lifecycle:

1. Cold Start: Parser begins processing a CESR stream by reading the first quadlet(s) to determine the code table selector

2. Primitive Extraction: For each primitive:

   • Read framing quadlet(s) to determine type and length
   • Extract the specified number of quadlets
   • Validate alignment and code table consistency

3. Domain Conversion: Convert between text and binary domains as needed:

   • Text domain for debugging, logging, archival
   • Binary domain for transmission, storage efficiency

4. Validation: Verify cryptographic properties:

   • Signature verification using extracted public keys
   • Digest validation for SAIDs
   • Seal verification for anchored data

5. Stream Continuation: Process subsequent primitives until stream end or error

Error Handling:

Quadlet-based parsing enables robust error detection:

• Alignment Errors: Non-quadlet-aligned data indicates corruption
• Code Table Errors: Invalid codes trigger parser rejection
• Length Errors: Insufficient quadlets for declared length indicates truncation
• Composability Errors: Failed round-trip conversion indicates protocol violation

Related Structures

Triplets (Binary Domain Equivalent):

A triplet is the binary domain equivalent of a quadlet, consisting of exactly 3 bytes (24 bits). The relationship is:

• 1 quadlet (4 Base64 characters) ↔ 1 triplet (3 bytes)
• Both encode exactly 24 bits of information
• Conversion between them is lossless and bidirectional

Primitives:

Cryptographic primitives are composed of one or more quadlets:

• Fixed-size primitives: Use a predetermined number of quadlets (e.g., Ed25519 public keys use specific quadlet counts)
• Variable-size primitives: Use length-encoding quadlets followed by value quadlets

Count Codes:

Count codes use quadlets to specify the number of subsequent primitives in a group:

• Enable pipelining and efficient stream processing
• Support hierarchical grouping of primitives
• Maintain quadlet alignment for composability

Framing Codes:

Framing codes occupy the first quadlet(s) of a primitive:

• Specify the primitive type (digest, signature, key, etc.)
• Indicate the lead size for proper decoding
• Determine the total length of the primitive

Self-Framing Primitives:

Self-framing primitives use quadlets to encode all necessary parsing information:

• Type information in leading quadlet(s)
• Size information enabling atomic extraction
• Value data in subsequent quadlets
• No external delimiters or envelopes required

This self-framing property, enabled by quadlet-based encoding, is essential for CESR's cold start stream parsing capability, where parsers can begin processing at any point in a stream without prior context.

Implementation Considerations

Performance Optimization:

Implementations should optimize quadlet operations:

• Batch Conversion: Convert multiple quadlets simultaneously using SIMD instructions
• Lookup Tables: Pre-compute Base64 encoding/decoding tables for 24-bit values
• Zero-Copy Parsing: Process quadlets in-place without intermediate buffers when possible

Memory Alignment:

Quadlet-based encoding naturally aligns with modern CPU architectures:

• 24-bit boundaries align with 32-bit and 64-bit word sizes
• Enables efficient memory access patterns
• Reduces cache misses in stream processing

Streaming Protocols:

Quadlet encoding is optimized for streaming:

• TCP Streams: Quadlets can be transmitted and parsed incrementally
• UDP Datagrams: Quadlet alignment enables efficient packetization
• HTTP: Quadlet-encoded CESR can be transmitted in HTTP bodies or headers

Interoperability:

Quadlet-based CESR ensures interoperability:

• Language-Agnostic: Implementations in Python, Rust, JavaScript, Go, etc. all produce identical quadlet encodings
• Version-Stable: Quadlet structure is fundamental and will not change across CESR versions
• Tool-Friendly: Text domain quadlets are human-readable and tool-parseable

• Non-quadlet-aligned text streams
• Non-triplet-aligned binary streams
• Truncated primitives (insufficient quadlets for declared length)

Code Table Errors:

• Invalid derivation codes not in active table
• Mismatched lead size indicators
• Unsupported primitive types

Composability Errors:

• Failed round-trip conversion tests
• Bit-level corruption during domain conversion
• Primitive boundary violations

Testing Requirements

Composability Tests: Verify round-trip conversion:

assert T(B(T(original))) == original
assert B(T(B(original))) == original

Alignment Tests: Verify all primitives maintain alignment:

assert len(text_primitive) % 4 == 0
assert len(binary_primitive) % 3 == 0

Interoperability Tests: Verify cross-implementation compatibility:

• Generate test vectors in one implementation
• Parse and validate in other implementations
• Verify identical results across all implementations

Security Considerations

Input Validation: Always validate quadlet alignment before processing:

• Reject malformed streams early to prevent buffer overflows
• Validate length fields before allocating memory
• Implement maximum primitive size limits

Constant-Time Operations: For cryptographic primitives:

• Use constant-time Base64 encoding/decoding when handling secrets
• Avoid timing side-channels in quadlet processing
• Clear sensitive data from memory after use

Language-Specific Notes

Python: Use bytes and bytearray for binary domain, str for text domain

Rust: Leverage zero-copy parsing with slices and &[u8] references

JavaScript: Use Uint8Array for binary domain, handle Base64 with btoa/atob or Buffer

Go: Use []byte slices and encoding/base64 package

Integration with KERI/ACDC

When implementing quadlet support for KERI/ACDC:

• KEL parsing: Extract quadlet-aligned key events from logs
• ACDC encoding: Ensure all SAIDs and signatures use quadlet alignment
• OOBI handling: Parse quadlet-encoded AIDs from OOBI URLs
• Witness receipts: Encode and decode quadlet-aligned receipt signatures