Distributed Consensus: By collecting receipts from multiple independent witnesses, the KERL provides evidence that key events have been observed by third parties, making it significantly harder for a controller to present different versions of their event history to different validators (duplicitous behavior).

Availability Enhancement: Witnesses maintain copies of the KERL and can provide it to validators even when the controller is offline, enabling indirect mode operation where identifiers remain verifiable without continuous controller presence.

Duplicity Detection: The witness receipt mechanism enables validators to detect when a controller has created conflicting versions of their key event history by comparing receipts from multiple witnesses. This is fundamental to KERI's security model.

Trust Establishment: The KERL provides the evidentiary basis for validators to establish trust in an identifier's current key state by verifying that sufficient non-duplicitous witnesses have attested to the event sequence.

Structural Organization

A KERL is organized as a chronological sequence of establishment events and their associated witness receipts:

Establishment Subsequence: The KERL maintains the complete sequence of establishment events (inception events and rotation events) that define the authoritative key state of the identifier. These events are the only ones that can change which keys control the identifier.

Receipt Attachments: For each establishment event, the KERL includes receipts from witnesses. Each receipt is a signed message from a witness's own AID attesting that the witness observed and verified the event. The receipt includes:

• Reference to the specific event being witnessed (typically via event digest)
• Witness's signature using their own signing keys
• Witness's identifier prefix
• Sequence number indicating the event's position in the log

Threshold Requirements: The KERL must satisfy the witness threshold specified in the identifier's configuration. For example, if an identifier specifies a threshold of 2-of-3 witnesses, each establishment event in the KERL must have receipts from at least 2 of the 3 designated witnesses to be considered properly witnessed.

Key Components

The KERL comprises several essential components:

Base KEL: The foundational sequence of key events produced by the controller, including:

• Inception event establishing the identifier
• Rotation events changing the authoritative key set
• Configuration data specifying witness sets and thresholds

Witness Receipts: Cryptographically signed attestations from witnesses, each containing:

