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

Performance Considerations

Receipt Generation Latency:

• Target: < 100ms for event verification and receipt generation
• Optimize signature verification using batch validation
• Use async I/O for witness-to-witness communication

Storage Requirements:

• KEL storage grows linearly with event count
• Typical event size: 200-500 bytes
• Plan for 1MB per 2000-5000 events per AID
• Implement KEL pruning for non-establishment events if needed

Network Bandwidth:

• Receipt exchange between witnesses is low-bandwidth
• Typical receipt size: 100-200 bytes
• For N witnesses, each event generates N*(N-1) receipt exchanges

Security Hardening

Witness Key Management:

• Use HSM or secure enclave for witness signing keys
• Implement key rotation for witness AIDs
• Separate witness signing keys from infrastructure keys

Access Control:

• Implement rate limiting on witness endpoints
• Use authentication for administrative operations
• Separate witness configuration from controller keys

Duplicity Response:

• Log all duplicitous events with timestamps
• Alert operators when duplicity is detected
• Maintain duplicitous event logs indefinitely
• Provide duplicity evidence to validators on request

Integration with KERIA

When using KERIA agents:

• Configure witness endpoints in keria-config.json
• KERIA handles automatic receipt collection
• Agents manage witness communication asynchronously
• Mailbox services provide store-and-forward for receipts

Testing Witness Infrastructure

Unit Tests:

• Test event validation logic
• Test receipt generation
• Test KAACE consensus algorithm
• Test duplicity detection

Integration Tests:

• Test witness pool with multiple witnesses
• Test witness rotation scenarios
• Test network partition handling
• Test Byzantine failure scenarios

Load Tests:

• Test throughput with high event rates
• Test concurrent event processing
• Test witness pool scalability
• Measure receipt generation latency under load