Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 29 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 KERI event stream is a verifiable stream of KERI data consisting of a [Key Event Log (KEL)](/concept/kel) and optionally a [Transaction Event Log (TEL)](/concept/tel), serialized using [CESR](/concept/cesr) encoding and stored in files or transmitted over networks as CESR stream resources.
A KERI event stream is a fundamental data structure in the Key Event Receipt Infrastructure (KERI) protocol that represents a serialized, verifiable stream of cryptographic events establishing and maintaining control over Autonomic Identifiers (AIDs). The event stream serves as the primary mechanism for communicating identifier state, key rotations, and associated data across the KERI ecosystem.
The KERI event stream fulfills several critical functions:
Identifier State Communication: Transmits the complete history of key events for an AID, enabling any validator to independently verify the current key state without relying on trusted intermediaries.
Cryptographic Verifiability: Provides end-to-end verifiable proof of identifier control through cryptographically signed events that form an immutable chain.
Interoperability Foundation: Enables different KERI implementations to exchange identifier information using a standardized serialization format.
Web Integration: Supports the did:webs DID method by providing web-accessible KERI data that combines web infrastructure discovery with KERI's cryptographic verification.
Implementations must handle CESR's self-framing properties correctly:
The keri.cesr file format should:
For did:webs implementations:
keri.cesr and did.json at paths derived from DID identifier: becomes %3A)application/cesr registration)Implement verification in stages:
A KERI event stream is organized as a concatenated sequence of CESR-encoded primitives that can include:
The stream maintains strict ordering requirements where events must appear in sequence number order, and each event cryptographically references its predecessor through digest chaining.
Each KERI event stream contains several essential components:
Event Messages: Serialized key events encoded in JSON, CBOR, or MessagePack with CESR framing codes. Each event includes:
KERI10JSON, KERI10CBOR, etc.)icp, rot, ixn)Cryptographic Attachments: CESR-encoded signatures and receipts that provide non-repudiable proof of event authenticity. These include:
Framing Information: Count codes and group codes that enable self-framing stream parsing without requiring complete buffer parsing.
KERI event streams use Composable Event Streaming Representation (CESR) as their encoding format. CESR provides critical properties:
Text-Binary Composability: Any CESR stream can be converted between text domain (Base64 URL-safe) and binary domain without loss. This composability property is mathematically guaranteed through 24-bit alignment constraints.
Self-Framing Primitives: Each primitive in the stream includes prepended derivation codes that specify type and optionally size, enabling parsers to extract elements atomically without parsing entire content.
Dual Domain Support: CESR streams can be represented in:
A-Z, a-z, 0-9, -, _) for human readability and text protocol compatibilityA typical KERI event stream file (keri.cesr) contains:
Version Identifier: The stream begins with a CESR version code specifying which code tables to use for parsing. This enables protocol evolution while maintaining backward compatibility.
Event Sequence: A concatenated series of events, each structured as:
[Count Code][Event Size][Event JSON/CBOR/MGPK][Attachment Count][Signatures/Receipts]
For example, an inception event in JSON format:
{
"v": "KERI10JSON00011c_",
"t": "icp",
"d": "EBFn5ge82EQwxp9eeje-UMEXF-v-3dlfbdVMX_PNjSft",
"i": "EBFn5ge82EQwxp9eeje-UMEXF-v-3dlfbdVMX_PNjSft",
"s": "0",
"kt": "1",
"k": ["DDSxKwKSZZq672OtzOlokik6L0rr3TtWrZDiHfnATU9j"],
"nt": "1",
"n": ["EJ4Ngh0jDrlkD774TdNbkhzVYnf-MwpHGAnqKmsCAB8A"],
"bt": "2",
"b": ["BGKVzj4ve0VSd8z_AmvhxYxnRk7GjHoSVZvBUNZH9_Xi",
"BuyRFMideczFZoapylLIyCjSdhtqVb31wZkRKvPfNqkw"],
"c": [],
"a": []
}
Followed by CESR-encoded controller signatures and witness receipts.
{
"v": "KERI10JSON00013a_",
"t": "rct",
"d": "EBFn5ge82EQwxp9eeje-UMEXF-v-3dlfbdVMX_PNjSft",
"i": "EBFn5ge82EQwxp9eeje-UMEXF-v-3dlfbdVMX_PNjSft",
"s": "0"
}
With attached witness signatures proving event observation.
KERI event streams have several size characteristics:
Event Size: Individual events vary based on:
Typical inception events range from 200-500 bytes in JSON format.
Stream Size: Complete event streams grow linearly with:
A KEL with 100 rotation events and 2 witnesses (as shown in [Document 8]) totals approximately 50-100 KB in CESR text format.
Alignment Constraints: CESR's 24-bit alignment requirement means:
KERI event stream creation follows a specific workflow:
1. Identifier Inception: The stream begins with an inception event that:
2. Event Serialization: Each event is serialized using:
3. Signature Attachment: Controller signs the event:
4. Witness Receipt Collection: For indirect mode operation:
5. Stream Assembly: Components concatenated:
KERI event streams are append-only structures. Updates occur through:
Key Rotation: Adding rotation events that:
Interaction Events: Adding interaction events that:
Witness Pool Updates: Rotation events can:
The append-only nature ensures:
Validating a KERI event stream involves multiple verification steps:
1. Stream Parsing: Using CESR self-framing properties:
2. Event Chain Validation: Verify cryptographic chaining:
3. Signature Verification: Check cryptographic signatures:
4. Key State Computation: Build current key state:
5. Duplicity Detection: Check for conflicting events:
6. Witness Agreement: For indirect mode:
KERI event streams integrate with multiple protocols:
did:webs DID Method: The did:webs specification uses KERI event streams as the cryptographic foundation:
did.json file is generated from current key state derived from the KERI event streamdid.json and keri.cesr files are hosted at web locations derived from the DID identifierFor example, the DID did:webs:example.com:dws:EBFn5ge82EQwxp9eeje-UMEXF-v-3dlfbdVMX_PNjSft resolves to:
https://example.com/dws/EBFn5ge82EQwxp9eeje-UMEXF-v-3dlfbdVMX_PNjSft/did.jsonhttps://example.com/dws/EBFn5ge82EQwxp9eeje-UMEXF-v-3dlfbdVMX_PNjSft/keri.cesrdid:keri DID Method: Uses KERI event streams directly:
ACDC Credentials: Authentic Chained Data Containers rely on KERI event streams:
IPEX Protocol: Issuance and Presentation Exchange uses event streams:
KERI event streams have a defined lifecycle:
Inception Phase:
Active Phase:
Recovery Phase (if keys compromised):
Delegation Phase (for hierarchical management):
Abandonment (optional):
KERI event streams interact with several related data structures:
Key Event Log (KEL): The core event sequence without receipts. A KERI event stream typically contains a KEL plus additional data.
Key Event Receipt Log (KERL): A KEL augmented with witness receipts, providing stronger validation guarantees.
Transaction Event Log (TEL): Tracks state changes for credentials and other transactions, anchored to the KEL via seals.
Duplicitous Event Log (DEL): Records conflicting events for duplicity evidence, maintained separately from the authoritative stream.
Escrow State: Temporary storage for out-of-order events awaiting dependencies, not part of the permanent stream.
Watcher Databases: Watchers maintain copies of event streams in promiscuous mode for ambient duplicity detection.
KERI event streams are stored and transmitted in multiple contexts:
File Storage: The keri.cesr file format stores complete event streams:
Database Storage: Implementations store parsed events:
Network Transmission: Streams transmitted via:
IANA Media Type: The specification references a pending IANA registration for application/cesr media type, which will standardize KERI event stream content negotiation in HTTP contexts.
Implementations optimize KERI event stream processing through:
Incremental Parsing: Using CESR's self-framing properties to parse events as they arrive without buffering entire streams.
Key State Caching: Maintaining computed key state to avoid re-processing entire KEL on each validation.
Parallel Verification: Verifying signatures concurrently when multiple signatures or receipts are present.
Stream Indexing: Building indexes on sequence numbers and digests for rapid event lookup.
KERI event streams provide several security guarantees:
Cryptographic Binding: Each event is cryptographically bound to its predecessor via digest chaining, preventing insertion or reordering attacks.
Non-Repudiation: Controller signatures provide non-repudiable proof of event authorization.
Duplicity Evidence: Conflicting events at the same sequence number provide cryptographic proof of malicious behavior.
Witness Consensus: Multiple independent witnesses provide Byzantine fault tolerance against single-point failures.
Pre-Rotation Protection: Pre-committed next keys protect against live attacks on current keys.
KERI event streams enable interoperability through:
Format Flexibility: Support for JSON, CBOR, and MessagePack serialization allows integration with diverse ecosystems.
CESR Composability: Text-binary conversion enables use in both human-readable and binary-optimized contexts.
Standard Compliance: Alignment with W3C DID Core through did:webs and did:keri methods.
Universal Resolver Integration: Compatibility with the Universal Resolver framework for DID resolution.
This comprehensive structure makes KERI event streams a robust foundation for decentralized identifier management, combining cryptographic security with practical web integration.