Configuration Data: Additional metadata including whether the identifier is transferable, delegation information if the identifier is delegated, and other protocol-specific settings.

Data Format

Key state is derived from processing the Key Event Log (KEL) for an identifier. While the KEL contains the complete history of all key events, the key state represents the current authoritative configuration at a specific sequence number.

Field Definitions

The key state structure includes the following fields:

i (Identifier): The AID prefix itself, which is the self-certifying identifier derived from the inception event.

s (Sequence Number): The sequence number of the most recent establishment event that defines this key state. This is critical for determining which key state is authoritative at any point in time.

d (Digest): The SAID (Self-Addressing Identifier) of the establishment event that created this key state. This provides cryptographic binding to the specific event.

t (Event Type): The type of the last establishment event (icp for inception, rot for rotation, dip for delegated inception, drt for delegated rotation).

k (Current Keys): An ordered list of the current authoritative public keys. Each key is represented as a CESR-encoded qualified cryptographic primitive.

kt (Current Threshold): The signing threshold for the current key set. This can be a simple integer (e.g., "2" meaning 2-of-N signatures required) or a fractional weight specification for more complex threshold schemes.

n (Next Key Digests): An ordered list of cryptographic digests representing commitments to the next set of keys. These digests are revealed during the next rotation event, enabling pre-rotation security.

nt (Next Threshold): The threshold that will apply to the next key set when it becomes current through a rotation event.

b (Backers/Witnesses): An ordered list of witness AIDs that provide key event receipts for this identifier.

bt (Backer Threshold): The number of witness receipts required for an event to be considered properly witnessed. This is also known as the TOAD (Threshold of Accountable Duplicity).

c (Configuration): An array of configuration trait strings that define operational characteristics of the identifier.

di (Delegator Identifier): If this is a delegated identifier, this field contains the AID of the delegating identifier.

Encoding Format

Key state information is typically represented in JSON format for human readability and debugging, but can be serialized in any format supported by KERI including CBOR and MessagePack. All cryptographic primitives within the key state use CESR encoding, which provides composable, self-describing representations that work in both text and binary domains.

Example key state representation:

{
  "i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
  "s": "3",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "t": "rot",
  "k": ["DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"],
  "kt": "1",
  "n": ["EZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM"],
  "nt": "1",
  "b": [
    "BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
    "BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM"
  ],
  "bt": "2",
  "c": [],
  "di": ""
}

Size and Constraints

The size of a key state structure varies based on:

• Number of current keys: Single-sig identifiers have one key, multi-sig identifiers may have many
• Number of next key digests: Typically matches the number of current keys but can differ in partial rotation scenarios
• Number of witnesses: Can range from zero (for direct mode identifiers) to dozens for high-security applications
• Configuration complexity: Additional configuration traits add to the structure size

There are no hard limits on these values, but practical considerations around witness coordination and signature collection typically keep witness counts below 20 and key counts below 10 for most applications.

Operations

Creation and Initialization

Key state is derived rather than directly created. The initial key state is established through an inception event, which is the first entry in the KEL. The inception event specifies:

1. The initial set of authoritative keys
2. The initial signing threshold
3. The first set of pre-rotated key commitments
4. The next threshold
5. The initial witness set and witness threshold
6. Configuration traits

Processing the inception event produces the initial key state at sequence number 0. This key state remains authoritative until the next establishment event (typically a rotation) occurs.

Updates and Modifications

Key state is immutable at any given sequence number but evolves through establishment events. The key state can only be modified through:

Rotation Events: A rotation event changes the key state by:

• Rotating the current keys to a new set (which must match the previously committed next key digests)
• Establishing new next key commitments
• Optionally modifying thresholds
• Optionally adding or removing witnesses

The rotation process follows strict cryptographic rules:

1. The rotation event must be signed by keys satisfying the prior next threshold using keys that match the prior next key digests
2. The rotation event must also be signed by keys satisfying the current threshold using the new current keys being established
3. This dual-threshold requirement ensures both continuity of control and proper authorization of the new key state

Delegated Rotation Events: For delegated identifiers, rotation requires cooperation between the delegate and delegator, with both parties contributing cryptographic commitments.

Interaction Events: Interaction events do not modify key state. They anchor external data to the current key state without changing any authoritative keys, thresholds, or witnesses.

Verification and Validation

Verifying key state involves multiple validation steps:

KEL Verification: The validator must process the entire KEL from inception through the target sequence number, verifying:

• All event signatures are valid
• All events follow proper sequencing
• All establishment events properly satisfy threshold requirements
• All pre-rotation commitments are correctly revealed in subsequent rotations
• The hash chain is intact (each event's prior digest matches the previous event's SAID)

Witness Receipt Verification: For identifiers using indirect mode, validators should verify that sufficient witness receipts exist for each establishment event, meeting the witness threshold requirement.

Duplicity Detection: Validators must check for duplicity by comparing the KEL against other versions they may have seen. If multiple inconsistent but internally valid KELs exist for the same identifier, this indicates duplicitous behavior by the controller.

Current vs. Historical Key State: Validators must distinguish between:

• Current key state: The key state at the latest sequence number, used for verifying new events
• Historical key state: The key state at a specific past sequence number, used for verifying events that were signed at that point in time

This distinction is critical for verifying ACDCs (Authentic Chained Data Containers) and other signed statements that reference a specific key state.

Usage Context

In Which Protocols

Key state is fundamental to multiple KERI-related protocols:

KERI Core Protocol: Key state is the primary mechanism for establishing control authority over AIDs. Every operation that requires proving control (signing events, issuing credentials, making authoritative statements) depends on the current key state.

ACDC Protocol: When issuing ACDCs, the issuer's key state at the time of issuance determines which keys are authoritative for signing the credential. Verifiers must reconstruct the issuer's key state at the issuance sequence number to validate the credential signature.

IPEX Protocol: The Issuance and Presentation Exchange (IPEX) protocol uses key state to verify that presentation and disclosure operations are authorized by the current controller of the presenting identifier.

did:keri and did:webs: These DID methods generate DID Documents by transforming the current key state into W3C DID Document format, mapping current keys to verification methods and witnesses to service endpoints.

Lifecycle Management

Key state lifecycle follows the identifier lifecycle:

Inception Phase: Initial key state is established with the inception event. This defines the starting security posture and governance structure.

Operational Phase: The key state remains stable during normal operations. Non-establishment events are signed using the current key state but don't modify it.

Rotation Phase: When keys need to be rotated (due to compromise, routine security hygiene, or governance changes), a rotation event creates a new key state at the next sequence number.

Delegation Phase: For delegated identifiers, key state changes require coordination with the delegating identifier, adding complexity to the lifecycle.

Recovery Phase: If keys are compromised, the pre-rotation mechanism allows recovery by rotating to the pre-committed next keys, even if the current signing keys are controlled by an attacker.

Abandonment Phase: An identifier can be made non-transferable by rotating to an empty next key digest list with a next threshold of zero, effectively abandoning the identifier and preventing any future rotations.

Related Structures

Key state interacts with several related data structures:

Key Event Log (KEL): The KEL is the source of truth from which key state is derived. The KEL contains the complete history, while key state represents the current snapshot.

Key Event Receipt Log (KERL): A KERL includes both the KEL and witness receipts. Validators use KERLs to verify that the key state has been properly witnessed.

Key State Notice (KSN): A KSN is a signed statement by the controller asserting their current key state. This provides a compact way to communicate key state without requiring the recipient to process the entire KEL.

Transaction Event Log (TEL): TELs for credential registries are anchored to the issuer's KEL. The key state at the time of anchoring determines which keys are authoritative for the registry operations.

Duplicitous Event Log (DEL): When duplicity is detected, the conflicting versions of events are stored in a DEL. Comparing key states derived from different KEL versions reveals the duplicitous behavior.

Key State in Multi-Signature Scenarios

Key state becomes more complex in multi-signature scenarios:

Threshold Schemes: The kt and nt fields can specify complex threshold requirements. For example, kt: "2" means 2-of-N signatures are required, while fractional weights enable more sophisticated governance (e.g., "2/3" meaning signatures with combined weight of 2 out of total weight 3).

Indexed Signatures: When verifying signatures on events, the indexed signature mechanism indicates which specific key from the key state was used for each signature, enabling efficient verification in multi-sig scenarios.

Partial Rotation: Partial rotation allows rotating only a subset of keys while keeping others in reserve. This creates key states where some next key digests are revealed while others remain blinded.

Custodial Rotation: The key state structure enables custodial rotation patterns where signing authority and rotation authority are split between different key sets, allowing operational delegation while maintaining ultimate control.

Key State in Delegated Identifiers

For delegated identifiers, key state includes additional complexity:

Delegator Reference: The di field contains the delegating identifier's AID, establishing the delegation relationship.

Cooperative Rotation: Rotation of a delegated identifier requires both the delegate's signature (satisfying the delegate's thresholds) and the delegator's approval (through an anchoring seal in the delegator's KEL).

Delegation Recovery: The delegator can supersede the delegate's key state through a superseding rotation, enabling recovery from delegate key compromise.

Nested Delegation: Delegated identifiers can themselves delegate to other identifiers, creating delegation trees where key state verification must traverse the entire delegation chain.

Key State Queries and Discovery

Applications need mechanisms to discover and verify key state:

OOBI (Out-Of-Band Introduction): OOBIs provide URLs for discovering an identifier's KEL and witnesses, enabling key state verification.

Key State Queries: The KERI protocol includes query messages that allow validators to request the current key state from witnesses or watchers.

Watcher Networks: Watchers maintain copies of KELs and can provide key state information to validators, enabling ambient verifiability.

Key State Caching: Validators may cache key state to avoid repeatedly processing the entire KEL, but must implement cache invalidation when new events are discovered.

Security Properties

Key state provides several critical security properties:

Cryptographic Binding: The key state is cryptographically bound to the KEL through the event SAID, preventing tampering.

Forward Security: Pre-rotation provides forward security by committing to future keys before they're exposed, protecting against certain classes of key compromise.

Duplicity Evidence: Inconsistent key states for the same identifier at the same sequence number provide cryptographic proof of duplicitous behavior.

Threshold Flexibility: The threshold mechanism enables flexible governance models while maintaining cryptographic security.

Witness Validation: The witness configuration in key state enables distributed validation without requiring a shared ledger or consensus mechanism.

Implementation Considerations

Implementing key state management requires careful attention to:

KEL Processing: Implementations must correctly process all event types and maintain accurate key state as events are added to the KEL.

Threshold Validation: Both simple integer thresholds and fractional weight thresholds must be correctly validated during signature verification.

Pre-Rotation Verification: Implementations must verify that rotation events correctly reveal previously committed next keys.

Witness Receipt Handling: For indirect mode identifiers, implementations must collect and verify witness receipts to ensure proper witnessing.

Duplicity Detection: Implementations should maintain mechanisms for detecting and handling duplicitous KELs.

Performance Optimization: For identifiers with long KEL histories, implementations may need to cache key state and implement incremental updates rather than reprocessing the entire KEL for each verification.

Key state is the cornerstone of KERI's security model, providing the authoritative configuration that enables verifiable control over identifiers without requiring centralized infrastructure or shared consensus mechanisms.

Multi-Signature Considerations

When implementing multi-sig support:

• Use indexed signatures to identify which key signed each signature
• Implement efficient threshold checking algorithms
• Support fractional weight thresholds for complex governance
• Handle partial rotation scenarios where some keys remain in reserve

Delegated Identifier Support

For delegated identifiers:

• Track the delegation relationship through the di field
• Verify that rotation events have corresponding anchoring seals in the delegator's KEL
• Implement cooperative rotation logic requiring both delegate and delegator participation
• Support nested delegation trees with recursive verification

Error Handling

Implementations should handle:

• Invalid signatures that don't satisfy thresholds
• Missing or incomplete KEL data
• Witness receipt timeouts
• Duplicitous KEL detection
• Pre-rotation commitment mismatches
• Malformed event structures

Testing Requirements

Comprehensive testing should cover:

• Single-sig and multi-sig key state derivation
• Rotation with pre-rotation verification
• Threshold satisfaction checking
• Witness receipt validation
• Duplicity detection
• Delegated identifier scenarios
• Partial rotation cases
• Error conditions and edge cases

Interoperability

To ensure interoperability:

• Follow CESR encoding standards for all cryptographic primitives
• Support all standard event types (icp, rot, ixn, dip, drt)
• Implement standard query protocols for key state discovery
• Use standard OOBI formats for witness and watcher discovery
• Support multiple serialization formats (JSON, CBOR, MessagePack)