Forward Chaining: Through pre-rotation, each establishment event includes a digest of the next rotation keys in its n (next) field, creating a forward commitment that protects against key compromise.

Self-Addressing: Each event includes a d (digest) field containing the SAID of the event itself, making the event content-addressable and tamper-evident.

Key Components

Every KEL begins with exactly one inception event (icp) that establishes the identifier and its initial key state. This is followed by zero or more:

• Rotation events (rot): Establishment events that change the authoritative key set
• Interaction events (ixn): Non-establishment events that anchor data without changing keys

The KEL structure is described as "hash-chained Key Events" which makes it blockchain-like in a narrow definition, but critically different: KELs do not require global ordering or distributed consensus mechanisms. Each identifier maintains its own independent KEL.

Data Format

Field Definitions

All key events in a KEL share common fields with specific semantics:

Version String (v): Identifies the KERI protocol version and serialization format (e.g., KERI10JSON000188_ indicates KERI version 1.0, JSON serialization, with specific byte count)

Identifier (i): The AID prefix that this KEL belongs to. This is the self-certifying identifier derived from the inception event.

Sequence Number (s): A monotonically increasing counter starting at 0 for inception. Sequence numbers use hexadecimal notation (0-9, a-f, 10-13, etc.) in CESR encoding.

Event Type (t): Indicates the event type:

• icp: Inception event
• rot: Rotation event
• ixn: Interaction event
• dip: Delegated inception (for delegated identifiers)
• drt: Delegated rotation

Digest (d): The SAID of the event itself, computed over the serialized event content

Prior Event Digest (p): Hash of the previous event (not present in inception)

Current Keys (k): Array of current authoritative public keys (establishment events only)

Next Key Digest (n): Digest(s) of pre-rotated next keys (establishment events only)

Current Threshold (kt): Signature threshold for current keys (establishment events only)

Next Threshold (nt): Signature threshold for next keys (establishment events only)

Witness Configuration: Fields wt (witness threshold), w (witness list), wr (witness remove), wa (witness add) manage the witness pool

Configuration Traits (c): Array of configuration flags (e.g., ["EO"] for establishment-only)

Anchors (a): Array of seals anchoring external data (interaction events)

Encoding Format

KELs are serialized using CESR (Composable Event Streaming Representation), which supports multiple serialization formats:

JSON Serialization: Human-readable format using KERI10JSON version string. Example:

{
  "v": "KERI10JSON000188_",
  "t": "icp",
  "d": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "0",
  "kt": "1",
  "k": ["DSuhyBcPZEZLK-fcw5tzHn2N46wRCG_ZOoeKtWTOunRA"],
  "n": ["EPYuj8mq_PYYsoBKkzX1kxSPGYBWaIya3slgCOyOtlqU"],
  "wt": "2",
  "w": ["BJq7UABlttINuWJh1Xl2lkqZG4NTdUdqnbFJDa6ZyxCC"],
  "c": []
}

CBOR/MGPK Serialization: Binary formats for compact transmission

CESR Native: Pure CESR encoding for maximum efficiency

All formats maintain insertion-ordered field maps to ensure deterministic serialization and SAID computation.

Size and Constraints

Event Size: Variable, depending on:

• Number of keys in current/next key sets
• Number of witnesses
• Serialization format (JSON is largest, binary formats more compact)
• Typical JSON inception events: 180-200 bytes
• Typical JSON rotation events: 160-180 bytes

Sequence Number Range: Theoretically unlimited, using hexadecimal notation. Practical limits depend on implementation.

Key Count: No hard limit, but practical considerations:

• Single-sig identifiers: 1 key
• Multi-sig identifiers: Typically 2-7 keys
• Large multi-sig groups: Up to dozens of keys possible

Witness Count: Typically 2-7 witnesses for production systems, though the protocol supports more

Operations

Creation and Initialization

Inception Process: Creating a KEL begins with generating an inception event:

