Comprehensive Explanation

next-threshold

Protocol Definition

Core Purpose and Objectives

The next-threshold (represented by the field label nsith in KERI event messages) is a fundamental parameter in the Key Event Receipt Infrastructure (KERI) protocol that establishes the signing threshold for the next rotation event. This threshold defines how many signatures from the pre-rotated key set are required to authorize the subsequent establishment event, creating a cryptographic commitment to future control authority requirements.

The next-threshold serves three critical protocol objectives:

1. Pre-commitment to rotation authority: By specifying the next-threshold in the current establishment event, the controller cryptographically commits to the signing requirements for the next rotation before those keys are exposed
2. Flexible threshold structures: Supports both simple integer thresholds (e.g., "2" requires 2 signatures) and fractionally-weighted thresholds for sophisticated multi-signature schemes
3. Security through forward commitment: Prevents attackers who compromise current keys from arbitrarily changing rotation requirements, as the next-threshold is already committed in the current event

Formal Specification References

The next-threshold is formally specified in:

• IETF KERI Draft Specification (draft-ssmith-keri): Defines nsith as a required field in inception and rotation events
• KERI Whitepaper v2.x: Establishes the theoretical foundation for pre-rotation and threshold structures
• Partial Rotation Specification: Extends next-threshold semantics to support partial rotation scenarios where only a subset of pre-rotated keys are exposed

The specification defines next-threshold as appearing in two event types:

• Inception events (icp): Establishes the initial next-threshold for the first rotation
• Rotation events (rot): Updates the next-threshold for subsequent rotations

Version History and Evolution

The next-threshold concept has evolved through several protocol refinements:

KERI v1.0 (Initial Specification):

• Basic next-threshold support with integer values only
• Simple M-of-N threshold semantics
• Next-threshold applied uniformly to all pre-rotated keys

KERI v2.0 (Enhanced Thresholds):

• Introduction of fractionally-weighted thresholds
• Support for complex threshold expressions
• Integration with CESR encoding for compact representation

Partial Rotation Extension (2022):

• Dual-threshold validation model introduced
• Next-threshold becomes "prior next-threshold" in rotation validation
• Support for reserve rotation and custodial rotation use cases
• Enables keeping some pre-rotated keys unexposed while rotating others

Protocol Architecture

Layering and Component Organization

The next-threshold operates within KERI's layered architecture:

Event Layer:

• Next-threshold is a top-level field in establishment event messages
• Encoded as a string representation of an integer or fractional weight
• Appears alongside current threshold (kt/isith) to define complete threshold structure

Key State Layer:

• Next-threshold is part of the key state derived from processing the KEL
• Validators maintain current next-threshold as part of identifier state
• Used during rotation validation to verify signature requirements are met

Validation Layer:

• Next-threshold from prior establishment event becomes validation criterion for current rotation
• Signature count/weight must meet or exceed the prior next-threshold
• Failure to meet threshold results in rotation rejection

Data Flow and Control Flow

Establishment Event Creation Flow:

1. Controller determines desired next-threshold for future rotation
2. Next-threshold value encoded as string in event message
3. Event serialized and signed by current authoritative keys
4. Event published to witnesses and stored in KEL

Rotation Validation Flow:

1. Validator receives rotation event with attached signatures
2. Validator retrieves prior establishment event from KEL
3. Prior event's next-threshold extracted as validation criterion
4. Rotation event's signatures counted/weighted against prior next-threshold
5. If threshold met: rotation accepted; if not met: rotation rejected

Partial Rotation Flow (when applicable):

1. Validator checks both prior next-threshold AND current threshold
2. Prior next-threshold validated against unblinded keys from prior event
3. Current threshold validated against new current keys being established
4. Both thresholds must be satisfied for valid partial rotation

State Management Approach

Next-threshold state management follows KERI's event-sourced architecture:

State Derivation:

• Next-threshold is not stored independently but derived from KEL processing
• Each establishment event updates the next-threshold in derived key state
• Validators replay KEL to reconstruct current next-threshold

State Transitions:

• Inception event: Establishes initial next-threshold (no prior state)
• Rotation event: Prior next-threshold becomes validation criterion; new next-threshold established for future rotation
• Interaction event: Next-threshold unchanged (non-establishment event)

State Consistency:

• Next-threshold is immutable once committed in an establishment event
• Cannot be changed retroactively without creating detectable duplicity
• All validators derive identical next-threshold from same KEL

Message Formats & Encoding

Establishment Event Structure

Next-threshold appears in establishment events with the field label nsith (next signing threshold):

Inception Event Example:

