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:

1. Validity: The event is cryptographically valid according to KERI validation rules (proper signatures, correct structure, valid cryptographic primitives)
2. Sequence Fit: The event fits the available tail sequence number in the validator's KEL (it's the next expected event in the sequence)
3. 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.

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
• Verifies derivation codes for cryptographic primitives

Step 3: Cryptographic Verification

• Validator verifies digital signatures using current authoritative keys
• For establishment events, validates threshold requirements
• Checks cryptographic digests for backward chaining (reference to previous event)
• Validates forward chaining commitments (pre-rotated key digests)

Step 4: Sequence Position Check

• Validator examines current KEL state to determine next expected sequence number
• Compares event's sequence number to expected position
• If sequence number matches: proceed to acceptance
• If sequence number is future: place in escrow for later processing
• If sequence number is past: reject as duplicate or late arrival

Step 5: First-Seen Determination

• If event passes all validation checks AND fits sequence position
• Validator checks if any event for this sequence position has been previously accepted
• If no prior event exists for this position: event is "first-seen"
• If prior event exists: event is rejected as conflicting (potential duplicity)

Step 6: Permanent Acceptance

• First-seen event is appended to validator's KEL
• Event becomes immutable part of the log
• Validator creates signed receipt for the event
• 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:

1. The conflicting event is rejected from the KEL
2. The conflict is logged as evidence of duplicity
3. The validator may create a Duplicitous Event Log (DEL) entry
4. Other validators are notified of the duplicity detection
5. Recovery mechanisms may be triggered if duplicity involves establishment events

Key Compromise Recovery: The first-seen policy is critical for detecting duplicity that may not be discovered until after a key rotation event:

• Delayed Detection: Duplicitous interaction events using current signing keys may not be detected immediately
• Post-Rotation Discovery: Duplicity becomes evident when different validators have different first-seen events in their KELs
• Recovery Process: Upon detection, judges and jury mechanisms are invoked following KERI's superseding rules for recovery

KEL Correction: Once an erroneous KEL has been corrected through the recovery process:

• Validators will never provide outdated KEL data or events
• The corrected version becomes the new authoritative state
• The "never unseen" principle is maintained for the corrected KEL

Usage Patterns

Typical Scenarios

Scenario 1: Normal Event Processing

In the most common case, events arrive in proper sequence:

1. Controller generates inception event for new AID
2. Witnesses receive inception event, validate, accept as first-seen at sequence 0
3. Witnesses create and exchange receipts
4. Controller generates interaction event at sequence 1
5. Witnesses receive interaction event, validate, accept as first-seen at sequence 1
6. Process continues for subsequent events

This scenario demonstrates the first-seen policy operating smoothly with no conflicts or escrow delays.

Scenario 2: Out-of-Order Arrival

Events may arrive out of sequence due to network conditions:

1. Controller publishes rotation event (sequence 5) and interaction event (sequence 6)
2. Witness A receives sequence 6 before sequence 5
3. Witness A places sequence 6 in escrow (future sequence)
4. Witness A receives sequence 5, validates, accepts as first-seen
5. Witness A checks escrow, finds sequence 6 now processable
6. Witness A validates sequence 6, accepts as first-seen

This demonstrates escrow handling without affecting first-seen determination.

Scenario 3: Duplicity Detection

A malicious controller attempts to create conflicting event histories:

1. Controller creates two different interaction events for sequence 3
2. Controller sends version A to Witness Set 1
3. Controller sends version B to Witness Set 2
4. Witness Set 1 accepts version A as first-seen
5. Witness Set 2 accepts version B as first-seen
6. Watchers observing both sets detect inconsistency
7. Duplicity is reported, triggering recovery mechanisms

This scenario shows how first-seen policy enables ambient duplicity detection.

Best Practices

For Controllers:

• Publish consistently: Send identical events to all designated witnesses
• Monitor receipts: Verify all witnesses accepted the same event version
• Avoid conflicts: Never create multiple versions of the same sequence number
• Sequence carefully: Ensure events are generated in proper sequence order

For Witnesses:

• Validate thoroughly: Perform complete cryptographic verification before acceptance
• Record permanently: Maintain immutable KEL records
• Exchange receipts: Coordinate with other witnesses to detect inconsistencies
• Monitor escrow: Regularly process escrowed events when dependencies arrive

For Watchers:

• Observe widely: Monitor multiple witness sets for comprehensive coverage
• Compare KELs: Detect inconsistencies across different validator views
• Report duplicity: Alert the network when conflicting first-seen events are detected
• Maintain independence: Operate without controller designation to provide unbiased observation

Integration Considerations

Witness Pool Configuration: The first-seen policy operates within the context of witness pools configured by controllers:

• Threshold Settings: The threshold of accountable duplicity (TOAD) determines how many witnesses must agree
• Pool Size: Larger witness pools provide more redundancy and duplicity detection capability
• Geographic Distribution: Distributed witnesses reduce risk of coordinated attacks

Watcher Network Integration: Watchers complement witnesses by providing independent verification:

• Promiscuous Observation: Watchers observe all KELs they encounter without designation
• Cross-Validation: Watchers compare KELs from multiple witnesses
• Ambient Detection: The distributed watcher network enables detection of duplicity anywhere in the system

Recovery Protocol Integration: The first-seen policy integrates with KERI's recovery mechanisms:

• Superseding Rules: When duplicity is detected, recovery follows specific superseding rules
• Judge/Jury Mechanisms: Advanced mode uses judge and jury pools for duplicity resolution
• KEL Correction: Corrected KELs maintain first-seen properties for legitimate events

Implications for KERI Architecture

The first-seen policy serves several critical architectural functions:

Deterministic Event Ordering

The policy establishes clear, irreversible ordering of events within each validator's perspective. This determinism is essential for:

• Consistent Key State: All validators observing the same first-seen events converge on identical key state
• Predictable Behavior: Applications can rely on stable event ordering
• Reproducible Verification: Any party can independently verify the event sequence

Duplicity Evidence Creation

The first-seen policy creates forensic evidence when controllers attempt to create conflicting event histories:

• Immutable Records: First-seen events cannot be changed, creating permanent evidence
• Distributed Witnesses: Multiple independent validators maintain separate records
• Provable Conflicts: Conflicting first-seen events across validators prove duplicitous behavior

Network Consistency Without Consensus

The policy enables rapid consensus across distributed validators without traditional consensus algorithms:

• No Global Ordering: KERI doesn't require total ordering across all identifiers
• Per-Identifier Ordering: Each KEL maintains its own sequence independently
• Lightweight Coordination: Witnesses coordinate through receipt exchange, not heavyweight consensus
• Scalable Architecture: Linear scaling as new identifiers are added

Security Foundation

The first-seen policy provides the basis for detecting and recovering from key compromise attacks:

• Early Detection: Duplicity is detected as soon as conflicting events are observed
• Recovery Triggers: Detection automatically initiates recovery protocols
• 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.