Duplicity detection is a cryptographic mechanism in KERI that identifies when a controller has created multiple conflicting versions of their Key Event Log (KEL) by comparing event logs across independent watchers and witnesses, making any attempt to present inconsistent key state histories cryptographically evident and verifiable.
Related Concepts
No related concepts available
Comprehensive Explanation
duplicity-detection
Process Definition
Duplicity detection is KERI's fundamental security mechanism for identifying external inconsistency in key event logs. Unlike internal inconsistency (which makes a log unverifiable), duplicity occurs when two or more versions of a KEL exist for the same AID where each version is internally consistent but mutually incompatible with other versions.
The process accomplishes three critical objectives:
Detection of malicious controllers: Identifies when a controller attempts to maintain multiple versions of their event history to deceive different validators
Protection against key compromise exploitation: Detects attempts to use compromised keys to create conflicting rotation events
Establishment of verifiable trust: Enables validators to make binary trust decisions based on cryptographic evidence rather than reputation
Duplicity detection is used continuously throughout the lifecycle of any KERI identifier, operating as an ambient verification mechanism where any party, anywhere, at any time can detect inconsistent behavior. The key participants include:
Controllers: The entities managing AIDs who may (maliciously or through compromise) create duplicitous events
Witnesses: Designated entities that observe and receipt key events, providing the first line of duplicity detection
Watchers: Independent observers that maintain copies of KELs and compare them for consistency
Validators: Entities making trust decisions based on duplicity evidence
Judges and Jurors: Components that evaluate duplicity evidence and determine reconcilability
Process Flow
Step 1: Event Publication and First-Seen Recording
Implementation Notes
Critical Implementation Considerations
First-Seen Policy Enforcement
Implementations MUST strictly enforce the first-seen policy:
Once an event is accepted for a sequence number, that position is permanently locked
Subsequent events claiming the same sequence MUST be rejected
Rejected events MUST be preserved as potential duplicity evidence
The first-seen event MUST NOT be replaced even if later events appear more authoritative
Multi-Source Validation
Validators MUST query multiple independent sources:
Sources should be geographically and organizationally diverse
Queries should be performed in parallel to minimize latency
Timeout handling must account for network delays without false positives
Duplicity Evidence Preservation
When duplicity is detected:
ALL conflicting versions MUST be preserved in DELs
Cryptographic signatures and receipts MUST be maintained
Source attribution (which witness/watcher reported which version) MUST be recorded
Evidence MUST be indexed to the corresponding KERL for efficient retrieval
Evidence MUST be made available to other validators for independent verification
Performance Optimization
Caching Strategy:
Cache KELs with appropriate TTL based on identifier activity
Invalidate cache on new event detection
Cache key state separately from full KEL for faster validation
Parallel Processing:
Query multiple witnesses/watchers concurrently
Use async/await patterns for non-blocking I/O
Implement timeout and retry logic for unreliable sources
Incremental Validation:
Only validate new events rather than entire KEL on each check
Maintain validated state checkpoints
Use event sequence numbers to determine what needs validation
Error Handling
Network Failures:
Distinguish between network errors and duplicity
Implement exponential backoff for retries
Maintain fallback witness/watcher lists
Log network errors separately from duplicity events
When a controller creates a key event (inception, rotation, or interaction), the event is published to designated witnesses. Each witness that receives the event:
Validates the event against KERI protocol rules
Checks sequence number to determine if it fits the available tail position in their KEL
Records as first-seen if valid and properly sequenced
Creates a receipt (signed acknowledgment) of the event
Promulgates receipts to other witnesses in the witness pool
The "first seen, always seen, never unseen" principle is critical: once a witness accepts an event for a given sequence number, that event becomes permanent in that witness's view. Any subsequent event claiming the same sequence number will be rejected and flagged as potentially duplicitous.
Step 2: Witness Agreement via KAACE
Witnesses coordinate through KAACE (KERI's Agreement Algorithm for Control Establishment) to reach consensus:
Receipt exchange: Each witness shares its receipt with all other witnesses
Consistency verification: Witnesses compare the events they've observed
State convergence: Witnesses that agree on events form a consistent view of the KEL
If witnesses observe different events for the same sequence number, this immediately signals potential duplicity. The witnesses do not attempt to resolve which version is "correct" - they simply record what they observed and make this evidence available.
Step 3: Watcher Network Monitoring
Watchers operate independently of the controller's designated witnesses, providing distributed duplicity detection:
Promiscuous observation: Watchers observe KELs without being designated by controllers
Independent recording: Each watcher maintains its own copy of observed KELs
Cross-validation: Watchers compare their observations with other watchers
Duplicity evidence collection: When inconsistencies are detected, watchers preserve both versions as evidence
The watcher network creates ambient duplicity detection - the property that duplicitous behavior can be detected by anyone, anywhere, at any time. This is KERI's primary defense against eclipse attacks, where an attacker attempts to isolate a validator from the honest network.
Step 4: Validator Evaluation
When a validator needs to establish trust in an AID:
KEL retrieval: Obtains the KEL from witnesses or watchers
Duplicity check: Queries multiple independent sources (witnesses, watchers) for the same KEL
Comparison: Identifies any discrepancies between versions
Evidence evaluation: If duplicity is detected, examines the conflicting versions
Step 5: Duplicity Classification
When duplicity is detected, it must be classified:
Reconcilable Duplicity: Occurs when one version can be definitively established as authoritative:
One version has proper witness receipts while the other lacks them
One version follows proper pre-rotation commitments while the other violates them
The controller can demonstrate which version is legitimate through recovery procedures
Irreconcilable Duplicity: Occurs when no version can be established as authoritative:
Multiple versions have equal witness support
Both versions appear cryptographically valid
No clear evidence indicates which version the controller intended
For irreconcilable duplicity, the validator typically rejects all versions and refuses to trust the AID.
Step 6: Recovery Process (for Reconcilable Duplicity)
When duplicity is detected but potentially reconcilable:
Judge invocation: Judges examine the KELs and DELs (Duplicitous Event Logs)
Jury evaluation: Jurors perform detailed duplicity detection on events and receipts
Superseding rules application: KERI's recovery protocol determines which version supersedes others
State correction: The authoritative KEL is established and propagated
Historical preservation: The duplicitous versions remain in DELs as evidence
The recovery process follows superseding rules defined in the KERI specification, which provide deterministic procedures for resolving conflicts.
Technical Requirements
Cryptographic Requirements
Non-repudiable Signatures: Every key event must be signed with non-repudiable digital signatures using the current authoritative keys. This ensures that duplicitous events provide cryptographic proof of misbehavior - the controller cannot deny having signed conflicting versions.
Self-addressing identifier (d field): Binds the event to its content
Next key digest (n field): Creates forward commitment through pre-rotation
These cryptographic commitments make it impossible to alter past events without detection and prevent certain classes of duplicity attacks.
Witness Signatures: Witness receipts must be cryptographically signed by the witness's own AID, creating a verifiable chain of custody for event observation. The witness cannot later deny having observed a particular event.
Timing Considerations
First-Seen Immutability: The first-seen policy creates temporal ordering constraints:
Events must be processed in sequence number order
Once an event is accepted for a sequence position, that position is locked
Out-of-order events may be placed in escrow but don't affect first-seen determination
Propagation Speed: Witness agreement and watcher propagation typically occur within microseconds across the network. This rapid convergence is critical for:
Minimizing the window for duplicity attacks
Enabling near-real-time duplicity detection
Supporting interactive protocols that depend on current key state
Grace Periods: Some KERI implementations (particularly in vLEI credentials) use grace periods during which duplicity may be detected before final commitment. This provides a buffer for network propagation and witness coordination.
Error Handling
Escrow Mechanisms: Events that cannot be immediately validated are placed in escrow:
Out-of-order events: Events with sequence numbers beyond the current tail
Missing prior events: Events that reference unknown previous events
Unverifiable signatures: Events with signatures that cannot be validated against current key state
Escrowed events are periodically re-evaluated as new information arrives. However, escrowed events do not affect first-seen determination - only events that pass validation and fit the sequence are considered first-seen.
Duplicity Evidence Preservation: When duplicity is detected:
Both (or all) conflicting versions must be preserved in DELs
The evidence must be indexed to the corresponding KERL events
Cryptographic proofs (signatures, receipts) must be maintained
The evidence must be made available to validators for independent verification
Network Partition Handling: During network partitions:
Different network segments may observe different events
Witnesses in each segment record their first-seen events
When the partition heals, duplicity becomes evident
Recovery procedures determine which version supersedes
Incremental validation: Only validate new events rather than entire KEL on each check
Witness selection: Prioritize witnesses with low latency and high reliability
Watcher federation: Use federated watcher networks for geographic distribution
Privacy Considerations:
Duplicity detection has privacy implications:
KEL visibility: KELs are typically public or semi-public, revealing identifier activity
Watcher observation: Watchers can track which identifiers are being monitored
Correlation risks: Duplicity evidence may reveal relationships between identifiers
Mitigation strategies: Use separate AIDs for different contexts, implement selective disclosure
Relationship to KERI Security Model
Duplicity detection is the cornerstone of KERI's security architecture. Unlike blockchain systems that prevent duplicity through global consensus and total ordering, KERI makes duplicity evident rather than impossible. This design choice provides several advantages:
Scalability: No global consensus required - each AID's KEL can be validated independently
Portability: Identifiers are not locked to specific ledgers or consensus mechanisms
Flexibility: Different identifiers can use different witness configurations based on security needs
Accountability: Duplicitous behavior provides cryptographic proof of misbehavior
Recovery: Legitimate controllers can recover from key compromise through pre-rotation
The duplicity detection mechanism enables KERI to achieve end-verifiable security without requiring trust in infrastructure. Validators can independently verify identifier integrity by comparing KELs from multiple sources, making KERI suitable for zero-trust architectures where no party is implicitly trusted.