{
  "v": "KERI10JSON0000e6_",
  "t": "icp",
  "d": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "0",
  "kt": "1",
  "k": ["DSuhyBcPZEZLK-fcw5tzHn2N46wRCG_ZOoeKtWTOunRA"],
  "nt": "1",
  "n": ["EPYuj8mq_PYYsoBKkzX1kxSPGYBWaIya3slgCOyOtlqU"],
  "bt": "0",
  "b": [],
  "c": [],
  "a": []
}

Rotation Event Example:

{
  "v": "KERI10JSON000160_",
  "t": "rot",
  "d": "E-dapdcC6XR1KWmWDsNl4J_OxcGxNZw1Xd95JH5a34fI",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "1",
  "p": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "kt": "1",
  "k": ["DVcuJOOJF1IE8svqEtrSuyQjGTd2HhfAkt9y2QkUtFJI"],
  "nt": "1",
  "n": ["E-dapdcC6XR1KWmWDsNl4J_OxcGxNZw1Xd95JH5a34fI"],
  "bt": "0",
  "b": [],
  "br": [],
  "ba": [],
  "a": []
}

Field Definitions and Semantics

Field Label: nt (in compact form) or nsith (in verbose form)

Data Type: String representation of threshold value

Value Formats:

1. Integer Threshold: Simple count of required signatures

   • Example: "1" requires 1 signature
   • Example: "3" requires 3 signatures
   • Semantics: Exactly this many signatures from next key set required

2. Fractionally-Weighted Threshold: Complex weighted expression

   • Example: "1/2" requires weight totaling at least 1/2
   • Example: "2/3" requires weight totaling at least 2/3
   • Semantics: Weighted sum of signing keys must meet or exceed threshold
   • Weights assigned to individual keys in next key list

Field Positioning:

• Appears after current threshold (kt) in field ordering
• Precedes next key digest list (n) in establishment events
• Required field in all establishment events (inception and rotation)

Validation Rules:

• Must be parseable as valid threshold expression
• Integer thresholds must be ≥ 0 and ≤ number of next keys
• Fractional thresholds must have valid numerator/denominator
• Cannot exceed the number of keys in next key list

Encoding Schemes

JSON Serialization:

• Next-threshold encoded as JSON string value
• Field label nt in compact JSON
• Field label nsith in verbose JSON
• Example: "nt": "2"

CESR Encoding:

• Next-threshold is part of the event message body
• Event body encoded with CESR version string prefix
• Example: KERI10JSON000160_ indicates KERI v1.0, JSON serialization, 160 bytes
• Threshold value itself remains as string within JSON structure

MessagePack (MGPK) Serialization:

• Next-threshold encoded as MessagePack string
• More compact than JSON for binary transmission
• Semantically identical to JSON representation

CBOR Serialization:

• Next-threshold encoded as CBOR text string
• Alternative compact binary format
• Maintains same threshold semantics

Protocol Mechanics

Message Exchange Patterns

Inception Event Publication:

1. Controller creates inception event with initial next-threshold
2. Event signed by inception keys (current keys)
3. Event transmitted to designated witnesses
4. Witnesses verify signatures against current threshold
5. Witnesses create and return receipts
6. Controller collects receipts into KERL

Rotation Event Publication:

1. Controller creates rotation event with updated next-threshold
2. Event signed by current keys (which were pre-rotated in prior event)
3. Event transmitted to witnesses
4. Witnesses verify signatures against prior next-threshold (not current threshold)
5. Witnesses verify new current threshold is satisfied
6. Witnesses create and return receipts
7. Controller collects receipts into KERL

Validation by Third Parties:

1. Validator receives KEL from witnesses or controller
2. Validator processes events in sequence order
3. For each rotation, validator extracts prior next-threshold
4. Validator verifies rotation signatures meet prior next-threshold
5. Validator updates derived key state with new next-threshold
6. Process repeats for subsequent rotations

State Transitions

Next-threshold state transitions follow establishment event processing:

Initial State (Pre-Inception):

• No next-threshold exists
• Identifier not yet established

Post-Inception State:

• Next-threshold established from inception event nt field
• Becomes validation criterion for first rotation
• Remains in effect until first rotation occurs

Post-Rotation State:

• Prior next-threshold used to validate rotation
• New next-threshold established from rotation event nt field
• New next-threshold becomes criterion for subsequent rotation

State Transition Diagram:

[No State] --inception--> [Next-Threshold = nt₀]
                                |
                                | rotation with nt₁
                                | (validated against nt₀)
                                ↓
                          [Next-Threshold = nt₁]
                                |
                                | rotation with nt₂
                                | (validated against nt₁)
                                ↓
                          [Next-Threshold = nt₂]
                                |
                               ...

Timing and Ordering Requirements

Temporal Ordering:

