Comprehensive Explanation

Transaction Event Log (TEL)

Structure Definition

The Transaction Event Log (TEL) is a fundamental data structure in the KERI ecosystem that extends the Key Event Log (KEL) architecture to support state tracking for credentials and other transactional data. While KELs establish control authority over cryptographic keys, TELs focus on tracking state transitions for verifiable credentials and other registry-managed entities.

Purpose and Role

TELs serve three critical functions within the KERI/ACDC ecosystem:

1. Credential Lifecycle Management: Track the issuance, revocation, and status of verifiable credentials (ACDCs)
2. Registry State Verification: Provide cryptographic proof of registry state through anchoring to controlling KELs
3. Decentralized State Tracking: Enable distributed verification of credential status without centralized registries

The TEL architecture implements a separation of concerns between identifier control (KEL) and credential state (TEL). The KEL establishes control authority over keys used to commit to TEL events and sign credentials, while TEL events establish the issuance/revocation state of credentials issued by the identifier controller.

Structural Organization

TELs are organized as hash-linked data structures where each event contains:

• Event content: Serialized transaction data (issuance, revocation, etc.)
• Cryptographic digest: Hash of the event content
• Anchoring seal: Reference to the KEL event that authorizes this TEL event
• Sequence number: Registry-specific "clock" for ordering events

Key Components

The TEL ecosystem consists of two primary log types:

Management TEL: Signals registry creation and tracks the list of Registrars (analogous to KEL Backers) that provide backing services for individual credential TELs. The management TEL can rotate the Registrar list through specific event types.

VC TEL (Virtual Credential Transaction Event Log): Tracks the issued or revoked state of each individual verifiable credential and contains a reference to its corresponding management TEL.

Data Format

Event Structure

All TEL events share common fields with KEL events but with important distinctions:

{
  "v": "KERI10JSON000188_",
  "i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "s": "3",
  "t": "iss",
  "d": "EKJccEf2Zf1xKh4dG3Y8FWS7a6s4reAXRZOkogZ2A",
  "dt": "2023-01-15T09:30:00.000000+00:00",
  "ri": "EACmRy7xMwsxUelUauaXtMxTfPAMPAI6FkekeolOjkggt"
}

Field Definitions:

• v (version): KERI version string with serialization format
• i (identifier): The AID of the registry or credential
• s (sequence number): Registry-specific "clock" (not KEL sequence)
• t (type): Event type (iss, rev, bis, brv, vcp, vrt)
• d (digest): SAID of the event
• dt (datetime): ISO 8601 timestamp
• ri (registry identifier): Reference to management TEL

Sequence Number Semantics

A critical distinction: the s field in TEL events represents a registry-specific "clock" rather than following the KEL's sequence numbering. Each transaction set can have its own clock mechanism:

• Bitcoin block height: For blockchain-anchored registries
• Wall clock time: For time-based registries
• Monotonically increasing integers: Most common for credential registries

This independence allows each registry to maintain its own sequencing logic while still anchoring to the KEL for authorization.

Event Source Seals

TEL events anchor to their controlling KEL using event source seals with JSON structure:

{
  "s": "3",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"
}

These seals are delivered as CESR-encoded attachments in the form of event source seal triples (duples of sequence number and digest):

-GAB
0AAAAAAAAAAAAAAAAAAAAAAw
ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM

The -GAB prefix is a CESR group framing code indicating an event source seal triple attachment follows.

Encoding Format

TELs use CESR (Composable Event Streaming Representation) encoding, supporting:

• JSON serialization: Human-readable format for development
• CBOR serialization: Compact binary format for production
• MGPK serialization: MessagePack format for efficiency

All serializations maintain insertion-ordered field maps for deterministic SAID computation.

Operations

Creation and Initialization

Management TEL Inception (vcp event):

1. Create TEL inception event with unique TEL-specific identifier
2. Generate hash digest of serialized TEL event content
3. Create anchoring seal in KEL interaction or rotation event
4. Sign the KEL event to commit to the TEL event digest

The management TEL establishes the Virtual Credential Registry (VCR) and designates initial Registrars.

VC TEL Inception (credential issuance):

1. Create credential ACDC with schema and attributes
2. Generate issuance event (iss or bis) in VC TEL
3. Anchor issuance event to issuer's KEL
4. Registrars witness and store the VC TEL event

Updates and Modifications

Credential Revocation (rev or brv event):

{
  "v": "KERI10JSON000188_",
  "i": "credential_AID",
  "s": "1",
  "t": "rev",
  "d": "event_SAID",
  "dt": "2023-06-15T14:30:00.000000+00:00",
  "ri": "registry_AID",
  "p": "prior_event_SAID"
}

Revocation events:

• Reference the prior event via p field (hash chaining)
• Increment sequence number
• Anchor to KEL for authorization
• Update credential state from "issued" to "revoked"

Registrar Rotation (vrt event):

The management TEL can rotate its Registrar list:

{
  "v": "KERI10JSON000188_",
  "i": "registry_AID",
  "s": "2",
  "t": "vrt",
  "d": "event_SAID",
  "ba": ["new_registrar_AID"],
  "br": ["removed_registrar_AID"]
}

Verification and Validation

TEL Verification Process:

1. Retrieve TEL events from Registrars or witnesses
2. Verify event signatures against anchoring KEL events
3. Validate hash chaining through prior event digests
4. Check KEL authorization for each TEL event
5. Compute current state by replaying event sequence

Validators verify authoritative state by:

• Validating signatures on the referenced KEL
• Verifying the digest commitment in KEL seals
• Confirming Registrar attestations
• Checking for duplicity across Registrar copies

Notably, TEL events do not require signatures - their authenticity derives from the digest commitment and signatures in the anchoring KEL events.

Usage Context

In Which Protocols

ACDC Credential Lifecycle:

TELs are fundamental to ACDC (Authentic Chained Data Container) credential management:

• Issuance: iss (simple) or bis (registry-backed) events
• Revocation: rev (simple) or brv (registry-backed) events
• Status Queries: Verifiers check TEL state before accepting credentials

IPEX (Issuance and Presentation Exchange):

The IPEX protocol relies on TELs for:

• Verifying credential validity during presentation
• Checking revocation status before acceptance
• Ensuring credential lifecycle integrity

vLEI Ecosystem:

GLEIF's verifiable Legal Entity Identifier system uses TELs extensively:

• QVI credential registries
• Legal Entity credential registries
• OOR and ECR role credential registries

Lifecycle Management

Grace Period Mechanism:

TELs implement a 90-day grace period for credential transitions:

• Credentials remain valid during grace period
• Revocation transactions process before registry commitment
• "Ghost credentials" exist during this interim state

State Transitions:

NULL → ISSUED → REVOKED
  ↑       ↓         ↓
  └───────┴─────────┘
     (grace period)

Related Structures

KEL (Key Event Log):

• TELs anchor to KELs for authorization
• KEL establishes control authority
• TEL establishes credential state

ACDC (Authentic Chained Data Container):

• ACDCs reference TEL registries via ri field
• TEL tracks ACDC lifecycle states
• ACDC SAIDs serve as TEL identifiers

CESR (Composable Event Streaming Representation):

• TELs use CESR encoding for all events
• Event source seals use CESR attachments
• Enables text/binary composability

Advanced Features

Blinded Revocation Registries

TELs support privacy-preserving revocation where:

• Current state is hidden/blinded
• Only the controller of a designated AID can disclose state
• Disclosure occurs at presentation time
• Prevents correlation through public revocation checks

Public vs. Private TELs

Public TELs (PTEL):

• Publicly accessible transaction logs
• Enable transparent credential status checking
• Use hash digests of VC contents as identifiers
• Allow correlation across credential presentations

Private TELs:

• Use salty nonce blinding factors
• Implement selective state disclosure
• Support privacy-preserving revocation
• Enable confidential credential management

Registrar Architecture

Registrars serve as backers for TELs, analogous to witnesses for KELs:

• Maintain copies of VC TELs
• Provide verification services
• Enable distributed state tracking
• Support threshold-based consensus

The management TEL tracks the Registrar list, enabling rotation for operational flexibility and security.

Security Properties

Cryptographic Anchoring

TEL security derives from:

• KEL signatures: Authorize TEL events
• Hash chaining: Ensures event ordering integrity
• SAID commitments: Bind event content to identifiers
• Registrar attestations: Provide distributed verification

Duplicity Detection

TELs inherit KERI's duplicity detection:

• Multiple Registrars maintain independent copies
• Inconsistent TEL versions are detectable
• First-seen policies prevent retroactive changes
• Ambient verifiability enables global consistency checks

End-Verifiability

Any validator can verify TEL state by:

• Retrieving TEL events from Registrars
• Validating anchoring KEL signatures
• Checking hash chain integrity
• Computing current state from event sequence

No trust in intermediaries is required - verification is cryptographically complete.