Structural Organization

The ksn is not stored as a primary data structure but rather computed on demand by processing the KEL. The computation process, often called "walking the KEL," involves:

1. Starting from the inception event (sequence 0)
2. Processing each subsequent establishment event (rotation events) in sequence order
3. Tracking witness adds and cuts across rotations
4. Ignoring interaction events (non-establishment events) for key state purposes
5. Arriving at the current state at the latest establishment event

This computation is necessary because:

• Non-establishment events can be intermixed with establishment events in the KEL
• The last event may not be an establishment event (it could be an interaction event)
• Witness configuration requires calculating cumulative adds and cuts from inception through all rotations
• Key state changes only occur at establishment events, not at every event

As documented in the did:webs specification: "Implementations MUST 'walk the KEL' to determine current key state" because "the last event in a KEL may not be an establishment event" and "the current witness set requires calculating 'adds' and 'cuts' from the inception event through all rotation events."

Key Components

A ksn message contains the following essential fields derived from KEL processing:

Identifier Field (i): The AID value itself, which serves as the subject of the key state notice. This is the self-certifying identifier whose state is being reported.

Sequence Number (s): The sequence number of the latest establishment event that determined this key state. This allows validators to understand which point in the KEL history this state represents.

Event Digest (d): The SAID (Self-Addressing IDentifier) of the establishment event at sequence s. This provides cryptographic binding to the specific event that established this state.

Prior Event Digest (p): The digest of the event immediately preceding the current establishment event, maintaining the hash chain integrity.

Current Keys (k): An array of CESR-encoded public keys that currently have signing authority over the identifier. These are the keys that can sign non-establishment events and participate in signing the next rotation event.

Next Key Digests (n): An array of cryptographic digests representing commitments to the pre-rotated keys that will become the current keys in the next rotation. This implements KERI's pre-rotation mechanism for forward security.

Current Threshold (kt): The signing threshold indicating how many signatures from the current key set are required to authorize operations. This can be a simple integer (e.g., "2" for 2-of-N) or a fractional weight specification for weighted thresholds.

Next Threshold (nt): The signing threshold that will apply to the next key set after rotation, committed to in advance.

Witness AIDs (b): An array of witness AIDs that are currently designated to provide key event receipts for this identifier. This list is computed by starting with the witnesses specified in the inception event and applying all witness adds (wa) and cuts (wr) from subsequent rotation events.

Witness Threshold (wt): The minimum number of witness receipts required for an event to be considered sufficiently witnessed, implementing the TOAD (Threshold of Accountable Duplicity) mechanism.

Configuration Traits (c): An array of configuration flags that affect identifier behavior, such as whether the identifier supports delegation (DnD - Do Not Delegate flag).

Delegator AID (di): If this is a delegated identifier, this field contains the AID of the delegator, establishing the delegation relationship.

Event Type (t): Set to ksn to identify this as a key state notice message.

Version String (v): The CESR version string indicating the encoding format, typically KERI10JSON for JSON serialization.

Data Format

Field Definitions

The ksn follows KERI's standard message format with specific field semantics:

{
  "v": "KERI10JSON0001ac_",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "3",
  "t": "ksn",
  "d": "EAoTNZH3ULvaU6Z-i0d8JJR2nmwyYAfSVPzhzS6b5CM",
  "p": "EULvaU6Z-i0d8JZH3JR2nmwyYAfSVPzhzS6b5CMoTN",
  "k": ["DaU6JR2nmwyYAfSVPzhzS6b5CMoTNZH3ULvaU6Z-i0d8"],
  "n": ["EZ-i0d8JJR2nmwyYAfSVPzhzS6b5CMoTNZH3ULvaU6"],
  "kt": "1",
  "nt": "1",
  "b": ["BGKVzj4ve0VSd8z_AmvhLg4lqcC_9WYX90k03q-R_Ydo"],
  "wt": "1",
  "c": [],
  "di": ""
}

Field Type Specifications:

• v: String - CESR version string with byte count
• i: String - Base64 URL-safe encoded AID (44 characters for Ed25519-based identifiers)
• s: String - Hexadecimal sequence number ("0", "1", "a" for 10, "b" for 11, etc.)
• t: String - Message type, always "ksn" for key state notices
• d: String - Base64 URL-safe encoded SAID of the establishment event
• p: String - Base64 URL-safe encoded digest of prior event
• k: Array of Strings - CESR-encoded public keys
• n: Array of Strings - CESR-encoded digests of next keys
• kt: String - Threshold specification (integer or fractional)
• nt: String - Next threshold specification
• b: Array of Strings - Witness AIDs
• wt: String - Witness threshold (integer)
• c: Array of Strings - Configuration trait codes
• di: String - Delegator AID (empty string if not delegated)

