Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 18 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 race condition in KERI occurs when the system's behavior depends on the sequence or timing of uncontrollable events, particularly in distributed witness coordination, concurrent key event processing, or duplicity detection, where different orderings of the same events can lead to inconsistent or undesirable states.
A race condition is a situation where the correctness of a system's behavior depends on the relative timing or sequence of events that cannot be controlled or predicted. In distributed systems like KERI, race conditions become particularly significant because multiple independent entities (witnesses, watchers, controllers) may observe or process events in different orders, potentially leading to inconsistent views of key state or duplicity detection failures.
KERI's distributed architecture creates several scenarios where race conditions can occur:
Witness Coordination: When a controller publishes a key event to multiple witnesses, the witnesses may receive and process the event at different times. If a malicious controller attempts to publish conflicting events (duplicity), the order in which witnesses receive these events affects their ability to detect the attack. The first-seen policy in KERI addresses this by having each witness commit to the first version of an event they observe, making duplicity detectable even if events arrive in different orders.
Concurrent Key Event Processing: In systems with multiple watchers or validators processing KEL events simultaneously, race conditions can occur when events are being verified against a key state that is itself being updated. For example, if a rotation event and an arrive nearly simultaneously, different validators might process them in different orders, temporarily creating inconsistent views of the current key state.
Witness Implementation: Witness implementations must maintain strict first-seen policies, recording the exact timestamp and content of the first version of each event observed. This creates an immutable record that can be used to detect duplicity even when different witnesses observe events in different orders.
Event Processing: Validators should implement proper escrow mechanisms to handle out-of-order event arrival. Events that reference not-yet-seen prior events should be temporarily stored rather than rejected, preventing race conditions from causing permanent processing failures.
Concurrency Control: Systems processing KELs concurrently must use appropriate locking or versioning mechanisms to ensure that key state updates are atomic and that validators always work with consistent snapshots of key state.
Network Timing: Implementations should not make assumptions about network timing or event ordering. The protocol is designed to be timing-independent, with correctness guaranteed by cryptographic commitments rather than temporal ordering.
Duplicity Detection Timing: The KAACE (KERI's Agreement Algorithm for Control Establishment) consensus mechanism must handle race conditions where witnesses observe potentially conflicting events. The algorithm's design ensures that even when events arrive in different orders at different witnesses, the system can still achieve agreement on the authoritative event sequence through the threshold of accountable duplicity (TOAD) mechanism.
KERI employs several architectural patterns to handle race conditions:
Append-Only Logs: The KEL structure is append-only, meaning events cannot be modified or reordered after commitment. This immutability prevents certain classes of race conditions by ensuring that once an event is witnessed, its position in the log is fixed.
Cryptographic Commitment: Each event includes cryptographic commitments (digests) to previous events, creating a hash chain that makes event ordering verifiable. Any attempt to reorder events would break the cryptographic chain, making tampering detectable.
First-Seen Policy: Witnesses commit to the first version of each event they observe, creating a permanent record that can be used to detect duplicity even if different witnesses saw events in different orders.
Escrow Mechanisms: KERI's escrow system handles out-of-order event arrival by temporarily storing events that cannot yet be processed, then processing them when prerequisite events arrive. This prevents race conditions from causing permanent inconsistencies.