Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 47 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.
HIO (Hierarchical Asynchronous Coroutines and I/O) is a Python library providing weightless hierarchical asynchronous coroutines with structured concurrency and async I/O, serving as the foundational infrastructure for KERI implementations like KERIpy and KERIA.
HIO (Hierarchical Asynchronous Coroutines and I/O) is a specialized Python library that implements weightless hierarchical asynchronous coroutines combined with non-blocking I/O operations. The name encapsulates its core functionality: organizing asynchronous operations hierarchically in Python while providing efficient I/O handling.
HIO is implemented in Python and serves as foundational infrastructure for the KERI ecosystem's Python-based implementations. It was specifically selected for KERIpy (the reference KERI protocol implementation) and KERIA (the cloud-based KERI agent) due to its alignment with KERI's core design principles.
HIO provides Rich Flow Based Programming with Hierarchical Structured Concurrency and Asynchronous I/O. This architecture enables:
The library addresses the fundamental challenge of building scalable, concurrent systems that can handle high-bandwidth network operations while maintaining code clarity and correctness through structured concurrency patterns.
When implementing HIO-based components, choose between two patterns:
doing.doify when your logic needs to suspend and resume execution (true generator semantics with yield or yield from).recur() when you're simply constructing and managing child Doers without needing suspensionThe style guide emphasizes: "If a custom .recur() function is implemented in a DoDoer subclass, the superclass .recur() must be called to resume normal DoDoer execution of all contained coroutines (Doers)."
HIO's hierarchical structure provides automatic resource cleanup, but developers must:
super().recur() when overriding .recur() methodsHIO integrates with Python's asyncio but provides higher-level abstractions. When mixing HIO with raw asyncio code:
For high-throughput KERI operations:
Follow the KERIpy style guide:
HIO's hierarchical structure aids debugging:
HIO serves as the asynchronous I/O foundation for KERI implementations. The KERI protocol is inherently asynchronous—witnesses, watchers, and agents must handle concurrent network communications, event processing, and cryptographic operations without blocking. HIO provides the infrastructure that makes this possible while adhering to KERI's minimal sufficient means design philosophy.
The choice of HIO for KERIpy represents a deliberate architectural decision that ensures the foundational I/O and concurrency layer aligns with KERI's core design values and operational requirements. As Document 2 states, HIO was selected because it "naturally supports KERI's asynchronous event processing model" and "provides the necessary concurrency capabilities without unnecessary complexity."
HIO's primary innovation is its implementation of hierarchical structured concurrency. Unlike traditional async/await patterns that can lead to unstructured concurrent code, HIO organizes asynchronous operations in a structured hierarchy with clear lifecycle management.
Structured concurrency means that concurrent operations are organized into scopes with well-defined entry and exit points. When a parent scope exits, all child operations are guaranteed to complete or be cancelled, preventing resource leaks and orphaned tasks that plague traditional concurrent programming.
The hierarchical aspect means these scopes can be nested, creating tree-like structures of concurrent operations where:
HIO implements Rich Flow Based Programming, a paradigm where applications are defined as networks of asynchronous processes communicating through well-defined connections. This approach is particularly well-suited to KERI's event-driven architecture where:
Flow-based programming enables developers to reason about complex asynchronous systems as data flowing through processing nodes rather than as imperative sequences of operations.
The term "weightless" refers to HIO's minimal overhead approach to coroutine management. Traditional threading models impose significant memory and context-switching costs. HIO's coroutines:
This weightless design is critical for KERI implementations that may need to manage:
HIO provides comprehensive non-blocking I/O capabilities essential for network-intensive KERI operations:
All I/O operations integrate seamlessly with the hierarchical coroutine model, ensuring that blocking I/O never stalls the entire application.
HIO builds upon foundational work from the ioflo framework, which pioneered hierarchical structured concurrency with lifecycle contexts. As Document 1 notes, "HIO builds on very early work on hierarchical structured concurrency with lifecycle contexts from ioflo."
The ioflo project established core concepts that HIO refined and adapted for modern Python async/await syntax:
This historical lineage means HIO incorporates lessons learned from years of production use in autonomous systems and distributed applications.
HIO's primary abstraction is the Doer class, which represents a unit of asynchronous work. Document 38 provides detailed guidance on working with Doers:
DoDoer Pattern: A DoDoer is a Doer that manages other Doers, creating the hierarchical structure. The style guide explains two patterns for implementing Doers:
doing.doify Pattern: Wraps a generator function (using yield or yield from) to create a Doer. This pattern is appropriate when the logic needs to suspend execution and resume later.
.recur() Override Pattern: Simplifies the doing.doify approach by directly overriding the .recur() method. This pattern is cleaner when the logic doesn't need generator mechanics but simply constructs and manages child Doers.
The style guide emphasizes: "If a custom .recur() function is implemented in a DoDoer subclass, the superclass .recur() must be called to resume normal DoDoer execution of all contained coroutines (Doers)."
HIO integrates with Python's asyncio event loop but provides higher-level abstractions that simplify concurrent programming. Rather than directly managing asyncio.Task objects and futures, developers work with Doers that handle lifecycle management automatically.
While not fully documented in the provided sources, Document 38 indicates that HIO includes Cues for inter-component communication. This suggests a message-passing or signaling mechanism that enables Doers to communicate without tight coupling.
In KERIpy, HIO provides the concurrency foundation for:
KERIA (KERI Agent in the cloud) extensively uses HIO for its multi-component architecture. Document 24 describes KERIA's four primary components, all built on HIO:
Message Router: Handles asynchronous KERI protocol messages, including multi-signature coordination where "the router manages asynchronous waiting for signature responses from multiple participants."
The Agency: Manages agent provisioning with persistent state that survives service restarts.
API Handler: Processes agent-specific API requests with cryptographic authentication.
Agents: Individual agent instances that operate on behalf of clients while maintaining security boundaries.
The asynchronous nature of these components—particularly the Message Router's ability to handle "asynchronous message routing" for multi-signature scenarios—depends entirely on HIO's hierarchical coroutine infrastructure.
While SignifyPy is a Python client library for KERIA, it also leverages HIO for managing asynchronous operations when communicating with KERIA agents. The TypeScript implementation (SignifyTS) implements similar patterns but in JavaScript's async/await model.
HIO embodies KERI's minimal sufficient means principle by providing exactly what's needed for hierarchical async programming without unnecessary features. As Document 43 states, HIO aligns with "the minimal sufficient means design principle of KERI."
This philosophy means HIO:
KERI's protocol design is fundamentally asynchronous. Witnesses may respond at different times, watchers operate independently, and delegation operations involve multi-party coordination. HIO's architecture naturally supports this through:
Document 20 establishes that KERI tooling selections follow five core characteristics, including "Best-in-class functionality" and "Proven performance over time." HIO's selection reflects these criteria:
KERI's CESR (Composable Event Streaming Representation) encoding enables efficient stream processing. HIO's coroutine model allows CESR parsers to:
HIO enables the KAACE (KERI Agreement Algorithm for Control Establishment) witness consensus mechanism through:
HIO supports watcher implementations that operate in "promiscuous mode," monitoring KELs without being designated witnesses. Watchers use HIO to:
HIO's weightless coroutine model enables KERI implementations to scale to:
The hierarchical structure enables efficient resource management:
Document 40 explains the performance architecture that HIO supports:
HIO is maintained in the ioflo/hio GitHub repository. Related documentation includes:
As part of the KERI ecosystem, HIO development is coordinated through:
Document 38 provides the official style guide for HIO usage in KERI projects, covering:
doing.doify vs .recur() overrideCompared to OS-level threading, HIO provides:
While HIO builds on Python's asyncio, it adds:
HIO's selection over alternatives like Trio, Curio, or raw asyncio reflects:
While not explicitly documented in the provided sources, HIO's role in the KERI ecosystem suggests ongoing development in:
HIO represents a carefully designed foundation for asynchronous programming in the KERI ecosystem. Its hierarchical structured concurrency model, weightless coroutines, and flow-based programming paradigm provide exactly what KERI implementations need: efficient, scalable, concurrent processing of cryptographic events and network operations without unnecessary complexity.
The library's alignment with KERI's minimal sufficient means philosophy, combined with its production-proven heritage from ioflo, makes it an ideal choice for building robust, high-performance identity infrastructure. As KERI adoption grows and implementations scale to handle increasing loads, HIO's architecture ensures that the foundational concurrency layer can meet these demands while maintaining code clarity and correctness.
When specifying HIO dependencies:
hio>=0.6.12 to ensure minimum feature availabilitykeri>=1.2.0-dev1)The style guide indicates planned documentation for Cues (inter-component communication). When this system is documented: