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 events
• d: SAID (Self-Addressing Identifier) - cryptographic digest of the event
• i: Identifier prefix - the AID this event belongs to
• s: Sequence number in hexadecimal format (e.g., "1", "2", "a", "10")
• p: Prior event digest - cryptographic link to the previous event in the KEL

Optional Fields:

• a: Anchors array - contains seals that cryptographically bind external data

The 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.

Key Components

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:

• Tamper evidence: Any modification to prior events breaks the chain
• Ordering proof: The sequence of events is cryptographically bound
• Completeness verification: Missing events can be detected

Anchors Array (a): The anchors array contains seal objects that bind external data to the KEL. Common seal types include:

1. Digest Seals: Simple cryptographic commitments to external data

   {"d": "EBWNHdSXCJnFJL5OuQPyM5K0neuniccM"}
   

2. Event Seals: References to other KERI events (used in delegation)

   {
     "i": "EAco5dU5WjDrxDBK4b4HrF82_rYb6MX6xsegjq4n0Y7M",
     "s": "3",
     "d": "EBkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM"
   }
   

3. Registry Seals: Anchors to TEL (Transaction Event Log) registries for credential management

Data Format

Field Definitions

Version String (v): Format: KERI{major}{minor}{kind}{size}_

• Major/minor version numbers (e.g., 10 for version 1.0)
• Kind: Serialization type (JSON, CBOR, MGPK)
• Size: Hexadecimal character count of the serialized event body
• Terminator: Underscore _ character

Example: 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:

1. Serializing the event with # placeholder characters in the d field
2. Computing the digest of this serialization
3. Replacing the placeholders with the actual digest value

This 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:

• Basic identifiers: Derived from public key
• Self-addressing identifiers: Derived from inception event digest
• Delegated identifiers: Include delegation information

Sequence Number (s): Hexadecimal string representing the event's position in the KEL. Sequence numbers:

• Start at "0" for inception
• Increment by 1 for each subsequent event
• Use lowercase hexadecimal for values ≥10 (e.g., "a" = 10, "10" = 16)
• Must be exactly one greater than the prior event's sequence number

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.

Encoding Format

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.

Size and Constraints

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:

• The version string's size field is hexadecimal, allowing up to 16^6 characters
• Large anchor arrays increase event size linearly
• Network MTU and database constraints may impose practical limits

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:

• Blake3-256: 44 characters in Base64 encoding
• SHA-256: 44 characters in Base64 encoding
• SHA3-256: 44 characters in Base64 encoding

The digest algorithm is indicated by the derivation code prefix in the SAID.

Operations

Creation and Initialization

Event Construction Process:

1. 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.

2. 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
   }
   

3. Compute SAID:

   • Serialize the event with # characters as SAID placeholder
   • Compute cryptographic digest of the serialization
   • Replace placeholder with the computed digest
   • This creates the self-referential SAID

4. Sign 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.

5. Attach Signatures: Signatures are attached to the event as CESR-encoded primitives. The attachment format depends on the signature type:

   • Indexed signatures for multi-sig: Include signature index
   • Non-indexed signatures for single-sig: Direct signature attachment

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]

Updates and Modifications

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:

• Provides tamper-evidence through cryptographic chaining
• Enables duplicity detection by comparing event versions
• Ensures non-repudiation of controller statements

Correction Mechanism: If an interaction event contains errors or needs to be superseded, the only option is to create a new interaction event that:

• References or supersedes the prior event
• Contains corrected information
• Advances the sequence number

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.

Verification and Validation

Validation Steps:

Validating an interaction event requires multiple checks:

1. Structural Validation:

   • Verify all required fields are present
   • Check field types match specification
   • Validate version string format
   • Confirm event type is "ixn"

2. 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"]
   

3. Sequence Validation:

   • Verify sequence number is exactly prior_sequence + 1
   • Check sequence number format (hexadecimal string)
   • Ensure no sequence number gaps or duplicates

4. Prior Event Verification:

   • Retrieve the prior event from the KEL
   • Verify the p field matches the prior event's SAID
   • Confirm the prior event exists and is valid

5. Key State Determination:

   • Process all prior establishment events to determine current key state
   • Identify the authoritative keys for signature verification
   • Determine the signing threshold

6. 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
   

7. Anchor Validation:

   • Verify seal objects have correct structure
   • For event seals, verify referenced events exist
   • For digest seals, verify digest format

Duplicity Detection:

Interaction events participate in duplicity detection:

• If two different interaction events exist with the same sequence number, this indicates duplicitous behavior
• Witnesses and watchers maintain first-seen records to detect duplicity
• Duplicity in interaction events may indicate key compromise or malicious controller behavior

Usage Context

Protocol Integration

KEL Construction: Interaction events are integral to KEL construction:

• They maintain the cryptographic chain between establishment events
• They provide data anchoring capabilities
• They enable controllers to make statements without key rotation overhead

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:

1. Controller publishes interaction event to witnesses
2. Each witness validates the event
3. Witnesses create and sign receipts
4. Receipts are collected to form the KERL (Key Event Receipt Log)

This witness receipting provides:

• Timestamp evidence of event publication
• Duplicity detection through first-seen policies
• Availability guarantees for event retrieval

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.

Lifecycle Management

Event Lifecycle Stages:

1. Creation: Controller constructs and signs the event
2. Publication: Event is transmitted to witnesses and watchers
3. Receipting: Witnesses validate and receipt the event
4. Propagation: Event and receipts spread through the network
5. Archival: Event becomes part of the permanent KEL record

Escrow Handling: Interaction events may be placed in escrow if:

• The prior event hasn't been received yet (out-of-order delivery)
• The current key state cannot be determined
• Witness receipts are incomplete

Escrowed events are held until dependencies are satisfied, then processed normally.

Recovery Scenarios: Interaction events play a role in key compromise recovery:

• If a controller's signing keys are compromised, attackers may create fraudulent interaction events
• The legitimate controller can recover by performing a rotation using pre-rotated keys
• The rotation supersedes any fraudulent interaction events created with compromised keys
• This demonstrates KERI's pre-rotation security model

Related Structures

Establishment Events: Interaction events complement establishment events:

• Establishment events define key state
• Interaction events use that key state to make statements
• Both participate in the same sequence numbering
• Both are cryptographically chained in the KEL

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.

Use Cases

Credential Issuance: When issuing an ACDC credential, the issuer creates an interaction event that anchors the credential:

1. Create the ACDC with all required fields
2. Compute the ACDC's SAID
3. Create an interaction event with a seal containing the ACDC SAID
4. Sign and publish the interaction event
5. The credential is now bound to the issuer's KEL

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:

1. External event occurs
2. Compute digest of event data
3. Create interaction event with digest seal
4. Witnesses receipt the interaction event
5. The witness receipts provide timestamp evidence

This creates a verifiable timestamp without requiring a trusted timestamping authority.

Key State Continuity: Between rotations, interaction events maintain KEL continuity:

• They advance the sequence number
• They extend the cryptographic chain
• They provide evidence of controller activity
• They enable detection of KEL truncation attacks

Even empty interaction events (with a: []) serve this continuity function.

Performance Optimization

• Cache parsed events to avoid repeated deserialization
• Index events by sequence number for fast lookup
• Use database transactions for atomic KEL updates
• Implement efficient SAID lookup structures

Error Handling

• Validate all fields before processing
• Provide clear error messages for validation failures
• Handle malformed events gracefully
• Log validation failures for debugging

Testing Requirements

• Test with various anchor array configurations
• Verify sequence number edge cases (9→a transition)
• Test multi-signature threshold satisfaction
• Validate SAID computation across serialization formats
• Test escrow and out-of-order event handling