Append-only event logs in KERI follow a backward and forward chained structure:

Backward chaining occurs through digest chaining, where each event includes a cryptographic digest (hash) of the previous event. This creates an immutable chain where:

• The first event (inception) has no previous digest
• Each subsequent event includes the digest of its predecessor
• Any modification to a past event breaks the chain
• Verification proceeds from inception forward, validating each digest

According to Document 12, the digest chaining mechanism ensures that "each event is cryptographically bound to previous events," creating what the specification terms duplicity evidence - a structure that enables detection of conflicting log versions.

Forward chaining is implemented through pre-rotation, where each establishment event includes a cryptographic commitment (digest) to the next set of rotation keys. This forward commitment:

• Protects against live key compromise
• Enables post-quantum security through one-way hash functions
• Prevents attackers from creating valid rotation events even with current key access
• Maintains an unbroken chain of cryptographic authority

Key Components

An append-only event log in KERI consists of several essential components:

1. Event Entries

Each entry in the log is a key event - a serialized data structure containing:

• Version string (v): Protocol version and serialization format
• Identifier prefix (i): The AID this log belongs to
• Sequence number (s): Monotonically increasing integer
• Event digest (d): SAID of the event itself
• Event type (t): Inception, rotation, or interaction
• Previous event digest (p): Backward chain link
• Key configuration: Current and next key commitments
• Signatures: Cryptographic signatures from controlling keys

2. Event Types

KERI defines three primary event types within the append-only structure:

• Inception events (icp): The first and only event that creates an identifier, establishing initial key state
• Rotation events (rot): Establishment events that change the authoritative key set
• Interaction events (ixn): Non-establishment events that anchor external data without changing keys

As Document 7 explains, events are organized into two subsequences:

• Establishment subsequence: Inception and rotation events that define key state
• Non-establishment subsequence: Interaction events for data anchoring

3. Cryptographic Binding

The append-only structure is cryptographically enforced through multiple mechanisms:

• Hash chaining: Each event's digest depends on all previous events
• Sequence numbers: Monotonically increasing integers prevent reordering
• Digital signatures: Each event is signed by the current authoritative keys
• Pre-rotation commitments: Forward links to future key states

Data Format

Serialization Formats

KERI append-only event logs support multiple serialization formats through CESR (Composable Event Streaming Representation):

• JSON: Human-readable text format for debugging and archival
• CBOR: Compact binary format for efficient transmission
• MGPK (MessagePack): Alternative binary format
• CESR native: Dual text-binary encoding with composability

All formats must preserve insertion-ordered field maps to ensure canonical serialization. As Document 10 specifies, "reproducible serialization is essential for SAID computation" and "round-trip serialization/deserialization must not alter field order."

Field Definitions

The standard field structure for events in an append-only log follows the KERI event message format:

{
  "v": "KERI10JSON00011c_",
  "t": "icp",
  "d": "EXq5YqaL6L48pf0fu7IUhL0JRaU2_RxFP0AL43wYn148",
  "i": "EXq5YqaL6L48pf0fu7IUhL0JRaU2_RxFP0AL43wYn148",
  "s": "0",
  "kt": "1",
  "k": ["DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"],
  "nt": "1",
  "n": ["EZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM"],
  "bt": "0",
  "b": [],
  "c": [],
  "a": []
}

Field semantics:

• v: Version string encoding protocol, serialization, and size
• t: Event type (icp=inception, rot=rotation, ixn=interaction)
• d: Self-addressing identifier (SAID) of this event
• i: Identifier prefix (matches d for inception)
• s: Sequence number (0 for inception, increments for each event)
• kt: Current signing threshold
• k: Current signing key list
• nt: Next signing threshold (for pre-rotation)
• n: Next key digest list (pre-rotation commitments)
• bt: Witness threshold
• b: Witness identifier list
• c: Configuration traits
• a: Anchored data seals

Encoding Format

Events are encoded using CESR primitives that provide:

Self-framing: Each primitive includes type and size information, enabling stream parsing without external schema knowledge.

