Escrow Storage

When an event cannot be immediately processed:

1. Classification: The event is categorized by escrow type (out-of-order, partially-signed, delegation pending, etc.)
2. Storage: The event is stored in the appropriate escrow database with metadata about required dependencies
3. Indexing: The system maintains indices to efficiently query escrowed events when dependencies arrive
4. Timeout Configuration: An escrow timeout is set (configurable, often measured in seconds to hours)

Dependency Resolution

As new information arrives in the system:

1. Trigger Events: New KEL events, signatures, or other data arrive that may satisfy escrow dependencies
2. Escrow Query: The system queries escrowed events to identify those whose dependencies are now satisfied
3. Validation Retry: Previously escrowed events are re-evaluated for processing
4. State Transition: Successfully validated events move from escrow to the main KEL or processing pipeline

Escrow Cleanup

The system manages escrow lifecycle:

1. Timeout Monitoring: Events that remain in escrow beyond configured timeouts are identified
2. Removal Decision: Timed-out events are removed from escrow (they may be invalid or from malicious actors)
3. Resource Management: Escrow cleanup prevents indefinite accumulation of unprocessable events
4. Logging: Removed events may be logged for forensic analysis

Technical Requirements

Cryptographic Requirements

Escrow operations must maintain cryptographic integrity:

• Signature Preservation: Escrowed events must preserve all attached signatures without modification
• Digest Integrity: Event digests must remain unchanged during escrow storage and retrieval
• CESR Encoding: Events in escrow maintain their CESR (Composable Event Streaming Representation) encoding
• Seal Verification: Anchoring seals must be verifiable when events exit escrow

Timing Considerations

The escrow mechanism operates within specific timing constraints:

Escrow Timeout Configuration: The escrow_config parameter (measured in seconds) determines how long events remain in escrow before automatic removal. This prevents indefinite storage of invalid or malicious events. Typical values range from seconds (for high-performance systems) to hours (for loosely-coordinated systems).

First-Seen Policy Interaction: The escrow mechanism operates independently of the first-seen rule. Events in escrow (including invalid or "garbage" events) do not affect first-seen determination. When a valid event arrives that matches the next expected sequence number, it is immediately accepted as first-seen regardless of what may be waiting in escrow.

Propagation Speed: When escrowed events are released and processed, watchers propagate the agreed-upon events within microseconds across the validator network, ensuring rapid convergence.

Error Handling

Robust error handling is essential for escrow operations:

Invalid Event Detection: Events that fail cryptographic validation or structural checks may be placed in escrow temporarily but should be removed quickly to prevent resource exhaustion.

Circular Dependencies: The system must detect and handle circular dependency scenarios where Event A waits for Event B, which waits for Event A.

Resource Limits: Escrow storage must implement limits to prevent denial-of-service attacks through escrow flooding.

Recovery Mechanisms: If escrow state becomes corrupted, the system must have recovery procedures to rebuild escrow from authoritative KEL sources.

Usage Patterns

Common Escrow Scenarios

Out-of-Order KEL Events

The most common escrow scenario occurs when KEL events arrive out of sequence:

Scenario: A validator receives Event N+2 before Event N+1 has arrived.

Escrow Action: Event N+2 is placed in out-of-order escrow, indexed by its sequence number.

Resolution: When Event N+1 arrives and is processed, the system queries escrow for Event N+2, validates it, and processes it in correct sequence order.

TEL-KEL Anchoring Dependencies

Transaction Event Logs (TELs) must be anchored to KEL events:

Scenario: A TEL event for a credential arrives before the corresponding KEL interaction event that anchors it.

Escrow Action: The TEL event is placed in escrow awaiting the anchoring KEL event.

Resolution: When the KEL event arrives with the appropriate seal, the TEL event is retrieved from escrow and processed.

Multisig Partial Signatures

Multisignature events require threshold-satisfying signatures:

Scenario: A multisig rotation event arrives with 2 of 3 required signatures.

Escrow Action: The partially-signed event enters escrow awaiting additional signatures.

Resolution: As additional signatures arrive, they are attached to the escrowed event. Once the threshold is satisfied, the event exits escrow and is processed.

Delegation Approval Pending

Delegated identifiers require approval from delegating identifiers:

Scenario: A delegated inception event arrives before the delegator has created the corresponding delegation seal.

Escrow Action: The delegated event is placed in delegation escrow.

Resolution: When the delegator's KEL includes the delegation seal, the delegated event is validated and processed.

Best Practices

Escrow Timeout Tuning: Configure escrow timeouts based on expected network latency and coordination requirements. High-performance systems may use seconds; loosely-coordinated systems may use hours or days.

Monitoring Escrow State: Implement monitoring to track escrow queue depths and identify potential issues (network partitions, malicious flooding, configuration errors).

Escrow Type Separation: Maintain separate escrow queues for different event types (out-of-order, partially-signed, delegation pending) to optimize query performance and timeout management.

Resource Limits: Implement per-identifier and global escrow limits to prevent resource exhaustion attacks.

Logging and Forensics: Log escrow operations (entry, exit, timeout) for debugging and security analysis.

Integration Considerations

Database Implementation: Escrow requires persistent storage with efficient indexing. The KERIpy implementation migrated from Sled to Redb for improved performance and reliability.

Witness Integration: Witnesses must escrow partially-signed multisig events and query escrow when new signatures arrive.

Watcher Integration: Watchers operating in promiscuous mode must escrow events from multiple identifiers and manage escrow state across their monitored KELs.

Agent Integration: Cloud agents (KERIA) must manage escrow state across multiple client AIDs in multi-tenant deployments.

IPEX Protocol: The Issuance and Presentation Exchange protocol relies on escrow for managing asynchronous credential issuance workflows where multiple parties must coordinate signatures over extended timeframes.

Escrow State Management

The escrow state represents a comprehensive snapshot of all temporary storage locations and pending operations across the KERI system. This state includes:

• Which events are currently held in escrow across all escrow types
• What specific information each escrowed event is waiting for (missing signatures, prerequisite events, delegation approvals)
• The relationships between escrowed events and their dependencies
• Timeout information for each escrowed event
• Metadata about escrow entry time, retry attempts, and validation failures

Effective escrow state management is essential for KERI implementations to handle the complexity of asynchronous, distributed event processing while maintaining protocol correctness and system performance. The escrow mechanism transforms KERI's fully asynchronous architecture from a theoretical challenge into a practical, implementable system that can handle real-world network conditions and coordination requirements.

Integration with IPEX

The IPEX protocol for credential issuance relies heavily on escrow for managing asynchronous workflows:

• Credential Issuance Escrow: Partially-signed credentials await threshold signatures
• Presentation Escrow: Credential presentations may be escrowed pending verification
• Extended Timeframes: IPEX workflows may require escrow timeouts measured in hours or days rather than seconds