Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 83 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.
Percolated Information Discovery (PID) is a bootstrap discovery mechanism in the OOBI protocol that enables scalable, zero-trust discovery of KERI and ACDC resources through end-verifiable information propagation based on Invasion Percolation Theory, where each discoverer can share discoveries with subsequent discoverers without requiring trust in intermediaries.
Percolated Information Discovery (PID) is a discovery mechanism integrated into the OOBI (Out-Of-Band Introduction) protocol that provides bootstrap discovery capabilities for both KERI and ACDC protocols. The mechanism is grounded in mathematical Invasion Percolation Theory from physics and enables a unique approach to information discovery in decentralized identity systems.
PID accomplishes several critical objectives:
PID is employed in several key scenarios:
Parse OOBI Structure: Extract URL and AID/SAID from OOBI string, handling various formats (bare, query string, well-known paths)
Retrieve Initial Data: Make HTTP GET request to OOBI endpoint to retrieve KEL and associated data
Never Trust OOBI Source: Treat all retrieved data as untrusted until cryptographic verification completes
KEL Validation: Implement complete KEL verification including inception event validation, rotation chain verification, pre-rotation commitment checking, and signature verification for all events
Witness Receipt Validation: Verify witness receipts meet TOAD threshold requirements and contain valid signatures from designated witnesses
Duplicity Detection: Implement algorithms to detect duplicitous events by comparing event sequences and identifying conflicts
Information Sharing: Implement mechanisms to share verified discovery information with other participants, including KEL caching, endpoint registry maintenance, and peer-to-peer information exchange
Resistance Modeling: Model network resistance factors including endpoint latency, availability metrics, and bandwidth considerations to optimize percolation paths
Cluster Management: Track discovery clusters and maintain connectivity information for efficient propagation
Aggressive Caching: Cache verified KELs with appropriate TTL policies, store endpoint information with health metrics, and implement cache invalidation on detected updates
Parallel Discovery: Pursue multiple discovery paths simultaneously, implement timeout and retry logic, and aggregate results from multiple sources
Watcher Integration: Connect to watcher networks for aggregated discovery, implement watcher health monitoring, and failover to alternative watchers
Invalid OOBI: Handle unreachable endpoints gracefully, implement exponential backoff for retries, and log failures for debugging
The PID process involves several participant types:
The PID process begins with an OOBI bootstrap. An OOBI provides the initial association between a URL and an AID or SAID (Self-Addressing Identifier). This bootstrap can occur through various out-of-band channels:
The OOBI itself is not trusted—it merely provides a starting point for discovery. The critical security property is that all information obtained via the OOBI must be verified through KERI's cryptographic mechanisms.
Once the OOBI is processed, the discoverer retrieves initial information from the specified endpoint. This typically includes:
This information is retrieved but not yet trusted—it must undergo cryptographic verification.
The discoverer performs end-verifiable validation of all retrieved information:
KEL Verification: Validates the key event log structure, including:
Witness Receipt Validation: Verifies witness receipts to ensure events have been properly witnessed according to the threshold of accountable duplicity (TOAD)
Duplicity Detection: Checks for any duplicitous events that would indicate compromise or malicious behavior
Because all information is end-verifiable, the discoverer can cryptographically confirm authenticity without trusting the OOBI source or any intermediaries.
Once information is verified, the discoverer becomes a potential percolation source for subsequent discoverers. This is where the "percolation" aspect becomes critical:
This creates a cascading discovery pattern where information "percolates" through the network along paths of least resistance.
The percolation follows principles from Invasion Percolation Theory:
Least Resistance Principle: Information flows preferentially through paths with lower "resistance" (easier discovery routes, more accessible endpoints, better network connectivity)
Selective Infiltration: Discovery naturally gravitates toward nodes with lower barriers to access
Cluster Formation: A connected cluster of discoverers forms, all possessing verified information about the same identifiers
Incremental Growth: The discovery cluster grows by adding new nodes through neighboring nodes with lowest resistance
This mathematical model ensures efficient propagation without requiring centralized coordination.
After the initial bootstrap and verification, subsequent operations become non-interactive:
This non-interactive property is critical for achieving high scalability in distributed identity systems.
PID relies on several cryptographic foundations:
Self-Certifying Identifiers: All AIDs must be self-certifying, enabling verification without external trust anchors
CESR Encoding: All cryptographic primitives must use CESR (Composable Event Streaming Representation) for consistent encoding across text and binary domains
Digital Signatures: All key events must be signed using non-repudiable digital signatures, typically Ed25519
Hash Chain Integrity: KELs must maintain cryptographic hash chains linking events through digests
Pre-Rotation Commitments: Establishment events must include pre-rotation commitments to future keys
PID operates with specific timing characteristics:
Asynchronous Operation: Discovery is fully asynchronous—discoverers operate independently without synchronization requirements
First-Seen Policy: Witnesses and watchers apply first-seen policies to establish event ordering
Eventual Consistency: The discovery network achieves eventual consistency as information percolates
Microsecond Propagation: Within a witness network, consensus on first-seen events propagates within microseconds
No Timeout Requirements: Unlike traditional discovery protocols, PID does not require timeout-based coordination
PID includes robust error handling mechanisms:
Invalid OOBI Handling: If an OOBI points to invalid or unreachable endpoints, the discovery simply fails without compromising security
Duplicity Detection: If discovered information contains duplicitous events, the duplicity is detected during verification and the information is rejected
Partial Information: If only partial information is available, discoverers can operate with what they have and obtain additional information through continued percolation
Stale Information: Stale information is detected through sequence number analysis and can be updated through fresh discovery
Malicious Sources: Because all information is end-verifiable, malicious sources cannot inject false information—they can only cause discovery failures
A new participant joins the KERI ecosystem:
A verifier needs to verify an ACDC credential:
A controller needs to configure witnesses:
Multiple Discovery Paths: Obtain OOBIs from multiple independent sources to reduce dependency on any single discovery path
Verify Before Trust: Always perform full cryptographic verification before trusting discovered information
Cache Verified Information: Store verified KELs and endpoint information to reduce discovery overhead
Monitor for Updates: Implement mechanisms to detect when cached information becomes stale
Contribute to Percolation: Share verified discovery information with other participants to strengthen the network
Use Well-Known Endpoints: Leverage well-known OOBI paths (e.g., /.well-known/keri/oobi/) for standardized discovery
Implement Watcher Networks: Deploy watchers as super-nodes that aggregate discovery information for efficient percolation
PID integrates with core KERI components:
PID enables ACDC credential verification:
The IPEX (Issuance and Presentation Exchange) protocol leverages PID:
Percolation theory is a mathematical framework originally developed to study fluid flow through porous media. The theory models:
While originating in physics, percolation theory has found applications across mathematics, computer science, epidemiology, and social sciences.
Invasion percolation is a specific variant that models how fluids infiltrate porous media:
Principle of Least Resistance: The invading fluid seeks paths of minimum resistance through the network
Selective Infiltration: As invasion progresses, the fluid selectively infiltrates sites with lower resistance
Connected Cluster Formation: A connected cluster of invaded sites forms incrementally
Neighbor-Based Growth: New sites are added through neighboring dry sites with lowest resistance
The invasion percolation model maps naturally to information discovery:
PID implements true zero-trust discovery:
PID has specific privacy characteristics:
PID is fundamentally enabled by OOBI:
SPED is a specific application of PID:
PID works in conjunction with BADA policy:
PID continues to evolve:
Percolated Information Discovery represents a fundamental innovation in decentralized identity systems, enabling scalable, secure discovery without centralized infrastructure or trusted intermediaries. By grounding the approach in mathematical percolation theory and leveraging KERI's end-verifiable security properties, PID provides a robust foundation for the discovery needs of the KERI and ACDC ecosystems.
Verification Failures: Reject information that fails cryptographic verification, log verification failures with detailed error information, and implement alerting for repeated failures
Partial Information: Handle scenarios where only partial KEL is available, implement progressive discovery to obtain missing events, and maintain consistency during incremental updates
Validate All Inputs: Never trust OOBI sources or percolation intermediaries, always perform full cryptographic verification, and implement defense against malformed data
Prevent Injection Attacks: Sanitize all URL inputs, validate JSON structure before parsing, and implement rate limiting to prevent DoS
Monitor for Attacks: Detect and log suspicious discovery patterns, implement anomaly detection for unusual percolation behavior, and alert on potential attack indicators
KERI Infrastructure: Integrate with witness networks for authoritative KEL retrieval, connect to watcher networks for aggregated discovery, and coordinate with cloud agents for identifier management
ACDC Credentials: Discover issuer KELs for credential verification, locate TEL registries for revocation checking, and resolve schema SAIDs for credential validation
IPEX Protocol: Discover presentation endpoints for credential exchange, locate issuance services for credential requests, and find verification services for credential validation