Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 120 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.
An interaction event is a non-establishment event in KERI that anchors external data to an AID's key event log without modifying the current key state, enabling controllers to make verifiable authoritative statements while maintaining the existing set of controlling keypairs.
An interaction event (commonly abbreviated as ixn) is one of the three fundamental key event types in the KERI protocol, alongside inception events and rotation events. Unlike establishment events which create or modify the key state of an AID, interaction events serve exclusively as data anchoring mechanisms that bind external information to the identifier's cryptographic history without altering control authority.
The defining characteristic of interaction events is their non-establishment nature: they do not change the current set of authoritative keypairs, signing thresholds, witness configurations, or any other aspect of the key state. Instead, they provide a mechanism for controllers to make cryptographically verifiable, non-repudiable statements that are bound to a specific point in the KEL (Key Event Log) timeline.
This separation between establishment and non-establishment events creates a clean architectural distinction in KERI:
Implementations must carefully track sequence numbers:
Before creating or validating an interaction event:
The SAID computation must be deterministic:
d field with exactly the right number of # charactersSignatures must be properly attached using CESR encoding:
When processing anchors:
Implement proper escrow handling:
When publishing interaction events to witnesses:
Interaction events follow the standard KERI event structure with specific field requirements:
Required Top-Level Fields:
v: Version string in CESR format (e.g., KERI10JSON000116_)t: Event type identifier, always "ixn" for interaction eventsd: SAID (Self-Addressing Identifier) - cryptographic digest of the eventi: Identifier prefix - the AID this event belongs tos: Sequence number in hexadecimal format (e.g., "1", "2", "a", "10")p: Prior event digest - cryptographic link to the previous event in the KELOptional Fields:
a: Anchors array - contains seals that cryptographically bind external dataThe a (anchors) field is the primary payload mechanism for interaction events. It contains an array of seal objects that reference external data structures, credentials, or other information the controller wishes to bind to their KEL.
Event Type Identifier (t):
The t field with value "ixn" distinguishes interaction events from other event types. This enables parsers and validators to apply the correct validation rules - specifically, interaction events must NOT modify key state and must reference the most recent establishment event for key state determination.
Sequence Number (s):
Interaction events participate in the same sequence numbering as establishment events, creating a unified, totally-ordered log. The sequence number increments by one for each event regardless of type. This unified sequencing is critical for duplicity detection - if a controller creates two different events with the same sequence number, this constitutes detectable duplicity.
Prior Event Digest (p):
The p field creates backward chaining by including the SAID of the immediately preceding event (whether establishment or interaction). This cryptographic linkage ensures:
Anchors Array (a):
The anchors array contains seal objects that bind external data to the KEL. Common seal types include:
Digest Seals: Simple cryptographic commitments to external data
{"d": "EBWNHdSXCJnFJL5OuQPyM5K0neuniccM"}
Event Seals: References to other KERI events (used in delegation)
{
"i": "EAco5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
"s": "3",
"d": "EBkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM"
}
Registry Seals: Anchors to TEL (Transaction Event Log) registries for credential management
Version String (v):
Format: KERI{major}{minor}{kind}{size}_
10 for version 1.0)JSON, CBOR, MGPK)_ characterExample: KERI10JSON000116_ indicates KERI 1.0, JSON serialization, 116 characters (0x116 = 278 decimal)
Event Type (t):
Fixed string value "ixn" identifying this as an interaction event. This field is critical for event routing and validation logic.
SAID (d):
A qualified CESR primitive containing the cryptographic digest of the entire event. The SAID is computed by:
# placeholder characters in the d fieldThis creates a self-referential identifier where the event's content determines its identifier, providing content-addressability and tamper-evidence.
Identifier (i):
The AID prefix this event belongs to. This must match the identifier established in the inception event and maintained through any rotations. The identifier format depends on the derivation method:
Sequence Number (s):
Hexadecimal string representing the event's position in the KEL. Sequence numbers:
"0" for inception"a" = 10, "10" = 16)Prior Event Digest (p):
The SAID of the immediately preceding event in the KEL. This creates the cryptographic chain that makes the KEL tamper-evident. The prior digest must match the actual SAID of the previous event, whether that event was an establishment or interaction event.
Anchors (a):
JSON array of seal objects. Each seal is a JSON object with fields specific to the seal type. The array may be empty ([]) for interaction events that serve only to advance the sequence number without anchoring external data.
Interaction events support multiple serialization formats through CESR:
JSON Serialization: The most common format for human-readable applications:
{
"v": "KERI10JSON000116_",
"t": "ixn",
"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3ULvYAfSVPzhzS6",
"i": "EAco5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
"s": "1",
"p": "EAco5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
"a": []
}
CBOR Serialization: Binary format for bandwidth-constrained environments. Uses CBOR (Concise Binary Object Representation) with the same logical structure but more compact encoding.
MGPK Serialization: Binary format using MessagePack encoding, offering similar compactness to CBOR with different performance characteristics.
All formats maintain semantic equivalence - the same logical event can be represented in any format and will produce the same SAID when properly serialized.
Minimum Size: An interaction event with empty anchors array is the smallest possible interaction event, typically around 200-300 bytes in JSON format depending on identifier length and sequence number.
Maximum Size: No hard maximum, but practical limits exist:
Sequence Number Range: Sequence numbers are unbounded in theory but represented as hexadecimal strings. Practical implementations may impose limits based on storage and processing capabilities.
SAID Length: Depends on the digest algorithm:
The digest algorithm is indicated by the derivation code prefix in the SAID.
Event Construction Process:
Determine Current Key State: Before creating an interaction event, the controller must know the current key state by processing all prior events in the KEL. This determines which keys are authorized to sign the new event.
Assemble Event Data:
event_data = {
"v": version_string,
"t": "ixn",
"d": "", # Placeholder for SAID
"i": identifier_prefix,
"s": hex(prior_sequence + 1),
"p": prior_event_said,
"a": anchors_array
}
Compute SAID:
# characters as SAID placeholderSign the Event: The controller signs the serialized event using the current authoritative keys. For a single-signature identifier:
signature = sign(serialize(event_data), current_private_key)
For multi-signature identifiers, multiple signatures must be collected according to the current threshold.
Attach Signatures: Signatures are attached to the event as CESR-encoded primitives. The attachment format depends on the signature type:
Anchor Construction:
When anchoring external data, the controller creates seal objects:
# Digest seal for arbitrary data
digest_seal = {
"d": compute_digest(external_data)
}
# Event seal for delegation
event_seal = {
"i": delegated_identifier,
"s": delegated_event_sequence,
"d": delegated_event_said
}
# Add to anchors array
event_data["a"] = [digest_seal, event_seal]
Immutability Principle: Once created and signed, interaction events are immutable. They cannot be modified, updated, or deleted. This immutability is fundamental to KERI's security model:
Correction Mechanism: If an interaction event contains errors or needs to be superseded, the only option is to create a new interaction event that:
This creates an audit trail showing the evolution of controller statements over time.
Key State Independence: Interaction events do not modify key state, so they cannot "update" the controlling keys, thresholds, or witness configuration. These modifications require rotation events.
Validation Steps:
Validating an interaction event requires multiple checks:
Structural Validation:
"ixn"SAID Verification:
# Remove SAID from event
event_copy = event.copy()
event_copy["d"] = "#" * len(event["d"])
# Recompute SAID
computed_said = compute_digest(serialize(event_copy))
# Verify match
assert computed_said == event["d"]
Sequence Validation:
Prior Event Verification:
p field matches the prior event's SAIDKey State Determination:
Signature Verification:
# For each attached signature
for signature in attached_signatures:
public_key = current_key_state.keys[signature.index]
assert verify(signature, event_bytes, public_key)
# Verify threshold satisfaction
assert len(valid_signatures) >= current_key_state.threshold
Anchor Validation:
Duplicity Detection:
Interaction events participate in duplicity detection:
KEL Construction: Interaction events are integral to KEL construction:
A typical KEL might have the pattern:
Inception (s:0) → Interaction (s:1) → Interaction (s:2) → Rotation (s:3) → Interaction (s:4)
Witness Receipting: Interaction events are receipted by witnesses just like establishment events:
This witness receipting provides:
TEL Anchoring: Interaction events are the primary mechanism for anchoring TEL (Transaction Event Log) events to the KEL:
{
"v": "KERI10JSON000116_",
"t": "ixn",
"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3ULvYAfSVPzhzS6",
"i": "EAco5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
"s": "5",
"p": "EBkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM",
"a": [
{
"i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3ULvYAfSVPzhzS6",
"s": "0",
"d": "EFH3dCdoFOLe71iheqcywJcnjtJtQIYPvAu6DZIl3MOA"
}
]
}
This anchors a TEL inception event (registry creation) to the controller's KEL, binding the registry's authority to the controller's key state.
Event Lifecycle Stages:
Escrow Handling: Interaction events may be placed in escrow if:
Escrowed events are held until dependencies are satisfied, then processed normally.
Recovery Scenarios: Interaction events play a role in key compromise recovery:
Establishment Events: Interaction events complement establishment events:
Key Event Receipts: Receipts are created for interaction events by witnesses:
{
"v": "KERI10JSON000116_",
"t": "rct",
"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3ULvYAfSVPzhzS6",
"i": "EAco5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
"s": "5"
}
Receipts reference the interaction event's SAID and sequence number, providing witness attestation.
Transaction Event Logs: TELs are anchored to KELs through interaction events. The TEL provides credential lifecycle management (issuance, revocation) while the KEL provides the root of trust through the controller's key state.
ACDCs: Authentic Chained Data Containers (credentials) are often anchored to KELs through interaction events. The interaction event's seal references the ACDC's SAID, binding the credential to the issuer's key state at a specific point in time.
Credential Issuance: When issuing an ACDC credential, the issuer creates an interaction event that anchors the credential:
Service Endpoint Declaration: Controllers can use interaction events to declare service endpoints:
{
"a": [
{
"d": "EFH3dCdoFOLe71iheqcywJcnjtJtQIYPvAu6DZIl3MOA"
}
]
}
Where the digest references a service endpoint descriptor document.
Delegation Authorization: In delegation scenarios, the delegator creates an interaction event that seals the delegate's establishment event:
{
"a": [
{
"i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3ULvYAfSVPzhzS6",
"s": "0",
"d": "EFH3dCdoFOLe71iheqcywJcnjtJtQIYPvAu6DZIl3MOA"
}
]
}
This authorizes the delegation by cryptographically binding the delegate's inception to the delegator's KEL.
Registry Creation: When creating a TEL registry for credential management, the controller anchors the registry inception event:
{
"a": [
{
"i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3ULvYAfSVPzhzS6",
"s": "0",
"d": "EFH3dCdoFOLe71iheqcywJcnjtJtQIYPvAu6DZIl3MOA"
}
]
}
This establishes the registry's authority chain back to the controller's root of trust.
Timestamp Anchoring: Interaction events can serve as timestamps for external events:
This creates a verifiable timestamp without requiring a trusted timestamping authority.
Key State Continuity: Between rotations, interaction events maintain KEL continuity:
Even empty interaction events (with a: []) serve this continuity function.