1. Key Generation: Generate initial signing key pair(s) and pre-rotated next key pair(s)
2. Witness Selection: Choose witness pool and establish witness threshold
3. Configuration: Set signing thresholds and configuration traits
4. Event Construction: Build inception event with all required fields
5. SAID Computation: Calculate the event's SAID by:
   • Serializing the event with placeholder # characters in the d field
   • Computing the cryptographic digest
   • Replacing placeholders with the actual SAID
6. Signing: Sign the event with the initial private key(s)
7. Witnessing: Send to witnesses for receipting
8. Publication: Make the inception event available for verification

The inception event establishes the AID prefix, which is either:

• Non-transferable: Derived directly from the public key
• Transferable: Derived from the inception event's SAID

Updates and Modifications

Rotation Operations: Changing the authoritative key set:

1. Pre-Rotation Verification: Verify that the rotation uses keys committed to in the previous event's n field
2. New Key Generation: Generate new current keys and new pre-rotated next keys
3. Event Construction: Build rotation event with:
   • Incremented sequence number
   • Digest of prior event
   • New current keys
   • New next key digests
   • Updated witness configuration (if changing)
4. Signing: Sign with the pre-rotated keys (now becoming current)
5. Witnessing: Obtain witness receipts
6. Appending: Add to the KEL

Interaction Operations: Anchoring data without key changes:

1. Seal Creation: Create cryptographic seals for data to anchor
2. Event Construction: Build interaction event with seals in a field
3. Signing: Sign with current keys
4. Witnessing: Obtain witness receipts
5. Appending: Add to the KEL

Delegation Operations: For delegated identifiers:

1. Delegator Approval: Obtain approval from delegating identifier
2. Delegated Event: Create delegated inception (dip) or rotation (drt)
3. Anchoring: Delegator anchors approval in their KEL
4. Verification: Validators verify both delegate and delegator KELs

Verification and Validation

KEL Verification Process: Validators verify a KEL by:

1. Inception Verification:

   • Verify the inception event is properly formatted
   • Verify the AID prefix matches the inception event derivation
   • Verify initial signatures
   • Verify witness receipts meet threshold

2. Chain Verification:

   • For each subsequent event:
     • Verify sequence number increments correctly
     • Verify prior digest matches previous event
     • Verify event SAID is correct
     • Verify signatures using current keys from prior event
     • For rotations: verify new keys match pre-rotated digests
     • Verify witness receipts meet threshold

3. Key State Computation:

   • Walk through establishment events to determine current key state
   • Track witness configuration changes
   • Identify the current authoritative key set

4. Duplicity Detection:

   • Compare KEL with other versions from different sources
   • Identify any conflicting events at the same sequence number
   • Flag duplicitous behavior if inconsistencies found

Internal Consistency: A KEL is internally consistent if:

• All cryptographic digests are correct
• All signatures verify against the appropriate keys
• The chain of prior digests is unbroken
• Pre-rotation commitments are honored

External Consistency: Multiple copies of a KEL are externally consistent if they contain identical events. External inconsistency (duplicity) occurs when different verifiable versions exist.

Usage Context

In Which Protocols

KERI Protocol: The KEL is the core data structure of KERI, providing:

• Identifier establishment and management
• Key rotation infrastructure
• Delegation mechanisms
• Witness coordination

ACDC Protocol: ACDCs (Authentic Chained Data Containers) rely on KELs for:

• Issuer identifier verification
• Credential signing key validation
• Revocation registry anchoring via TEL

IPEX Protocol: Issuance and Presentation Exchange uses KELs for:

• Authenticating credential issuers
• Verifying credential holders
• Establishing trust in exchanges

did:keri Method: The did:keri DID method uses KELs as:

• The authoritative source for DID document generation
• The verification mechanism for DID operations

did:webs Method: The did:webs method combines web-based discovery with KEL-backed security

Lifecycle Management

Creation Phase: KEL begins with inception event, establishing the identifier and initial key state

Active Phase: KEL grows through:

• Rotation events as keys are rotated for security
• Interaction events as data is anchored
• Delegation events if delegating to other identifiers

Witness Management: Throughout lifecycle:

• Witnesses can be added/removed via rotation events
• Witness threshold can be adjusted
• Witness receipts provide distributed validation

Delegation Lifecycle: For delegated identifiers:

