Step 1: OOBI Generation

• A controller or service generates an OOBI associating a URL with an AID
• The OOBI can be as simple as a tuple: (url, aid)
• Example: ("http://8.8.5.6:8080/oobi", "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM")

Step 2: OOBI Distribution

• OOBIs are shared through out-of-band channels:
  • QR codes for mobile applications
  • Email or messaging for human-to-human sharing
  • Configuration files for automated systems
  • Well-known URIs following RFC-8615 standards
  • Social media or web pages for public discovery

Step 3: OOBI Resolution

• The recipient resolves the OOBI by accessing the provided URL
• The URL acts as a service endpoint returning verifiable information
• The response typically includes:
  • The AID's Key Event Log (KEL)
  • Witness endpoint information
  • Service endpoint configurations
  • Additional metadata for verification

Step 4: Cryptographic Verification

• The discovered information is verified using KERI's BADA (Best Available Data Acceptance) policy
• The KEL is validated for:
  • Cryptographic signature integrity
  • Hash chain consistency
  • Witness receipt validation
  • Duplicity detection
• Critical: The OOBI itself is not trusted; only the cryptographically verified KEL establishes trust

Step 5: State Persistence

• Verified AIDs and their endpoints are stored locally
• Aliases may be assigned for human-readable reference
• Relationships between AIDs are tracked for future interactions

Percolated Information Discovery (PID)

KERI implements a more sophisticated discovery mechanism called Percolated Information Discovery, based on Invasion Percolation Theory:

Bootstrap Phase:

• Initial OOBI provides entry point into the discovery network
• Bootstrap information includes both discovery and verification data
• After bootstrap, subsequent authorization becomes non-interactive

Percolation Propagation:

• Each discoverer can share what they discover with other discoverers
• Information "percolates" through the network following paths of least resistance
• The percolation mechanism itself does not need to be trusted
• End-verifiability ensures security regardless of the percolation path

Zero-Trust Properties:

• Percolation intermediaries are untrusted
• Cryptographic verification occurs at endpoints
• Duplicity detection protects against malicious percolation
• Ambient verifiability enables anyone to verify anywhere, anytime

Witness Discovery

Witness discovery follows a specific pattern critical to KERI's security model:

Witness Pool Configuration:

• Controllers designate witnesses during AID inception
• Witness AIDs are included in the inception event
• Witness endpoints are discovered through OOBIs

Witness OOBI Resolution:

• Each witness has its own OOBI for endpoint discovery
• Example format: http://witness-demo:5642/oobi/{witness_AID}/witness
• Resolution returns the witness's KEL and service endpoints

Witness Verification:

• Witness KELs are validated like any other AID
• Witness receipts are verified against witness public keys
• Threshold requirements (TOAD) determine minimum witness confirmations

Mailbox Discovery:

• Witnesses often provide mailbox services for asynchronous communication
• Mailbox endpoints are discovered through witness OOBIs
• Controllers authorize witnesses to act as mailboxes through end role assignments

Watcher Network Discovery

Watchers provide additional security through duplicity detection:

Watcher Selection:

• Validators choose their own watcher networks
• Watchers operate in "promiscuous mode" monitoring multiple AIDs
• Watcher discovery uses standard OOBI mechanisms

Watcher Queries:

• Validators query watchers for KEL copies
• Multiple watcher responses are compared for consistency
• Discrepancies indicate potential duplicity

Watcher Aggregation:

• Watchers may act as super-nodes aggregating discovery information
• Watcher networks provide scalable discovery infrastructure
• Integration with DHT systems (Keridemlia) enables distributed discovery

Technical Requirements

Cryptographic Requirements

SAID Verification:

• All discovered data structures must be Self-Addressing Identifiers (SAIDs)
• SAID computation uses cryptographic digests (typically Blake3-256)
• CESR encoding ensures composability across text and binary domains

Signature Validation:

• All key events must have valid signatures from current authoritative keys
• Multi-signature thresholds must be satisfied
• Pre-rotation commitments must be verified

Hash Chain Integrity:

• Each event must correctly reference the previous event's digest
• Forward chaining through pre-rotation digests must be consistent
• Any break in the chain invalidates the KEL

Timing Considerations

Asynchronous Operations:

• Discovery operations are inherently asynchronous
• Witnesses may not respond immediately
• Mailbox polling may be required for message retrieval

