Comprehensive Explanation

key-event-receipt

Structure Definition

A key event receipt is a fundamental data structure in the KERI (Key Event Receipt Infrastructure) protocol that serves as cryptographic evidence that one or more witnesses have received, verified, and attested to a specific key event. Unlike the key event itself, which represents a state change in an AID's control authority, a key event receipt is a separate message that provides independent verification of that event's existence and validity.

Core Components

The key event receipt consists of two mandatory components:

1. Body: A reference structure that identifies the key event being receipted. Rather than duplicating the entire key event, the body contains identifying information that uniquely points to the event, typically including:

   • The AID (Autonomic Identifier) of the event being receipted
   • The sequence number of the event
   • The SAID (Self-Addressing Identifier) digest of the event

2. Attachments: One or more cryptographic signatures from witnesses. The specification uses "MUST" to indicate this is a protocol-level requirement - a key event receipt without witness signatures is invalid. Each signature attachment:

   • Is created by a witness using its own private key
   • Attests to the witness's observation and validation of the referenced event
   • Is encoded using CESR (Composable Event Streaming Representation)

Structural Separation

The key event receipt deliberately separates the reference (body) from the attestation (signatures). This design provides several advantages:

• Compactness: The receipt doesn't duplicate the potentially large key event data
• Efficiency: Multiple witnesses can provide receipts for the same event without redundant data transmission
• Composability: Receipts can be aggregated and transmitted separately from the events they reference
• Verification independence: Validators can verify receipts against locally stored events

Data Format

Message Structure

Key event receipts follow KERI's standard message format using CESR encoding. The structure typically appears as:

{Event Reference Body}
{CESR-encoded Signature Attachments}

Body Format

The body of a key event receipt is a structured message that references the target event. Based on the source documents, the body includes:

• Version string (v): Indicates the KERI protocol version (e.g., KERI10JSON)
• Event type (t): Typically rct (receipt) or vrc (verifiable credential receipt)
• Identifier (i): The AID of the witness providing the receipt
• Sequence number (s): The witness's own sequence number
• Anchor section (a): Contains references to the receipted event:
  • Target identifier (i): The AID whose event is being receipted
  • Target sequence (s): The sequence number of the receipted event
  • Target digest (d): The SAID of the receipted event

Signature Attachments

Signature attachments use CESR encoding with specific framing codes:

• Count codes: Indicate the number and type of signatures (e.g., -CAB for witness receipts)
• Indexed signatures: When multiple witnesses provide receipts, each signature is indexed to identify which witness created it
• Base64 encoding: Signatures are encoded in CESR's text domain for human readability and debugging

Encoding Variants

Key event receipts support multiple serialization formats:

• JSON: Human-readable format using KERI10JSON version string
• CBOR: Binary format for efficient transmission
• MGPK: MessagePack format for compact binary representation

All formats maintain the same logical structure and can be converted between domains using CESR's composability properties.

Operations

Creation and Initialization

The creation of a key event receipt follows a specific workflow:

1. Event Reception: A witness receives a key event message from a controller or another witness
2. Event Verification: The witness validates:
   • Cryptographic signatures on the event
   • Sequence number consistency
   • Hash chain integrity (previous event digest)
   • Pre-rotation commitments (next key digests)
3. Receipt Generation: If validation succeeds, the witness:
   • Creates a receipt body referencing the event
   • Signs the receipt body with its own private key
   • Attaches the signature using CESR encoding
4. Receipt Transmission: The witness sends the receipt to:
   • The controller who created the event
   • Other witnesses in the witness pool
   • Validators who request the receipt

Receipt Aggregation

Multiple witnesses can provide receipts for the same event. These receipts can be:

• Collected individually: Each receipt transmitted separately
• Aggregated: Multiple witness signatures attached to a single receipt body
• Bundled: Receipts for multiple events transmitted together

The aggregation process maintains the independence of each witness's attestation while enabling efficient transmission.

Verification and Validation

Validators verify key event receipts through a multi-step process:

1. Receipt Structure Validation:

   • Verify CESR encoding is well-formed
   • Confirm required fields are present
   • Check version string compatibility

2. Event Reference Resolution:

   • Locate the referenced key event in the KEL
   • Verify the event digest matches the receipt's reference
   • Confirm sequence numbers align

3. Witness Signature Verification:

   • Identify the witness from the receipt's identifier field
   • Retrieve the witness's current public key from its KEL
   • Verify the signature using the witness's public key
   • Confirm the witness was designated by the controller at the time of the event

4. Threshold Validation:

   • Count valid witness receipts for the event
   • Compare against the controller's witness threshold (TOAD)
   • Determine if sufficient witnesses have receipted the event

Receipt Storage

Key event receipts are stored in KERLs (Key Event Receipt Logs), which combine:

• The KEL (Key Event Log) containing the events themselves
• All consistent key event receipt messages from witnesses

This combined structure enables validators to verify both the events and their witness attestations as a unified verifiable data structure.

Usage Context

Role in KERI Protocol

Key event receipts serve multiple critical functions in KERI:

1. Distributed Consensus: Receipts enable witnesses to reach agreement on key events without requiring a shared ledger or blockchain. The KAACE (KERI's Agreement Algorithm for Control Establishment) uses receipts to achieve Byzantine fault-tolerant consensus.

2. Duplicity Detection: When a controller creates conflicting versions of an event (duplicity), witnesses will receipt different versions. Comparing receipts from multiple witnesses reveals this duplicity, as witnesses will have signed different event digests.

3. Availability: Receipts enable indirect mode operation where validators can verify events even when the controller is offline. Witnesses maintain receipted events and can provide them to validators on demand.

4. Accountability: The TOAD mechanism uses receipts to establish accountability. When M witnesses receipt an event, the controller accepts accountability for that event, even if some witnesses are faulty.

Lifecycle Management

Key event receipts follow a specific lifecycle:

1. Generation: Created immediately after a witness validates an event
2. Promulgation: Distributed to other witnesses and stored in the witness's database
3. Collection: Gathered by validators who need to verify the event
4. Archival: Stored permanently in KERLs as part of the verifiable history
5. Verification: Used repeatedly by validators to confirm event validity

Receipts are never deleted or modified - they form part of the immutable audit trail for an identifier's history.

Integration with Other Structures

Key event receipts interact with several other KERI data structures:

• KEL (Key Event Log): Receipts reference events in the KEL and are combined with the KEL to form a KERL
• KERL (Key Event Receipt Log): The combined structure of KEL + receipts that provides the complete verifiable history
• Witness Pools: Collections of witnesses that generate receipts according to the controller's configuration
• OOBI (Out-Of-Band Introduction): Used to discover witnesses and retrieve their receipts
• TEL (Transaction Event Log): Credential registries that use receipts to anchor credential state changes

Operational Modes

Key event receipts enable different operational modes in KERI:

• Direct Mode: Controllers exchange events directly without witnesses. Receipts are not used in pure direct mode, though controllers may still receipt each other's events.
• Indirect Mode: Witnesses receipt events and provide them to validators. This is the primary use case for key event receipts.
• Hybrid Mode: Some events are witnessed while others are exchanged directly, allowing flexible security/performance trade-offs.

Security Properties

Key event receipts provide several security guarantees:

1. Non-repudiation: A witness cannot deny having receipted an event, as the receipt contains its cryptographic signature
2. Tamper-evidence: Any modification to a receipted event is detectable because the receipt's event digest will no longer match
3. Duplicity evidence: Conflicting receipts from the same witness for different versions of an event prove duplicitous behavior
4. Threshold security: The TOAD mechanism ensures that compromising fewer than M witnesses cannot prevent event validation

Performance Considerations

Key event receipts impact system performance in several ways:

• Network overhead: Each witness generates and transmits a receipt, multiplying network traffic by the number of witnesses
• Storage requirements: KERLs are larger than KELs due to receipt storage
• Verification cost: Validators must verify multiple witness signatures for each event
• Latency: Event finality depends on collecting sufficient receipts, which requires network round-trips

These costs are offset by the security benefits of distributed consensus and duplicity detection.

Implementation Patterns

Witness Receipt Generation

Witnesses implement receipt generation as an asynchronous process:

1. Event arrives via HTTP POST or TCP stream
2. Event is queued for validation
3. Validation occurs in background thread
4. Receipt is generated and signed
5. Receipt is stored in local database
6. Receipt is transmitted to configured endpoints

This asynchronous pattern prevents blocking on cryptographic operations and enables high throughput.

Receipt Collection Strategies

Validators can collect receipts using different strategies:

• Eager collection: Request receipts immediately after receiving an event
• Lazy collection: Defer receipt collection until validation is needed
• Batch collection: Request receipts for multiple events simultaneously
• Subscription: Subscribe to witness receipt streams for continuous updates

The choice depends on latency requirements, network conditions, and validation frequency.

Receipt Verification Optimization

Implementations optimize receipt verification through:

• Signature caching: Cache verified signatures to avoid redundant cryptographic operations
• Batch verification: Verify multiple signatures simultaneously using batch verification algorithms
• Parallel verification: Verify receipts from different witnesses in parallel threads
• Incremental verification: Verify receipts as they arrive rather than waiting for all receipts

These optimizations significantly improve validation performance in high-throughput scenarios.

Error Handling

Implementations must handle various error conditions:

• Missing receipts: Some witnesses may not provide receipts due to network failures or malicious behavior
• Invalid receipts: Receipts with invalid signatures or incorrect references must be rejected
• Conflicting receipts: Receipts for different versions of the same event indicate duplicity
• Threshold failures: Insufficient receipts prevent event validation

Robust error handling ensures the system degrades gracefully under adverse conditions.