• Complete Key Event Data
• Cryptographic signature attachments
• Receipt attachments from witnesses
• Additional CESR-encoded attachments

This hierarchical structure enables efficient processing, verification, and transmission of key events while maintaining cryptographic integrity at each layer.

Event Type Taxonomy

Key events are categorized into two fundamental classes:

Establishment Events: Events that establish or change the authoritative key state:

• Inception Event (icp): The first event that creates an AID and establishes initial key state
• Rotation Event (rot): Changes the authoritative keypairs through KERI's pre-rotation mechanism

Establishment events form a critical subsequence within the KEL that defines the complete history of control authority changes.

Non-Establishment Events: Events that do not change key state:

• Interaction Event (ixn): Anchors external data to the current key state without modifying control authority

This distinction is architecturally significant because validators can efficiently determine current key state by processing only the establishment event subsequence, while interaction events provide additional functionality without complicating key state computation.

Data Format

Serialization Standards

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

Primary Formats:

• JSON (KERI10JSON): Human-readable text format for development and debugging
• CBOR: Compact binary format for efficient transmission
• MessagePack (MGPK): Alternative binary format

The version string in each event explicitly identifies the serialization format, enabling parsers to correctly interpret the event structure.

Field Structure and Ordering

KERI mandates insertion-ordered field maps where field order is preserved during serialization/deserialization. This ordering is critical for:

• Reproducible SAID computation
• Consistent hash chain verification
• Deterministic event processing

The normative field ordering for establishment events follows:

[v, t, d, i, s, p, kt, k, nt, n, bt, b, c, a]

Where:

• v: Version string
• t: Event type (ilk)
• d: Event SAID
• i: Identifier prefix
• s: Sequence number (hex-encoded)
• p: Previous event digest
• kt: Current signing threshold
• k: Current signing keys array
• nt: Next signing threshold
• n: Next key digests array (pre-rotation)
• bt: Witness threshold
• b: Witness identifier array
• c: Configuration array
• a: Anchoring seals array

Cryptographic Primitives

All cryptographic material in key events is encoded as qualified CESR primitives:

Derivation Codes: Prepended codes indicating the cryptographic algorithm:

• E: Ed25519 public key or Blake3-256 digest
• D: Ed25519 public key
• B: Ed25519 non-transferable prefix

Example qualified primitive:

EDSxKwKSZZq672OtzOlokik6L0rr3TtWrZDiHfnATU9j

The first character (E) is the derivation code, followed by the Base64 URL-safe encoded cryptographic material.

Size Constraints

Key events must align on 24-bit boundaries to maintain CESR composability:

• Text domain: Multiples of 4 characters (6 bits per character)
• Binary domain: Multiples of 3 bytes (8 bits per byte)
• 24 bits = LCM(6, 8)

This alignment ensures lossless round-trip conversion between text and binary representations without crossing primitive boundaries.

Operations

Event Creation

Inception Event Creation:

1. Key Generation: Generate two sets of asymmetric key pairs:

   • Current signing keys (exposed)
   • Next rotation keys (pre-rotated, kept secret)

2. Digest Computation: Compute cryptographic digests of next keys:

   next_digest = Blake3(next_public_key)
   

3. Event Construction: Build the inception event structure:

   {
     "v": "KERI10JSON0000e6_",
     "t": "icp",
     "d": "",
     "i": "",
     "s": "0",
     "kt": "1",
     "k": ["<current_key>"],
     "nt": "1",
     "n": ["<next_key_digest>"],
     "bt": "2",
     "b": ["<witness1>", "<witness2>"],
     "c": [],
     "a": []
   }
   

