Comprehensive Explanation

witness

Process Definition

A witness in KERI is a designated infrastructure component that performs three critical functions: verifying key events, signing receipts, and maintaining copies of Key Event Logs (KELs). Unlike traditional blockchain validators, witnesses operate through a lightweight consensus mechanism called KAACE (KERI's Agreement Algorithm for Control Establishment) that enables distributed validation without requiring global ordering or proof-of-work.

The witness process accomplishes several objectives:

• Event Validation: Cryptographically verifies that incoming key events are properly structured and signed
• Receipt Generation: Creates signed receipts (key event receipt messages) that attest to event observation
• KEL Storage: Maintains authoritative copies of KELs for identifiers they witness
• Duplicity Detection: Enables detection of conflicting event versions through distributed observation
• High Availability: Provides persistent storage and retrieval of key events when controllers are offline

Witnesses are used in KERI's indirect mode of operation, where controllers may be intermittently connected or require high availability for their identifiers. The key participants include:

• Controller: The entity that designates witnesses and generates key events
• Witness Pool: The set of witnesses designated for an AID (typically 3-7 witnesses)
• Validators: Entities that query witnesses to verify key state
• Other Witnesses: Peer witnesses that exchange receipts to establish consensus

Process Flow

The witness process follows a well-defined sequence of operations:

1. Witness Designation

During inception or rotation events, the controller specifies:

• Witness List (w field): AIDs of designated witnesses
• Witness Threshold (wt field): Minimum number of witness receipts required
• TOAD (Threshold of Accountable Duplicity): Minimum witnesses for controller accountability

Example inception event with witness configuration:

{
  "v": "KERI10JSON000188_",
  "t": "icp",
  "d": "EPNYUP688XxtHUfxeHlqxqSduMHmWrpjRzlUCKPtvB7t",
  "i": "EPNYUP688XxtHUfxeHlqxqSduMHmWrpjRzlUCKPtvB7t",
  "s": "0",
  "kt": "1",
  "k": ["DDSxKwKSZZq672OtzOlokik6L0rr3TtWrZDiHfnATU9j"],
  "n": "EJ4Ngh0jDrlkD774TdNbkhzVYnf-MwpHGAnqKmsCAB8A",
  "bt": "2",
  "b": [
    "BJq7UABlttINuWJh1Xl2lkqZG4NTdUdqnbFJDa6ZyxCC",
    "BDg1zxxf8u4Hx5IPraZzmStfSCZFZbDzMHjqVcFW5OfP"
  ],
  "c": [],
  "a": []
}

2. Event Reception

When a controller generates a key event:

1. Controller signs the event with current authoritative keys
2. Controller transmits the signed event to designated witnesses
3. Each witness receives the event message via HTTP/TCP
4. Witness validates the event structure and CESR encoding

3. Event Verification

Each witness performs cryptographic verification:

• Signature Validation: Verifies signatures against current key state
• Sequence Validation: Confirms sequence number follows previous event
• Digest Chain Validation: Verifies previous event digest (p field) matches
• Pre-rotation Validation: For rotations, confirms new keys match prior commitment
• Threshold Validation: Ensures sufficient signatures for multi-sig AIDs

4. Receipt Generation

Upon successful verification, the witness:

1. Creates a key event receipt (rct) message
2. Signs the receipt with the witness's own AID
3. Includes the event digest being receipted
4. Stores the event in its local KEL copy

Example receipt structure:

{
  "v": "KERI10JSON000091_",
  "t": "rct",
  "d": "EPNYUP688XxtHUfxeHlqxqSduMHmWrpjRzlUCKPtvB7t",
  "i": "EPNYUP688XxtHUfxeHlqxqSduMHmWrpjRzlUCKPtvB7t",
  "s": "0"
}

Followed by CESR-encoded witness signature attachment.

5. Receipt Exchange (KAACE)

Witnesses participate in the KAACE consensus algorithm:

1. Each witness transmits its receipt to all other witnesses in the pool
2. Witnesses collect receipts from peers
3. Agreement is reached when each witness has:
   • Observed the same event version
   • Received receipts from all other witnesses
4. The agreed-upon event becomes part of the KERL (Key Event Receipt Log)

6. State Publication

Witnesses make KELs available through:

• OOBI endpoints: HTTP endpoints for KEL retrieval
• Mailbox services: Store-and-forward message delivery
• Query responses: Answer key state queries from validators

7. Duplicity Detection

If a witness receives conflicting versions of an event:

1. Witness stores both versions in a Duplicitous Event Log (DEL)
2. Witness continues to provide receipts but flags duplicity
3. Validators querying the witness can detect the inconsistency
4. The first-seen policy ensures the initial version is preserved

Technical Requirements

Cryptographic Requirements

Witness Identity:

• Each witness MUST control its own self-certifying AID
• Witness AID MAY be transferable (supporting key rotation) or non-transferable
• Witness signing keys MUST provide minimum 128-bit cryptographic strength
• Supported algorithms include Ed25519 and ECDSA secp256k1

Signature Operations:

• Witnesses MUST sign receipts using their current authoritative keys
• Signatures MUST be encoded in CESR format
• Multi-signature witnesses MUST satisfy their own threshold requirements

Event Validation:

• MUST verify all signatures on incoming events
• MUST validate hash chain integrity (previous digest matching)
• MUST verify pre-rotation commitments during rotation events
• MUST enforce sequence number monotonicity

Timing Considerations

Event Processing:

• Witnesses operate asynchronously - no global clock synchronization required
• Receipt generation should occur within seconds of event reception
• KAACE consensus typically completes in milliseconds to seconds
• No strict ordering required between different AIDs' events

Availability Requirements:

• Witnesses SHOULD maintain high availability (99%+ uptime recommended)
• Witness pools provide redundancy - system tolerates N - threshold failures
• Controllers can rotate witness sets if witnesses become unavailable

Escrow Handling:

• Witnesses MUST escrow out-of-order events until dependencies arrive
• Escrow timeout policies prevent indefinite storage of invalid events
• Escrowed events are processed once dependencies are satisfied

Error Handling

Invalid Events:

• Witnesses MUST reject events with invalid signatures
• Witnesses MUST reject events with broken hash chains
• Witnesses MUST reject events violating sequence constraints
• Rejection does not generate receipts

Duplicity Handling:

• Witnesses MUST store all versions of duplicitous events
• Witnesses MUST continue operating despite detecting duplicity
• Witnesses MUST make duplicity evidence available to validators

Network Failures:

• Witnesses MUST handle intermittent controller connectivity
• Witnesses MUST retry receipt delivery to peer witnesses
• Witnesses MUST maintain event queues during network partitions

Usage Patterns

Typical Scenarios

Scenario 1: Basic Witness Configuration

For a standard transferable AID requiring high availability:

kli incept --name my-keystore --alias my-aid \
  --icount 1 --isith 1 \
  --ncount 1 --nsith 1 \
  --wits BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha \
        BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM \
        BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX \
  --toad 2

This creates an AID with:

• 3 witnesses specified by their AIDs
• TOAD of 2 (requires 2 witness receipts for accountability)
• Single signing key with rotation capability

Scenario 2: Witness Pool for Multi-Sig AID

For a 3-of-5 multi-signature identifier:

kli incept --name multisig-keystore --alias multisig-aid \
  --icount 5 --isith 3 \
  --ncount 5 --nsith 3 \
  --wits <witness-1-AID> <witness-2-AID> <witness-3-AID> \
        <witness-4-AID> <witness-5-AID> \
  --toad 3

This configuration:

• Requires 3 of 5 controller signatures
• Uses 5 witnesses for high redundancy
• TOAD of 3 ensures strong duplicity protection

Scenario 3: Witness Rotation

Changing witness set during rotation:

kli rotate --name my-keystore --alias my-aid \
  --witness-remove <old-witness-AID> \
  --witness-add <new-witness-AID>

The rotation event includes:

• wr field: witnesses to remove
• wa field: witnesses to add
• New witness configuration takes effect immediately

Best Practices

Witness Selection:

• Choose witnesses operated by independent entities
• Distribute witnesses geographically for resilience
• Verify witness availability and reputation before designation
• Use minimum 3 witnesses for production systems
• Consider 5-7 witnesses for high-security applications

Threshold Configuration:

• Set TOAD to N - F where N is witness count and F is maximum tolerable failures
• For 5 witnesses, TOAD of 3 tolerates 2 failures
• Higher TOAD provides stronger duplicity protection but reduces fault tolerance

Witness Discovery:

• Publish witness OOBIs through multiple channels
• Use well-known URIs for witness endpoint discovery
• Implement witness discovery via DHT for decentralized systems
• Maintain witness contact information in secure configuration

Operational Monitoring:

• Monitor witness receipt generation latency
• Track witness availability metrics
• Implement alerting for witness failures
• Regularly test witness rotation procedures

Integration Considerations

With KERIA Agents:

• KERIA agents automatically handle witness communication
• Agents manage receipt collection and KAACE participation
• Agents provide mailbox services for asynchronous delivery
• Configuration specifies witness endpoints in agent config files

With Watchers:

• Watchers query witnesses to build independent KEL copies
• Watchers compare witness responses to detect duplicity
• Watchers operate in "promiscuous mode" (not designated by controller)
• Watcher networks provide additional validation layer

With Verifiers:

• Verifiers query witnesses to obtain current key state
• Verifiers validate witness receipts as proof of consensus
• Verifiers can detect duplicity by querying multiple witnesses
• Verifiers implement BADA (Best Available Data Acceptance) policy

With Registries (TELs):

• Transaction Event Logs use witnesses as "registrars"
• Registrars witness credential issuance/revocation events
• TEL events are anchored to KEL events via seals
• Witness infrastructure supports both KEL and TEL operations

Advanced Witness Patterns

Ledger-Backed Witnesses

Some witnesses use blockchain/DLT for KEL storage:

• Cardano Backer: Anchors KELs to Cardano blockchain
• Provides immutable audit trail
• Combines KERI security with blockchain persistence
• Useful for regulatory compliance scenarios

Witness Pools with Geographic Distribution

For global high-availability:

• Deploy witnesses across continents (EU, NA, APAC)
• Use CDN-like distribution for low-latency access
• Implement regional failover strategies
• Example: GLEIF vLEI uses geographically distributed witness pools

Hierarchical Witness Structures

For delegated identifiers:

• Root AID uses high-security witness pool
• Delegated AIDs may use different witness sets
• Witness configuration inherits security properties
• Enables scalable organizational identity structures

Witness-as-a-Service

Commercial witness offerings:

• Managed witness infrastructure
• SLA-backed availability guarantees
• Professional key management
• Integration with enterprise identity systems