Timeout Management:

• OOBI resolution should implement reasonable timeouts
• Witness queries may require retry logic
• Watcher network queries should be parallelized

Caching Strategies:

• Discovered endpoints should be cached locally
• KEL state should be persisted to avoid redundant verification
• Cache invalidation must occur on key rotation events

Error Handling

OOBI Resolution Failures:

• Network errors should trigger retry with exponential backoff
• Invalid URLs should be logged and reported
• Malformed responses should be rejected with clear error messages

Verification Failures:

• Invalid signatures must cause immediate rejection
• Hash chain breaks indicate corrupted or malicious KELs
• Duplicity detection should trigger security alerts

Witness Unavailability:

• Threshold requirements (TOAD) allow for some witness failures
• Insufficient witness responses should prevent event acceptance
• Alternative witnesses may be discovered through OOBI sharing

Watcher Inconsistencies:

• Conflicting KEL versions from watchers indicate duplicity
• Validators must investigate and resolve inconsistencies
• Duplicitous controllers should be flagged and potentially rejected

Usage Patterns

Initial AID Creation and Discovery

Scenario: A new controller creates an AID and needs to establish witness connections.

Pattern:

1. Generate AID with inception event specifying witness AIDs
2. Resolve witness OOBIs to discover endpoints
3. Send inception event to witnesses for receipting
4. Wait for witness receipts to confirm event acceptance
5. Generate controller OOBI for sharing with others

Best Practices:

• Use well-known witness pools for initial testing
• Configure at least 3 witnesses for production use
• Set TOAD to require majority witness confirmation
• Store witness OOBIs in configuration files for reproducibility

Credential Presentation Discovery

Scenario: A holder needs to present a credential to a verifier.

Pattern:

1. Holder generates OOBI for their AID
2. Holder shares OOBI with verifier through secure channel
3. Verifier resolves OOBI to discover holder's KEL
4. Verifier validates holder's key state
5. Holder presents credential with cryptographic proof
6. Verifier validates credential against holder's verified keys

Best Practices:

• Use QR codes for in-person presentations
• Implement challenge-response for authentication
• Verify issuer AIDs through their OOBIs
• Check credential registry status through TEL discovery

Multi-Signature Coordination Discovery

Scenario: Multiple parties need to coordinate on a multi-sig AID.

Pattern:

1. Each participant creates individual AID
2. Participants exchange OOBIs through secure channels
3. Each participant resolves others' OOBIs
4. Challenge-response authentication establishes mutual verification
5. Multi-sig inception event is coordinated
6. Witnesses are discovered and configured for the group AID

Best Practices:

• Use video calls for OOBI exchange to prevent MITM attacks
• Implement challenge-response to verify control
• Configure shared witness pools for the multi-sig AID
• Use mailbox services for asynchronous coordination

Delegated Identifier Discovery

Scenario: A delegate needs to discover and verify their delegator.

Pattern:

1. Delegator creates delegation event in their KEL
2. Delegator shares OOBI with delegate
3. Delegate resolves delegator OOBI
4. Delegate verifies delegation event in delegator's KEL
5. Delegate creates delegated inception event
6. Delegate's KEL references delegator's AID and delegation event

Best Practices:

• Verify delegation seal in delegator's KEL
• Ensure delegator's KEL is witnessed and stable
• Configure delegate witnesses to be discoverable
• Maintain delegation chain for hierarchical structures

Schema and Credential Discovery

Scenario: A verifier needs to discover and validate credential schemas.

Pattern:

1. Credential includes schema SAID
2. Verifier discovers schema through data OOBI
3. Schema is retrieved from well-known URI or registry
4. Schema SAID is verified against retrieved content
5. Credential is validated against schema structure

Best Practices:

• Use well-known URIs for schema hosting (e.g., /.well-known/keri/schema/{SAID})
• Implement schema caching to reduce network requests
• Verify schema SAIDs before using for validation
• Support multiple schema versions through SAID references

Watcher Network Integration

Scenario: A validator wants to use watchers for enhanced security.

Pattern:

1. Validator discovers watcher network through OOBIs
2. Validator queries multiple watchers for target AID's KEL
3. Watcher responses are compared for consistency
4. Inconsistencies trigger duplicity investigation
5. Consistent KEL is accepted as valid

Best Practices:

