Comprehensive Explanation

Registry

Process Definition

A registry in the KERI/ACDC ecosystem serves as an authoritative record-keeping system that tracks the lifecycle state of verifiable credentials and other data objects. Unlike traditional centralized registries that require trusted third parties, KERI registries are implemented as Transaction Event Logs (TELs) - cryptographically verifiable, hash-linked data structures that are anchored to the controlling identifier's Key Event Log (KEL).

What It Accomplishes

The registry accomplishes several critical functions:

1. State Tracking: Maintains the current status of credentials (issued, revoked, suspended)
2. Cryptographic Proof: Provides verifiable proof of registry state through cryptographic commitments
3. Decentralized Verification: Enables any validator to independently verify the authoritative state without trusting intermediaries
4. Lifecycle Management: Tracks the complete lifecycle of credentials from issuance through revocation
5. Audit Trail: Creates an immutable, verifiable history of all state changes

When It's Used

Registries are used in several key scenarios:

• Credential Issuance: Recording when a verifiable credential is issued to a holder
• Credential Revocation: Marking credentials as revoked when they should no longer be trusted
• Status Verification: Allowing verifiers to check the current validity status of presented credentials
• Registry Creation: Establishing new credential registries for specific issuers or credential types
• Backer Management: Tracking which entities (Registrars) provide backing services for the registry

Key Participants

The registry process involves several key roles:

1. Registry Controller: The AID that controls the registry, typically the credential issuer
2. Registrars (Backers): Entities that maintain copies of the TEL and provide verification services
3. Credential Holders: Entities that receive credentials tracked in the registry
4. Verifiers: Entities that query the registry to check credential status
5. Validators: Any party that can cryptographically verify the registry state

Process Flow

Registry Creation

The registry creation process follows a specific sequence:

Step 1: Management TEL Inception

• The registry controller creates a Management Transaction Event Log (Management TEL)
• This TEL signals the creation of the Virtual Credential Registry (VCR)
• The Management TEL tracks the list of Registrars that will act as backers
• The inception event is anchored to the controller's KEL through a cryptographic seal

Step 2: Registrar Configuration

• The Management TEL records which Registrars will provide backing services
• Registrars are analogous to witnesses in KERI KELs
• Each Registrar maintains a copy of the TEL and provides receipts
• The configuration specifies thresholds for Registrar consensus

Step 3: Registry Activation

• Once the Management TEL is established and witnessed, the registry becomes operational
• The registry can now track individual credential lifecycle events
• The registry identifier (ri field) is used to reference this registry in credentials

Credential Lifecycle Tracking

Issuance Event (bis - backed vc issue)

When a credential is issued:

1. VC TEL Creation: A Virtual Credential Transaction Event Log (VC TEL) is created for the specific credential
2. Issuance Transaction: An issuance transaction is recorded in the VC TEL
3. Management Reference: The VC TEL contains a reference to its corresponding Management TEL
4. KEL Anchoring: The issuance transaction is anchored to the issuer's KEL through a seal in an interaction or rotation event
5. Registrar Witnessing: Registrars observe the transaction and provide receipts
6. State Update: The credential's state is set to "issued"

Revocation Event (brv - backed vc revoke)

When a credential is revoked:

1. Revocation Transaction: A revocation transaction is added to the credential's VC TEL
2. KEL Anchoring: The revocation is anchored to the issuer's KEL
3. Registrar Witnessing: Registrars observe and receipt the revocation
4. State Update: The credential's state changes to "revoked"
5. Grace Period: Some implementations include a grace period (default 90 days) before finalization
6. Ghost Credential: During the grace period, the credential may exist as a "ghost credential" - technically valid but pending revocation

State Verification

When a verifier checks credential status:

Step 1: Credential Presentation

• The holder presents the credential to the verifier
• The credential includes a registry identifier (ri field)

Step 2: Registry Resolution

• The verifier resolves the registry identifier to locate the TEL
• This may involve OOBI resolution or other discovery mechanisms

Step 3: TEL Retrieval

• The verifier retrieves the relevant VC TEL for the credential
• The verifier also retrieves the Management TEL to verify registry authority

Step 4: Cryptographic Verification

• The verifier validates the TEL's cryptographic anchoring to the issuer's KEL
• The verifier checks Registrar receipts to confirm consensus
• The verifier verifies the KEL signatures to confirm issuer authority

Step 5: State Determination

• The verifier examines the VC TEL to determine current state
• The most recent transaction determines the credential's status
• The verifier makes a trust decision based on the verified state

State Changes and Monotonicity

The registry follows a RUN (Read, Update, Nullify) model rather than traditional CRUD:

• Read: Query the current state from the TEL
• Update: Add new transactions to change state (issuance, revocation)
• Nullify: Mark credentials as revoked (no deletion)

This model ensures:

• Monotonicity: State changes are append-only and irreversible
• Auditability: Complete history is preserved
• Replay Protection: Sequence numbers and timestamps prevent replay attacks

Technical Requirements

Cryptographic Requirements

Hash-Linked Structure

• TELs must be hash-linked data structures
• Each transaction includes a cryptographic digest of the previous transaction
• This creates a tamper-evident chain of state changes

KEL Anchoring

• All TEL transactions must be anchored to the controlling KEL
• Anchoring is achieved through event source seals in KEL events
• The seal contains the sequence number and digest of the TEL transaction
• This binds the TEL to the authoritative key state of the issuer

Registrar Receipts

• Registrars must provide signed receipts for TEL transactions
• Receipts prove that Registrars have observed the transaction
• A threshold of Registrar receipts is required for consensus
• Receipts are encoded in CESR format for composability

SAID Integration

• Registry identifiers should be SAIDs (Self-Addressing Identifiers)
• SAIDs provide content-addressable integrity verification
• Any modification to the registry structure invalidates the SAID

Timing Considerations

Sequence Numbering

• TEL transactions use sequence numbers for ordering
• Sequence numbers may represent different "clocks" (wall time, block height, monotonic counter)
• For credential registries, monotonically increasing integers are typical

Grace Periods

• Some implementations include grace periods for revocation (default 90 days)
• During the grace period, credentials may exist as "ghost credentials"
• Grace periods allow for revocation processing and notification

Timestamp Validation

• Timestamps in TEL transactions should be validated against acceptable ranges
• Clock drift and network latency must be accounted for
• KRAM (KERI Request Authentication Method) provides replay attack protection

Asynchronous Processing

• Registry operations are inherently asynchronous
• Registrars may observe transactions at different times
• Eventual consistency is achieved through Registrar consensus

Error Handling

Duplicity Detection

• If multiple conflicting versions of a TEL exist, duplicity is detected
• Validators can identify inconsistencies by comparing TEL versions
• Duplicity evidence can be used to challenge the registry controller

Missing Transactions

• If a transaction is missing from the sequence, the TEL is incomplete
• Validators should reject incomplete TELs or request missing transactions
• Redundancy through multiple Registrars mitigates deletion attacks

Invalid Anchoring

• If a TEL transaction is not properly anchored to the KEL, it is invalid
• Validators must verify the cryptographic seal in the KEL
• Invalid transactions should be rejected

Threshold Failures

• If insufficient Registrar receipts are available, consensus is not achieved
• The transaction may be in escrow pending additional receipts
• Validators should wait for threshold satisfaction before accepting state changes

Key Compromise

• If the registry controller's keys are compromised, the registry may be attacked
• KERI's pre-rotation mechanism provides recovery from key compromise
• Validators should monitor for duplicity and suspicious state changes

Usage Patterns

Public Verifiable Credential Registry

The most common usage pattern is a Public Verifiable Credential Registry that tracks credentials issued by a specific issuer:

Setup Phase

1. Issuer creates a Management TEL to establish the registry
2. Issuer designates Registrars to provide backing services
3. Issuer publishes OOBIs for registry discovery

Issuance Phase

1. Issuer creates a credential with a registry identifier (ri field)
2. Issuer creates a VC TEL for the credential
3. Issuer records an issuance transaction in the VC TEL
4. Issuer anchors the transaction to their KEL
5. Registrars witness and receipt the transaction

