Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 17 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.
Keridemlia is a distributed hash table (DHT) implementation combining KERI with Kademlia protocol to provide decentralized discovery of witness IP addresses and identifier-to-controller mappings, functioning as a DNS-like service specifically designed for the KERI ecosystem.
Keridemlia is a specialized distributed hash table (DHT) implementation that merges KERI (Key Event Receipt Infrastructure) with the Kademlia peer-to-peer protocol. The name is a portmanteau reflecting this combination. Written as a modification of the Python Kademlia library, keridemlia serves as decentralized infrastructure for witness discovery within the KERI ecosystem, eliminating reliance on centralized DNS-like services while maintaining cryptographic verifiability of all published data.
The implementation addresses a critical architectural requirement: enabling indirect mode KERI operations where validators need to discover and communicate with witnesses without centralized coordination. Unlike traditional DHTs that accept arbitrary data, keridemlia implements end-to-end cryptographic verification of all stored mappings, preventing data poisoning attacks that plague conventional distributed hash tables.
Keridemlia integrates directly with the KERIpy library, utilizing KERI's specialized database classes for storing key events, keys, and metadata. This tight integration ensures that published data maintains consistency with KERI's key event logs (KELs) and key state semantics.
Implementations MUST perform full cryptographic verification before storing any data:
After verification, implementations SHOULD:
The implementation modifies Kademlia's storage backend to use KERIpy database classes:
Keridemlia provides two fundamental mapping services that mirror DNS functionality but with KERI-specific semantics:
1. Transferable AID to Key Event State Mappings
For transferable identifiers, keridemlia stores mappings from Autonomic Identifiers (AIDs) to their current Key Event State (KES). This enables validators to:
The KES includes critical information such as current signing keys, next key digests, witness configurations, and threshold requirements. By publishing this state to the DHT, controllers enable distributed discovery while maintaining cryptographic proof of authenticity.
2. Non-transferable Witness AID to IP Address Mappings
For non-transferable identifiers used by witnesses, keridemlia stores mappings from witness AIDs to their network endpoints (IP addresses and ports). This enables:
Witnesses use non-transferable identifiers because they don't require key rotation capabilities—if a witness's keys are compromised, the witness simply creates a new identifier rather than rotating keys. This simplifies the security model for witness infrastructure.
The defining innovation of keridemlia is its mandatory cryptographic verification of all published data before storage. Unlike traditional DHTs where malicious nodes can publish arbitrary data, keridemlia implements verification logic that:
For KES Mappings:
For IP Address Mappings:
After verification, keridemlia strips signatures before storage to optimize space and prevent signature reuse attacks. The verification happens at publication time, and subsequent retrievals rely on the DHT's content-addressable properties to ensure integrity.
Keridemlia exposes a simplified REST API over the underlying Kademlia DHT with four primary endpoints:
POST /id - Publish AID to KES mapping
GET /id/<aid> - Retrieve KES for specific AID
POST /ip - Publish witness AID to IP address mapping
GET /ip/<witness_id> - Retrieve IP addresses for witness AID
This API design prioritizes simplicity and verifiability over feature richness, reflecting KERI's philosophy of minimizing attack surface through reduced complexity.
Keridemlia integrates with the broader KERI ecosystem through several mechanisms:
KERIpy Database Integration: The implementation modifies Kademlia's storage backend to use KERIpy's database classes, ensuring consistency with how KERI stores events and key state. This enables:
Witness Discovery Protocol: Keridemlia serves as the discovery layer for KERI's witness protocol, enabling:
Out-of-Band Introduction (OOBI) Enhancement: While OOBI provides initial bootstrap, keridemlia enables ongoing discovery without repeated out-of-band communication. Once an identifier is published to keridemlia, validators can discover current witness endpoints dynamically.
The whitepaper documents extensive research comparing three distributed storage approaches:
Hierarchical Systems (DNS-like):
Blockchain-based Systems:
DHT-based Systems (Kademlia):
Kademlia specifically was chosen because:
Keridemlia's security model addresses traditional DHT vulnerabilities through KERI's cryptographic primitives:
Sybil Attack Mitigation: While keridemlia doesn't prevent Sybil attacks (malicious actors creating many nodes), it renders them ineffective through cryptographic verification. Even if an attacker controls a majority of DHT nodes, they cannot:
Data Poisoning Prevention: Traditional DHTs accept any data, enabling poisoning attacks. Keridemlia's verification layer ensures:
Eclipse Attack Resistance: By distributing data across multiple DHT nodes and enabling validators to query multiple sources, keridemlia reduces vulnerability to eclipse attacks where an attacker isolates a victim from honest nodes.
Duplicity Detection: Keridemlia enables ambient duplicity detection by allowing validators to query multiple DHT nodes and compare results. If different nodes return conflicting KELs for the same identifier, duplicity is detected, triggering KERI's accountability mechanisms.
The whitepaper analyzes keridemlia's performance profile:
Lookup Latency:
Storage Requirements:
Network Bandwidth:
Scalability:
Keridemlia provides CNAME-like functionality but with fundamental differences:
Similarities:
Differences:
Based on the whitepaper (dated 2022), keridemlia was described as a research prototype demonstrating feasibility. The document does not provide:
The implementation modifies the Python Kademlia library to integrate with KERIpy's database classes and adds verification logic, but the whitepaper focuses on architectural design rather than implementation details.
Keridemlia is not part of the core KERI protocol specification. Instead, it represents one possible implementation of the discovery layer that KERI requires for indirect mode operations. The KERI protocol itself is agnostic to discovery mechanisms—implementations could use:
Keridemlia's value proposition is providing decentralized, verifiable discovery that aligns with KERI's trust model without introducing centralized dependencies.
The whitepaper identifies several areas for future development:
Enhanced Privacy:
Performance Optimization:
Governance Mechanisms:
Interoperability:
Keridemlia represents a thoughtful application of DHT technology to KERI's discovery requirements, addressing traditional DHT vulnerabilities through cryptographic verification while maintaining decentralization and scalability. By combining Kademlia's proven routing algorithms with KERI's self-certifying identifiers and verifiable key event logs, keridemlia provides a discovery infrastructure that aligns with KERI's security model and decentralization philosophy.
The implementation demonstrates that decentralized discovery is feasible for KERI without sacrificing security or introducing centralized trust dependencies. While the whitepaper describes a research prototype rather than production-ready infrastructure, it establishes the architectural foundation for building scalable, verifiable discovery services in the KERI ecosystem.
Keridemlia is one possible discovery mechanism—implementations should consider:
The choice depends on deployment scale, security requirements, and operational constraints.