• Next-threshold commitment occurs in event N
• Next-threshold validation occurs in event N+1
• Time gap between commitment and validation is unbounded
• No protocol-level timeout for rotation

Sequence Number Ordering:

• Establishment events have monotonically increasing sequence numbers
• Next-threshold at sequence S validates rotation at sequence S+1
• Sequence numbers must be consecutive for establishment events
• Interaction events may occur between establishment events without affecting next-threshold

Validation Ordering:

• Prior establishment event must be validated before current rotation
• Cannot validate rotation without access to prior next-threshold
• KEL must be processed in sequence order to derive correct next-threshold

Security Properties

Threat Model

Next-threshold security addresses several attack vectors:

Key Compromise Attacks:

• Live Attack: Attacker compromises current signing keys
• Dead Attack: Attacker compromises keys after they've been rotated
• Threshold Attack: Attacker compromises subset of keys below threshold

Rotation Manipulation Attacks:

• Unauthorized Rotation: Attacker attempts rotation without sufficient signatures
• Threshold Lowering: Attacker attempts to reduce next-threshold to enable future attack
• Threshold Raising: Attacker attempts to increase next-threshold to cause denial of service

Duplicity Attacks:

• Forked KEL: Attacker creates alternative KEL with different next-threshold
• Conflicting Rotations: Attacker publishes multiple rotations with different thresholds

Security Guarantees

Pre-Rotation Security:

The next-threshold provides security through pre-rotation commitment:

1. Forward Commitment: Next-threshold is committed before next keys are exposed
2. Immutable Requirement: Attacker cannot change next-threshold retroactively
3. Threshold Protection: Even if current keys compromised, attacker must meet next-threshold

Threshold Integrity:

Next-threshold ensures rotation authority integrity:

1. Minimum Signature Requirement: Rotation requires at least next-threshold signatures
2. Weight Validation: Fractional thresholds ensure sufficient weighted authority
3. Supermajority Protection: Properly configured thresholds prevent minority attacks

Duplicity Detection:

Next-threshold enables duplicity detection:

1. Consistent Validation: All validators apply same next-threshold from KEL
2. Conflicting Rotations: Different rotations with same prior next-threshold are detectable
3. Ambient Verifiability: Any party can verify rotation met next-threshold

Attack Resistance

Resistance to Key Compromise:

Scenario: Attacker compromises current signing keys

Protection Mechanism:

• Attacker cannot rotate to arbitrary keys
• Must use pre-rotated keys committed in prior event
• Must provide signatures meeting next-threshold
• If next keys also compromised, legitimate controller can use reserve rotation

Resistance to Threshold Manipulation:

Scenario: Attacker attempts to lower next-threshold to enable future attack

Protection Mechanism:

• Next-threshold change requires valid rotation event
• Rotation requires meeting current next-threshold
• Attacker must already have threshold-satisfying key compromise
• Legitimate controller can detect and respond to unauthorized threshold changes

Resistance to Denial of Service:

Scenario: Attacker raises next-threshold to prevent legitimate rotation

Protection Mechanism:

• Threshold increase requires valid rotation event
• Rotation requires meeting current next-threshold
• Legitimate controller retains rotation authority through pre-rotated keys
• Partial rotation enables recovery using reserve keys

Post-Quantum Security:

Next-threshold contributes to post-quantum security:

1. Hash-Based Commitment: Next keys committed via cryptographic digest
2. One-Way Function: Quantum computer cannot reverse digest to find next keys
3. Forward Security: Even if current keys broken, next keys remain hidden
4. Threshold Redundancy: Multiple pre-rotated keys provide defense in depth

Interoperability

Dependencies on KERI/ACDC Protocols

KERI Core Protocol Dependencies:

1. Key Event Log (KEL):

   • Next-threshold stored in establishment events within KEL
   • KEL processing derives current next-threshold state
   • KEL replay enables validation of historical next-threshold usage

2. Pre-Rotation Mechanism:

   • Next-threshold validates signatures from pre-rotated keys
   • Pre-rotation commitment (n field) works in conjunction with next-threshold
   • Both must be present in establishment events

3. Witness Protocol:

   • Witnesses validate rotation events against prior next-threshold
   • Witness receipts confirm threshold satisfaction
   • Witness threshold (bt) is separate from next-threshold

4. CESR Encoding:

   • Next-threshold encoded within CESR event messages
   • CESR version string indicates serialization format
   • Threshold value remains as string within serialized event

ACDC Protocol Integration:

1. Credential Issuance:

   • ACDC issuers use AIDs with next-threshold configurations
   • Issuer key rotation follows next-threshold requirements
   • Credential validity depends on issuer AID key state

2. Credential Revocation:

   • Revocation registry anchored to issuer KEL
   • Registry updates require meeting issuer's current threshold
   • Next-threshold affects future revocation authority

3. Delegation:

   • Delegated AIDs inherit threshold structure from delegator
   • Delegator's next-threshold affects delegation approval
   • Delegated rotations may have independent next-threshold

Integration Points

Witness Integration:

• Witnesses receive establishment events with next-threshold
• Witnesses store next-threshold as part of key state
• Witnesses validate rotation signatures against prior next-threshold
• Witness threshold (bt) operates independently of next-threshold

Watcher Integration:

• Watchers monitor KELs for duplicity
• Watchers verify next-threshold consistency across KEL versions
• Conflicting next-thresholds indicate duplicitous behavior
• Watchers provide ambient duplicity detection

Validator Integration:

• Validators derive next-threshold from KEL processing
• Validators verify rotation events meet prior next-threshold
• Validators update key state with new next-threshold after rotation
• Validation failure if threshold not met

Agent Integration:

• KERIA agents manage next-threshold configuration
• Agents coordinate multi-sig threshold satisfaction
• Agents track which keys have signed rotation events
• Agents enforce threshold requirements before event publication

Implementation Considerations

Common Challenges

Threshold Configuration Complexity:

Challenge: Determining appropriate next-threshold values for security vs. availability trade-offs

Guidance:

• Higher thresholds provide better security but reduce availability
• Lower thresholds improve availability but increase compromise risk
• Consider operational requirements (key availability, signing coordination)
• Use TOAD principles for witness thresholds
• Consider ample calculations for supermajority requirements

Multi-Signature Coordination:

Challenge: Collecting threshold-satisfying signatures in distributed environments

Guidance:

• Implement signature escrow mechanisms for asynchronous signing
• Use IPEX protocol for multi-party coordination
• Consider timeout policies for signature collection
• Implement notification systems for pending signature requests
• Support partial signature submission and aggregation

Partial Rotation Validation:

Challenge: Validating both prior next-threshold and current threshold in partial rotations

Guidance:

• Implement dual-threshold validation logic
• Track which pre-rotated keys have been exposed vs. reserved
• Verify unblinded keys match prior next key digests
• Ensure both thresholds satisfied before accepting rotation
• Support reserve rotation and custodial rotation use cases

Fractional Weight Handling:

Challenge: Implementing fractionally-weighted threshold calculations

Guidance:

• Use rational number arithmetic (not floating point)
• Implement weight assignment to individual keys
• Calculate weighted sum of signatures
• Compare weighted sum to threshold fraction
• Handle edge cases (equal weights, zero weights)

Performance Considerations

KEL Processing Performance:

Consideration: Deriving next-threshold requires processing entire KEL

Optimization Strategies:

• Cache derived key state including next-threshold
• Implement incremental KEL processing
• Store key state snapshots at rotation events
• Use database indexing for establishment events
• Avoid redundant KEL replay for same identifier

Signature Verification Performance:

Consideration: Threshold validation requires verifying multiple signatures

Optimization Strategies:

• Parallelize signature verification operations
• Use batch verification when supported by signature scheme
• Short-circuit verification once threshold met
• Cache verification results for duplicate signatures
• Optimize signature primitive parsing

Multi-Signature Coordination Performance:

Consideration: Collecting threshold signatures may involve network latency

Optimization Strategies:

• Use asynchronous signature collection
• Implement signature aggregation protocols
• Support offline signing with later submission
• Use push notifications for signature requests
• Implement signature escrow with timeout policies

Storage Performance:

Consideration: Storing KEL with all establishment events and thresholds

Optimization Strategies:

• Use compact CESR binary encoding for storage
• Implement KEL compression for archived events
• Store only establishment events for key state derivation
• Use database indexing for threshold queries
• Implement KEL pruning for non-establishment events (with caution)

Testing and Validation

Unit Testing:

• Test threshold parsing (integer and fractional)
• Test threshold comparison logic
• Test signature counting and weighting
• Test edge cases (zero threshold, maximum threshold)
• Test invalid threshold values

Integration Testing:

• Test inception with various next-thresholds
• Test rotation with threshold validation
• Test partial rotation with dual thresholds
• Test multi-signature coordination
• Test threshold changes across rotations

Security Testing:

• Test insufficient signature rejection
• Test threshold manipulation detection
• Test duplicity detection with conflicting thresholds
• Test key compromise scenarios
• Test denial of service resistance

Interoperability Testing:

• Test threshold handling across KERI implementations
• Test CESR encoding/decoding of thresholds
• Test witness validation of thresholds
• Test watcher duplicity detection
• Test agent coordination of multi-sig thresholds