Data Format

Message Structure

Receipts follow KERI's standard message format using CESR (Composable Event Streaming Representation) encoding. The structure includes:

Receipt Message Body (JSON serialization example):

{
  "v": "KERI10JSON0000ed_",
  "t": "rct",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
  "s": "3"
}

Field Definitions:

• v: Version string indicating KERI protocol version and serialization format
• t: Message type, always "rct" for receipts (or "vrc" for validator receipts)
• d: Digest (SAID) of the event being receipted
• i: Identifier of the controller whose event is being receipted
• s: Sequence number of the event (hexadecimal encoding for values >9)

Signature Attachments: Following the message body, receipts include CESR-encoded signature attachments:

-AAB
AA<base64-signature-from-witness-1>
AB<base64-signature-from-witness-2>

The -AAB prefix is a CESR count code indicating the attachment type and count.

Encoding Format

Receipts use CESR's dual text-binary encoding:

• Text Domain: Base64 URL-safe encoding for human readability and debugging
• Binary Domain: Compact binary representation for efficient transmission
• Composability: Round-trip conversion between domains preserves all information

Size and Constraints

• Fixed-size components: Version strings, type codes, and identifiers have deterministic lengths based on their CESR derivation codes
• Variable-size components: Signature attachments scale with the number of witnesses
• Sequence numbers: Use hexadecimal encoding (0-9, a-f, 10-ff, etc.) for compact representation

Operations

Creation and Initialization

Witness Receipt Generation:

1. Event Reception: Witness receives a key event message from the controller
2. Validation: Witness verifies:
   • Cryptographic signatures on the event
   • Event sequence integrity (proper chaining via prior event digest)
   • Compliance with the controller's current key state
3. Receipt Construction: Witness creates receipt message referencing the validated event
4. Signing: Witness signs the receipt with its own private key
5. Promulgation: Witness broadcasts the receipt to other witnesses and stores it in the KERL (Key Event Receipt Log)

Controller Receipt Collection:

Controllers collect receipts from their designated witness pool to achieve the threshold of accountable duplicity (TOAD). Once sufficient receipts are gathered, the event is considered "established" within the witness network.

Updates and Modifications

Receipts are immutable once created. They represent a specific witness's observation of a specific event at a specific point in time. However, the collection of receipts for an event can grow:

• Additional Witnesses: New witnesses can add their receipts to an event
• Receipt Aggregation: Multiple receipts for the same event are collected and stored together
• First-Seen Policy: The first receipt from each witness is authoritative; subsequent conflicting receipts indicate duplicity

Verification and Validation

Receipt Verification Process:

1. Extract Event Reference: Parse the receipt body to obtain (i, s, d) tuple
2. Locate Referenced Event: Retrieve the key event from the KEL using the identifier and sequence number
3. Verify Event Digest: Confirm the digest in the receipt matches the actual event's SAID
4. Validate Witness Signatures: For each attached signature:
   • Identify the witness using the signature index or witness list
   • Retrieve the witness's public key from its own KEL
   • Verify the cryptographic signature
5. Check Witness Authorization: Confirm the signing witnesses are in the controller's designated witness pool for that event

Duplicity Detection:

When validators receive multiple receipts from the same witness for events at the same sequence number but with different digests, this indicates duplicitous behavior by either the controller or the witness. This is a critical security event that triggers duplicity detection protocols.

Usage Context

In Which Protocols

KERI Indirect Mode:

Receipts are fundamental to KERI's indirect mode operation, where controllers designate witnesses to provide high availability and distributed consensus. The receipt mechanism enables:

• Witness Pools: Controllers configure a set of witnesses with a threshold (e.g., "2 of 3 witnesses must receipt")
• KAACE Consensus: Witnesses use receipts to reach agreement on key events
• Validator Verification: Validators can verify events by checking witness receipts rather than requiring direct controller interaction

Direct Mode Receipts:

Even in direct mode, where controllers exchange events peer-to-peer, receipts serve as acknowledgments. The receiving controller acts as a validator and may generate receipts to confirm event observation.

Transaction Event Logs (TELs):

Receipts also apply to TEL events for credential issuance and revocation, where registrars (analogous to witnesses) receipt transaction events.

Lifecycle Management

Receipt Storage:

