Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 10 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.
The current state of all temporary storage locations in a KERI implementation that track events awaiting additional information before they can be successfully processed, enabling the protocol to handle fully asynchronous event arrival where events may arrive out of order or with missing dependencies.
The escrow state represents a fundamental operational concept in KERI protocol implementations that addresses the inherent challenges of fully asynchronous, distributed event processing. At its core, escrow state is a snapshot of all temporary storage locations within a KERI system that tracks which events are currently waiting for additional information, what specific dependencies each event requires, and the relationships between escrowed events and their missing components.
The concept derives from the financial/legal term "escrow" - a temporary holding arrangement where assets or documents are held by a third party until specified conditions are met. In KERI's technical context, events are "held in escrow" (temporarily stored) until their processing prerequisites are satisfied, at which point they can be released from escrow and successfully processed.
Key properties of escrow state include:
The need for escrow mechanisms in distributed systems has long been recognized in computer science, particularly in contexts involving:
Asynchronous message passing systems: Where messages may arrive in arbitrary order due to network delays, routing variations, or processing differences across nodes.
Distributed databases: Where transactions may reference data that hasn't yet been replicated to all nodes, requiring temporary storage until consistency is achieved.
Event sourcing architectures: Where events must be processed in logical order despite arriving in physical disorder, necessitating buffering and reordering mechanisms.
KERI implementations must carefully design escrow state management to balance correctness, performance, and resource consumption:
Storage structures: Use efficient data structures (hash tables, indexed databases) that enable fast lookup of escrowed events by their dependencies. When a new event arrives, the implementation must quickly identify which escrowed events it satisfies.
Timeout policies: Implement configurable timeout values for different escrow categories. TEL anchoring might have shorter timeouts (seconds to minutes) while delegation verification might allow longer periods (minutes to hours). Events exceeding timeouts should be logged and potentially discarded to prevent resource exhaustion.
Resource limits: Enforce maximum escrow sizes to prevent memory exhaustion attacks where malicious actors flood the system with events requiring escrow. Implement eviction policies (LRU, priority-based) when limits are reached.
Dependency resolution: When processing a newly arrived event, check escrow state for events that were waiting for this dependency. Process released events recursively, as processing one escrowed event may satisfy dependencies for others.
Monitoring and observability: Expose escrow state metrics (current escrow size, average escrow duration, timeout rates) to enable operators to detect issues like network problems or attack attempts.
Persistence considerations: For production systems, escrow state should be persisted to durable storage to survive process restarts. However, very old escrowed events (beyond reasonable timeout periods) need not be persisted across restarts.
The keripy reference implementation provides concrete examples of escrow state management that other implementations can reference, though the specific implementation details may vary based on language, performance requirements, and deployment context.
Traditional approaches to handling out-of-order events typically involve:
KERI's escrow state concept builds on these foundations but addresses the specific challenges of a fully asynchronous, decentralized identity protocol where no central coordinator exists and events must be processed correctly despite arbitrary arrival patterns.
KERI's design philosophy embraces full asynchronicity as a core principle, making no guarantees about event arrival order. This design choice enables:
However, this asynchronicity creates processing challenges that escrow state directly addresses.
Transaction Event Log (TEL) Anchoring: One of the most common escrow scenarios involves TEL events for credentials. A TEL event (such as credential issuance or revocation) may arrive at a validator before the corresponding anchoring event in the KEL that cryptographically commits to it. The TEL event cannot be verified without the anchor, so it must be escrowed until the anchoring interaction event or rotation event arrives and can be validated.
Multisignature Event Processing: For multisig establishment events, individual signatures may arrive at different times from different signing parties. The event cannot be fully processed until a sufficient threshold of signatures has been collected. During this collection period, the partial event and accumulated signatures reside in escrow state, waiting for the threshold to be satisfied.
Out-of-Order Key Events: In distributed KERI deployments, a rotation event might arrive before all witnesses have confirmed the prior event. The rotation must be escrowed until the prior event's witness receipts are collected and verified, ensuring the key state progression is valid.
Delegated Identifier Events: For delegated identifiers, a delegated event may arrive before the corresponding delegating event from the delegator. The delegated event must be escrowed until the delegation authorization can be verified in the delegator's KEL.
KERI implementations must maintain escrow storage mechanisms that:
The escrow state encompasses several categories of information:
Forward dependency tracking: Events awaiting prerequisite events that must occur before them in logical sequence (e.g., waiting for an anchoring event)
Threshold accumulation: Events awaiting additional signatures or confirmations to meet required thresholds
Metadata management: Information about what each escrowed event is waiting for, when it entered escrow, and any timeout conditions
Relationship mapping: Connections between escrowed events and their dependencies, enabling efficient lookup when dependencies arrive
The keripy reference implementation manages escrow state through specialized database structures that enable efficient querying and updating as new events arrive. When a new event is received, the implementation:
KERI's escrow state differs from traditional distributed system buffering in several key ways:
Cryptographic verification: Escrow release is based on cryptographic validation of dependencies, not just sequence number ordering or timeout expiration.
Multiple dependency types: KERI escrow must handle diverse dependency types (anchoring, thresholds, delegation, witness confirmation) rather than simple sequence gaps.
End-verifiable integrity: The escrow mechanism must preserve KERI's end-verifiable properties, ensuring that events processed after escrow release maintain full cryptographic integrity.
Duplicity detection: Escrow state interacts with duplicity detection mechanisms, as escrowed events may reveal inconsistencies when compared with subsequently arriving events.
Credential Verification: When a verifier receives an ACDC credential presentation, they must verify the credential's status in its TEL. If the TEL events arrive before the anchoring KEL events, escrow state enables the verifier to temporarily hold the TEL events until the anchors can be verified, then complete verification without requiring the presenter to retransmit information.
Witness Pool Coordination: When a controller rotates their witness pool, different witnesses may receive and process the rotation at different times. Escrow state allows each witness to hold events that reference the new witness configuration until they've confirmed the rotation themselves.
Delegated Identifier Management: Organizations using hierarchical delegation trees can issue delegated identifiers even when network conditions cause delegation events to arrive out of order at various validators. Escrow state ensures correct processing regardless of arrival sequence.
Correctness without coordination: Escrow state enables KERI implementations to process events in their correct logical order without requiring centralized coordination or synchronous protocols.
Resilience to network conditions: Systems can tolerate arbitrary network delays, packet reordering, and temporary partitions while maintaining protocol correctness.
Scalability: By avoiding synchronous blocking, escrow-based processing enables high-throughput event processing across distributed validator networks.
Flexibility: Different implementations can employ different escrow strategies (timeout policies, storage limits, eviction algorithms) while maintaining protocol compatibility.
Resource consumption: Maintaining escrow state requires memory and storage resources proportional to the number of out-of-order events, potentially creating resource exhaustion vulnerabilities if not properly bounded.
Processing latency: Events held in escrow experience processing delays until their dependencies arrive, which may impact time-sensitive operations.
Implementation complexity: Escrow state management adds significant complexity to KERI implementations, requiring careful design of storage structures, dependency tracking, and timeout handling.
Timeout policy challenges: Determining appropriate timeout values for escrowed events involves trade-offs between responsiveness (short timeouts) and tolerance for network delays (long timeouts).
The source documents explicitly clarify that KERI's technical concept of escrow state is entirely unrelated to the legal/financial concept of "escrow states" in real estate transactions, despite sharing terminology. This distinction prevents confusion between the protocol's temporary event storage mechanism and legal escrow arrangements.