• Query at least 3 independent watchers
• Use geographically distributed watchers
• Implement parallel queries for performance
• Log and investigate any duplicity detected

Integration Considerations

Web Application Integration

Client-Side Discovery:

• Use SignifyTS for browser-based OOBI resolution
• Implement QR code scanning for mobile OOBI sharing
• Cache discovered endpoints in browser storage
• Handle CORS restrictions for cross-origin OOBI resolution

Server-Side Discovery:

• Use KERIA agents for cloud-based discovery
• Implement OOBI resolution APIs for client applications
• Provide discovery endpoints for service integration
• Support webhook notifications for discovery events

Mobile Application Integration

OOBI Sharing:

• Generate QR codes for OOBI distribution
• Support NFC for proximity-based OOBI exchange
• Implement deep links for OOBI handling
• Use secure enclaves for key material protection

Background Discovery:

• Implement background tasks for witness polling
• Use push notifications for discovery events
• Optimize battery usage with intelligent polling
• Cache discovered data for offline access

Enterprise System Integration

Configuration Management:

• Store witness OOBIs in configuration files
• Use environment variables for endpoint configuration
• Implement service discovery for internal infrastructure
• Support dynamic witness pool updates

Monitoring and Observability:

• Log all discovery operations for audit trails
• Monitor witness availability and response times
• Alert on duplicity detection events
• Track discovery success rates and failures

Blockchain Integration

Ledger-Backed Discovery:

• Use blockchain as backer for KEL storage
• Discover ledger registrars through OOBIs
• Verify ledger-anchored events through blockchain queries
• Support multiple ledger types (Ethereum, Cardano, etc.)

Hybrid Approaches:

• Combine witness-based and ledger-based discovery
• Use ledgers for high-value identifier discovery
• Maintain witness pools for performance
• Implement fallback discovery mechanisms

Partial Witness Availability: Handle witness threshold scenarios:

• Accept events when TOAD threshold is met
• Queue events when insufficient witnesses respond
• Retry witness queries with timeout
• Consider alternative witnesses if configured

Multi-Signature Coordination

OOBI Exchange Protocol: Establish secure OOBI sharing:

• Use video calls for initial OOBI exchange
• Implement challenge-response authentication
• Verify all participants before multi-sig inception
• Document OOBI exchange in audit logs

Asynchronous Coordination: Handle timing challenges:

• Use mailbox services for asynchronous message delivery
• Implement polling for multi-sig event collection
• Set reasonable timeouts for signature collection
• Provide status visibility for all participants

Production Deployment

Witness Infrastructure: Deploy reliable witness networks:

• Use geographically distributed witnesses
• Implement witness monitoring and alerting
• Maintain witness availability SLAs
• Provide witness discovery through well-known URIs

Watcher Networks: Integrate watcher services:

• Deploy independent watcher infrastructure
• Query multiple watchers for critical operations
• Implement duplicity detection workflows
• Log and investigate all duplicity events

Monitoring and Observability: Track discovery operations:

• Log all OOBI resolutions with timestamps
• Monitor witness response times and availability
• Alert on verification failures and duplicity
• Track discovery success rates and failure modes

Integration Patterns

Web Applications: Use SignifyTS for browser-based discovery:

• Implement OOBI resolution in client-side code
• Use KERIA agents for server-side operations
• Handle CORS restrictions for cross-origin requests
• Cache discovered data in browser storage

Mobile Applications: Optimize for mobile constraints:

• Use QR codes for OOBI sharing
• Implement background discovery tasks
• Optimize battery usage with intelligent polling
• Support offline operation with cached data

Enterprise Systems: Integrate with existing infrastructure:

• Store witness OOBIs in configuration management
• Use service discovery for internal KERI infrastructure
• Implement monitoring and alerting
• Support dynamic witness pool updates

Testing Strategies

Unit Testing: Test discovery components in isolation:

• Mock OOBI resolution responses
• Test verification logic with known KELs
• Validate error handling paths
• Test caching behavior

Integration Testing: Test end-to-end discovery flows:

• Use witness demo for testing
• Test multi-party coordination scenarios
• Validate watcher network integration
• Test failure recovery mechanisms

Security Testing: Validate security properties:

• Test with malformed OOBIs
• Verify rejection of invalid KELs
• Test duplicity detection
• Validate challenge-response authentication