Encoding Format

Key state notices use CESR (Composable Event Streaming Representation) encoding, which provides:

Dual Text/Binary Support: The same ksn can be represented in either text (JSON) or binary (CBOR/MessagePack) format with lossless round-trip conversion.

Self-Framing Primitives: All cryptographic material (keys, digests, signatures) includes prepended derivation codes that specify the cryptographic algorithm and enable self-describing parsing.

Composability: Multiple ksn messages can be concatenated in a stream with unambiguous boundaries, enabling efficient batch processing.

The version string v field encodes both the KERI protocol version and the byte count of the message, enabling stream parsers to extract messages atomically without parsing the entire content.

Size and Constraints

Minimum Size: A ksn for a single-signature, non-delegated identifier with no witnesses is approximately 300-400 bytes in JSON format.

Typical Size: Most production ksn messages range from 500-1500 bytes depending on:

• Number of current keys (multi-sig configurations)
• Number of witnesses
• Presence of delegation
• Configuration traits

Maximum Size: No hard limit exists, but practical constraints include:

• Network MTU considerations for UDP transport
• Database field size limits
• Memory allocation in embedded systems

Sequence Number Range: Sequence numbers are hexadecimal strings, theoretically unbounded but practically limited by the identifier's operational lifetime.

Operations

Creation and Initialization

Key state notices are computed, not created in the traditional sense. The process involves:

KEL Walking Algorithm:

1. Initialize State: Start with empty key state structure
2. Process Inception: Extract initial keys, thresholds, witnesses, and configuration from the inception event at sequence 0
3. Iterate Rotations: For each rotation event in sequence order:
   • Update current keys from the rotation's k field
   • Update next key digests from the rotation's n field
   • Update thresholds from kt and nt fields
   • Apply witness adds (wa) and cuts (wr) to the witness list
   • Update sequence number and event digests
4. Skip Interactions: Ignore interaction events as they don't change key state
5. Finalize State: The resulting structure is the current key state

Optimization - Persistent Key State: As documented in the keriox changelog, modern implementations optimize this by:

• Deriving and persisting IdentifierState key states directly in the events database
• Replacing on-demand compute_state functions with direct get_key_state retrieval
• Using transactions for atomic state updates when new establishment events are added

This eliminates redundant KEL replay operations, particularly beneficial for witnesses and watchers handling concurrent queries.

Updates and Modifications

Key state notices are immutable snapshots - they are not updated in place. Instead:

New State Computation: When a new establishment event is added to the KEL, a new ksn is computed reflecting the updated state.

State Versioning: Each ksn is implicitly versioned by its sequence number s, allowing historical state queries ("What was the key state at sequence 5?").

Incremental Updates: Implementations may optimize by applying only the changes from the new establishment event to the previous state rather than reprocessing the entire KEL.

Verification and Validation

Validating a ksn involves several cryptographic and logical checks:

KEL Consistency Verification:

1. Retrieve KEL: Obtain the complete KEL for the AID specified in the i field
2. Walk KEL: Independently compute the key state by processing the KEL
3. Compare States: Verify that the computed state matches all fields in the received ksn
4. Sequence Verification: Confirm the s field matches the sequence number of the latest establishment event
5. Digest Verification: Verify the d field matches the SAID of the establishment event at sequence s

Cryptographic Binding Verification:

• Hash Chain Integrity: Verify the p field correctly references the prior event's digest
• Pre-rotation Commitment: Verify that current keys k match the next key digests n from the previous rotation (proving the keys were pre-committed)
• Witness Signatures: If the ksn is accompanied by witness receipts, verify the signatures against the witness AIDs in the b field

Delegation Verification (if di is non-empty):

1. Retrieve Delegator KEL: Obtain the KEL for the delegator AID specified in di
2. Find Delegation Seal: Locate the delegation seal in the delegator's KEL that authorizes this identifier
3. Verify Seal Binding: Confirm the seal references the correct inception or rotation event of the delegated identifier

Usage Context

In Which Protocols

KERI Core Protocol: The ksn is a fundamental message type in KERI, used for:

• Query Responses: Witnesses respond to /ksn/{aid} queries with the current key state
• State Synchronization: Watchers use ksn messages to communicate observed key states
• Validation Workflows: Validators request ksn messages to verify identifier control authority

did:keri Method: The did:keri specification uses ksn as the authoritative source for DID Document generation, with explicit field mappings:

• i → DID subject identifier
• k → Verification Methods with authentication/assertion relationships
• n → Verification Methods with capabilityInvocation relationships
• b → Service endpoints with type "witness"
• di → Verification Method with capabilityDelegation relationship

did:webs Method: Similarly, did:webs derives DID Documents from ksn messages, bridging KERI's security with web-based discovery.

IPEX Protocol: The Issuance and Presentation Exchange protocol uses ksn messages to verify the key state of credential issuers and holders during ACDC exchanges.

KERIA Agent API: The KERIA cloud agent exposes REST endpoints that return ksn messages for managed identifiers, enabling client applications to query current key states.

Lifecycle Management

The lifecycle of a ksn is tied to the KEL lifecycle:

Genesis State: The first ksn is derived from the inception event, representing the initial key state at sequence 0.

Evolution Through Rotations: Each rotation event triggers computation of a new ksn reflecting the updated key state.

Historical Queries: Implementations may cache or persist ksn messages at various sequence numbers to support historical state queries without full KEL replay.

Expiration: A ksn becomes "stale" when a new establishment event is added to the KEL. However, historical ksn messages remain valid for understanding past key states.

Revocation: If an identifier is abandoned (rotated to empty next key digests with zero threshold), the final ksn represents the terminal state.

Related Structures

Key Event Log (KEL): The ksn is a derived view of the KEL. The KEL is the authoritative source of truth, while the ksn is a computed representation of current state.

Key Event Receipt Log (KERL): A KERL includes both the KEL and witness receipts. The ksn can be computed from either a KEL or KERL, with the KERL providing additional validation through witness signatures.

Transaction Event Log (TEL): TELs track credential issuance and revocation state. While structurally similar to KELs, TELs have their own state representation and do not use ksn messages.

Identifier State: In implementation terms (particularly in keriox), the IdentifierState data structure is the in-memory or persisted representation of what a ksn communicates over the network.

DID Document: In DID-based systems, the DID Document is a transformation of the ksn into W3C DID specification format, with the ksn serving as the source of truth.

Query Messages: KERI defines query message types (qry) that request ksn responses from witnesses and watchers, forming a request-response pattern.

State Notification Messages: Related to ksn, state notification messages communicate key state changes to interested parties, often including the ksn as payload.

Implementation Considerations

Performance Optimization

As documented in the keriox changelog, the shift from on-demand computation to persistent key state storage represents a critical performance optimization:

Before Optimization: Every ksn query required walking the entire KEL from inception to current state, causing:

• High CPU usage for long-lived identifiers with many rotations
• Latency spikes during concurrent queries
• Redundant computation of identical states

After Optimization: Key states are computed once when establishment events are added and persisted:

• Constant-time retrieval regardless of KEL length
• Reduced CPU load on witnesses and watchers
• Improved query response times

Witness and Watcher Deployment

In production deployments, witnesses and watchers must efficiently serve ksn queries:

Caching Strategy: Implement LRU caches for frequently queried AIDs to avoid database lookups.

Concurrent Query Handling: Use read-optimized database configurations to support high query volumes without blocking KEL updates.

State Consistency: Ensure atomic updates when new establishment events arrive to prevent serving inconsistent states during transitions.

DID Resolution Integration

When implementing DID resolvers for did:keri or did:webs:

Authoritative Source: Always derive DID Documents from ksn messages, never cache DID Documents independently of key state.

Update Detection: Monitor for new establishment events and regenerate DID Documents when key state changes.

Historical Resolution: Support DID URL parameters for resolving historical key states at specific sequence numbers.

Security Considerations

State Verification: Never trust a ksn message without independent KEL verification. An attacker could forge a ksn claiming arbitrary key state.

Witness Threshold Enforcement: When validating a ksn, ensure it is accompanied by sufficient witness receipts as specified by the wt field.

Delegation Chain Validation: For delegated identifiers, recursively verify the entire delegation chain up to the root delegator.

Replay Attack Prevention: Include timestamps or sequence number checks to prevent replay of old ksn messages claiming outdated key states.

Witness Threshold Enforcement: Verify sufficient witness receipts accompany the ksn as specified by the wt field.

Delegation Chain Validation: For delegated identifiers, recursively verify the entire delegation chain.

Replay Prevention: Include sequence number checks to prevent acceptance of outdated key states.

Error Handling

Missing Events: Handle cases where KEL is incomplete or events are out of order.

Inconsistent State: Detect and report when computed key state doesn't match received ksn.

Witness Unavailability: Implement fallback mechanisms when witnesses are unreachable.

Database Failures: Ensure graceful degradation when persistent storage is unavailable.