Verification Phase

1. Holder presents the credential to a verifier
2. Verifier resolves the registry identifier
3. Verifier retrieves the VC TEL and Management TEL
4. Verifier validates the cryptographic anchoring
5. Verifier checks the current state (issued/revoked)
6. Verifier makes a trust decision

Revocation Phase

1. Issuer decides to revoke the credential
2. Issuer adds a revocation transaction to the VC TEL
3. Issuer anchors the revocation to their KEL
4. Registrars witness and receipt the revocation
5. The credential's state changes to "revoked"

Blinded Revocation Registry

For privacy-preserving use cases, a Blinded Revocation Registry can be used:

Privacy Properties

• The current state of the TEL is hidden or blinded
• Only the controller of a designated AID can disclose the state
• Disclosure occurs at the time of presentation
• This prevents correlation through public registry queries

Implementation

• Uses cryptographic techniques like salted hashes
• Provides protection against rainbow table attacks
• Requires sufficient entropy in the blinding factors
• The presenter performs decomposition to enable verification

Use Cases

• High-privacy credentials where correlation is a concern
• Selective disclosure scenarios
• Credentials with sensitive attributes

Schema Registry

While traditional systems use centralized schema registries, ACDC eliminates the need for centrally controlled namespace registries:

ACDC Approach

• Schemas are identified by SAIDs
• SAIDs provide content-addressable integrity
• No central registry is required for schema management
• Schemas can be distributed through OOBIs or other mechanisms

Benefits

• Decentralization: No single point of control
• Portability: Schemas are not tied to specific infrastructure
• Integrity: SAIDs ensure schema immutability
• Interoperability: Schemas can be referenced universally

vLEI Credential Registry

The vLEI (verifiable Legal Entity Identifier) ecosystem uses registries extensively:

QVI Credential Registry

• GLEIF issues QVI credentials to Qualified vLEI Issuers
• A registry tracks the issuance and revocation of QVI credentials
• QVIs use their credentials to issue Legal Entity credentials

Legal Entity Credential Registry

• QVIs maintain registries for Legal Entity credentials
• Each Legal Entity credential is tracked in a VC TEL
• The registry enables verification of Legal Entity credentials

Role Credential Registries

• Legal Entities maintain registries for OOR and ECR credentials
• Role credentials are tracked for issuance and revocation
• Verifiers can check the status of role credentials

Best Practices

Registry Design

• Use a Management TEL to track registry infrastructure
• Designate multiple Registrars for redundancy
• Set appropriate thresholds for Registrar consensus
• Publish OOBIs for registry discovery

Transaction Management

• Anchor all transactions to the controlling KEL
• Use sequence numbers for ordering
• Include timestamps for temporal validation
• Ensure Registrar receipts are collected

State Verification

• Always verify the cryptographic anchoring to the KEL
• Check Registrar receipts for consensus
• Validate the KEL signatures
• Monitor for duplicity

Error Handling

• Implement retry logic for Registrar communication
• Handle missing transactions gracefully
• Detect and report duplicity
• Provide clear error messages

Privacy Considerations

• Use blinded registries for high-privacy use cases
• Minimize correlation through registry queries
• Implement graduated disclosure patterns
• Consider chain-link confidentiality

Integration Considerations

KERI Integration

• Registries are tightly integrated with KERI KELs
• The KEL provides the root of trust for the registry
• Registry operations must be coordinated with KEL events

ACDC Integration

• ACDCs reference registries through the ri field
• The registry identifier should be a SAID
• Credentials can be verified by checking the registry

IPEX Integration

• The IPEX protocol handles credential presentation
• Verifiers use IPEX to request credential status
• Holders use IPEX to present credentials with registry proofs

Witness/Watcher Integration

• Registrars function similarly to witnesses
• Watchers can monitor registries for duplicity
• The witness/watcher infrastructure supports registry operations

Discovery Integration

• OOBIs enable registry discovery
• Well-known URIs can publish registry endpoints
• KERI DHT can be used for registry discovery