The Hab structure maintains several logical data stores within the LMDB backend:

• Key material store: Private keys encrypted with the keystore passcode
• KEL store: Ordered sequence of key events for the identifier
• Receipt store: Witness receipts and watcher confirmations
• State cache: Current key state derived from the KEL
• Credential store: ACDCs (Authentic Chained Data Containers) issued to or by this identifier
• Configuration metadata: Witness lists, delegation relationships, and operational parameters

Key Components

A Hab contains several essential components:

Prefix (AID): The unique identifier string that this Hab manages. This is typically a self-certifying identifier derived from the inception key material.

Keystore: The encrypted storage for private key material. In KERIpy, this uses the Salter primitive to derive encryption keys from a user-provided passcode, ensuring that private keys are never stored in plaintext.

Kever (Key Event Verifier): The component responsible for processing and validating key events, maintaining the authoritative key state for the identifier.

Kevery (Key Event Registry): The collection of all Kevers managed by this Hab, enabling verification of events from other identifiers that this Hab interacts with.

Seqner: Tracks the sequence numbers of events in the KEL, ensuring proper ordering and detecting gaps or duplicates.

Tholder: Manages threshold structures for multi-signature operations, including both current signing thresholds and next rotation thresholds.

Data Format

Field Definitions

While the Hab itself is a runtime object rather than a serialized data structure, it manages several persistent data formats:

Key Material Storage:

• Private keys: Stored as encrypted binary blobs using the keystore passcode-derived encryption key
• Public keys: Stored as CESR-encoded qualified primitives with derivation codes
• Key digests: Pre-rotated key commitments stored as CESR-encoded digests

KEL Storage:

• Events: Serialized as JSON, CBOR, or MessagePack with CESR-encoded attachments
• Signatures: CESR-encoded indexed signatures attached to events
• Receipts: CESR-encoded witness signatures with timestamps

State Cache:

• Current keys: List of active public key verifiers
• Next key digests: Commitments to pre-rotated keys
• Thresholds: Current and next signing thresholds
• Witness configuration: List of designated witnesses and witness threshold
• Sequence number: Current event sequence in the KEL

Encoding Format

The Hab uses CESR (Composable Event Streaming Representation) for all cryptographic primitives, providing:

• Self-framing: Each primitive includes its type and size in the encoding
• Composability: Primitives can be concatenated and converted between text and binary domains
• Compactness: Minimal overhead for encoding cryptographic material

Key events within the KEL are serialized using one of three formats:

1. JSON: Human-readable text format for debugging and interoperability
2. CBOR: Compact binary format for efficient storage and transmission
3. MessagePack: Alternative binary format with broad language support

All three formats maintain insertion-ordered field maps to ensure deterministic serialization for SAID computation and signature verification.

Size and Constraints

The size of a Hab's persistent storage depends on:

• Number of key events: Each rotation or interaction adds to the KEL
• Number of witnesses: More witnesses mean more receipts to store
• Credential volume: ACDCs issued to or by the identifier
• Delegation depth: Delegated identifiers require storing delegation events

Typical Hab storage requirements:

• Minimal identifier: ~10 KB (inception event, key material, basic state)
• Active identifier: ~100 KB - 1 MB (multiple rotations, credentials, receipts)
• High-volume identifier: >1 MB (extensive event history, many credentials)

LMDB's memory-mapped architecture means that Habs can efficiently manage large datasets without loading everything into RAM, making the system scalable to thousands of identifiers per Habery.

Operations

Creation and Initialization

Hab Inception:

Creating a new Hab involves several steps:

1. Keystore Initialization: Generate or load the keystore with a passcode-derived encryption key
2. Key Generation: Create the inception key pair and pre-rotated key pair
3. Inception Event Creation: Construct the inception event with:
   • Inception key(s) as current keys
   • Digest(s) of pre-rotated key(s) as next keys
   • Witness configuration (list and threshold)
   • Configuration traits (delegation, multi-sig, etc.)
4. Event Signing: Sign the inception event with the inception key(s)
5. KEL Initialization: Store the signed inception event as the first entry in the KEL
6. State Initialization: Derive the initial key state from the inception event

For multi-signature identifiers, the inception process involves coordination between multiple participants, each contributing their key material and signatures to create a group identifier.

For delegated identifiers, the inception event includes a reference to the delegating identifier's prefix and requires approval from the delegator through a delegation seal in the delegator's KEL.

Updates and Modifications

Key Rotation:

Rotating keys in a Hab follows the KERI pre-rotation protocol:

1. Rotation Event Creation: Construct a rotation event with:
   • Previous event digest (backward chaining)
   • Current pre-rotated key(s) now becoming active
   • New pre-rotated key digest(s) for future rotation
   • Updated witness configuration (if changed)
   • Sequence number increment
2. Event Signing: Sign with the current pre-rotated key(s) (not the old signing keys)
3. KEL Append: Add the signed rotation event to the KEL
4. State Update: Update the key state to reflect new active keys and next key commitments
5. Witness Propagation: Send the rotation event to designated witnesses for receipting

Interaction Events:

For anchoring external data without changing keys:

1. Interaction Event Creation: Construct an interaction event with:
   • Previous event digest
   • Sequence number increment
   • Seals (digests of external data to anchor)
2. Event Signing: Sign with current active key(s)
3. KEL Append: Add to the KEL
4. State Update: Update sequence number and seal registry

Credential Operations:

The Hab manages ACDC credentials through:

• Issuance: Creating and signing ACDCs with the identifier as issuer
• Reception: Receiving and storing ACDCs issued to the identifier
• Presentation: Generating presentation exchanges for credential disclosure
• Revocation: Managing credential revocation through TEL (Transaction Event Log) anchoring

