Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 171 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.
A public hash-linked data structure of transactions that tracks state anchored to a Key Event Log (KEL), enabling transparent and verifiable tracking of credential lifecycle states (issuance/revocation) through cryptographically chained transaction events.
A Public Transaction Event Log (PTEL) is a cryptographically verifiable, append-only data structure that records state transitions for verifiable credentials within the KERI ecosystem. Unlike the Key Event Log (KEL) which establishes control authority over cryptographic keys, the PTEL establishes and tracks the state of credentials issued by the controller of an identifier.
The PTEL serves as the foundation for implementing Public Verifiable Credential Registries within KERI-based systems. Its primary purposes include:
The PTEL architecture implements a critical separation of concerns between control authority (managed by KELs) and credential state (managed by PTELs). The KEL establishes who has the authority to commit to PTEL events and sign credentials, while the PTEL establishes the current validity state of those credentials.
PTELs are organized as hash-linked chains where each transaction event cryptographically commits to the previous event through digest inclusion. This creates a tamper-evident structure where any modification to historical events breaks the cryptographic chain.
Implementers must maintain clear separation between:
This separation enables independent verification of both control authority and credential state, providing robust security guarantees.
Unlike KEL events which are directly signed, PTEL events derive their authenticity from:
This design reduces cryptographic overhead while maintaining strong security through the established KEL control authority.
The current PTEL specification is explicitly designed for public credentials only. The use of credential SAIDs as identifiers enables correlation across presentations. For privacy-preserving credential systems requiring unlinkability, alternative approaches would be needed.
Successful PTEL implementation requires careful Registrar network design:
PTEL sequence numbers are independent of KEL sequence numbers. A single KEL event can anchor multiple PTEL events. Implementers should:
When implementing ACDC issuance with PTEL backing:
ri field referencing management TELThe PTEL architecture consists of two primary components:
Management TEL: Signals the creation of the Virtual Credential Registry (VCR) and tracks the list of Registrars that act as backers for individual credential TELs. Registrars are analogous to witnesses in KELs, providing distributed validation and availability for credential state information.
VC TEL (Virtual Credential Transaction Event Log): Tracks the issued or revoked state of each individual credential and contains a reference to its corresponding management TEL. Each credential has its own VC TEL that records all state transitions throughout its lifecycle.
Every PTEL event contains several essential fields:
i (Identifier): The AID of the credential registry controllers (Sequence Number): Represents the "clock" for the transaction set, which may be independent of KEL sequence numberst (Event Type): Identifies the type of transaction event (inception, issuance, revocation, etc.)d (Digest): The SAID of the event itself, providing content-addressable integrityp (Prior Event Digest): Hash of the previous event, creating the cryptographic chainPTEL events follow the standard KERI event structure with specific fields for transaction management:
Common Fields (present in all PTEL events):
v: Version string specifying KERI version and serialization formati: Identifier of the registry controller (AID)s: Sequence number (hexadecimal string representation)t: Event type identifierd: Self-addressing identifier (SAID) of the eventp: Prior event digest (SAID of previous event)Registry-Specific Fields:
ri: Registry identifier (for VC TEL events)ra: Registry anchor (reference to management TEL)ba: Backer (Registrar) listbr: Backer removal listbt: Backer thresholdCredential-Specific Fields:
vc: Verifiable credential SAID (for issuance events)dt: Datetime of transactionPTEL events are encoded using CESR (Composable Event Streaming Representation), supporting both:
JSON Serialization: Human-readable format for debugging and development
{
"v": "KERI10JSON000116_",
"i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
"s": "0",
"t": "vcp",
"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
"bt": "2",
"b": ["BFUOWBaJz-sB_6b-_u_P9W8hgBQ8Su9mAtN9cY2sVGiY"],
"c": ["NB"]
}
Binary Serialization: Compact format for efficient transmission and storage using CESR binary encoding.
PTEL events have variable size depending on:
Typical constraints:
Management TEL Inception (vcp event):
The first step in creating a PTEL-based registry is establishing the management TEL through an inception event:
vcp (verifiable credential registry inception) eventVC TEL Inception (iss event):
For each credential to be issued, a separate VC TEL is created:
iss (verifiable credential issuance) eventCredential Revocation (rev event):
Revoking a credential involves:
rev event referencing the credential SAIDRegistrar Rotation:
The management TEL supports rotation of the Registrar set:
ba) and remove (br)bt) if neededPTEL Verification Process:
Validators verify PTEL events through a multi-step process:
Importantly, PTEL events themselves do not require signatures. The cryptographic commitment comes from:
This design reduces overhead while maintaining strong security guarantees through the KEL's established control authority.
PTELs are integral to several KERI ecosystem protocols:
ACDC Credential Issuance: When issuing ACDC credentials, issuers create VC TEL entries to establish the credential's initial issued state. The ACDC's ri (registry identifier) field references the management TEL, creating a verifiable link between the credential and its state tracking mechanism.
IPEX (Issuance and Presentation Exchange): During IPEX exchanges, verifiers check the PTEL to confirm a presented credential has not been revoked. The PTEL provides the authoritative source for credential status.
vLEI Ecosystem: The vLEI (verifiable Legal Entity Identifier) system extensively uses PTELs to track the lifecycle of organizational credentials, including:
PTEL lifecycle follows this progression:
Phase 1: Registry Establishment
Phase 2: Credential Issuance
Phase 3: Active State Management
Phase 4: Revocation (if needed)
Phase 5: Registry Maintenance
Key Event Log (KEL): The PTEL's authoritative anchor. Every PTEL event must be sealed in a KEL event to be considered valid. The KEL provides:
Key Event Receipt Log (KERL): When witnesses receipt KEL events containing PTEL seals, they create KERLs that provide additional validation of the PTEL's anchoring.
ACDC Credentials: The primary consumers of PTEL services. ACDCs reference PTELs through their ri field, enabling verifiers to check credential status.
OOBI (Out-Of-Band Introduction): Used to discover Registrars and retrieve PTEL events. OOBIs provide the network-level mechanism for locating and accessing PTEL data.
The PTEL specification explicitly states it is designed for public credentials only. The use of hash digests of credential contents as identifiers allows for correlation of credential uses across different presentations. This design trade-off prioritizes:
Transparency: Any party can verify credential status Auditability: Complete history of credential lifecycle is publicly available Simplicity: No complex privacy-preserving cryptography required
For private credentials requiring unlinkability, alternative approaches using blinded registries or zero-knowledge proofs would be necessary, though these are outside the scope of the current PTEL specification.
Implementers must carefully consider:
Registrar Count: More Registrars increase availability and fault tolerance but add coordination overhead. The specification recommends a minimum of 5 Registrars with a sufficient majority threshold.
Registrar Independence: Registrars should be operated by independent entities to prevent collusion and ensure genuine distributed validation.
Threshold Configuration: The backer threshold (bt) must balance security (requiring enough confirmations to prevent single-point failures) with availability (not requiring so many confirmations that temporary Registrar unavailability blocks operations).
Unlike KELs where sequence numbers must strictly follow the order of key management events, PTEL sequence numbers represent a registry-specific "clock" that can be:
Independent of KEL Sequence: A single KEL event can anchor multiple PTEL events with different sequence numbers
Context-Specific: Different registries can use different sequencing schemes (monotonic integers, timestamps, block heights)
Flexible: The sequence number scheme can be chosen based on the registry's operational requirements
For most credential registries, simple monotonically increasing integers provide the clearest and most maintainable approach.
PTEL events are anchored to KELs using Event Source Seals with the structure:
{
"s": "3",
"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"
}
In CESR encoding, these seals are delivered as attachments in duple format (s, d) with the group framing code -GAB:
-GAB
0AAAAAAAAAAAAAAAAAAAAAAw
ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM
Implementers must ensure:
Efficient Status Checking:
Verifiers should implement efficient PTEL query patterns:
Consistency Verification:
When querying multiple Registrars, verifiers should:
PTEL integration with ACDC issuance and presentation:
During Issuance:
ri field referencing management TELDuring Presentation:
ri field to identify registryDuring Revocation:
This workflow ensures that credential state is always verifiable through the PTEL infrastructure, providing a robust foundation for credential lifecycle management in the KERI ecosystem.
This ordering ensures verifiers can immediately check credential status upon first presentation.
For high-volume verification scenarios:
Implementations should handle:
Thorough testing should cover: