Loading vLEI.wiki Fetching knowledge base...
vLEI.wiki Comprehensive knowledge base for KERI (Key Event Receipt Infrastructure) and vLEI (verifiable Legal Entity Identifier) ecosystem.
Made by Key State Capital .
© 2025 vLEI.wiki. Educational resource for KERI/vLEI ecosystem.
next-threshold - vLEI.wiki | KERI Knowledge Base - vLEI.wiki
Back to ConceptsShort Definition The next-threshold (nsith) is a protocol parameter in KERI establishment events that specifies the minimum number or fractional weights of signatures required from the next (pre-rotated) key set to authorize the subsequent rotation event, enabling secure key rotation through cryptographic commitment to future signing requirements.
Related Concepts No related concepts available
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:
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
Flexible threshold structures : Supports both simple integer thresholds (e.g., "2" requires 2 signatures) and fractionally-weighted thresholds for sophisticated multi-signature schemes
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
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
Implementation Notes Critical Implementation Requirements
Threshold Validation Logic
Implementations MUST validate rotation events against the prior next-threshold , not the current threshold. This is a common implementation error that breaks KERI security guarantees.
Correct Validation Sequence :
Retrieve prior establishment event from KEL
Extract nt field as prior next-threshold
Count/weight signatures on rotation event
Verify signature count/weight meets or exceeds prior next-threshold
Only then accept rotation and update key state
Partial Rotation Support
Implementations supporting partial rotation MUST implement dual-threshold validation:
Prior Next-Threshold Validation : Verify signatures from unblinded prior next keys meet prior next-threshold
Current Threshold Validation : Verify signatures from new current keys meet new current threshold
Both validations must pass for valid partial rotation
Fractional Weight Handling
Implementations supporting fractionally-weighted thresholds MUST:
Use rational number arithmetic (avoid floating point)
Parse threshold expressions correctly (e.g., "2/3")
Assign weights to individual keys in key list
Calculate weighted sum of signatures
Compare weighted sum to threshold fraction using rational comparison
State Management
Implementations MUST derive next-threshold from KEL processing, not store it independently:
Process KEL events in sequence order
Update next-threshold state after each establishment event
Cache derived key state for performance
Invalidate cache when KEL changes
Support KEL replay for state reconstruction
Multi-Signature Coordination
Implementations supporting multi-signature AIDs MUST:
Implement signature escrow for asynchronous signing
Track which participants have signed
Enforce threshold before event publication
Support signature aggregation
Handle timeout scenarios gracefully
Security Considerations
Threshold Configuration :
Validate threshold values are within valid range
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:
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
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
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 :
Controller determines desired next-threshold for future rotation
Next-threshold value encoded as string in event message
Event serialized and signed by current authoritative keys
Event published to witnesses and stored in KEL
Rotation Validation Flow :
Validator receives rotation event with attached signatures
Validator retrieves prior establishment event from KEL
Prior event's next-threshold extracted as validation criterion
Rotation event's signatures counted/weighted against prior next-threshold
If threshold met: rotation accepted; if not met: rotation rejected
Partial Rotation Flow (when applicable):
Validator checks both prior next-threshold AND current threshold
Prior next-threshold validated against unblinded keys from prior event
Current threshold validated against new current keys being established
Both thresholds must be satisfied for valid partial rotation
State Management Approach Next-threshold state management follows KERI's event-sourced architecture:
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
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)
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
Establishment Event Structure Next-threshold appears in establishment events with the field label nsith (next signing threshold):
{
"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": []
}
{
"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
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
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
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)
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
Next-threshold encoded as JSON string value
Field label nt in compact JSON
Field label nsith in verbose JSON
Example: "nt": "2"
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
Next-threshold encoded as CBOR text string
Alternative compact binary format
Maintains same threshold semantics
Protocol Mechanics
Message Exchange Patterns Inception Event Publication :
Controller creates inception event with initial next-threshold
Event signed by inception keys (current keys)
Event transmitted to designated witnesses
Witnesses verify signatures against current threshold
Witnesses create and return receipts
Controller collects receipts into KERL
Rotation Event Publication :
Controller creates rotation event with updated next-threshold
Event signed by current keys (which were pre-rotated in prior event)
Event transmitted to witnesses
Witnesses verify signatures against prior next-threshold (not current threshold)
Witnesses verify new current threshold is satisfied
Witnesses create and return receipts
Controller collects receipts into KERL
Validation by Third Parties :
Validator receives KEL from witnesses or controller
Validator processes events in sequence order
For each rotation, validator extracts prior next-threshold
Validator verifies rotation signatures meet prior next-threshold
Validator updates derived key state with new next-threshold
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
Next-threshold established from inception event nt field
Becomes validation criterion for first rotation
Remains in effect until first rotation occurs
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
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
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:
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
Forked KEL : Attacker creates alternative KEL with different next-threshold
Conflicting Rotations : Attacker publishes multiple rotations with different thresholds
Security Guarantees The next-threshold provides security through pre-rotation commitment:
Forward Commitment : Next-threshold is committed before next keys are exposed
Immutable Requirement : Attacker cannot change next-threshold retroactively
Threshold Protection : Even if current keys compromised, attacker must meet next-threshold
Next-threshold ensures rotation authority integrity:
Minimum Signature Requirement : Rotation requires at least next-threshold signatures
Weight Validation : Fractional thresholds ensure sufficient weighted authority
Supermajority Protection : Properly configured thresholds prevent minority attacks
Next-threshold enables duplicity detection:
Consistent Validation : All validators apply same next-threshold from KEL
Conflicting Rotations : Different rotations with same prior next-threshold are detectable
Ambient Verifiability : Any party can verify rotation met next-threshold
Attack Resistance Resistance to Key Compromise :
Scenario : Attacker compromises current signing keys
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
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
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
Next-threshold contributes to post-quantum security:
Hash-Based Commitment : Next keys committed via cryptographic digest
One-Way Function : Quantum computer cannot reverse digest to find next keys
Forward Security : Even if current keys broken, next keys remain hidden
Threshold Redundancy : Multiple pre-rotated keys provide defense in depth
Interoperability
Dependencies on KERI/ACDC Protocols KERI Core Protocol Dependencies :
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
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
Witness Protocol :
Witnesses validate rotation events against prior next-threshold
Witness receipts confirm threshold satisfaction
Witness threshold (bt) is separate from next-threshold
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 :
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
Credential Revocation :
Revocation registry anchored to issuer KEL
Registry updates require meeting issuer's current threshold
Next-threshold affects future revocation authority
Delegation :
Delegated AIDs inherit threshold structure from delegator
Delegator's next-threshold affects delegation approval
Delegated rotations may have independent next-threshold
Integration Points
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
Watchers monitor KELs for duplicity
Watchers verify next-threshold consistency across KEL versions
Conflicting next-thresholds indicate duplicitous behavior
Watchers provide ambient duplicity detection
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
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
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
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
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
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)
KEL Processing Performance :
Consideration : Deriving next-threshold requires processing entire KEL
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
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
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
Consideration : Storing KEL with all establishment events and thresholds
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
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
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
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
Reject thresholds exceeding number of next keys
Reject zero thresholds for transferable identifiers
Consider operational availability when setting thresholds
Compare next-thresholds across KEL versions
Flag conflicting next-thresholds as duplicitous
Implement watcher integration for ambient duplicity detection
Support emergency rotation using reserve keys
Implement threshold increase for enhanced security
Enable custodial rotation for operational flexibility
Interoperability Requirements
Encode next-threshold as string in event JSON
Support both compact (nt) and verbose (nsith) field labels
Maintain field ordering per KERI specification
Support multiple serialization formats (JSON, MGPK, CBOR)
Witnesses MUST validate rotation against prior next-threshold
Witnesses MUST NOT accept rotation with insufficient signatures
Witness receipts confirm threshold satisfaction
Agents MUST enforce threshold requirements
Agents MUST coordinate multi-sig signature collection
Agents MUST support threshold configuration by controllers