Verification and Validation

KEL Verification:

The Hab continuously validates its KEL integrity:

1. Signature Verification: All events must have valid signatures from authorized keys
2. Digest Verification: Backward chaining digests must match previous events
3. Pre-rotation Verification: Rotation events must use keys committed in previous events
4. Sequence Verification: Event sequence numbers must be monotonically increasing
5. Threshold Verification: Multi-sig events must meet the required signature threshold

Witness Receipt Validation:

For each event, the Hab validates witness receipts:

1. Witness Signature Verification: Receipts must be signed by designated witnesses
2. Event Digest Verification: Receipt must reference the correct event digest
3. Threshold Achievement: Sufficient witnesses must receipt the event (TOAD threshold)
4. Duplicity Detection: Conflicting receipts from the same witness indicate duplicity

State Consistency:

The Hab maintains consistency between:

• KEL and State: Current state must be derivable from the KEL
• Local and Witnessed State: Local KEL must match witnessed KERL
• Delegation State: Delegated identifiers must have valid delegation seals in delegator KELs

Usage Context

In Which Protocols

The Hab is used throughout the KERI protocol stack:

KERI Core Protocol:

• Managing identifier lifecycle (inception, rotation, interaction)
• Processing key events and maintaining KELs
• Coordinating with witnesses for event receipting
• Detecting and handling duplicity

OOBI (Out-Of-Band Introduction):

• Resolving OOBIs to discover witness endpoints
• Publishing OOBIs for identifier discovery
• Bootstrapping trust relationships

ACDC (Authentic Chained Data Container):

• Issuing verifiable credentials
• Receiving and storing credentials
• Managing credential schemas and registries

IPEX (Issuance and Presentation Exchange):

• Conducting credential issuance exchanges
• Performing credential presentation exchanges
• Negotiating disclosure terms

TEL (Transaction Event Log):

• Anchoring credential issuance and revocation events
• Managing credential registries
• Tracking credential status

Lifecycle Management

A Hab's lifecycle includes:

Creation Phase:

• Keystore initialization with passcode
• Inception event generation and signing
• Witness configuration and OOBI publication

Active Phase:

• Regular interaction events for data anchoring
• Periodic key rotations for security
• Credential issuance and presentation
• Witness receipt collection and validation

Delegation Phase (if applicable):

• Delegation approval from delegator
• Delegated event processing
• Delegation revocation handling

Recovery Phase (if needed):

• Key compromise detection
• Emergency rotation using pre-rotated keys
• Witness reconfiguration
• State reconstruction from KEL

Abandonment Phase (optional):

• Rotation to empty next key list
• Making identifier non-transferable
• Final state publication

Related Structures

Habery:

A Habery is the collection manager for multiple Habs. In KERIpy and KERIA, a Habery:

• Manages multiple Habs within a single keystore
• Provides unified access to all identifiers
• Coordinates multi-identifier operations
• Handles keystore-level operations (unlock, lock, backup)

The relationship is: Habery : Hab :: Wallet : Account

Kever:

A Kever (Key Event Verifier) is the component within a Hab that processes and validates key events. While a Hab manages one identifier's complete state, the Kever specifically handles:

• Event validation logic
• State derivation from events
• Duplicity detection
• Witness receipt processing

Kevery:

A Kevery is the registry of all Kevers (both local Habs and remote identifiers) that a given Hab interacts with. This enables:

• Verification of events from other identifiers
• Multi-party protocol coordination
• Delegation relationship management

Seqner:

A Seqner tracks event sequence numbers within a Hab's KEL, ensuring:

• Monotonic sequence progression
• Gap detection
• Replay attack prevention

Tholder:

A Tholder manages threshold structures for multi-signature operations, including:

• Current signing thresholds
• Next rotation thresholds
• Fractional weight calculations
• Threshold satisfaction verification

Implementation Patterns

Single-Sig Hab:

The simplest Hab manages a single-signature identifier:

• One key pair for signing
• One pre-rotated key pair for rotation
• Straightforward event signing and rotation

Multi-Sig Hab:

For group identifiers, the Hab coordinates:

• Multiple participants' key material
• Threshold signature collection
• Partial rotation support
• Group consensus on events

Delegated Hab:

For delegated identifiers, the Hab manages:

• Delegation approval from delegator
• Delegated event anchoring
• Delegation revocation handling
• Hierarchical key management

Custodial Hab:

For custodial arrangements, the Hab supports:

• Split signing and rotation authority
• Custodian key management
• Owner rotation control
• Custodian replacement

The Hab abstraction is fundamental to KERI's architecture, providing a clean separation between identifier management and protocol operations, enabling scalable, secure, and flexible identity systems.

Performance Considerations

KEL Verification: As KELs grow, verification time increases. Implementations should:

• Cache verified key states to avoid re-verifying the entire KEL
• Use incremental verification for new events
• Implement efficient event indexing in LMDB
• Consider KEL compaction for very long histories

Error Handling

Duplicity Detection: Habs must handle duplicity (conflicting events) by:

• Maintaining a duplicitous event log (DEL) separate from the KEL
• Alerting controllers to duplicity events
• Refusing to process events after duplicity is detected
• Providing mechanisms for duplicity resolution

Backup and Recovery

Keystore Backup: Habs should support:

• Exporting encrypted keystore backups
• Importing keystore backups with passcode verification
• Exporting KELs for archival purposes
• Reconstructing state from KEL backups

Integration with KERIA

Cloud Agent Architecture: In KERIA, each Hab runs as an agent instance:

• Habs are accessed via REST API endpoints
• Authentication uses KERI Request Authentication Method (KRAM)
• Multiple Habs can run in a single KERIA server
• Each Hab has its own isolated keystore within the server's Habery