Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 71 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
A witness pool is a collection of witnesses available for selection by an AID controller to provide key event witnessing services, forming part of the KERI infrastructure for distributed consensus. Controllers designate witnesses from the pool to verify, sign, and store key events, with the pool providing redundancy, fault tolerance, and protection against compromise through threshold-based agreement mechanisms.
A witness pool represents a fundamental architectural component in KERI's distributed trust infrastructure, serving as a collection of available witnesses from which an AID (Autonomic Identifier) controller can select participants to provide key event witnessing services. The witness pool enables controllers to establish distributed verification and storage of their Key Event Logs (KELs) without relying on centralized infrastructure or trusted third parties.
The witness pool accomplishes several critical functions within the KERI ecosystem:
Distributed Verification: By providing multiple independent witnesses, the pool enables distributed verification of key events without requiring a shared ledger or blockchain infrastructure. Each witness independently validates events before signing receipts, creating multiple verification points that must be compromised simultaneously for an attack to succeed.
Fault Tolerance: The pool architecture provides resilience against witness failures, whether due to technical issues, network partitions, or malicious behavior. Controllers can configure threshold requirements that allow the system to continue operating even when some witnesses are unavailable or compromised.
Flexibility and Portability: Controllers can select witnesses from the pool based on their specific security requirements, trust relationships, and operational needs. The pool model enables controllers to change their witness configuration through rotation events, providing true identifier portability across different infrastructure providers.
Attack Surface Multiplication: As documented in the principle, witness pools multiply attack surfaces rather than adding them. An attacker must compromise multiple independent witnesses simultaneously, making the combined system highly secure even when individual witnesses have relatively modest security guarantees.
When implementing witness pool support, consider:
Witness Discovery Mechanisms: Implement multiple discovery paths including well-known URIs, OOBI resolution, DHT lookups, and DID resolution. The vLEI governance framework mandates publication to "at least one ecosystem discovery mechanism" including well-known URIs, search engines, KERI DHT, and DID resolvers.
Witness Selection Algorithms: Implement algorithms that help controllers select appropriate witnesses based on trust relationships, geographic distribution, security requirements, and threshold constraints. The ample formula (n+f+1)/2 <= m <= n-f should be used to validate threshold configurations.
Threshold Validation: Validate that configured TOAD values satisfy the ample constraint for the given witness pool size. Reject configurations that cannot achieve supermajority consensus or that provide insufficient fault tolerance.
The KERI Agreement Algorithm for Control Establishment requires:
Receipt Exchange Protocol: Implement witness-to-witness receipt exchange where each witness broadcasts receipts to all other witnesses in the pool. This enables the distributed consensus mechanism.
Agreement Detection: Implement logic to detect when sufficient witnesses have receipted an event. Agreement is reached when the TOAD threshold is met and each witness has received receipts from the required number of peer witnesses.
Timeout Handling: Implement timeout mechanisms for witness responses. If witnesses don't respond within configured timeouts, the system should either retry or proceed with available witnesses if TOAD threshold can still be met.
Parallel Event Submission: Send events to all witnesses in parallel rather than sequentially to minimize latency. Use asynchronous I/O or threading to avoid blocking on slow witnesses.
Connection Management: Maintain persistent connections to frequently-used witnesses using connection pooling. Implement reconnection logic with exponential backoff for failed connections.
Receipt Collection: Implement asynchronous receipt collection that proceeds once TOAD threshold is met rather than waiting for all witnesses. Store receipts as they arrive for later verification.
Dual Witness Set Handling: During rotation, both old and new witness sets must receipt the rotation event. Implement logic to track receipts from both sets and ensure sufficient coverage from each.
Witness pools are employed in KERI's indirect mode operations, which contrast with direct mode peer-to-peer exchanges. According to Document 2, indirect mode is used when:
The vLEI ecosystem extensively uses witness pools, as documented in Document 6, which mandates "minimum 5 witnesses using KAACE sufficient majority threshold" for production deployments.
The witness pool ecosystem involves several participant types:
Controllers: AID controllers who select witnesses from the pool and configure threshold requirements through establishment events. Controllers maintain ultimate authority over their witness configuration and can rotate witnesses as needed.
Witnesses: Independent entities that provide witnessing services, each controlling their own self-referential identifier. Witnesses may be self-hosted by controllers, provided by third-party services, or operated by trusted organizations. As Document 19 clarifies, "each witness controls its own self-referential identifier, which may or may not be the same as the identifier it witnesses for."
Validators: Entities that verify key events by checking witness receipts and applying their own validation policies. Validators may maintain their own watcher networks to independently monitor witness behavior.
Pool Operators: Organizations or communities that maintain witness infrastructure and make it available for controller selection. The KERI ecosystem includes both public witness pools (like the demo witness network) and private pools operated by enterprises or consortia.
The process of utilizing a witness pool begins with controller selection and configuration:
Step 1: Pool Discovery
Controllers discover available witnesses through multiple mechanisms, as specified in Document 14:
The tutorial in Document 12 demonstrates practical pool discovery using a pre-configured demo network with three witnesses (Wan, Wes, and Wil), each with known prefixes and HTTP endpoints.
Step 2: Witness Selection
Controllers select specific witnesses from the available pool based on:
As Document 17 explains, the number of witnesses must satisfy the ample constraint to ensure supermajority consensus: (n+f+1)/2 <= m <= n-f, where n is total witnesses, f is potentially faulty witnesses, and m is the minimum required for agreement.
Step 3: Inception Configuration
During AID inception, the controller specifies witness configuration in the inception event:
{
"v": "KERI10JSON00011c_",
"t": "icp",
"d": "EXq5YqaL6L48pf0fu7IUhL0JRaU2_RxFP0AL43wYn148",
"i": "EXq5YqaL6L48pf0fu7IUhL0JRaU2_RxFP0AL43wYn148",
"s": "0",
"kt": "1",
"k": ["DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"],
"nt": "1",
"n": ["EZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM"],
"bt": "2",
"b": [
"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM",
"BIKKuvBwpmDVA4Ds-EpL5bt9OqPzWPja2LigFYZN2YfX"
],
"c": [],
"a": []
}
Key fields:
bt (backer threshold): Minimum witness receipts required (TOAD value)b (backers): Array of witness AIDs selected from the poolOnce configured, witnesses participate in the KAACE (KERI's Agreement Algorithm for Control Establishment) consensus process:
Step 4: Event Promulgation
When a controller creates a new key event:
Step 5: Independent Verification
Each witness performs cryptographic verification:
Step 6: Receipt Generation
Upon successful verification, each witness:
Step 7: Receipt Exchange and Agreement
Witnesses exchange receipts to achieve consensus:
Document 18 explains that "agreement on an event in a key event log (KEL) means each witness has observed the exact version of the event and each witness' receipt has been received by every other witness."
Step 8: Witness Configuration Changes
Controllers can modify their witness pool selection through rotation events:
This process enables witness portability, allowing controllers to migrate between witness providers without changing their identifier.
Witness Identifier Security
As specified in Document 14, witnesses typically use non-transferable AIDs for their own identifiers. This design choice reflects that:
Signature Strength
Document 6 mandates:
Receipt Verification
Validators verifying witness receipts must:
Asynchronous Operation
Witness pools operate asynchronously, as emphasized in Document 2:
First-Seen Policy
The first-seen policy is critical for duplicity detection:
Escrow Mechanisms
Witnesses implement escrow for out-of-order events:
Witness Unavailability
The pool architecture handles witness failures gracefully:
Duplicity Detection and Response
When duplicity is detected:
Witness Misbehavior
If a witness behaves maliciously:
Network Partitions
During network partitions:
Enterprise Deployment
Enterprises typically deploy witness pools with:
Document 31 demonstrates enterprise patterns where multi-signature group AIDs use shared witness pools, with each participant in the multisig group relying on the same witness infrastructure.
vLEI Ecosystem
The GLEIF vLEI ecosystem, as documented in Document 45, uses witness pools for:
Development and Testing
Development environments use simplified witness pools:
kli witness demoWitness Selection Criteria
When selecting witnesses from a pool:
Threshold Configuration
Best practices for TOAD configuration:
Witness Pool Maintenance
Ongoing maintenance practices:
Mailbox Authorization
As demonstrated in Document 31, controllers should:
kli ends add command with --role mailboxClient Library Integration
When integrating witness pools into applications:
OOBI Resolution
Witness discovery through OOBI:
kli oobi generate as shown in Document 47?name=Wan&tag=witness)Multi-Tenant Architectures
For systems managing multiple AIDs:
Credential Issuance Integration
When issuing ACDCs (Authentic Chained Data Containers):
Blockchain Integration
Witness pools can work alongside blockchain backers:
Parallel Witness Communication
Optimize witness pool operations by:
Witness Pool Sizing
Balance security and performance:
Caching Strategies
Implement caching to reduce witness queries:
The witness pool architecture represents a fundamental innovation in KERI's approach to decentralized trust, enabling secure, scalable, and portable identifier management without dependence on blockchains or centralized authorities. By carefully selecting witnesses, configuring appropriate thresholds, and following best practices, controllers can achieve high levels of security while maintaining operational flexibility and performance.
Graceful Migration: When rotating witnesses, implement graceful migration that maintains service continuity. New witnesses should be fully synchronized before old witnesses are removed.
Rollback Capability: Implement rollback mechanisms in case witness rotation fails. The system should be able to continue operating with the old witness set if the new configuration cannot be established.
First-Seen Enforcement: Implement strict first-seen policies where witnesses record and never change the first version of an event they observe. This is critical for duplicity detection.
Duplicity Detection: Implement mechanisms to detect when different witnesses have different versions of the same event. This indicates controller duplicity and should trigger alerts.
Witness Authentication: Always verify witness signatures using the witness's public key. Validate that the witness AID is in the controller's designated witness set before accepting receipts.
Receipt Verification: Implement comprehensive receipt verification including signature validation, timestamp checking (if applicable), and confirmation that the receipt references the correct event SAID.
Caching Strategy: Cache witness public keys, recent receipts, and witness endpoint information to reduce repeated queries. Implement TTL policies and cache invalidation on witness rotation.
Batch Operations: When processing multiple events, batch witness communications to reduce network overhead. Send multiple events in a single request where the witness API supports it.
Witness Pool Sizing: Provide guidance to users on appropriate witness pool sizes. The typical range is 5-7 witnesses for production, with 3 witnesses acceptable for development. Critical infrastructure may use 9-11 witnesses.
Witness Health Monitoring: Implement monitoring of witness availability, response times, and receipt generation rates. Alert operators when witnesses become unavailable or slow.
Metrics Collection: Collect metrics on witness pool performance including average receipt collection time, witness availability percentages, and TOAD threshold achievement rates.
Incident Response: Implement procedures for rapidly rotating witnesses if compromise is suspected. This should be a well-tested operational procedure that can be executed quickly.
Demo Witness Networks: Provide demo witness networks for development and testing, similar to the three-witness demo pool (Wan, Wes, Wil) documented in the training materials.
Fault Injection: Test witness pool behavior under various failure scenarios including witness unavailability, network partitions, slow witnesses, and malicious witnesses.
Rotation Testing: Regularly test witness rotation procedures to ensure they work correctly. This should be part of operational readiness testing.
Client Library Integration: When building client libraries, abstract witness pool complexity behind simple APIs. Users should be able to configure witness pools without understanding KAACE internals.
Configuration Management: Support witness pool configuration through configuration files, environment variables, and programmatic APIs. The configuration should be easily auditable and version-controlled.
Multi-Tenant Support: For systems managing multiple AIDs, implement witness pool management that allows different AIDs to use different pools while sharing infrastructure where appropriate.
vLEI Requirements: For vLEI ecosystem implementations, ensure compliance with governance framework requirements including minimum 5 witnesses, KAACE sufficient majority threshold, and appropriate discovery mechanisms.
Audit Logging: Implement comprehensive audit logging of witness pool operations including witness selection, rotation events, receipt collection, and duplicity detection events.
Key Management: Follow governance framework requirements for witness key management including cryptographic strength (128 bits minimum), approved algorithms (Ed25519, EcDSASecp256k1), and CESR encoding.