• Delegator maintains approval through anchoring
• Delegate can be revoked by delegator
• Delegation tree can be arbitrarily deep

Abandonment: An identifier can be abandoned by:

• Rotating to empty next key digest list
• Setting next threshold to 0
• After abandonment, no further events are accepted

Recovery: If keys are compromised:

• Pre-rotated keys enable recovery
• Rotation to new keys using unexposed pre-rotated keys
• Duplicity detection identifies malicious rotations

Related Structures

KERL (Key Event Receipt Log): A KEL that includes all consistent key event receipts from witnesses. The KERL provides the "receipt infrastructure" that gives KERI its name.

TEL (Transaction Event Log): Transaction Event Logs are anchored to KELs to track credential lifecycle (issuance/revocation). TELs provide a secondary root-of-trust derived from the KEL's primary root-of-trust.

Witness Pool: The set of witnesses designated in the KEL that provide receipts and maintain copies of the KEL for high availability.

Watcher Network: Watchers maintain copies of KELs they observe (without being designated) to enable ambient duplicity detection.

Key State: The current authoritative key configuration derived from processing the KEL up to a given sequence number.

Delegation Tree: For delegated identifiers, the KEL is part of a hierarchical structure where delegator KELs anchor delegated KELs.

Storage and Distribution

Controller Storage: The identifier controller maintains the authoritative KEL copy

Witness Storage: Each witness maintains a copy and provides receipts

Watcher Storage: Watchers maintain copies for duplicity detection

Backer Storage: Backers (including ledger-based backers) may store KELs

Caching: Validators may cache KELs for performance

OOBI Discovery: OOBIs (Out-of-Band Introductions) provide URLs for KEL discovery and retrieval

Performance Characteristics

Verification Cost: Linear in the number of events (O(n) where n = sequence number)

Storage Cost: Grows linearly with number of events

Network Cost: KEL must be transmitted for verification (can be cached)

Optimization Strategies:

• Key State Notices: Compact representation of current key state
• Partial KELs: Transmit only recent events with key state proof
• Witness Receipts: Reduce verification burden through witness consensus
• Caching: Cache verified KELs to avoid repeated verification

Witness Coordination

Receipt Collection: Implement robust receipt collection:

• Use asynchronous receipt gathering with timeouts
• Implement retry logic for failed witness communications
• Support partial receipt collection (threshold-based)

Witness Pool Management: Handle witness configuration changes:

• Support witness rotation through establishment events
• Implement witness discovery via OOBIs
• Handle witness failures gracefully

Delegation Support

Delegator Verification: For delegated identifiers:

• Verify delegator's KEL before accepting delegated events
• Check that delegator has anchored approval in their KEL
• Implement recursive delegation tree verification

Delegation Revocation: Support delegation revocation:

• Monitor delegator's KEL for revocation events
• Invalidate delegated identifier when delegation is revoked
• Implement grace periods for delegation changes

Error Handling

Malformed Events: Reject events that:

• Have invalid CESR encoding
• Fail signature verification
• Have incorrect sequence numbers
• Have broken hash chains
• Violate pre-rotation commitments

Recovery Procedures: Implement recovery for:

• Lost or corrupted KEL data (restore from witnesses)
• Key compromise (use pre-rotated keys)
• Witness failures (use remaining witnesses above threshold)

Testing Strategies

Unit Tests: Test individual KEL operations:

• Event creation and serialization
• SAID computation
• Signature verification
• Chain validation

Integration Tests: Test KEL interactions:

• Witness coordination
• Duplicity detection
• Delegation verification
• Recovery scenarios

Fuzzing: Use fuzzing to test KEL parsing:

• Malformed CESR encoding
• Invalid field values
• Boundary conditions

Security Considerations

Timing Attacks: Implement constant-time operations for:

• Signature verification
• Digest computation
• Key comparison

Resource Exhaustion: Protect against:

• Excessively large KELs (implement size limits)
• Rapid event submission (rate limiting)
• Witness flooding (request throttling)

Key Management: Follow best practices:

• Never log or transmit private keys
• Use secure random number generation
• Implement key rotation schedules
• Support hardware security modules