The first-seen policy is a fundamental ordering rule in KERI where validators (witnesses/watchers) permanently accept the first valid event they receive for a given sequence position in a Key Event Log (KEL), establishing an immutable record under the principle 'first seen, always seen, never unseen' that enables duplicity detection across the distributed network.
Related Concepts
No related concepts available
Comprehensive Explanation
first-seen
Process Definition
The first-seen policy is a core consensus mechanism in KERI that defines how validators (specifically witnesses and watchers) handle incoming key events to establish authoritative ordering within a Key Event Log (KEL). When a validator receives an event, it is considered "first-seen" if it meets three critical criteria:
Validity: The event is cryptographically valid according to KERI validation rules (proper signatures, correct structure, valid cryptographic primitives)
Sequence Fit: The event fits the available tail sequence number in the validator's KEL (it's the next expected event in the sequence)
Temporal Priority: The event is the first such event received for that sequence position
Once an event meets these criteria and is accepted into the validator's KEL, it becomes permanently fixed under the foundational principle: "First seen, always seen, never unseen". This immutability is not merely a design preference but a security requirement that enables KERI's duplicity detection mechanism.
The first-seen policy operates independently of the timing of events held in escrow. Events may arrive out of order or be temporarily held in escrow if they cannot yet be validated (for example, if they reference a sequence number not yet reached). The escrow mechanism can contain invalid or garbage data, but only valid events that fit the proper sequence position trigger the first-seen acceptance.
Implementation Notes
Critical Implementation Details
Immutability Enforcement
Implementations MUST enforce the "first seen, always seen, never unseen" principle with absolute rigor. Once an event is accepted as first-seen:
The event MUST NOT be removed from the KEL
The event MUST NOT be modified in any way
The event's sequence position MUST remain fixed
Any attempt to alter first-seen events MUST be rejected
This immutability is not a performance optimization but a security requirement. Violations compromise the entire duplicity detection mechanism.
Escrow Management
Escrow implementation requires careful attention:
Separate Storage: Escrowed events MUST be stored separately from the KEL
Validation State: Track why each event is escrowed (missing predecessor, future sequence, etc.)
Timeout Handling: Implement reasonable timeouts for escrowed events
Garbage Collection: Remove invalid or expired escrowed events
Dependency Tracking: Maintain references between escrowed events and their dependencies
Concurrent Event Handling
In production systems, multiple events may arrive simultaneously:
Atomic Operations: First-seen checks and KEL updates MUST be atomic
Race Condition Prevention: Use appropriate locking or transactional mechanisms
Ordering Guarantees: Ensure consistent ordering when events arrive concurrently
Receipt Generation: Coordinate receipt creation with KEL updates
Duplicity Logging
When rejecting events due to first-seen conflicts:
Preserve Evidence: Store rejected events for forensic analysis
Detailed Logging: Record timestamps, source, and reason for rejection
Comparison Data: Log differences between first-seen and rejected events
Alert Mechanisms: Notify administrators of potential duplicity
Performance Considerations
KEL Indexing: Index KELs by sequence number for fast first-seen lookups
Escrow Queues: Use efficient data structures for escrow management
Key Participants
The first-seen policy involves several key participants in the KERI ecosystem:
Controllers: Generate and publish key events to their designated witnesses
Witnesses: Designated validators that receive, verify, store, and sign key events, creating key event receipts
Watchers: Independent validators operating in "promiscuous mode" that observe and record KELs without being designated by controllers
Validators: Any entity evaluating the validity of key events and KEL state
Verifiers: Entities cryptographically verifying signatures and digests on event messages
Process Flow
Event Reception and Initial Processing
When a validator receives a key event message, the first-seen process follows this sequence:
Step 1: Event Arrival
Event message arrives at validator (witness or watcher)
Message contains serialized key event data with attached signatures
Event includes sequence number indicating its position in the KEL
Step 2: Structural Validation
Validator parses the event message using CESR encoding
Checks event structure conforms to KERI protocol specifications
Validates all required fields are present and properly formatted
Receipt is propagated to other validators and the controller
State Changes and Escrow Management
The first-seen policy interacts with KERI's escrow mechanism in specific ways:
Escrow Independence: Events in escrow do not affect first-seen determination. An event waiting in escrow because it references a future sequence number does not prevent a properly sequenced event from being accepted as first-seen.
Escrow Resolution: When a first-seen event is accepted, the validator checks escrow for any events that can now be processed. Events in escrow that reference the newly accepted event's sequence number as their predecessor can be evaluated for first-seen acceptance.
Garbage Collection: Invalid events in escrow that cannot be validated even after waiting for dependencies are eventually discarded. These never achieve first-seen status.
Decision Points and Branching
The first-seen process includes several critical decision points:
Valid vs. Invalid: If an event fails cryptographic validation, it is immediately rejected without consideration for first-seen status. Invalid events may be logged for security analysis but never enter the KEL.
Sequence Match vs. Mismatch: Events with sequence numbers that don't match the expected next position are handled differently:
Future sequence: Placed in escrow, may become first-seen later
Past sequence: Rejected, may indicate duplicity attempt
Current sequence: Evaluated for first-seen acceptance
First vs. Subsequent: The critical branching point:
First event for position: Accepted as first-seen, becomes permanent
Subsequent event for position: Rejected, triggers duplicity detection
Technical Requirements
Cryptographic Requirements
The first-seen policy depends on robust cryptographic verification:
Signature Verification: All events must be signed by authoritative keys. For multi-sig identifiers, the signing threshold must be met. Signature verification uses the current key state established by previous events in the KEL.
Digest Verification: Events include cryptographic digests for:
Backward chaining: Digest of previous event ensures unbroken chain
Forward chaining: Digest of next keys (pre-rotation) enables secure key rotation
Content integrity: SAIDs ensure event content hasn't been tampered with
Cryptographic Strength: KERI requires minimum 128-bit security strength for all cryptographic operations. This ensures that collision attacks on digests are computationally infeasible, preventing attackers from creating alternative events with the same digest.
Timing Considerations
Network Propagation: The first-seen policy operates in a distributed network where events propagate at different speeds to different validators. This creates natural timing variations:
Different First-Seen Numbers: Different validators may have different first-seen sequence numbers for the same originating transaction event. This is acceptable as long as the events themselves are consistent.
Microsecond Propagation: When a watched set of validators agrees on first-seen events, watchers observing these validators propagate the consensus within microseconds across the validator network.
Escrow Timeout: Events in escrow have implicit timeouts. If dependencies don't arrive within reasonable time windows, escrowed events may be discarded.
Clock Synchronization: While KERI doesn't require precise clock synchronization across validators, reasonable time agreement helps with:
Escrow timeout decisions
Detecting abnormally delayed events
Coordinating recovery processes
Error Handling
The first-seen policy includes specific error handling mechanisms:
Duplicitous Events: When a validator receives a second, conflicting event for a sequence position where a first-seen event already exists:
Accountability: Controllers are accountable for any duplicitous events
Deterrence: The certainty of detection deters malicious behavior
The first-seen policy represents a fundamental departure from blockchain-based consensus, achieving security through ambient duplicity detection rather than computational proof-of-work or stake-based mechanisms. This approach enables KERI to provide strong security guarantees while maintaining the scalability and portability required for internet-scale identity infrastructure.
Receipt Caching: Cache witness receipts to avoid redundant verification
Batch Processing: Process multiple events in batches when possible