Composability: Groups of primitives can be converted between text and binary domains without loss, as Document 15 explains: "Converting a group of concatenated primitives from text (T) to binary (B) domain produces the same result as converting each primitive individually and then concatenating."

Qualified cryptographic primitives: All cryptographic material (keys, digests, signatures) includes prepended derivation codes that specify the algorithm used:

• E: Ed25519 public key
• D: Blake3-256 digest
• 0B: ECDSA secp256k1 signature

This self-describing encoding enables algorithm agility - the ability to support multiple cryptographic algorithms within the same log structure.

Size and Constraints

Sequence number constraints:

• Must be monotonically increasing integers
• Start at 0 for inception
• Increment by 1 for each subsequent event
• Maximum value is implementation-dependent but typically 64-bit unsigned integer

Digest constraints:

• Must use cryptographically strong hash functions (minimum 256-bit security)
• Default is Blake3-256 for performance
• SHA-256 and SHA3-256 also supported
• Digest must cover the entire serialized event with digest field set to dummy value

Key constraints:

• Minimum key strength: 128-bit security equivalent
• Supported algorithms: Ed25519, ECDSA secp256k1, Ed448
• Multi-sig configurations support weighted thresholds
• Pre-rotation commitments must use one-way hash functions

Event size:

• No hard maximum, but practical limits for network transmission
• Typical inception event: 200-500 bytes
• Rotation events: 300-600 bytes
• Interaction events: 150-400 bytes (depending on anchored data)

Operations

Creation and Initialization

Inception Process:

Creating an append-only event log begins with the inception event, which establishes the identifier and initial key state. According to Document 12, this process involves:

1. Generate entropy: Create high-entropy random seed (minimum 128 bits)
2. Derive key pairs: Use cryptographic derivation from seed
3. Create inception event: Construct event with initial keys and configuration
4. Compute SAID: Calculate self-addressing identifier for the event
5. Sign event: Apply signatures from initial key set
6. Publish: Distribute to witnesses and watchers

The inception event is unique and immutable - there can be only one inception event per identifier, and it cannot be changed after creation. This provides the cryptographic root of trust for the entire log.

Example inception workflow:

# Generate random seed
seed = generate_entropy(256)  # 256 bits of entropy

# Derive initial key pair
private_key = derive_private_key(seed, algorithm='Ed25519')
public_key = derive_public_key(private_key)

# Derive next (pre-rotated) key pair
next_private_key = derive_private_key(seed, index=1)
next_public_digest = hash(derive_public_key(next_private_key))

# Create inception event
event = {
    'v': 'KERI10JSON00011c_',
    't': 'icp',
    's': '0',
    'kt': '1',
    'k': [encode_key(public_key)],
    'nt': '1',
    'n': [encode_digest(next_public_digest)],
    'bt': '0',
    'b': [],
    'c': [],
    'a': []
}

# Compute SAID
event['d'] = compute_said(event)
event['i'] = event['d']  # For inception, i == d

# Sign event
signature = sign(serialize(event), private_key)

Updates and Modifications

Appending Events:

The append-only property means that updates occur only through appending new events, never modifying existing ones. The two types of updates are:

1. Rotation Events (changing key state):

def create_rotation_event(kel, current_keys, next_keys):
    # Get previous event
    previous_event = kel[-1]
    
    # Create rotation event
    rotation = {
        'v': 'KERI10JSON00011c_',
        't': 'rot',
        'i': previous_event['i'],  # Same identifier
        's': str(int(previous_event['s']) + 1),  # Increment sequence
        'p': previous_event['d'],  # Previous event digest
        'kt': '1',
        'k': [encode_key(k) for k in current_keys],
        'nt': '1',
        'n': [encode_digest(hash(k)) for k in next_keys],
        'bt': '0',
        'b': [],
        'c': [],
        'a': []
    }
    
    # Compute SAID
    rotation['d'] = compute_said(rotation)
    
    # Sign with PREVIOUS keys (proving control)
    signatures = [sign(serialize(rotation), k) for k in previous_keys]
    
    return rotation, signatures

2. Interaction Events (anchoring data):

def create_interaction_event(kel, current_keys, anchored_data):
    previous_event = kel[-1]
    
    interaction = {
        'v': 'KERI10JSON00011c_',
        't': 'ixn',
        'i': previous_event['i'],
        's': str(int(previous_event['s']) + 1),
        'p': previous_event['d'],
        'a': [{
            'd': compute_digest(anchored_data)
        }]
    }
    
    interaction['d'] = compute_said(interaction)
    
    signatures = [sign(serialize(interaction), k) for k in current_keys]
    
    return interaction, signatures

Immutability Enforcement:

The append-only property is enforced through multiple mechanisms:

• Digest chaining: Modifying any past event breaks all subsequent digest links
• Sequence numbers: Gaps or duplicates are immediately detectable
• Witness receipts: Independent witnesses sign events, creating external evidence
• First-seen policy: The first version of an event at a given sequence number is authoritative

Verification and Validation

Log Verification Process:

Verifying an append-only event log involves multiple validation steps:

1. Structural Validation:

def verify_log_structure(kel):
    # Check inception is first
    if kel[0]['t'] != 'icp':
        raise ValidationError("First event must be inception")
    
    # Verify sequence numbers
    for i, event in enumerate(kel):
        if int(event['s']) != i:
            raise ValidationError(f"Sequence number mismatch at index {i}")
    
    # Verify digest chain
    for i in range(1, len(kel)):
        if kel[i]['p'] != kel[i-1]['d']:
            raise ValidationError(f"Digest chain broken at index {i}")
    
    return True

2. Cryptographic Validation:

def verify_event_signatures(event, signatures, key_state):
    # Serialize event for signature verification
    serialized = serialize(event)
    
    # Get current authoritative keys from key state
    current_keys = key_state['k']
    threshold = int(key_state['kt'])
    
    # Verify sufficient valid signatures
    valid_sigs = 0
    for sig in signatures:
        for key in current_keys:
            if verify_signature(serialized, sig, key):
                valid_sigs += 1
                break
    
    if valid_sigs < threshold:
        raise ValidationError(f"Insufficient signatures: {valid_sigs} < {threshold}")
    
    return True

3. Key State Validation:

As Document 16 explains, key state validation ensures that:

• Current keys match those established in the most recent establishment event
• Pre-rotation commitments are properly maintained
• Rotation events use keys that match previous pre-rotation commitments
• Witness configurations are properly updated

4. Duplicity Detection:

The append-only structure enables ambient duplicity detection - the ability for any observer to detect conflicting versions of the log:

def detect_duplicity(kel1, kel2):
    # Find first point of divergence
    for i in range(min(len(kel1), len(kel2))):
        if kel1[i]['d'] != kel2[i]['d']:
            return {
                'duplicitous': True,
                'sequence': i,
                'event1': kel1[i],
                'event2': kel2[i]
            }
    
    # Check for truncation
    if len(kel1) != len(kel2):
        return {
            'duplicitous': True,
            'type': 'truncation',
            'length1': len(kel1),
            'length2': len(kel2)
        }
    
    return {'duplicitous': False}

Usage Context

In KERI Protocol

Append-only event logs are the foundational data structure of KERI, used in multiple contexts:

1. Key Event Logs (KELs):

The primary use case is the KEL, which records all key management events for an identifier. As Document 1 establishes, KELs provide:

• Verifiable history of all key state changes
• Cryptographic proof of control authority
• Duplicity evidence through comparison of log versions
• Portable identity that can move between infrastructures

2. Key Event Receipt Logs (KERLs):

A KERL extends the KEL by including witness receipts - signatures from designated witnesses that attest to having observed specific events. According to Document 5, KERLs:

• Track establishment events (inception and rotation)
• Include witness commitments to events
• Are append-only but not hash-chained (unlike KELs)
• Provide secondary verification through witness consensus

3. Transaction Event Logs (TELs):

The TEL applies the append-only pattern to credential lifecycle management:

• Issuance events: Record credential creation
• Revocation events: Mark credentials as invalid
• Transfer events: Change credential control (for transferable credentials)

As Document 7 explains, TELs provide "cryptographic proof of registry state by reference to the corresponding controlling KEL."

Lifecycle Management

Creation Phase:

1. Generate inception event with initial key configuration
2. Publish to witnesses for receipt collection
3. Distribute to watchers for ambient verification
4. Store in local database for controller access

Active Phase:

1. Append rotation events when keys need changing
2. Append interaction events to anchor external data
3. Collect witness receipts for each new event
4. Respond to verification requests from validators

Recovery Phase:

If key compromise is detected:

1. Use pre-rotated keys to create recovery rotation event
2. Publish recovery event to witnesses
3. Notify watchers of the recovery
4. Update key state to reflect new authoritative keys

The append-only structure ensures that even compromised keys cannot erase the evidence of compromise - the entire history remains verifiable.

Archival Phase:

For long-term preservation:

1. Export complete log in canonical serialization
2. Store with cryptographic integrity proofs
3. Maintain witness receipts as external evidence
4. Preserve in multiple formats for redundancy

Related Structures

Relationship to Blockchains:

As Document 1 notes, blockchains are a well-known example of append-only logs where:

• Events are transactions
• Bitcoin implements totally ordered signed transfers
• Global consensus ensures single authoritative version

However, KERI's append-only logs differ fundamentally:

• No global ordering: Each identifier has its own independent log
• No consensus requirement: Verification is cryptographic, not consensus-based
• Portable: Not locked to any specific ledger or blockchain
• Lightweight: No mining or proof-of-work required

Relationship to Certificate Transparency:

Certificate Transparency (CT) also uses append-only logs, as Document 35 describes:

• Public logs record all issued certificates
• Merkle tree structures enable efficient verification
• Append-only property prevents certificate deletion
• Enables detection of misissued certificates

KERI extends these concepts by:

• Eliminating dependence on trusted Certificate Authorities
• Enabling self-certifying identifiers
• Supporting key rotation through pre-rotation
• Providing decentralized verification

Relationship to Event Sourcing:

The append-only event log pattern is also used in event sourcing architectures:

• Current state is derived from event history
• Events are immutable facts
• State can be reconstructed by replaying events
• Enables audit trails and temporal queries

KERI applies these principles to key management:

• Current key state is derived from establishment events
• Key events are immutable cryptographic facts
• Key state can be reconstructed from inception forward
• Complete audit trail of all key changes is preserved

Integration with Other KERI Components

Witnesses:

Witnesses interact with append-only logs by:

• Receiving events from controllers
• Validating event structure and signatures
• Signing receipts to attest to event observation
• Storing events for later retrieval
• Participating in KAACE consensus algorithm

Watchers:

Watchers operate in "promiscuous mode" to:

• Collect events from multiple sources
• Detect duplicitous versions of logs
• Provide ambient verification services
• Enable discovery of identifier key state

Validators:

Validators use append-only logs to:

• Verify signatures on messages
• Determine current authoritative keys
• Detect duplicity through log comparison
• Establish trust in identifier control

OOBI (Out-Of-Band Introduction):

OOBI enables discovery of append-only logs by:

• Providing URLs to witness endpoints
• Bootstrapping initial log retrieval
• Enabling percolated discovery of key state
• Supporting zero-trust verification

Security Properties

Tamper Evidence:

The append-only structure provides strong tamper evidence through:

• Cryptographic binding: Hash chains make modification detectable
• Signature verification: Each event is signed by authoritative keys
• Witness attestation: External parties provide independent evidence
• Duplicity detection: Conflicting versions can be compared

Non-Repudiation:

Controllers cannot deny events they have signed because:

• Digital signatures provide cryptographic proof of authorship
• Witness receipts create external evidence
• Append-only property prevents deletion of evidence
• First-seen policy establishes authoritative version

Forward Integrity:

Pre-rotation provides forward integrity by:

• Committing to future keys before they are exposed
• Using one-way hash functions for commitments
• Preventing attackers from creating valid rotations
• Enabling recovery from key compromise

Post-Quantum Security:

As Document 18 explains, the append-only structure with pre-rotation provides post-quantum security:

• Pre-rotation commitments use hash functions
• Hash functions are believed to be quantum-resistant
• Even if signature algorithms are broken, pre-rotated keys remain secure
• Enables migration to quantum-resistant algorithms

Performance Considerations

Storage Requirements:

• Linear growth with number of events
• Typical identifier: 10-100 events over lifetime
• Average event size: 200-500 bytes
• Total storage: typically < 50 KB per identifier

Verification Performance:

• Linear time complexity: O(n) where n = number of events
• Cryptographic operations dominate: signature verification
• Typical verification time: < 100ms for 100-event log
• Can be optimized with key state caching

Network Efficiency:

• Incremental updates: only new events need transmission
• Compact encoding: CESR provides efficient serialization
• Witness receipts: additional overhead for each event
• Typical bandwidth: < 1 KB per event with receipts

Comparison with Alternative Approaches

vs. Mutable Databases:

Traditional mutable databases (CRUD model) differ fundamentally:

• CRUD: Create, Read, Update, Delete operations
• Append-only: Read, Update (append), Nullify operations

As Document 3 explains, the RUN model (Read, Update, Nullify) provides:

• Verifiable history: Complete audit trail preserved
• Tamper evidence: Modifications are detectable
• Non-repudiation: Cannot deny past statements
• Decentralized control: No central authority required

vs. Blockchain Ledgers:

Blockchains provide global append-only logs but with significant differences:

• Global ordering: Blockchains require consensus on total order
• Resource intensive: Mining or staking required
• Platform locked: Identifiers tied to specific blockchain
• Scalability limits: Transaction throughput constraints

KERI's approach provides:

• Independent logs: No global ordering required
• Lightweight: No mining or consensus overhead
• Portable: Not locked to any infrastructure
• Scalable: Linear with number of identifiers, not transactions

vs. Certificate Transparency Logs:

CT logs share the append-only property but differ in:

• Centralized trust: Depend on trusted log operators
• Certificate focus: Designed for X.509 certificates
• No key rotation: Certificates are replaced, not rotated
• External verification: Requires trusted monitors

KERI provides:

• Decentralized trust: Self-certifying identifiers
• Key rotation: Built-in support through pre-rotation
• Self-verification: End-verifiable without trusted parties
• Portable: Not tied to specific infrastructure

• Use append-only storage backend: Leverage filesystem or database append-only features
• Implement write-ahead logging: Ensure durability before acknowledging events
• Support multiple serialization formats: Store in canonical format but support conversion
• Maintain backup copies: Replicate logs across multiple storage locations

Security Best Practices

• Validate all inputs: Never trust event data without cryptographic verification
• Implement rate limiting: Prevent denial-of-service through event flooding
• Use constant-time comparisons: Prevent timing attacks on digest verification
• Protect private keys: Never store unencrypted keys with event logs
• Implement key rotation schedules: Rotate keys proactively, not just reactively

Error Handling

• Distinguish validation failures: Separate structural errors from cryptographic failures
• Provide detailed error messages: Include sequence number and event type in errors
• Implement recovery mechanisms: Support log repair from witness copies
• Log all validation attempts: Maintain audit trail of verification operations

Testing Requirements

• Test digest chain validation: Verify detection of modified events
• Test sequence number validation: Ensure gaps and duplicates are caught
• Test signature verification: Validate both valid and invalid signatures
• Test duplicity detection: Verify conflicting log versions are identified
• Test key rotation: Ensure proper pre-rotation commitment validation
• Test witness integration: Validate receipt collection and verification

Interoperability

• Support multiple CESR encodings: JSON, CBOR, MGPK, and native CESR
• Implement version negotiation: Handle different protocol versions gracefully
• Provide standard APIs: Follow KERI API specifications for consistency
• Document serialization format: Enable independent implementations to interoperate