4. SAID Derivation: For self-addressing identifiers:

   • Replace d and i fields with dummy characters (#)
   • Compute digest over entire structure
   • Replace dummy characters with computed digest
   • Both d and i contain identical values

5. Signature Generation: Sign the complete event with current private key

6. Attachment: Append CESR-encoded signature as attachment

Rotation Event Creation:

1. Key Revelation: Reveal the pre-rotated keys from previous event

2. New Pre-rotation: Generate new next keys and compute digests

3. Event Construction: Build rotation event referencing previous event:

   {
     "v": "KERI10JSON000160_",
     "t": "rot",
     "d": "",
     "i": "<identifier>",
     "s": "1",
     "p": "<previous_event_digest>",
     "kt": "1",
     "k": ["<revealed_key>"],
     "nt": "1",
     "n": ["<new_next_digest>"],
     "bt": "2",
     "br": [],
     "ba": [],
     "a": []
   }
   

4. Verification: Ensure revealed key matches digest from previous event

5. Signing: Sign with revealed (now current) private key

Interaction Event Creation:

1. Seal Construction: Create anchoring seals for external data:

   {
     "i": "<identifier>",
     "s": "<sequence>",
     "d": "<digest>"
   }
   

2. Event Construction: Build interaction event:

   {
     "v": "KERI10JSON000098_",
     "t": "ixn",
     "d": "",
     "i": "<identifier>",
     "s": "2",
     "p": "<previous_event_digest>",
     "a": [<seals>]
   }
   

3. Signing: Sign with current authoritative keys

Event Verification

Verification follows a multi-stage process:

1. Structural Validation:

• Verify CESR encoding correctness
• Validate field ordering
• Check version string format
• Ensure required fields present

2. Cryptographic Verification:

• Extract signature attachments
• Verify signatures against event body
• For inception: verify signature against derived public key
• For rotation: verify signature against revealed pre-rotated key
• For interaction: verify signature against current authoritative keys

3. Hash Chain Verification:

• Compute digest of previous event
• Compare with p field in current event
• Verify unbroken chain from inception

4. Pre-rotation Verification (for rotations):

• Extract revealed key from k field
• Compute digest of revealed key
• Compare with corresponding digest in previous event's n field
• Verify match confirms legitimate rotation

5. Sequence Validation:

• Verify sequence numbers increment monotonically
• Check for gaps or duplicates
• Ensure inception starts at sequence 0

6. Threshold Verification:

• Count attached signatures
• Verify count meets or exceeds kt threshold
• For multi-sig, verify indexed signatures

Event Processing

Processing key events involves updating the key state:

Key State Computation:

1. Initialize: Start with empty key state

2. Process Inception:

   • Set current keys from k field
   • Set current threshold from kt field
   • Store next key digests from n field
   • Store next threshold from nt field
   • Initialize witness configuration

3. Process Rotations:

   • Verify revealed keys match stored next digests
   • Update current keys to revealed keys
   • Update current threshold
   • Store new next key digests
   • Update witness configuration (adds/cuts)

4. Process Interactions:

   • No key state changes
   • Process anchored seals
   • Update sequence tracking

5. Result: Current authoritative key state for identifier

Usage Context

Role in KERI Protocol

Key events serve as the fundamental building blocks of KERI's identifier management:

Primary Functions:

1. Control Authority Establishment: Inception events create identifiers and bind them to initial keys
2. Control Authority Transfer: Rotation events enable secure key rotation while maintaining identifier persistence
3. Data Anchoring: Interaction events create verifiable commitments to external data
4. Audit Trail: Complete event history provides verifiable provenance of control authority

Security Properties:

• Non-repudiation: Signatures provide cryptographic proof of controller actions
• Duplicity Detection: Multiple versions of same event are detectable
• Forward Security: Pre-rotation protects against key compromise
• Backward Chaining: Hash links prevent event insertion or reordering

Integration with KEL

Key events are stored in Key Event Logs (KELs):

KEL Structure:

• Ordered sequence of key events
• First event MUST be inception
• Subsequent events reference previous via digest
• Append-only (no modifications or deletions)

KEL Properties:

• Verifiable: Each event cryptographically verifiable
• Duplicity Evident: Conflicting versions detectable
• Self-Certifying: No external trust required
• Portable: Can be transmitted and verified anywhere

Witness Receipting

Key events are receipted by witnesses:

Receipt Process:

1. Controller sends key event to witnesses
2. Witnesses verify event validity
3. Witnesses create receipt messages (rct)
4. Receipts include witness signatures
5. Receipts reference event via digest

Receipt Structure:

{
  "v": "KERI10JSON000091_",
  "t": "rct",
  "d": "<event_digest>",
  "i": "<identifier>",
  "s": "<sequence>"
}

Receipts transform a KEL into a Key Event Receipt Log (KERL), providing distributed consensus on event history.

Transaction Event Log Anchoring

Key events anchor Transaction Event Logs (TELs) for credential management:

Anchoring Mechanism:

1. TEL events (issuance, revocation) are created
2. TEL event digests are sealed in key event anchors
3. Key event signatures commit to TEL events
4. Verification traces from TEL through key event to KEL

Seal Structure:

{
  "i": "<registry_identifier>",
  "s": "<tel_sequence>",
  "d": "<tel_event_digest>"
}

This anchoring provides cryptographic binding between credential state and identifier control authority.

ACDC Integration

Key events support ACDC (Authentic Chained Data Container) credentials:

Issuer Binding: ACDC issuer field (i) references an AID whose key state is established by key events

Signature Verification: ACDC signatures are verified against current keys from key state derived from key events

Revocation: ACDC revocation status is anchored to key events via TEL seals

Delegation: ACDC delegation chains follow AID delegation established through key events

Lifecycle Management

Creation Phase:

• Generate cryptographic material
• Construct event structure
• Compute SAIDs
• Sign event
• Publish to witnesses

Active Phase:

• Events are immutable once published
• Witnesses maintain copies
• Validators verify and process
• Key state evolves through new events

Rotation Phase:

• Pre-rotated keys are revealed
• New pre-rotations established
• Control authority transfers securely
• Old keys become stale

Abandonment:

• Rotation to empty next key list
• Next threshold set to 0
• No further events accepted
• Identifier becomes non-transferable

Performance Considerations

Event Size:

• JSON inception: ~230 bytes
• JSON rotation: ~160 bytes
• JSON interaction: ~98 bytes
• Binary formats 25-30% smaller

Processing Speed:

• Signature verification: ~10,000 events/second
• Hash chain verification: ~50,000 events/second
• Full KEL validation: ~5,000 events/second

Storage Requirements:

• Average event: ~200 bytes
• 1000 events: ~200 KB
• Witness receipts: +50 bytes per witness per event

Related Structures

Key Event Message: Encompasses key event data plus signature attachments

Key Event Receipt: References key event and includes witness signatures

Key State: Derived from processing key event sequence

Establishment Event: Subset of key events that modify key state

Non-Establishment Event: Subset of key events that anchor data without key state changes

Performance Optimization

• Cache key state after processing establishment events
• Skip interaction events when computing current key state
• Use binary serialization (CBOR/MGPK) for bandwidth-constrained scenarios
• Batch process events when validating large KELs

Error Handling

• Invalid signatures should reject entire event
• Hash chain breaks should halt KEL processing
• Sequence gaps should be treated as incomplete KELs
• Pre-rotation mismatches indicate potential compromise or error

Storage Considerations

• Store events in append-only data structures
• Index by sequence number for efficient retrieval
• Maintain separate indices for establishment vs. non-establishment events
• Consider using LMDB or similar key-value stores for KEL storage

Witness Receipt Processing

• Collect receipts asynchronously from witness pool
• Verify receipt signatures against witness AIDs
• Ensure receipt references correct event digest
• Implement timeout mechanisms for receipt collection

Delegation Support

• Delegated identifiers include di field referencing delegator
• Delegating events must be anchored in delegator's KEL
• Verify delegation authorization before accepting delegated events
• Maintain separate KELs for delegator and delegate