• KERL Construction: Receipts are stored alongside their corresponding key events to form the Key Event Receipt Log
• Witness Databases: Each witness maintains its own database of receipts it has issued
• Controller Databases: Controllers collect and store receipts from their witness pool
• Validator Caches: Validators may cache receipts for frequently verified identifiers

Receipt Retrieval:

Validators query witnesses for receipts using KERI's query protocol:

{
  "v": "KERI10JSON000091_",
  "t": "qry",
  "d": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
  "dt": "2024-01-15T10:30:00.000000+00:00",
  "r": "logs",
  "rr": "",
  "q": {
    "i": "EH7Oq9oxCgYa-nnNLvwhp9sFZpALILlRYyB-6n4WDi7w",
    "s": "5"
  }
}

Witnesses respond with the requested event and all associated receipts.

Related Structures

Key Event Logs (KELs):

Receipts are intimately connected to KELs. A KEL without receipts is just a sequence of self-signed events. Adding receipts transforms it into a KERL, providing distributed validation.

Key Event Messages:

Receipts reference key event messages. The relationship is:

• Key Event Message = Event Body + Controller Signatures
• Receipt = Event Reference + Witness Signatures

Witness Lists:

Each establishment event (inception or rotation) specifies a witness list. Receipts must come from witnesses in this list to be valid for that event.

Duplicity Event Logs (DELs):

When receipts reveal duplicity (multiple receipts from the same witness for conflicting events), this information is recorded in a DEL for that identifier.

Advanced Receipt Concepts

Indexed Signatures

When receipting events from multi-sig AIDs, receipts may use indexed signatures to indicate which specific witness provided the receipt. This is particularly important when witness pools contain multiple witnesses.

Receipt Escrow

KERI implementations maintain escrow databases for receipts that arrive before their corresponding events (due to network asynchrony). These receipts are held until the referenced event arrives, then processed.

Receipt Chaining

While individual receipts don't chain to each other, the collection of receipts for sequential events creates an implicit chain of witness observations, providing a verifiable history of witness participation.

Transferable vs Non-Transferable Receipts

Receipts themselves are not transferable—they represent a specific witness's observation at a specific time. However, they receipt both transferable and non-transferable identifiers.

Security Properties

Cryptographic Guarantees

Receipts provide:

• Non-repudiation: Witnesses cannot deny having issued a receipt due to digital signatures
• Integrity: Any tampering with the receipt body invalidates the signature
• Authenticity: Signatures prove the receipt came from the claimed witness
• Binding: The receipt is cryptographically bound to a specific event via its digest

Attack Resistance

Replay Attacks: Receipts include sequence numbers and event digests, preventing replay of old receipts for new events.

Forgery: Without access to a witness's private key, attackers cannot forge valid receipts.

Duplicity: The receipt mechanism itself enables duplicity detection—conflicting receipts from the same witness expose malicious behavior.

Implementation Considerations

Performance Optimization

• Batch Processing: Implementations can batch receipt generation for multiple events
• Parallel Verification: Receipt signatures can be verified in parallel
• Caching: Frequently accessed receipts can be cached to reduce database queries

Network Efficiency

• Receipt Aggregation: Multiple receipts can be transmitted together in a single message
• Selective Transmission: Only receipts meeting the threshold need to be transmitted to validators
• Compression: CESR's binary encoding provides compact representation for network transmission

Database Design

• Indexing: Receipts should be indexed by (identifier, sequence number) for efficient retrieval
• Partitioning: Large-scale implementations may partition receipt storage by identifier prefix
• Archival: Old receipts for superseded key states can be archived while maintaining availability

Database Schema Example

CREATE TABLE receipts (
    id SERIAL PRIMARY KEY,
    event_identifier TEXT NOT NULL,
    event_sequence INTEGER NOT NULL,
    event_digest TEXT NOT NULL,
    witness_aid TEXT NOT NULL,
    signature BYTEA NOT NULL,
    received_at TIMESTAMP DEFAULT NOW(),
    INDEX idx_event (event_identifier, event_sequence),
    INDEX idx_witness (witness_aid),
    UNIQUE (event_identifier, event_sequence, witness_aid)
);

Testing Strategies

Unit Tests: Test receipt generation, verification, and storage independently

Integration Tests: Test receipt exchange between witnesses in a simulated network

Duplicity Tests: Verify that conflicting receipts are properly detected and logged

Performance Tests: Measure receipt processing throughput under load