Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 188 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.
In computing, input/output (I/O) refers to the communication between an information processing system (such as a computer) and the outside world, where inputs are signals or data received by the system and outputs are signals or data sent from it.
Input/Output (I/O) represents the fundamental mechanism by which computing systems exchange data with external entities. In computing, input/output is the communication between an information processing system, such as a computer, and the outside world, possibly a human or another information processing system. Inputs are the signals or data received by the system, and outputs are the signals or data sent from it. The term can also be used as part of an action: "to perform I/O" is to perform an input or output operation.
Within the KERI (Key Event Receipt Infrastructure) and ACDC (Authentic Chained Data Container) ecosystem, I/O operations take on specialized significance as they form the communication substrate for cryptographically verifiable identity operations, credential exchanges, and distributed consensus mechanisms. The efficiency, security, and reliability of I/O operations directly impact the performance and trustworthiness of the entire decentralized identity infrastructure.
KERI's architecture fundamentally revolves around the generation, transmission, and verification of key events. These events form an append-only key event log (KEL) that provides the verifiable history of an Autonomic Identifier (AID). The I/O patterns for key events include:
Event Generation (Output): When a controller creates an inception event or rotation event, the system performs cryptographic operations and serializes the event data. The event must be encoded in CESR (Composable Event Streaming Representation) format, which provides both text and binary serialization options optimized for streaming. CESR's self-framing property ensures that events can be efficiently extracted from I/O streams without requiring external framing context.
Asynchronous I/O Architecture: KERI implementations leverage asynchronous I/O patterns to handle concurrent operations efficiently. The HIO framework in keripy provides hierarchical coroutines that manage I/O without blocking, enabling scalable witness networks and high-throughput credential processing.
Stream-Based Processing: CESR's self-framing properties enable efficient stream I/O where primitives can be parsed incrementally without buffering entire messages, reducing memory overhead and latency in network communication.
I/O Separation in Components: KERI architecture separates I/O concerns across components—controllers handle key generation and signing (minimal I/O), agents manage network I/O, and witnesses/watchers perform continuous I/O monitoring. This separation enables flexible deployment models from edge devices to cloud infrastructure.
Event Reception (Input): Validators, witnesses, and watchers receive key event streams as input. The CESR encoding enables efficient stream processing where primitives can be parsed atomically from the stream. The self-describing nature of CESR primitives means that receiving systems can process events without prior negotiation of encoding schemes.
Event Receipting (Bidirectional): The witness network performs continuous I/O operations. Witnesses receive key events as input from controllers, perform validation, and output signed receipts. These receipts form the key event receipt log (KERL), which provides the secondary root-of-trust in KERI's indirect mode. The bidirectional nature of this communication is critical for establishing distributed consensus on key state.
KERI supports two fundamental operational modes with distinct I/O characteristics:
Direct Mode implements synchronous, peer-to-peer communication where:
Indirect Mode relies on witness-mediated communication:
Out-Of-Band Introductions (OOBIs) provide a critical mechanism for bootstrapping I/O channels in KERI systems. An OOBI associates a KERI AID with a URL (typically an HTTP endpoint), enabling discovery of I/O endpoints for witnesses, watchers, and other KERI infrastructure components.
OOBIs solve the cold-start problem in distributed systems: before parties can engage in KERI protocol operations, they must establish where to perform I/O operations. The OOBI mechanism provides this initial configuration data, after which all subsequent I/O can be verified cryptographically through KERI's event logs.
The percolated information discovery mechanism built on OOBIs enables efficient propagation of endpoint information through the network, reducing the I/O overhead for discovery operations across large-scale deployments.
CESR provides the encoding foundation for all KERI I/O operations, addressing fundamental efficiency challenges in cryptographic protocol communications:
Text-Binary Composability: CESR enables seamless conversion between text and binary domains, allowing systems to choose the appropriate representation for their I/O context. Text encoding supports human readability and debugging, while binary encoding provides compactness for high-throughput scenarios. Critically, concatenated primitives can be converted as a group between domains while maintaining individual primitive separability.
Self-Framing Primitives: Each CESR primitive includes type, size, and value information in a single atomic encoding. This eliminates the need for delimiters or envelope structures when parsing I/O streams. A receiving system can extract primitives atomically from a stream without maintaining external parsing state, which is essential for efficient stream processing and pipelining.
Stream Processing and Pipelining: CESR's design enables efficient cold-start stream parsing, where a processor can begin extracting meaningful data immediately upon receiving the stream without requiring prior synchronization. This property is critical for scalable I/O architectures where streams may be interrupted, reconnected, or multiplexed.
Group Framing Codes: CESR supports group framing codes that enable pipelined processing of multiple primitives. This allows I/O systems to process batches of related cryptographic materials (such as multiple signatures on the same event) efficiently, reducing per-primitive overhead in high-throughput scenarios.
The CESR specification explicitly addresses performance considerations for I/O operations:
Compact Binary Encoding: Binary CESR provides minimal overhead for cryptographic primitives, critical for bandwidth-constrained I/O channels or high-throughput applications.
Concatenation Without Framing Overhead: Unlike traditional serialization formats that require field separators or length prefixes, CESR's self-framing eliminates per-field framing overhead in I/O streams.
Alignment Optimization: CESR carefully manages byte alignment to optimize I/O operations. The specification defines lead bytes and pad characters to ensure efficient processing on modern CPU architectures.
HIO (Hierarchical Asynchronous Coroutines and I/O) provides the Python implementation framework for managing asynchronous I/O in KERI systems. HIO enables Rich Flow Based Programming Hierarchical Structured Concurrency with Asynchronous IO, building on work from the ioflo project on hierarchical structured concurrency with lifecycle contexts.
The critical insight of HIO is that KERI's I/O patterns—handling multiple concurrent key event streams, witness communications, and credential exchanges—require sophisticated asynchronous coordination. Traditional synchronous I/O models would create blocking operations that prevent scalable implementations.
Key HIO Capabilities for KERI I/O:
Non-Blocking Operations: HIO enables KERI agents to perform I/O operations without blocking the main execution thread. When waiting for witness responses or network data, the agent can continue processing other events, maximizing throughput.
Hierarchical Structure: HIO's hierarchical model maps well to KERI's architectural patterns, where agents manage multiple AIDs, each with their own witness configurations and communication patterns. The hierarchy enables clean separation of I/O contexts while maintaining coordinated operation.
Lifecycle Management: HIO provides structured lifecycle contexts that ensure I/O resources are properly initialized and cleaned up, preventing resource leaks in long-running KERI services.
Coroutine Coordination: HIO enables multiple coroutines to cooperate on I/O operations, essential for patterns like gathering responses from multiple witnesses or coordinating multi-signature operations.
KERIA (KERI Agent in the cloud) demonstrates practical application of asynchronous I/O patterns in KERI infrastructure. KERIA exposes three distinct HTTP I/O interfaces:
Boot Interface: Single endpoint for agent worker initialization—minimal I/O surface for secure bootstrapping.
Admin Interface: REST API providing command and control I/O from Signify clients. This interface handles:
The Admin Interface implements KRAM (KERI Request Authentication Method) for replay attack protection, requiring each request to include timestamp fields that must fall within an acceptable time window. This ensures I/O integrity even over untrusted networks.
KERI Protocol Interface: CESR over HTTP endpoint for protocol interactions with other KERI entities. This interface handles:
The separation of these I/O interfaces enables security boundaries: the Admin Interface can be network-isolated for client access only, while the Protocol Interface must be exposed for broader KERI ecosystem communication.
The IPEX (Issuance and Presentation Exchange) Protocol defines structured I/O patterns for ACDC credential operations. IPEX models both credential issuance and presentation as disclosure operations, providing a unified I/O protocol for credential exchange.
Credential Issuance I/O Flow:
Each message in this flow is a CESR-encoded structure that can be efficiently transmitted over various I/O channels—HTTP, message queues, or direct peer-to-peer connections.
Presentation I/O Flow:
The I/O overhead for verification is significant in IPEX. A verifier must potentially perform multiple network I/O operations to fully validate a credential. KERI's caching mechanisms and KERL witnesses help optimize this by providing authoritative sources for KEL data, reducing redundant I/O.
IPEX supports graduated disclosure patterns that optimize I/O by revealing credential information incrementally:
Compact Disclosure: Initial I/O transmits only SAIDs (Self-Addressing Identifiers) of field maps, minimizing bandwidth. The SAID serves as a cryptographic commitment—verifiers can later request full disclosure and verify it matches the compact form.
Selective Disclosure: Holders reveal specific attributes while keeping others concealed, reducing I/O payload size and limiting information exposure.
Partial Disclosure: Progressive revelation of information based on verifier agreement to terms, enabling multi-stage I/O exchanges where each stage gates access to additional data.
These disclosure patterns reduce unnecessary I/O by allowing protocols to share only the minimum information required at each stage of interaction.
Witnesses perform continuous I/O operations as part of KERI's distributed consensus mechanism:
Event Reception: Witnesses receive establishment and interaction events from controllers via HTTP POST operations. The CESR encoding ensures efficient parsing of incoming event streams.
Validation Processing: While not strictly I/O, witnesses perform cryptographic validation on received events, checking signatures and hash chains.
Receipt Generation: Witnesses create signed receipts (key event receipts) and store them in their logs. These receipts are made available for I/O queries from validators.
Receipt Transmission: Witnesses transmit receipts back to controllers and make them available to validators through query endpoints.
KAACE (KERI's Agreement Algorithm for Control Establishment) requires witnesses to coordinate through I/O operations. Each witness must observe the same event and each witness's receipt must be received by every other witness. This creates an I/O coordination pattern where witnesses perform inter-witness communication to achieve agreement.
The threshold of accountable duplicity (TOAD) parameter enables controllers to balance I/O overhead against security. A higher TOAD requires fewer witness confirmations, reducing I/O operations but providing less protection against duplicity. A lower TOAD increases I/O coordination overhead but strengthens duplicity detection.
Watchers operate in promiscuous mode, performing extensive I/O operations:
Continuous Monitoring: Watchers subscribe to KEL updates from multiple witnesses, performing continuous I/O polling or stream reception.
Duplicity Detection: Watchers compare KEL versions received from different sources, performing I/O to gather comprehensive views of identifier state.
Alert Generation: Upon detecting duplicity, watchers perform I/O operations to notify interested parties (validators, controllers, other infrastructure).
Watchers impose significant I/O overhead on the system but provide critical ambient duplicity detection. The I/O cost scales with the number of identifiers monitored and the frequency of state checking.
Transaction Event Logs (TELs) provide verifiable credential registry functionality through a distinct I/O pattern:
Registry Inception: Creating a TEL (management TEL or credential TEL) requires I/O operations to:
Credential Lifecycle Events: Issuance and revocation events require:
Status Queries: Verifiers perform I/O operations to query TEL state:
The I/O overhead for TEL operations is significant because each credential state change requires anchoring to the issuer's KEL, which itself may require witness coordination. This creates cascading I/O operations across multiple KERI infrastructure layers.
The TEL specification supports blinded registries where credential status is not publicly readable. This I/O pattern requires:
Holder-Mediated Disclosure: Credential holders must actively disclose TEL state to verifiers, performing I/O operations to transmit the current state and proof of its validity.
Privacy-Preserving Verification: Verifiers receive TEL state via holder I/O rather than direct registry queries, preventing correlation of verification events.
Salty Nonce Blinding Factor: The cryptographic commitment mechanism enables holders to selectively reveal TEL state while maintaining privacy. The I/O payload includes the blinding factor that enables verifiers to confirm the disclosed state matches the committed value.
KERI I/O operations must protect against replay attacks where adversaries retransmit captured messages:
KRAM (KERI Request Authentication Method): All requests from web clients must include ISO-8601 timestamp fields that fall within an acceptable time window relative to the server's clock. This ensures I/O messages cannot be replayed after the time window expires.
Event Sequence Numbers: KEL events include monotonically increasing sequence numbers. KERI validators reject events with sequence numbers they have already processed, preventing replay of I/O messages containing key events.
First-Seen Policy: KERI's first-seen policy means that once a witness or validator has processed an event at a given sequence number, subsequent I/O messages with different events at that sequence are rejected as duplicitous.
Eclipse Attacks: Adversaries attempt to control all I/O channels to a target, preventing them from receiving authoritative KEL data. KERI mitigates this through:
Man-in-the-Middle: Because KERI events are cryptographically signed, adversaries intercepting I/O cannot forge valid events. However, they can:
Denial of Service: Adversaries can overwhelm I/O channels with spurious requests. KERI systems implement:
Multi-signature AIDs require coordinated I/O among multiple controllers:
Event Proposal: One controller generates a proposed event and performs I/O operations to share it with co-controllers.
Signature Gathering: Co-controllers receive the proposal, validate it, sign it, and perform I/O to transmit their signatures back.
Event Assembly: A controller assembles the fully-signed event with signatures from all required participants.
Broadcast: The assembled event is transmitted via I/O operations to witnesses and other infrastructure.
The I/O complexity scales with the number of signing participants and the coordination mechanism used. Synchronous coordination requires real-time I/O availability from all participants. Asynchronous coordination accumulates signatures over time but increases latency.
KERI supports fractionally-weighted threshold structures where:
Weight Distribution: Different keys can have different weights (specified as fractions).
Threshold Specification: The signing threshold specifies the minimum cumulative weight required.
Signature I/O: Signatures must be gathered until the cumulative weight exceeds the threshold. The I/O pattern requires:
The I/O overhead can be optimized by prioritizing signers with higher weights, potentially satisfying the threshold with fewer I/O round-trips.
KERI supports bare metal TCP endpoints for direct protocol communication. TCP provides:
Reliable Ordered Delivery: Critical for maintaining KEL event ordering during I/O.
Stream-Oriented Communication: Aligns with CESR's stream processing model.
Connection Management: TCP connection establishment and teardown provide clear I/O session boundaries.
HTTP serves as the primary I/O transport for many KERI operations:
RESTful Patterns: KERIA's Admin Interface uses REST conventions for I/O operations, with resources (AIDs, credentials, events) accessed via standard HTTP methods.
CESR Over HTTP: The KERI Protocol Interface transmits CESR-encoded data over HTTP, using content-type negotiation to select text vs. binary encoding.
Service Endpoints: Service endpoints (URLs) provide discoverable I/O locations for KERI infrastructure components.
KERIA implements server-sent events for streaming I/O patterns:
Mailbox Notifications: Clients establish persistent connections to receive push notifications of events requiring attention.
Event Streaming: Real-time delivery of key events, credential notifications, and protocol state changes without polling overhead.
This I/O pattern reduces latency for time-sensitive operations while minimizing unnecessary network traffic compared to polling approaches.
KERI extends to IoT scenarios where device controllers manage AIDs for digitally-connected devices:
Constrained I/O: IoT devices often have limited bandwidth, intermittent connectivity, and power constraints. CESR's compact binary encoding minimizes I/O overhead.
Edge Computing: KERI enables cryptographic verification at the edge without requiring constant I/O to centralized services.
Device Delegation: Parent devices can delegate authority to child devices, creating hierarchical I/O topologies where edge devices communicate locally while anchoring to authoritative KELs during connectivity windows.
KERI systems implement caching to reduce redundant I/O:
KEL Caching: Once a KEL has been retrieved and validated, subsequent operations can use the cached version until the sequence number advances.
Witness Receipt Caching: Validators cache witness receipts to avoid re-querying witnesses for already-confirmed events.
TEL State Caching: Credential status can be cached with appropriate TTL policies, reducing I/O to registry backers.
CESR's group framing codes enable efficient batch I/O:
Bulk Event Submission: Multiple events can be transmitted in a single I/O operation, amortizing protocol overhead.
Batch Receipt Processing: Witnesses can return receipts for multiple events in a single response.
Credential Batch Presentation: Holders can present multiple credentials in a single I/O exchange, reducing round-trip overhead.
KERI implementations maintain connection pools to witness and watcher networks, reducing I/O overhead from repeated connection establishment.
Production KERI systems require I/O monitoring:
Latency Tracking: Monitor I/O latency to witnesses, watchers, and peer controllers to detect network issues or overloaded infrastructure.
Throughput Metrics: Track event processing rates, credential operations per second, and network bandwidth utilization.
Error Rates: Monitor I/O failures, timeout events, and retry attempts to identify reliability issues.
Resource Utilization: Track I/O buffer usage, connection pool exhaustion, and asynchronous task queue depths.
Input/Output operations form the fundamental communication substrate for KERI and ACDC systems, enabling the exchange of cryptographically verifiable identity information across distributed networks. The I/O architecture must balance competing demands: minimizing latency and bandwidth overhead while maintaining strong security properties and supporting asynchronous operation patterns.
CESR provides the encoding foundation that optimizes I/O efficiency through self-framing primitives and text-binary composability. HIO enables scalable asynchronous I/O processing in Python implementations. The witness and watcher networks rely on carefully designed I/O protocols to achieve distributed consensus and ambient duplicity detection. IPEX structures credential exchange through well-defined I/O message flows. TELs provide verifiable registry operations through I/O patterns anchored to KERI's key event logs.
Understanding these I/O patterns, their security properties, and their performance characteristics is essential for implementing, deploying, and operating KERI-based identity infrastructure at scale. The design consistently prioritizes verifiability and security while providing the I/O efficiency required for practical distributed identity systems.