Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 188 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
A Key Event Log (KEL) is a verifiable, append-only, cryptographically-chained data structure that records all key management events for an Autonomic Identifier (AID), providing a complete, tamper-evident history of key state changes from inception through all rotations and interactions.
The Key Event Log (KEL) is the foundational verifiable data structure in KERI that maintains the complete history of key events for an Autonomic Identifier (AID). As defined in the KERI specification, a KEL is a "verifiable data structure that is a backward and forward chained, signed, append-only log of key events for an AID."
The KEL serves multiple critical functions in the KERI ecosystem:
A KEL is organized as a sequential chain of key events, where each event is cryptographically linked to its predecessor through hash digests. The structure exhibits several critical properties:
Append-Only Nature: Events can only be added to the end of the log; existing events cannot be modified or deleted. This immutability is enforced through cryptographic chaining.
Backward Chaining: Each event (except inception) includes a digest of the previous event in its p (prior) field, creating a tamper-evident chain. Any modification to a prior event would break the chain.
Database Design: KELs should be stored with efficient indexing:
Event Serialization: Support multiple serialization formats (JSON, CBOR, MGPK) while maintaining deterministic field ordering for SAID computation
Caching Strategy: Implement key state caching to avoid repeated KEL processing:
Incremental Verification: When receiving new events, verify only from the last verified sequence number rather than re-verifying the entire KEL
Parallel Verification: For large KELs, consider parallel verification of independent event chains (though events must still be processed in sequence order)
Witness Receipt Optimization: Batch witness receipt verification rather than verifying each receipt individually
First-Seen Policy: Implement strict first-seen semantics:
Watcher Integration: Implement watcher network integration for ambient duplicity detection:
Key Storage: Securely store pre-rotated keys separately from current keys:
Rotation Validation: Strictly enforce pre-rotation commitments:
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.
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:
rot): Establishment events that change the authoritative key setixn): Non-establishment events that anchor data without changing keysThe 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.
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 eventrot: Rotation eventixn: Interaction eventdip: Delegated inception (for delegated identifiers)drt: Delegated rotationDigest (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)
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.
Event Size: Variable, depending on:
Sequence Number Range: Theoretically unlimited, using hexadecimal notation. Practical limits depend on implementation.
Key Count: No hard limit, but practical considerations:
Witness Count: Typically 2-7 witnesses for production systems, though the protocol supports more
Inception Process: Creating a KEL begins with generating an inception event:
# characters in the d fieldThe inception event establishes the AID prefix, which is either:
Rotation Operations: Changing the authoritative key set:
n fieldInteraction Operations: Anchoring data without key changes:
a fieldDelegation Operations: For delegated identifiers:
dip) or rotation (drt)KEL Verification Process: Validators verify a KEL by:
Inception Verification:
Chain Verification:
Key State Computation:
Duplicity Detection:
Internal Consistency: A KEL is internally consistent if:
External Consistency: Multiple copies of a KEL are externally consistent if they contain identical events. External inconsistency (duplicity) occurs when different verifiable versions exist.
KERI Protocol: The KEL is the core data structure of KERI, providing:
ACDC Protocol: ACDCs (Authentic Chained Data Containers) rely on KELs for:
IPEX Protocol: Issuance and Presentation Exchange uses KELs for:
did:keri Method: The did:keri DID method uses KELs as:
did:webs Method: The did:webs method combines web-based discovery with KEL-backed security
Creation Phase: KEL begins with inception event, establishing the identifier and initial key state
Active Phase: KEL grows through:
Witness Management: Throughout lifecycle:
Delegation Lifecycle: For delegated identifiers:
Abandonment: An identifier can be abandoned by:
Recovery: If keys are compromised:
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.
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
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:
nReceipt Collection: Implement robust receipt collection:
Witness Pool Management: Handle witness configuration changes:
Delegator Verification: For delegated identifiers:
Delegation Revocation: Support delegation revocation:
Malformed Events: Reject events that:
Recovery Procedures: Implement recovery for:
Unit Tests: Test individual KEL operations:
Integration Tests: Test KEL interactions:
Fuzzing: Use fuzzing to test KEL parsing:
Timing Attacks: Implement constant-time operations for:
Resource Exhaustion: Protect against:
Key Management: Follow best practices: