Structural Organization

The management TEL inherits the core structural properties of all Transaction Event Logs within KERI:

Event-Based Architecture: Like all TELs, the management TEL is an append-only log of events, each cryptographically anchored to a controlling Key Event Log (KEL). This anchoring mechanism ensures that all registry operations are authorized by valid key states of the registry controller.

Hash-Linked Chain: Events within the management TEL form a hash-linked data structure where each event contains a cryptographic digest of the previous event, creating an immutable audit trail of registry governance changes.

KEL Anchoring: According to Document 3, TEL events do not require their own signatures. Instead, authenticity derives from:

1. Creating the TEL event with its unique identifier
2. Generating a hash digest of the serialized TEL event content
3. Embedding this digest as an event source seal in a KEL event
4. Signing the KEL event, which creates a cryptographic commitment to the TEL event

This design means validators verify the authoritative state of a management TEL by validating signatures on the referenced KEL, not on the TEL events themselves.

Key Components

The management TEL contains several critical components:

Registry Identifier: A unique identifier for the Virtual Credential Registry being managed. This identifier distinguishes one registry from another within the broader KERI ecosystem.

Registrar List: The authoritative list of identifiers that serve as Registrars (Backers) for the registry. As noted in Document 11, "Registrars are analogous to Backers in KERI KELs, and Registrar lists are analogous to Backer lists in KERI KELs."

Rotation Capability: The Registrar list can be rotated through specific management TEL events, allowing the registry controller to add, remove, or replace Registrars as operational needs change. This provides operational flexibility while maintaining cryptographic integrity.

Event Source Seals: Each management TEL event is anchored to the controlling KEL through event source seals, which are delivered as attachments in the form of event source seal triples (sequence number and digest pairs).

Data Format

Field Definitions

According to Document 3, all TEL events share common fields with KEL events:

i (Identifier): The identifier for the management TEL itself. This is the registry identifier that distinguishes this management TEL from others.

s (Sequence Number): Represents the "clock" for the management TEL's transaction set. Unlike KEL sequence numbers that strictly follow event ordering, TEL sequence numbers can represent different timing mechanisms. For credential registries, this is typically a monotonically increasing integer, but the specification allows for alternative clocks like Bitcoin block height or wall clock time.

t (Event Type): Specifies the type of management TEL event. Document 4 defines several event types for verifiable credential registries:

• vcp (VDR Inception): Verifiable Data Registry inception event that creates the management TEL
• vrt (VDR Rotation): Verifiable Data Registry rotation event that updates the Registrar list
• Additional event types may be defined for specific registry operations

Registrar List Fields: The management TEL must contain fields that specify:

• Current Registrars (identifiers of entities serving as Backers)
• Threshold requirements (if applicable)
• Configuration parameters for Registrar operations

Encoding Format

Management TEL events are encoded using CESR (Composable Event Streaming Representation), which provides:

Dual Text-Binary Encoding: Events can be represented in either text domain (Base64 URL-safe) or binary domain, with full round-trip conversion capability between domains.

Self-Framing Primitives: All cryptographic primitives (digests, signatures, identifiers) within the management TEL are self-framing, meaning they include derivation codes that specify their type and length, enabling stream parsing without external schema information.

Composability: Multiple management TEL events can be concatenated into streams that maintain their individual integrity while supporting efficient batch processing.

Event Source Seal Format

As documented in Document 3, event source seals that anchor management TEL events to the controlling KEL have the JSON structure:

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

Where:

• s is the sequence number of the KEL event providing the anchor
• d is the digest of the management TEL event being anchored

These seals are delivered as attachments in CESR format:

-GAB
0AAAAAAAAAAAAAAAAAAAAAAw
ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM

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

Size and Constraints

Event Size: Management TEL events are relatively compact, containing primarily:

• Event metadata (identifier, sequence, type): ~100-200 bytes
• Registrar list: Variable, depending on number of Registrars (typically 44 bytes per identifier)
• Event source seal attachments: ~100 bytes per seal

Registrar List Constraints: While the specification does not mandate a maximum number of Registrars, practical considerations suggest:

• Sufficient Registrars to ensure availability and redundancy
• Not so many that coordination becomes impractical
• Typical deployments might use 3-7 Registrars for balance between security and operational complexity

Sequence Number Range: The s field uses a monotonically increasing integer for credential registries, providing effectively unlimited sequence space (64-bit integers support over 18 quintillion events).

Operations

Creation and Initialization

Registry Inception Process:

1. Controller Decision: The controller of a KEL decides to create a verifiable credential registry

2. Management TEL Inception Event Creation:

   • Generate unique registry identifier
   • Specify initial Registrar list
   • Set initial sequence number (typically 0)
   • Define event type as vcp (VDR inception)
   • Serialize the event content

3. Digest Generation: Create a cryptographic hash digest of the serialized management TEL inception event

4. KEL Anchoring:

   • Create or select a KEL event (typically an interaction event or rotation event)
   • Embed the management TEL event digest as an event source seal in the KEL event
   • Sign the KEL event with the controller's authoritative keys

5. Publication: Distribute the management TEL inception event along with the anchoring KEL event to Registrars and other interested parties

This process establishes the Virtual Credential Registry and designates the initial set of Registrars who will provide backing services for individual VC TELs.

Updates and Modifications

Registrar Rotation:

The primary update operation for management TELs is rotating the Registrar list. According to Document 11, "Registrars can be rotated with events specific to a certain type of TEL."

The rotation process follows a similar pattern to inception:

1. Create Rotation Event:

   • Increment sequence number
   • Set event type to vrt (VDR rotation)
   • Specify new Registrar list (may add, remove, or replace Registrars)
   • Include digest of previous management TEL event for hash-chaining

2. Anchor to KEL:

   • Generate digest of rotation event
   • Embed digest in KEL event as event source seal
   • Sign KEL event with current authoritative keys

3. Propagate Changes: Notify affected parties (old and new Registrars, credential holders, verifiers) of the Registrar list change

Operational Considerations:

• Coordination: Registrar rotations require coordination with existing Registrars to ensure continuity of service
• Timing: Rotations should be planned to minimize disruption to credential verification operations
• Threshold Management: If threshold-based Registrar schemes are used, rotations must maintain sufficient Registrars to meet threshold requirements

Verification and Validation

Management TEL Validation Process:

Validators verify management TEL authenticity through the following steps:

1. Retrieve Management TEL Events: Obtain the sequence of management TEL events from Registrars or other sources

2. Retrieve Controlling KEL: Obtain the KEL that controls the registry identifier

3. Verify KEL Integrity:

   • Validate KEL signatures using KERI's standard verification process
   • Verify hash-chaining within the KEL
   • Confirm current key state

4. Verify TEL Anchoring:

   • For each management TEL event, locate the corresponding KEL event containing the event source seal
   • Recompute the digest of the management TEL event
   • Verify the recomputed digest matches the digest in the KEL event's seal
   • Confirm the KEL event is properly signed by authoritative keys

5. Verify TEL Hash-Chaining:

   • Verify each management TEL event (after inception) includes the correct digest of the previous event
   • Confirm sequence numbers increment properly

6. Validate Registrar List:

   • Verify Registrar identifiers are valid AIDs
   • Confirm Registrar list changes follow proper rotation procedures

As noted in Document 3, "Validators can verify the authoritative state of any TEL by validating the signatures on the referenced KEL." This means the security of the management TEL derives entirely from the security of the controlling KEL.

Duplicity Detection:

KERI's ambient duplicity detection extends to management TELs:

• If a controller creates conflicting versions of a management TEL (e.g., two different Registrar lists at the same sequence number), this constitutes duplicity
• Registrars and watchers can detect such duplicity by comparing management TEL versions
• Detected duplicity undermines trust in the registry and may trigger governance responses

Usage Context

In Which Protocols

The management TEL is a core component of several KERI-based protocols:

Public Transaction Event Log (PTEL) Protocol: As defined in Document 4, the PTEL specification establishes management TELs as the foundation for public verifiable credential registries. The PTEL protocol defines:

• Event types for management TEL operations
• Anchoring mechanisms to KELs
• Registrar coordination procedures

vLEI Ecosystem: The verifiable Legal Entity Identifier (vLEI) ecosystem, governed by GLEIF, uses management TELs to establish credential registries for:

• Legal Entity vLEI Credentials
• Official Organizational Role (OOR) vLEI Credentials
• Engagement Context Role (ECR) vLEI Credentials

Each Qualified vLEI Issuer (QVI) operates a management TEL to govern their credential issuance infrastructure.

ACDC Issuance and Revocation: Authentic Chained Data Containers (ACDCs) that require public verifiability of issuance and revocation state use management TELs to establish the registry infrastructure. The management TEL designates which Registrars will maintain VC TELs for individual ACDCs.

Lifecycle Management

Inception Phase:

• Registry controller creates management TEL inception event
• Initial Registrars are designated and notified
• Registrars begin accepting VC TEL events for credentials issued under the registry

Operational Phase:

• Management TEL remains relatively stable, with infrequent Registrar rotations
• Individual VC TELs reference the management TEL for Registrar information
• Verifiers query Registrars listed in the management TEL to obtain credential state

Evolution Phase:

• Registrar rotations occur as operational needs change (e.g., Registrar availability issues, security concerns, scaling requirements)
• Each rotation creates a new management TEL event, anchored to the controlling KEL
• Old and new Registrars coordinate to ensure continuity of service

Termination Phase:

• If a registry is decommissioned, the management TEL may be explicitly terminated through a final event
• Alternatively, the registry may become inactive without explicit termination, with the management TEL simply ceasing to have new events
• Existing VC TELs remain verifiable through their historical Registrar references

Related Structures

Key Event Log (KEL):

The management TEL is fundamentally dependent on its controlling KEL. As stated in Document 17, "The registry is fundamentally anchored to the controller's KEL, establishing the cryptographic root of trust for all credential state information tracked by the registry."

The KEL provides:

• Control authority over the registry identifier
• Cryptographic anchoring for management TEL events
• Key rotation and recovery capabilities
• Duplicity detection for the registry controller

Virtual Credential Transaction Event Log (VC TEL):

Each individual credential tracked by the registry has its own VC TEL. According to Document 6, the VC TEL "contains a reference to the corresponding management transaction event log."

This reference linkage means:

• VC TELs inherit their Registrar list from the management TEL
• Verifiers can discover which Registrars to query by following the reference from VC TEL to management TEL
• Registrar rotations in the management TEL automatically apply to all VC TELs under that registry

Registrar Infrastructure:

Registrars listed in the management TEL function as Backers for the registry. They:

• Maintain copies of the management TEL and all VC TELs under the registry
• Respond to queries about credential state
• Provide redundancy and availability for credential verification
• May participate in consensus mechanisms for accepting new VC TEL events

Virtual Credential Registry (VCR):

The management TEL signals the creation of the Virtual Credential Registry, which is the logical registry structure encompassing:

• The management TEL itself
• All VC TELs issued under the registry
• The Registrar infrastructure
• Governance policies and procedures

The VCR is not a separate data structure but rather the conceptual entity that the management TEL brings into existence and governs.

Architectural Patterns

Separation of Concerns:

The two-tier TEL architecture (management TEL + VC TELs) provides important separation:

• Governance layer (management TEL): Handles registry infrastructure, Registrar tracking, and governance
• Credential layer (VC TEL): Handles individual credential state tracking with references back to the management layer

This separation allows:

• Independent tracking of individual credential states
• Centralized governance through the management TEL
• Scalable architecture where multiple VC TELs reference a single management TEL
• Clear authority chains from individual credentials back through Registrars to the controlling KEL

Delegated Authority:

The management TEL enables a form of delegated authority:

• The registry controller (KEL controller) delegates credential state tracking to Registrars
• Registrars act as trusted infrastructure without having control authority over the registry
• This delegation is cryptographically verifiable through the management TEL's anchoring to the KEL

Scalability Through Indirection:

By separating registry governance (management TEL) from individual credential tracking (VC TELs), the architecture scales efficiently:

• A single management TEL can govern thousands or millions of VC TELs
• Registrar rotations affect all VC TELs simultaneously without requiring updates to each VC TEL
• Verifiers can cache management TEL information and reuse it across multiple credential verifications

Operational Considerations

Registrar Selection:

Controllers must carefully select Registrars for their management TEL:

• Availability: Registrars must be reliably available to respond to verification queries
• Performance: Registrars must handle query load efficiently
• Trust: While Registrars don't have control authority, they do have operational influence over credential verification
• Geographic Distribution: Distributed Registrars improve resilience and reduce latency for global verifiers

Registrar Coordination:

Management TEL operations require coordination among Registrars:

• New Registrars must synchronize existing VC TEL data
• Departing Registrars should ensure smooth handoff
• Registrars may need to coordinate on accepting new VC TEL events (depending on registry policies)

Privacy Considerations:

As noted in Document 4, "This document addresses public VCs only. The use of hash digests of VC contents allows for correlation of VC uses."

This means:

• Management TELs are inherently public structures
• Registrar lists are publicly visible
• Registry operations are publicly auditable
• Private credential use cases require different architectures (e.g., blinded TELs)

Governance Integration:

Management TELs should integrate with broader governance frameworks:

• Registry policies should specify Registrar requirements
• Registrar rotation procedures should be documented
• Dispute resolution mechanisms should address Registrar failures or misbehavior
• Compliance requirements may dictate Registrar selection and operations

The vLEI Ecosystem Governance Framework provides an example of how management TELs integrate with comprehensive governance structures for credential ecosystems.

• Reject events with sequence numbers that skip values
• Reject events with duplicate sequence numbers (duplicity detection)
• Maintain sequence number state across system restarts

Clock Independence: While credential registries typically use simple integer sequences, implementations should support alternative clock mechanisms (Bitcoin block height, wall clock) for future extensibility

Verification Performance

Caching Strategies: Verifiers should cache:

• Management TEL events to avoid repeated retrieval
• Registrar lists to avoid repeated parsing
• KEL events that anchor management TEL events

Batch Verification: When verifying multiple credentials from the same registry:

• Verify the management TEL once and reuse the Registrar list
• Batch KEL signature verifications when possible
• Consider implementing a verification cache with appropriate TTL

Error Handling

Missing Anchors: If a management TEL event's anchoring KEL event cannot be found:

• Treat the management TEL event as unverified
• Implement retry logic with exponential backoff
• Consider querying multiple sources (witnesses, watchers) for the KEL

Registrar Unavailability: If Registrars listed in the management TEL are unavailable:

• Implement fallback to alternative Registrars in the list
• Consider implementing a quorum-based approach (accept if M of N Registrars respond)
• Log Registrar availability issues for operational monitoring

Duplicity Detection: If conflicting management TEL versions are detected:

• Log the duplicity event with full details
• Notify operators/governance bodies
• Consider implementing automatic quarantine of the affected registry
• Preserve evidence of duplicity for forensic analysis

Integration with VC TELs

Reference Validation: When processing VC TELs that reference a management TEL:

• Verify the management TEL reference is a valid SAID
• Retrieve and verify the referenced management TEL
• Use the Registrar list from the management TEL for VC TEL verification

Registrar Rotation Handling: When a management TEL Registrar rotation occurs:

• VC TEL verifications should accept responses from either old or new Registrars during a transition period
• Implement logic to handle VC TEL events that may have been witnessed by old Registrars before rotation
• Consider implementing a "rotation epoch" concept to track which Registrar list applies to which VC TEL events

Security Considerations

KEL Security Dependency: The security of a management TEL is entirely dependent on the security of its controlling KEL. Implementations should:

• Use strong key management for the controlling KEL
• Implement appropriate key rotation policies
• Consider using multi-signature or delegated identifiers for high-value registries

Registrar Trust Model: While Registrars don't have control authority, they do have operational influence:

• Implement monitoring for Registrar behavior
• Consider implementing reputation systems for Registrars
• Design governance processes for handling Registrar misbehavior

Replay Attack Prevention: Management TEL events are protected against replay attacks through:

• Sequence number monotonicity
• Hash-chaining to previous events
• Anchoring to KEL events with their own replay protection

Testing Recommendations

Unit Tests: Implement comprehensive unit tests for:

• Management TEL event creation and serialization
• Digest computation and verification
• Event source seal encoding and decoding
• Registrar list parsing and validation

Integration Tests: Test interactions between:

• Management TEL and controlling KEL
• Management TEL and VC TELs
• Management TEL and Registrar infrastructure

Scenario Tests: Test specific scenarios:

• Registrar rotation with multiple VC TELs
• Registrar unavailability and fallback
• Duplicity detection and handling
• Large-scale registries with many VC TELs

Operational Monitoring

Implementations should provide monitoring for:

• Management TEL event creation and anchoring success rates
• Registrar availability and response times
• Verification success rates and latency
• Duplicity detection events
• KEL anchoring failures

This monitoring data is essential for maintaining reliable credential registry operations and detecting operational or security issues early.