Structural Organization

The receipt-log is organized as a chronologically ordered sequence where:

• Each entry corresponds to a key event receipt signed by a witness
• Receipts are indexed to their corresponding events in the KEL (Key Event Log)
• The ordering preserves the temporal sequence in which witnesses confirmed events
• Multiple receipts may exist for the same key event (one from each witness)

Key Components

A receipt-log contains:

1. Witness Signatures: Digital signatures from witnesses attesting to key events
2. Event References: Cryptographic links to the key events being receipted
3. Sequence Information: Ordering data maintaining temporal consistency
4. Witness Identifiers: AIDs of the witnesses providing receipts

Data Format

Receipt Structure

Each receipt in the log follows the CESR (Composable Event Streaming Representation) encoding format, containing:

Receipt Message Components:

• Version String (v): CESR version identifier
• Event Digest (d): SAID (Self-Addressing Identifier) of the receipted event
• Witness AID (i): Identifier of the witness providing the receipt
• Sequence Number (s): Event sequence number in the KEL
• Signature Attachment: Witness's indexed signature on the event

Encoding Format

Receipt-logs leverage CESR's dual text/binary encoding:

Text Domain: Base64 URL-safe encoding for human readability and debugging Binary Domain: Compact binary representation for efficient streaming and storage Composability: Round-trip conversion between text and binary without crossing primitive boundaries

Size and Constraints

Receipt Size: Variable, depending on:

• Signature algorithm (Ed25519: ~88 bytes, ECDSA: ~96 bytes)
• Number of witnesses (each adds one receipt per event)
• Event complexity (establishment events require more data)

Log Growth: Linear with respect to:

• Number of key events in the KEL
• Size of the witness pool
• For N events and W witnesses: approximately N × W receipts

Storage Optimization: Receipt-logs can be compacted by:

• Storing only receipts for establishment events (inception and rotation)
• Using SAID references instead of full event copies
• Implementing sparse storage for inactive identifiers

Operations

Creation and Initialization

Receipt-Log Genesis:

1. Witness Designation: Controller specifies witness pool in inception event
2. Initial Receipt: First receipt corresponds to inception event validation
3. Threshold Configuration: Controller sets witness threshold (minimum receipts required)

Initialization Process:

1. Controller creates inception event
2. Controller sends event to designated witnesses
3. Each witness validates event cryptographically
4. Witnesses generate signed receipts
5. Receipts are collected into receipt-log
6. Controller verifies threshold is met

Updates and Modifications

Append-Only Property: Receipt-logs are strictly append-only; existing receipts cannot be modified or deleted. This immutability is fundamental to KERI's security model.

Receipt Addition Process:

1. Event Promulgation: Controller sends new key event to witnesses
2. Witness Validation: Each witness independently verifies:
   • Event signature validity
   • Sequence number correctness
   • Hash chain integrity
   • Pre-rotation commitment (for rotation events)
3. Receipt Generation: Witness creates signed receipt message
4. Receipt Storage: Receipt is appended to the receipt-log
5. Threshold Check: System verifies sufficient receipts exist

Witness Rotation: When witnesses are rotated:

• New witnesses begin receipting subsequent events
• Old witness receipts remain in historical log
• Receipt-log reflects witness pool changes over time

Verification and Validation

Receipt Verification Process:

1. Signature Validation: Verify witness signature on receipt using witness's public key
2. Event Matching: Confirm receipt references correct event digest
3. Sequence Consistency: Validate sequence numbers are monotonically increasing
4. Witness Authorization: Verify witness was designated in current or prior establishment event
5. Threshold Satisfaction: Confirm sufficient receipts exist per TOAD (Threshold of Accountable Duplicity)

Duplicity Detection:

Receipt-logs enable duplicity detection through:

1. Cross-Witness Comparison: Compare receipts from different witnesses for the same sequence number
2. Conflict Identification: Detect if witnesses receipted different events at same sequence
3. DEL Construction: Build Duplicitous Event Log documenting conflicts
4. Validator Alert: Signal duplicitous behavior to validators

First-Seen Policy: Witnesses implement first-seen immutability:

• First version of an event witnessed is permanently recorded
• Subsequent conflicting versions are rejected or logged as duplicitous
• This prevents controller from presenting different event versions to different witnesses

Usage Context

In Which Protocols

KERI Protocol Core:

Receipt-logs are integral to KERI's indirect mode operations:

• Witness Infrastructure: Witnesses maintain receipt-logs for all identifiers they witness
• KERL Construction: Key Event Receipt Log combines KEL with receipt-log
• Validator Queries: Validators retrieve receipt-logs to verify key state

ACDC Credential Issuance:

Receipt-logs support ACDC (Authentic Chained Data Container) credential systems:

• Issuer Verification: Validators check issuer AID's receipt-log before accepting credentials
• Revocation Registry: TEL (Transaction Event Log) events are receipted by witnesses
• Chain of Trust: Receipt-logs validate entire delegation chain

vLEI Ecosystem:

In the vLEI (verifiable Legal Entity Identifier) ecosystem:

• QVI Validation: QVI identifiers require robust receipt-logs
• Legal Entity Credentials: Receipt-logs prove issuer authority
• Regulatory Compliance: Auditable receipt-logs demonstrate proper authorization

Lifecycle Management

Active Phase:

• Continuous receipt collection as new events occur
• Real-time threshold monitoring
• Periodic witness health checks

Archival Phase:

• Inactive identifiers may have receipt-logs archived
• Historical receipts remain verifiable
• Sparse storage for long-term retention

Recovery Scenarios:

• Receipt-logs enable key recovery after compromise
• Historical receipts prove legitimate rotation authority
• Pre-rotation commitments verified through receipt-log

Related Structures

Key Event Log (KEL):

• Receipt-log complements KEL by adding witness attestations
• KEL contains events; receipt-log contains witness confirmations
• Together they form the KERL

Key Event Receipt Log (KERL):

• KERL = KEL + receipt-log
• Provides complete verifiable history
• Enables end-verifiable validation

Duplicitous Event Log (DEL):

• Records conflicting receipts detected in receipt-log
• Indexes duplicitous events to KERL
• Maintained by jurors for duplicity detection

Transaction Event Log (TEL):

• TEL events are anchored to KEL through seals
• TEL may have its own receipt-log for registry operations
• Receipt-logs validate TEL state changes

Implementation Considerations

Witness Pool Management

Optimal Pool Size: Balance between:

• Security: Larger pools provide better duplicity detection
• Performance: More witnesses increase receipt collection latency
• Cost: Each witness requires infrastructure resources

Typical configurations:

• Minimum: 3 witnesses (enables 2-of-3 threshold)
• Recommended: 5-7 witnesses for production systems
• High Security: 9+ witnesses for critical identifiers

Threshold Configuration

TOAD Selection:

The threshold M must satisfy: M ≥ N - F

Where:

• N = total number of witnesses
• F = maximum tolerable faulty witnesses
• M = minimum receipts required

Example: With 7 witnesses tolerating 2 faults: M ≥ 5

Storage Architecture

Database Design:

1. Indexed Storage: Receipt-logs indexed by:

   • AID (identifier being witnessed)
   • Sequence number
   • Witness AID
   • Event digest

2. Efficient Retrieval: Support queries for:

   • All receipts for a given event
   • All receipts from a specific witness
   • Receipt-log for an entire identifier

3. Replication: Receipt-logs should be:

   • Replicated across multiple witness nodes
   • Backed up regularly
   • Geographically distributed for resilience

Network Protocols

Receipt Exchange:

• Push Model: Controller sends events to witnesses; witnesses return receipts
• Pull Model: Validators query witnesses for receipt-logs
• Gossip Protocol: Witnesses may exchange receipts for consistency

OOBI Integration:

OOBI (Out-Of-Band Introduction) enables receipt-log discovery:

• Witness endpoints published via OOBI
• Validators discover witnesses through OOBI resolution
• Receipt-logs retrieved via HTTP/TCP endpoints

Performance Optimization

Caching Strategies:

• Cache recent receipts for fast validation
• Implement receipt-log checkpoints for large identifiers
• Use bloom filters for rapid duplicity detection

Parallel Processing:

• Query multiple witnesses concurrently
• Aggregate receipts asynchronously
• Implement timeout handling for slow witnesses

Security Hardening

Witness Compromise Mitigation:

• Threshold configuration prevents single witness compromise
• Watcher networks provide additional validation
• Regular witness rotation reduces long-term exposure

Eclipse Attack Prevention:

• Diverse witness selection across network topology
• Multiple independent witness operators
• Watcher networks provide ambient duplicity detection

Receipt Forgery Prevention:

• Cryptographic signatures prevent receipt forgery
• Witness key management follows best practices
• Regular witness key rotation

Advanced Topics

Receipt-Log Compaction

For long-lived identifiers with extensive histories:

1. Establishment-Only Storage: Store receipts only for establishment events
2. Merkle Tree Compression: Use Merkle trees to compress receipt sequences
3. Checkpoint Snapshots: Create periodic checkpoints of receipt-log state

Multi-Signature Receipts

For multi-sig witness configurations:

• Witnesses may use threshold signatures
• Receipt-log contains aggregated signatures
• Reduces storage overhead for large witness pools

Cross-Chain Receipt Validation

When witnesses use ledger-backed storage:

• Receipts may reference blockchain transactions
• Receipt-log includes ledger proofs
• Enables hybrid KERI/blockchain architectures

Privacy-Preserving Receipts

For confidential identifiers:

• Receipts may use blind signatures
• Receipt-log structure preserved while hiding event details
• Enables private witness attestation

Conclusion

The receipt-log is a cornerstone data structure in KERI's security architecture, enabling distributed validation, duplicity detection, and high availability without requiring centralized infrastructure or blockchain consensus. By maintaining ordered records of witness attestations, receipt-logs provide the cryptographic evidence necessary for validators to establish trust in identifier key states through ambient verifiability. Proper implementation of receipt-log management, including witness pool configuration, threshold selection, and storage optimization, is essential for building robust KERI-based identity systems that can scale from individual use cases to global infrastructure like the vLEI ecosystem.

Duplicity Detection

Implementation Strategy:

• Compare receipts from all witnesses for each sequence number
• Flag any sequence where witnesses receipted different event digests
• Construct DEL (Duplicitous Event Log) for detected conflicts
• Alert validators immediately upon duplicity detection

First-Seen Policy:

• Witnesses must record the first version of an event they observe
• Subsequent conflicting versions should be rejected or logged separately
• Implement timestamp recording for first-seen events

Threshold Management

Dynamic Threshold Adjustment:

• Allow threshold changes through rotation events
• Ensure threshold changes are properly receipted
• Validate that new thresholds satisfy M ≥ N - F constraint

Threshold Verification:

• Always verify threshold is met before accepting key state
• Implement timeout handling if threshold not reached
• Consider partial threshold acceptance for non-critical operations

Testing and Validation

Test Scenarios:

• Test with various witness pool sizes (3, 5, 7, 9 witnesses)
• Simulate witness failures and verify threshold handling
• Test duplicity detection with conflicting receipts
• Verify receipt-log recovery after witness restart
• Test performance under high event throughput

Integration Testing:

• Test receipt-log integration with KEL validation
• Verify KERL construction from KEL + receipt-log
• Test cross-witness consistency checks
• Validate OOBI-based witness discovery

Monitoring and Observability

Key Metrics:

• Receipt collection latency per witness
• Threshold satisfaction rate
• Witness availability and uptime
• Duplicity detection events
• Receipt-log storage growth rate

Alerting:

• Alert on threshold not met within timeout
• Alert on duplicity detection
• Alert on witness unavailability
• Alert on receipt signature validation failures

Compatibility Considerations

KERIpy Compatibility:

• Receipt-logs must use CESR encoding
• Follow KERIpy's LMDB storage patterns
• Implement compatible witness protocol
• Support KERIpy's OOBI resolution

Cross-Implementation Interoperability:

• Ensure receipt format compatibility across KERI implementations (KERIpy, KERIox, etc.)
• Test receipt-log exchange between different implementations
• Validate CESR encoding/decoding consistency

Scalability Considerations

Large-Scale Deployments:

• Implement receipt-log sharding for high-volume identifiers
• Use distributed storage for receipt-logs
• Consider CDN-like distribution for popular identifiers
• Implement caching layers for frequently accessed receipt-logs

Resource Management:

• Monitor storage growth and implement archival strategies
• Implement receipt-log pruning for inactive identifiers
• Use compression for archived receipt-logs
• Consider tiered storage (hot/warm/cold) based on access patterns