Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 133 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 watcher is an entity or component that maintains copies of Key Event Receipt Logs (KERLs) for identifiers but is not designated by the controller, operating in promiscuous mode to enable ambient duplicity detection across the KERI network.
A watcher is a critical infrastructure component in KERI that maintains copies of Key Event Receipt Logs (KERLs) for autonomic identifiers (AIDs) without being formally designated by the identifier's controller. Unlike witnesses, which are explicitly chosen by controllers to provide receipting services, watchers operate independently and promiscuously—monitoring and recording key events without selective criteria.
Watchers implement the "first-seen wins" principle: the first version of a key event log observed by a watcher becomes the permanent record for that watcher. This immutability is captured in the rule: "First seen, always seen, never unseen." This operational principle is fundamental to KERI's duplicity detection mechanism.
Watchers are central to KERI's security model, which replaces traditional consensus mechanisms with duplicity detection. Rather than requiring global agreement on a single canonical event sequence, KERI allows multiple independent watchers to observe and record KELs. If a controller attempts to publish inconsistent versions of their KEL (duplicitous behavior), watchers will detect this by comparing their first-seen records.
The distributed nature of watchers creates a powerful deterrent: because watchers can be anyone and anywhere, controllers of public identifiers face significant risk if they attempt duplicity. The unpredictability of watcher deployment means controllers cannot know which entities are monitoring their KELs, making duplicitous behavior detectable and therefore undesirable.
Resource Constraints: The primary limitation on watcher network expansion is resource availability. Organizations must balance security benefits (more watchers) against operational costs (infrastructure maintenance).
Trust Relationships: Validators should establish relationships with multiple geographically and organizationally diverse watchers to maximize eclipse attack resistance.
Cooperative Sharing: Even competing organizations benefit from sharing duplicity information across the ecosystem, similar to certificate transparency systems in traditional PKI.
Watchers represent a fundamental architectural innovation in KERI, replacing expensive consensus mechanisms with efficient duplicity detection through distributed observation.
Promiscuous Mode: Watchers run in promiscuous mode, using the same codebase as witnesses but operating without the selective acceptance criteria that witnesses employ. This "lacking standards of selection" approach enables comprehensive monitoring across the KERI ecosystem.
Validator Trust Relationships: Validators establish trust relationships with specific watchers. When validating an identifier's key state, validators query their trusted watchers to obtain KERL copies and detect any inconsistencies. This creates a confirmation network separate from the witness promulgation network.
Escrow and Reconciliation: Watchers may temporarily hold events in escrow when they arrive out of order or cannot be immediately validated. The first-seen principle applies only to valid events that fit the proper sequence position in the KEL.
Eclipse Attack Mitigation: The primary threat to KERI systems is eclipse attacks, where an attacker isolates a validator from honest network participants. Expanding watcher network reach provides the primary defense—the more geographically and organizationally distributed watchers are, the harder it becomes to eclipse a validator's view of the network.
Ambient Verifiability: Watchers enable ambient verifiability—the principle that any data can be verified by anybody, anywhere, at any time. This property is fundamental to KERI's zero-trust architecture.
In the ACDC credential ecosystem, watchers play a crucial role in verifying the KEL-backed data that provides the cryptographic foundation for verifiable credentials. When credentials are presented, verifiers can query watchers to confirm the issuer's key state and detect any duplicitous behavior in the credential issuance chain.