Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 90 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
In KERI, 'stable' refers to the state of cryptographic verifiability across a network where a particular identifier, event, or data set is consistent, fully verified, and cannot be contested within the KERI infrastructure.
Stable in KERI represents a critical threshold state in the lifecycle of cryptographic events and identifiers. When something achieves stability in KERI, it has transitioned from a pending or unverified state to one where cryptographic verification is complete and the verified element has achieved consistency that cannot be challenged within the KERI framework.
The concept encompasses three fundamental properties:
Stability is not a binary property that exists or doesn't exist—rather, it represents a threshold that is crossed when sufficient cryptographic evidence has been gathered and verified. This threshold varies depending on the type of KERI primitive being considered (identifiers, key events, credentials, etc.) and the witness/watcher configuration.
In traditional distributed systems, the concept of "stable" typically refers to data that has been committed to persistent storage or replicated across a sufficient number of nodes to survive failures. Byzantine Fault Tolerant (BFT) consensus algorithms define stability as the point where enough honest nodes have agreed on a value that it cannot be reversed.
Blockchain systems define stability through concepts like "finality" or "confirmation depth"—the number of blocks that have been added after a transaction, making it computationally infeasible to reverse. Bitcoin, for example, considers transactions with 6+ confirmations to be stable for most purposes.
Implementations must provide mechanisms to:
Test suites should verify:
Production systems should monitor:
Certificate Transparency (CT) systems introduced the concept of "stable" logs where certificate issuance events are recorded in append-only Merkle trees. Once an entry is included in a signed tree head (STH) that has been widely observed, it becomes stable—any attempt to remove or modify it would be detectable.
KERI builds on these concepts but applies them specifically to the domain of identifier control authority and key management.
In KERI, an Autonomic Identifier (AID) achieves stability when its associated event sequence has been:
The stability threshold for an identifier is reached when the KAACE (KERI's Agreement Algorithm for Control Establishment) consensus mechanism confirms that enough witnesses agree on the event sequence. This typically requires:
M witnesses (where M >= N - F, with N being total witnesses and F being maximum faulty witnesses)Key rotation events present a particularly important case for stability. After a controller issues a rotation event:
During the transition from pending to stable, validators may encounter both the old and new key states. KERI's first-seen policy and duplicity detection mechanisms ensure that once a rotation achieves stability, any conflicting rotation attempts can be detected as duplicitous behavior.
The pre-rotation mechanism in KERI adds an additional layer of stability assurance: the commitment to next keys is made stable in the previous establishment event, creating a cryptographic chain that makes unauthorized rotations detectable even if they achieve witness consensus.
A Key Event Log (KEL) achieves stability when:
The Key Event Receipt Log (KERL), which includes witness receipts, provides stronger stability guarantees than a bare KEL because it includes cryptographic proof that designated witnesses observed the events.
For ACDCs (Authentic Chained Data Containers), stability involves:
A credential cannot be considered fully stable until all elements of its verification chain are stable, including the issuer's AID, any delegating AIDs in the authorization chain, and the registry tracking its issuance/revocation status.
KERI's concept of stability differs from blockchain finality in important ways:
Implementations determine stability through:
function isStable(event, witnesses, watchers) {
// Check witness receipts
receipts = getReceipts(event)
if (receipts.count < threshold) {
return false // Insufficient witness confirmation
}
// Check for duplicity
if (detectDuplicity(event, witnesses)) {
return false // Duplicitous event cannot be stable
}
// Check watcher confirmation (if configured)
if (watchers.configured && !watchersConfirm(event)) {
return false // Watcher disagreement
}
return true // Event is stable
}
Controllers must understand that newly created identifiers or rotated keys are not immediately stable. There is a propagation period during which:
During this period, verifiers may not yet recognize the new key state. Controllers should:
Verifiers must check stability before trusting identifier key states:
Verifying against unstable key states creates security vulnerabilities, as the key state may not yet be authoritative or may be subject to duplicity.
Issuers should ensure stability before issuing credentials:
Issuing credentials against unstable identifiers can result in credentials that cannot be verified or that reference key states that may change.
Witness and watcher operators play a critical role in stability:
Stability introduces latency into KERI operations:
Systems must balance security requirements (higher witness thresholds, more watchers) against performance needs (faster stability achievement). The configurable nature of KERI's witness thresholds allows this trade-off to be tuned per identifier.
Stability provides security guarantees but with trade-offs:
Controllers must choose stability parameters appropriate to their threat model and use case requirements.