Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 38 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.
The threshold of accountable duplicity (TOAD) is a controller-declared parameter specifying the minimum number M of witness confirmations (from N total witnesses) required before accepting accountability for a key event, calculated as M >= N - F where F represents potentially faulty witnesses, enabling fault-tolerant witness consensus while maintaining clear duplicity detection boundaries.
The threshold of accountable duplicity (TOAD) is a fundamental fault-tolerance parameter in KERI's witness-based architecture that defines when a controller accepts accountability for a key event based on witness confirmations. TOAD establishes the minimum number M of witness receipts required from a total of N witnesses before the controller considers an event sufficiently confirmed, with the relationship expressed as M >= N - F, where F represents the number of potentially faulty witnesses.
TOAD accomplishes several critical objectives in KERI's security architecture:
Fault Tolerance: Enables the system to continue operating correctly despite witness failures, compromises, or network partitions. By requiring only M confirmations rather than unanimous agreement from all N witnesses, the system can tolerate up to F faulty witnesses while maintaining security guarantees.
Duplicity Detection Boundaries: Establishes clear thresholds for when duplicitous behavior becomes accountable. Without TOAD, any evidence of duplicity might trigger permanent identifier abandonment, making the system fragile. TOAD allows controllers to distinguish between recoverable faults (compromised interaction signing keys) and non-recoverable faults (compromised ).
Choosing appropriate TOAD values requires careful analysis of security requirements and operational constraints:
Security Analysis: Assess the threat model to determine how many witness compromises the system should tolerate. For Byzantine fault tolerance against malicious witnesses, use M >= ceil((2N + 1) / 3). For simple crash fault tolerance, M >= ceil((N + 1) / 2) provides majority consensus.
Availability Requirements: Higher TOAD values provide stronger security but require more witnesses to be available. Calculate the probability of achieving M confirmations given expected witness availability rates. For example, with 95% witness availability and N=5, M=4 has lower availability than M=3.
Performance Impact: Larger TOAD values increase latency for event confirmation as more witness receipts must be collected. Measure actual receipt collection times in your deployment environment and set timeouts accordingly.
Implementations must rigorously verify all witness receipts:
Signature Verification: Use the witness's current public keys from its KEL to verify receipt signatures. Implementations must handle witness key rotations correctly by determining which keys were authoritative when the receipt was created.
Witness List Validation: Verify that the witness providing the receipt is in the declared witness list for the identifier. Receipts from unlisted witnesses must be rejected and should not count toward TOAD thresholds.
Event Digest Matching: Confirm that the receipt signs the correct event SAID. Receipts for different event versions indicate either witness malfunction or duplicity and must be handled according to duplicity detection protocols.
Receipt Freshness: Implement policies for receipt age limits. Very old receipts may indicate network delays or witness unavailability and should be treated cautiously.
TOAD is central to duplicity detection mechanisms:
Threshold-Based Duplicity: When M or more witnesses confirm conflicting event versions, the controller has crossed the accountability threshold. Implementations should immediately flag this as non-recoverable duplicity and cease trusting the identifier.
Sub-Threshold Duplicity: When fewer than M witnesses confirm conflicting versions, this may indicate recoverable key compromise. Implementations should monitor for additional confirmations and allow recovery through pre-rotation mechanisms if the duplicity remains below TOAD.
Validator Trust Calibration: Provides validators with explicit information about the controller's declared accountability threshold, enabling validators to make informed trust decisions. Validators can independently assess whether the declared TOAD meets their security requirements.
Flexible Security Policies: Allows different identifiers to implement different security postures based on their use cases. High-security applications can require larger M values (more witness confirmations), while lower-risk applications can use smaller M values for improved availability.
TOAD is declared and enforced at specific points in an AID's lifecycle:
Inception Event Declaration: The controller makes the initial TOAD declaration during the inception event that creates the identifier. This declaration is cryptographically bound to the identifier through the KEL structure and becomes part of the identifier's verifiable history.
Rotation Event Modification: Controllers can modify TOAD during rotation events, allowing the threshold to evolve as security requirements change, witness configurations are updated, or operational experience reveals optimal threshold values.
Event Confirmation Process: TOAD is evaluated during the witness confirmation process for every key event. When witnesses provide signed receipts for an event, the controller and validators count confirmations against the declared TOAD threshold to determine when the event achieves sufficient witness agreement.
Duplicity Assessment: When duplicity detection mechanisms identify conflicting versions of events, TOAD determines whether the duplicity crosses the accountability threshold. Duplicity below the TOAD threshold may be treated as recoverable fault behavior, while duplicity at or above the threshold indicates non-recoverable compromise.
The TOAD mechanism involves three primary participants with distinct roles:
Controller: Declares the TOAD value in establishment events, determining the minimum witness confirmation threshold they will accept for accountability. The controller's TOAD declaration represents their assessment of adequate security given their witness configuration and risk tolerance.
Witnesses: Provide signed receipts for key events they observe and verify. Witnesses operate independently, each maintaining their own copy of the KERL (Key Event Receipt Log). The collective behavior of M witnesses determines when events achieve the TOAD threshold.
Validators: Independently assess whether the controller's declared TOAD provides sufficient security for their trust decisions. Validators may require higher confirmation thresholds (MV >= MC) than the controller declares, reflecting different risk profiles and security requirements.
The TOAD process begins when a controller creates a new AID through an inception event. The controller must specify several witness-related parameters:
Witness List (wits): Array of witness AID prefixes designated to provide receipts for this identifier's events.
Witness Threshold (toad): The TOAD value M representing the minimum number of witness confirmations required.
Witness Count (N): Implicitly defined by the length of the witness list.
The inception event is serialized, signed by the controller's initial keys, and transmitted to the designated witnesses. This event becomes the first entry in the identifier's KEL, cryptographically binding the TOAD declaration to the identifier's history.
After the controller publishes a key event (inception, rotation, or interaction), the event propagates to the designated witness pool:
Event Transmission: The controller sends the signed event to each witness in the witness list, typically using OOBI (Out-Of-Band Introduction) endpoints to locate witnesses.
Witness Verification: Each witness independently verifies the event's cryptographic signatures, validates the event structure against KERI protocol rules, and checks consistency with previously witnessed events in their local KERL.
Receipt Generation: Witnesses that successfully verify the event create signed receipts. A receipt is a cryptographic signature over the event using the witness's own signing keys, providing non-repudiable evidence that the witness observed and validated the event.
Receipt Propagation: Witnesses may exchange receipts with each other (witness gossip) and make receipts available to validators through query interfaces. This creates a distributed record of witness confirmations.
As receipts accumulate, both the controller and validators evaluate whether the TOAD threshold has been met:
Receipt Counting: Count the number of valid witness receipts received for the event. Each receipt must be cryptographically verified using the witness's public key and must correspond to a witness in the declared witness list.
Threshold Comparison: Compare the receipt count against the declared TOAD value M. If the count is >= M, the event has achieved the TOAD threshold.
Controller Accountability: Once M receipts are collected, the controller accepts accountability for the event. This means the controller acknowledges that sufficient witnesses have confirmed the event, and the controller can be held responsible for any duplicitous behavior related to this event.
Validator Trust Decision: Validators independently assess whether M confirmations provide adequate security for their purposes. Validators may require MV >= MC, meaning they might need more confirmations than the controller's declared threshold before trusting the event.
Controllers can modify TOAD during rotation events to adapt to changing security requirements:
Rotation Event Creation: The controller creates a rotation event that includes updated witness configuration parameters, including a new TOAD value if desired.
Witness List Updates: The rotation event may also modify the witness list (adding or removing witnesses), which affects the calculation of N and therefore the valid range for M.
Threshold Validation: The new TOAD value must satisfy M >= N - F where N is the new witness count. Validators verify this constraint when processing the rotation event.
Historical Continuity: The rotation event is chained to previous events through cryptographic digests, maintaining verifiable history of all TOAD changes. Validators can audit the complete history of threshold modifications.
When duplicity is detected (conflicting versions of events), TOAD determines accountability:
Duplicity Evidence Collection: Watchers, validators, or witnesses detect conflicting event versions by comparing events with the same sequence number but different content.
Witness Confirmation Analysis: Determine how many witnesses confirmed each conflicting version. If M or more witnesses confirmed one version, that version is considered the authoritative event.
Accountability Threshold: If M or more witnesses confirmed multiple conflicting versions, the controller has crossed the accountability threshold and is demonstrably duplicitous. This indicates non-recoverable compromise.
Recovery vs. Abandonment Decision: Duplicity below the TOAD threshold may indicate recoverable key compromise (interaction signing keys), allowing recovery through pre-rotation mechanisms. Duplicity at or above TOAD indicates rotation key compromise, typically requiring identifier abandonment.
Witness Signature Verification: All witness receipts must be cryptographically verified using the witness's public keys. The verification process must:
Event Digest Consistency: Receipts sign the SAID (Self-Addressing Identifier) of the event, which is a cryptographic digest of the event content. This ensures:
Threshold Constraint Validation: The TOAD value M must satisfy the constraint M >= N - F where:
Typically, F is calculated as F = N - M, meaning the system can tolerate up to N - M faulty witnesses. For Byzantine fault tolerance, common configurations use M = ceil((2N + 1) / 3), providing tolerance for up to floor((N - 1) / 3) Byzantine faulty witnesses.
Asynchronous Receipt Collection: TOAD operates in an asynchronous environment where:
Timeout Policies: Implementations should define timeout policies for receipt collection:
Witness Availability: TOAD provides fault tolerance for witness unavailability:
Event Ordering: TOAD evaluation must respect event sequence numbers:
Insufficient Receipts: When fewer than M receipts are collected:
Invalid Receipts: Receipts that fail cryptographic verification must be rejected:
Conflicting Receipts: When witnesses provide receipts for conflicting event versions:
Witness List Changes: When rotation events modify the witness list:
High-Security Identifiers: Organizations requiring strong security guarantees typically configure:
M >= ceil((2N + 1) / 3)N = 7, M = 5, F = 2 provides tolerance for 2 Byzantine faulty witnessesBalanced Security-Availability: General-purpose identifiers balance security and availability:
N = 3, M = 2, F = 1 provides tolerance for 1 faulty witnessHigh-Availability Identifiers: Applications prioritizing availability over maximum security:
N = 3, M = 2, F = 1 confirms events quickly while maintaining basic fault toleranceDelegated Identifiers: Delegated AIDs inherit security properties from delegators:
N = 7, M = 5; delegates use N = 3, M = 2TOAD Configuration Guidelines:
Calculate F First: Determine the maximum number of faulty witnesses you need to tolerate based on your threat model, then set M = N - F.
Byzantine Tolerance: For protection against Byzantine faults (malicious witnesses), use M >= ceil((2N + 1) / 3), which provides tolerance for up to floor((N - 1) / 3) Byzantine faulty witnesses.
Avoid Minimum Thresholds: Setting M = 1 provides no fault tolerance and should be avoided except for testing. Minimum production configuration should be N = 3, M = 2.
Witness Diversity: Select witnesses from diverse operators, geographic locations, and infrastructure providers to reduce correlated failure risks.
Monitor Witness Performance: Track witness response times and availability to identify underperforming witnesses that should be rotated out.
Plan for Witness Rotation: Design witness configurations that allow graceful witness replacement through rotation events without service disruption.
Document TOAD Rationale: Maintain documentation explaining why specific TOAD values were chosen for each identifier, including threat model assumptions and security requirements.
Validator Threshold Independence: Validators should implement their own threshold requirements (MV) independent of controller declarations (MC):
MV > MCWitness Infrastructure: TOAD requires robust witness infrastructure:
Watcher Integration: Watchers complement TOAD by providing validator-side duplicity detection:
Application Layer Policies: Applications using KERI should define policies for:
Multi-Signature Coordination: For multisig identifiers, TOAD interacts with signing thresholds:
Delegation Hierarchies: In delegated identifier trees:
Watcher Coordination: Integrate with watcher networks to detect duplicity across the broader ecosystem. Watchers provide independent verification of TOAD threshold achievement and can alert validators to duplicitous behavior.
TOAD operates in an asynchronous environment requiring careful state management:
Receipt Escrow: Implement escrow mechanisms to handle out-of-order receipt arrival. Receipts for event N+1 may arrive before receipts for event N are complete. Store these in escrow until the prerequisite events are confirmed.
Timeout Policies: Define maximum wait times for achieving TOAD thresholds. When timeouts expire, implementations should retry witness contact, escalate to operators, or fail gracefully depending on application requirements.
Partial Confirmation Handling: Decide how to handle events that receive some but not M confirmations. Options include: waiting indefinitely, timing out and retrying, or proceeding with reduced confidence for low-security operations.
Managing witness configurations requires operational discipline:
Witness Rotation Planning: When rotating witnesses through rotation events, ensure the new witness set can achieve the new TOAD threshold before removing old witnesses. Coordinate witness additions and removals to avoid availability gaps.
Witness Diversity: Select witnesses from diverse operators, geographic regions, and infrastructure providers. Correlated failures (same cloud provider outage) can prevent achieving TOAD thresholds.
Witness Monitoring: Implement monitoring for witness availability, response times, and receipt quality. Proactively rotate out underperforming witnesses before they impact TOAD achievement.
Witness Discovery: Maintain up-to-date OOBI information for all witnesses. Implement fallback discovery mechanisms when primary OOBI endpoints are unavailable.
Validators should implement independent TOAD assessment:
Minimum TOAD Policies: Define minimum acceptable TOAD values for different identifier types and use cases. Reject identifiers with insufficient TOAD values for high-security operations.
Dynamic Threshold Adjustment: Validators may dynamically adjust their required threshold (MV) based on context. High-value transactions may require higher MV than routine operations.
TOAD History Auditing: Audit the complete history of TOAD changes in an identifier's KEL. Suspicious patterns (repeatedly lowering TOAD) may indicate compromise attempts.
Cross-Validation: Compare TOAD achievement across multiple watchers and witnesses. Inconsistent reports may indicate network partitions or targeted attacks.
Optimize TOAD-related operations for production performance:
Parallel Receipt Collection: Contact all witnesses in parallel rather than sequentially. Use asynchronous I/O to maximize throughput.
Receipt Caching: Cache witness receipts to avoid redundant verification. Invalidate caches when witness keys rotate.
Batch Verification: When processing multiple events, batch cryptographic verification operations to amortize computational costs.
Witness Prioritization: Prioritize receipt collection from historically reliable witnesses. Implement adaptive algorithms that learn witness performance characteristics.
Implement robust error recovery for TOAD-related failures:
Insufficient Receipts: When M receipts cannot be collected, implement retry logic with exponential backoff. Provide operator notifications for persistent failures.
Invalid Receipts: Log invalid receipts for security analysis. Repeated invalid receipts from a witness may indicate compromise and should trigger witness rotation.
Network Partitions: Detect network partition scenarios where different validator populations see different witness confirmations. Implement partition recovery protocols.
Witness Compromise: When witness compromise is detected, immediately rotate to new witnesses and reassess TOAD values. Notify all validators of the compromise.
Thoroughly test TOAD implementations:
Threshold Boundary Testing: Test behavior at exactly M confirmations, M-1 confirmations, and M+1 confirmations. Verify correct threshold evaluation.
Fault Injection: Simulate witness failures, network delays, and Byzantine behavior. Verify the system maintains security guarantees with up to F faulty witnesses.
Duplicity Scenarios: Test detection of duplicity at various confirmation levels. Verify correct distinction between recoverable and non-recoverable duplicity.
Performance Testing: Measure receipt collection latency under various network conditions and witness configurations. Verify timeout policies work correctly.
Rotation Testing: Test TOAD modification through rotation events. Verify smooth transitions between old and new threshold values.