Comprehensive Explanation

receipt-log

Structure Definition

A receipt-log is a fundamental data structure in the KERI (Key Event Receipt Infrastructure) protocol that maintains an ordered sequence of key event receipts from a designated set of witnesses. The receipt-log serves as cryptographic proof that witnesses have observed, verified, and attested to specific key events in an AID's (Autonomic Identifier) history.

Purpose and Role

The receipt-log fulfills several critical functions in KERI's security architecture:

1. Distributed Validation: Provides independent verification of key events through witness attestations, enabling duplicity detection without requiring a centralized authority or blockchain.

2. Availability Guarantee: Ensures that key event history remains accessible even when the identifier's controller is offline, supporting indirect mode operations.

3. Consensus Evidence: Documents witness agreement on key events, forming the basis for KAACE (KERI's Agreement Algorithm for Control Establishment) consensus.

4. Duplicity Detection: Enables validators to detect conflicting versions of key event histories by comparing receipt-logs from multiple witnesses, implementing ambient verifiability.

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.