• Witness identifier (the witness's own AID)
• Event reference (digest or sequence number)
• Witness signature
• Timestamp (optional but recommended)

Witness Configuration: Metadata specifying:

• Current witness set (list of witness AIDs)
• Witness threshold (minimum receipts required)
• Witness rotation history (changes to witness set over time)

Consistency Proofs: The cryptographic chain linking events and receipts, enabling validators to verify:

• Event sequence integrity through backward chaining
• Pre-rotation commitments through forward chaining
• Witness attestation validity through signature verification

Data Format

Field Definitions

A KERL does not have a single unified serialization format but rather consists of a KEL plus associated receipt messages. The KEL events follow the standard KERI event format:

Event Structure (using CESR encoding):

{
  "v": "KERI10JSON00011c_",  // Version string
  "t": "icp" or "rot",        // Event type (inception/rotation)
  "d": "EXq5YqaL6L48...",      // Event SAID
  "i": "EXq5YqaL6L48...",      // Identifier prefix
  "s": "0",                    // Sequence number
  "kt": "1",                   // Current signing threshold
  "k": ["DaU6JR2nmwyZ..."],   // Current signing keys
  "nt": "1",                   // Next threshold
  "n": ["EZ-i0d8JZAoT..."],   // Next key digests (pre-rotation)
  "bt": "2",                   // Witness threshold
  "b": ["BGKVzj4ve0V..."],    // Witness identifiers
  "c": [],                     // Configuration traits
  "a": []                      // Anchored data seals
}

Receipt Structure:

{
  "v": "KERI10JSON00011c_",  // Version string
  "t": "rct",                 // Receipt type
  "d": "EXq5YqaL6L48...",      // Event SAID being receipted
  "i": "BGKVzj4ve0V..."       // Witness identifier
}

The receipt is followed by attached signatures from the witness in CESR format.

Encoding Format

KERLs use CESR (Composable Event Streaming Representation) for encoding, which provides:

Dual Text/Binary Support: CESR enables round-trip conversion between human-readable text (Base64) and compact binary representations without loss of information or primitive boundaries.

Self-Framing: Each primitive (event, signature, receipt) includes a derivation code that specifies its type and length, enabling parsers to extract elements from a stream without external schema information.

Composability: Multiple primitives can be concatenated and the stream remains parseable, enabling efficient pipelining and streaming protocols.

Qualified Primitives: All cryptographic material includes prepended codes indicating the algorithm used (e.g., E for Ed25519 public keys, 0B for Ed25519 signatures), making the KERL cryptographically agile.

Size and Constraints

Event Size: Individual key events typically range from 200-500 bytes in text format, depending on:

• Number of current keys (multi-sig configurations)
• Number of pre-rotated key digests
• Number of witnesses
• Presence of anchored data seals

Receipt Size: Each witness receipt adds approximately 100-150 bytes, including:

• Receipt message structure (~50 bytes)
• Witness signature (~88 bytes for Ed25519)
• CESR framing codes (~10 bytes)

KERL Growth: A KERL grows linearly with the number of establishment events and witnesses:

• Each rotation adds one event plus N receipts (where N = witness threshold)
• A typical identifier with 3 witnesses and 10 rotations would have a KERL of approximately 5-10 KB

Practical Limits: While there are no hard protocol limits, practical considerations include:

• Witness set size typically 3-7 witnesses (Byzantine fault tolerance considerations)
• Rotation frequency balanced against operational overhead
• Storage and bandwidth constraints for witness infrastructure

Operations

Creation and Initialization

Inception Process: KERL creation begins with the identifier's inception event:

1. Controller generates inception event specifying:

   • Initial signing keys
   • Pre-rotated key digests
   • Witness set and threshold
   • Configuration traits

2. Controller signs inception event with initial keys

3. Controller promulgates event to witnesses via direct communication or through witness discovery mechanisms (OOBI)

4. Witnesses verify and receipt:

   • Verify event signature against controller's keys
   • Verify event structure and cryptographic bindings
   • Generate receipt message
   • Sign receipt with witness's own keys
   • Return receipt to controller

5. Controller collects receipts until threshold is met

6. KERL is established when sufficient receipts are collected

Witness Selection: Controllers choose witnesses based on:

• Trust relationships (self-hosted, third-party services, or community witnesses)
• Geographic/jurisdictional distribution
• Availability and reliability requirements
• Cost considerations

Updates and Modifications

Rotation Operations: The primary update operation is key rotation:

1. Controller generates rotation event:

   • References previous event via digest
   • Includes new signing keys
   • Includes new pre-rotated key digests
   • May update witness set or threshold
   • Signed with current (pre-rotated) keys

2. Event promulgation to witnesses (same process as inception)

3. Receipt collection until threshold met

4. KERL extension with new event and receipts

Witness Rotation: Controllers can change their witness set through rotation events:

• Add new witnesses to the set
• Remove witnesses from the set
• Change witness threshold
• Witnesses from the previous event must receipt the rotation that changes the witness set

Append-Only Constraint: KERLs are strictly append-only:

• Events cannot be deleted or modified
• Receipts cannot be removed
• The only way to "undo" an event is to rotate to new keys
• This immutability is fundamental to duplicity detection

Verification and Validation

KERL Verification Process: Validators verify a KERL through multiple steps:

1. Event Chain Verification:

• Verify inception event signature against embedded keys
• Verify each rotation event signature against pre-rotated keys from previous event
• Verify backward chaining (each event's digest matches reference in next event)
• Verify forward chaining (rotation keys match pre-committed digests)

2. Receipt Verification:

• For each establishment event, verify sufficient receipts exist (meet threshold)
• Verify each receipt signature against witness's identifier
• Verify receipt references correct event (via digest)
• Verify witnesses are from the designated set

3. Consistency Verification:

• Verify no gaps in sequence numbers
• Verify configuration changes are valid
• Verify witness set changes follow protocol rules
• Verify thresholds are met at each step

4. Duplicity Detection:

• Compare KERL against other copies from different witnesses
• Detect conflicting events at same sequence number
• Detect conflicting receipts from same witness
• Flag any inconsistencies for investigation

Validation Outcomes: Verification produces one of several outcomes:

• Valid: KERL is internally consistent, properly witnessed, and matches other copies
• Invalid: KERL has structural errors, missing receipts, or signature failures
• Duplicitous: KERL conflicts with other verified copies, indicating controller malfeasance
• Incomplete: KERL lacks sufficient receipts (may be in-progress)

Usage Context

In Which Protocols

KERI Core Protocol: KERLs are the fundamental data structure for indirect mode operation in KERI:

• Enable identifier verification when controller is offline
• Provide distributed consensus without blockchain
• Enable ambient duplicity detection
• Support witness-based availability

DID:KERI Method: The did:keri DID method uses KERLs as the authoritative source for DID Document resolution:

• DID Documents are derived from current KERL state
• Resolution involves retrieving and verifying the KERL
• DID operations (create, update, deactivate) map to KERL operations

ACDC Credentials: Authentic Chained Data Container credentials reference KERLs:

• Issuer and issuee identifiers are backed by KERLs
• Credential verification requires KERL verification
• Credential chains follow KERL delegation relationships

IPEX Protocol: Issuance and Presentation Exchange relies on KERLs:

• Parties exchange credentials backed by verified KERLs
• Presentation verification includes KERL verification
• Trust establishment depends on KERL consistency

Lifecycle Management

Active Phase: During normal operation:

• Controller performs rotations as needed (key refresh, security updates)
• Witnesses maintain current KERL copies
• Validators retrieve and verify KERLs on demand
• Watchers monitor for duplicity

Delegation Phase: For hierarchical identifiers:

• Parent KERL must be verified before child KERL
• Delegation events in parent KERL authorize child identifiers
• Child KERLs reference parent events via seals

Recovery Phase: After key compromise:

• Controller rotates to recovery keys (pre-rotated)
• New rotation event extends KERL
• Compromised keys are revoked by rotation
• KERL provides audit trail of compromise and recovery

Abandonment Phase: When identifier is no longer needed:

• Controller rotates to empty next key set (threshold 0)
• This makes identifier non-transferable
• KERL remains verifiable but no further rotations possible
• Historical events remain verifiable indefinitely

Related Structures

KEL (Key Event Log): The base structure that KERL extends:

• KEL contains only controller-signed events
• KERL adds witness receipts to KEL
• KEL is sufficient for direct mode operation
• KERL is required for indirect mode

TEL (Transaction Event Log): Credential-specific event logs:

• TEL tracks credential issuance and revocation
• TEL events are anchored to KERL via seals
• TEL verification requires KERL verification
• TEL provides credential-specific state while KERL provides identifier state

DEL (Duplicitous Event Log): Records of inconsistent behavior:

• DEL contains conflicting events from same controller
• Maintained by jurors and watchers
• Used to prove duplicity
• References events from multiple conflicting KERLs

Witness Pool: Infrastructure supporting KERL creation:

• Witness pool provides available witnesses
• Controllers select witnesses from pool
• Witnesses maintain KERL copies
• Pool enables witness rotation and redundancy

Implementation Considerations

Storage: KERLs require persistent storage:

• Controllers store their own KERL
• Witnesses store KERLs for identifiers they witness
• Watchers store KERLs for identifiers they monitor
• Validators may cache KERLs for performance

Network Communication: KERL distribution uses:

• Direct HTTP/TCP for controller-to-witness communication
• OOBI for witness discovery
• Query protocols for KERL retrieval
• Streaming protocols for efficient transfer

Cryptographic Operations: KERL processing requires:

• Signature verification (Ed25519, ECDSA, etc.)
• Hash computation (Blake3, SHA-256, etc.)
• Digest comparison for chain verification
• Key derivation for hierarchical keys

Concurrency: KERL operations must handle:

• Concurrent receipt collection from multiple witnesses
• Race conditions in witness response timing
• Partial receipt sets during threshold collection
• Network failures and retry logic

Security Properties

Duplicity Evidence: KERLs make duplicity evident:

• Conflicting events at same sequence number are detectable
• Witness receipts provide independent attestation
• Watchers can compare KERLs from different sources
• First-seen policy prevents retroactive changes

Byzantine Fault Tolerance: KERL witness thresholds provide:

• Tolerance for faulty or malicious witnesses
• Configurable security/availability trade-offs
• Immune agreement through KAACE algorithm
• Supermajority requirements for critical operations

Post-Quantum Security: KERLs support post-quantum cryptography:

• Pre-rotation hides future keys
• Hash-based commitments resist quantum attacks
• Cryptographic agility enables algorithm updates
• Forward security through one-time key use

Ambient Verifiability: KERLs enable verification by anyone:

• No trusted infrastructure required
• End-to-end verifiable from inception to current state
• Portable across different networks and platforms
• Independent verification by multiple parties

Duplicity Detection

Watcher Integration: Implement watcher queries to detect duplicity:

• Query multiple watchers for same AID
• Compare returned KERLs for consistency
• Flag any discrepancies for investigation

First-Seen Policy: Watchers must implement strict first-seen:

• Record timestamp of first observation
• Reject any conflicting events at same sequence
• Maintain DEL for detected duplicity

Gossip Protocols: Consider implementing gossip for duplicity alerts:

• Watchers share duplicity evidence
• Validators subscribe to duplicity feeds
• Rapid propagation of duplicity detection

Witness Management

Witness Discovery: Implement OOBI-based witness discovery:

• Bootstrap with known witness endpoints
• Discover additional witnesses through OOBI resolution
• Maintain witness availability metrics

Witness Rotation: Handle witness set changes gracefully:

• Old witnesses must receipt rotation event
• New witnesses become active after rotation
• Maintain historical witness sets for verification

Witness Failure Handling: Implement robust failure handling:

• Detect unresponsive witnesses (timeouts)
• Attempt alternative witnesses if available
• Alert controller if threshold cannot be met

Security Considerations

Receipt Validation: Thoroughly validate receipts:

• Verify receipt signature against witness AID
• Verify receipt references correct event digest
• Verify witness is in designated set
• Reject receipts from unauthorized witnesses

Replay Attack Prevention: Protect against receipt replay:

• Receipts are bound to specific events via digest
• Sequence numbers prevent reordering
• Timestamps (if used) should be monotonic

Denial of Service: Protect against DoS attacks:

• Rate limit receipt processing
• Validate event structure before expensive crypto ops
• Implement resource limits (max KERL size, max witnesses)

Interoperability

CESR Compliance: Strictly follow CESR encoding rules:

• Use correct derivation codes for all primitives
• Maintain composability in concatenated streams
• Support both text and binary domains

Version Compatibility: Handle KERI version evolution:

• Parse version strings in events
• Support multiple KERI versions if needed
• Gracefully reject unsupported versions

Cross-Implementation Testing: Test against multiple KERI implementations:

• KERIpy (Python reference implementation)
• KERI-ox (Rust implementation)
• Signify (TypeScript client)
• Ensure KERLs are portable across implementations