Receipt Types and Variants

KERI defines multiple receipt types based on the signing entity:

Non-Transferable Receipts (ntr):

• Signed by non-transferable identifiers (witnesses)
• Cannot perform key rotation
• Prefix starts with 'B' indicating basic derivation
• Used for witness pool validation

Transferable Receipts (vrc):

• Signed by transferable identifiers
• Support key rotation capabilities
• Prefix starts with 'E' indicating self-addressing derivation
• Used for validator and controller cross-validation

Protocol Mechanics

Receipt Generation Workflow

1. Event Reception: Witness receives a key event message from controller
2. Validation: Witness validates event structure, signatures, and sequence
3. Receipt Creation: Witness generates receipt message with own signature
4. Promulgation: Receipt is distributed to other witnesses and validators
5. Storage: Receipt is stored in Key Event Receipt Log (KERL)

Message Flow Sequence

Controller → Event → Witness₁
                  ↓
                Receipt₁ → KERL
                  ↓
                Witness₂ ← Receipt₁
                  ↓
                Receipt₂ → KERL

Cryptographic Foundation

Signature Attachment Format

Receipts use CESR (Composable Event Streaming Representation) for signature attachments:

-AABAA<base64-signature-data>

Signature Components:

• -AAB: Counter code indicating single signature attachment
• AA: Derivation code for Ed25519 signature
• <base64-signature-data>: 88-character Base64 encoded signature

Indexed Signatures for Multi-Key Scenarios

For multi-signature witnesses or validators:

-AACAA<index><base64-signature-data>

Index Encoding:

• Index embedded in signature attachment
• Enables identification of specific signing key
• Supports threshold signature schemes

Implementation Specifications

Receipt Validation Algorithm

def validate_receipt(receipt_msg, event_msg, witness_kel):
    # 1. Verify receipt structure
    if not verify_receipt_structure(receipt_msg):
        raise ValidationError("Invalid receipt structure")
    
    # 2. Verify receipt SAID
    computed_said = compute_said(receipt_msg)
    if computed_said != receipt_msg['d']:
        raise ValidationError("Receipt SAID mismatch")
    
    # 3. Verify witness authority
    witness_keys = get_current_keys(witness_kel, receipt_msg['i'])
    if not verify_signature(receipt_msg, witness_keys):
        raise ValidationError("Invalid witness signature")
    
    # 4. Verify event reference
    if receipt_msg['s'] != event_msg['s']:
        raise ValidationError("Sequence number mismatch")
    
    return True

Storage and Retrieval

KERL Database Schema

CREATE TABLE receipts (
    said TEXT PRIMARY KEY,
    controller_aid TEXT NOT NULL,
    sequence_number INTEGER NOT NULL,
    witness_aid TEXT NOT NULL,
    event_said TEXT NOT NULL,
    receipt_data BLOB NOT NULL,
    signature_data BLOB NOT NULL,
    timestamp INTEGER NOT NULL,
    INDEX idx_controller_seq (controller_aid, sequence_number),
    INDEX idx_witness (witness_aid),
    INDEX idx_event (event_said)
);

Retrieval Optimization

class ReceiptStore:
    def get_receipts_for_event(self, controller_aid, sequence_number):
        """Retrieve all receipts for a specific event"""
        query = """
            SELECT * FROM receipts 
            WHERE controller_aid = ? AND sequence_number = ?
            ORDER BY timestamp ASC
        """
        return self.db.execute(query, (controller_aid, sequence_number))
    
    def get_witness_receipts(self, witness_aid, since_timestamp=None):
        """Retrieve receipts from specific witness"""
        query = "SELECT * FROM receipts WHERE witness_aid = ?"
        params = [witness_aid]
        
        if since_timestamp:
            query += " AND timestamp > ?"
            params.append(since_timestamp)
            
        return self.db.execute(query, params)

Technical Relationships

Integration with Key Event Logs

Receipts form a secondary validation layer for KEL events:

KEL Event → Receipt Generation → KERL Storage → Duplicity Detection
    ↓              ↓                  ↓              ↓
  Primary      Secondary          Persistent     Security
 Validation   Validation          Storage       Mechanism

Witness Pool Coordination

Receipts enable witness pool consensus through KAWA (KERI's Algorithm for Witness Agreement):

1. Threshold Calculation: TOAD = ceil(2/3 * witness_count)
2. Receipt Collection: Gather receipts from witness pool
3. Consensus Determination: Verify threshold met for event acceptance
4. Duplicity Detection: Compare receipt consistency across witnesses

Transaction Event Log Integration

For ACDC credentials, receipts validate TEL (Transaction Event Log) events:

{
  "v": "KERI10JSON",
  "t": "rct",
  "d": "EtelReceiptSAID",
  "i": "EcredentialIssuerAID",
  "s": "1",
  "receipts": [
    {
      "i": "EregistrarAID",
      "s": "1",
      "d": "EtelEventSAID"
    }
  ]
}

Performance Analysis

Computational Complexity

Receipt Generation:

• Time Complexity: O(1) for single signature, O(k) for k-signature threshold
• Space Complexity: O(1) per receipt message
• Signature Verification: O(1) per Ed25519 signature (~64μs)

Receipt Validation:

• Time Complexity: O(n) where n = number of receipts to validate
• Database Lookup: O(log n) with proper indexing
• Batch Validation: O(n) with vectorized operations

Network Overhead

Receipt Message Size:

• Base receipt: ~200 bytes (JSON)
• Single signature: +88 bytes (Base64 encoded)
• Multi-signature: +88 bytes per additional signature
• CESR binary encoding: ~25% size reduction

Network Patterns:

• Witness-to-witness propagation: O(w²) where w = witness count
• Controller-to-witness: O(w) per event
• Validator queries: O(1) per receipt lookup

Storage Requirements

KERL Growth Rate:

• Per event: ~300 bytes base + (88 bytes × witness_count)
• Daily volume (1000 events, 5 witnesses): ~734 KB
• Annual storage (enterprise): ~268 MB

Edge Cases & Error Handling

Failure Modes

Partial Receipt Collection:

def handle_partial_receipts(event, receipts, threshold):
    if len(receipts) < threshold:
        # Insufficient receipts - event remains in escrow
        return EventStatus.ESCROWED
    elif len(receipts) >= threshold:
        # Sufficient receipts - event accepted
        return EventStatus.ACCEPTED

Receipt Duplicity:

def detect_receipt_duplicity(receipts):
    witness_receipts = {}
    duplicitous_witnesses = set()
    
    for receipt in receipts:
        witness_aid = receipt['receipts'][0]['i']
        event_said = receipt['receipts'][0]['d']
        
        if witness_aid in witness_receipts:
            if witness_receipts[witness_aid] != event_said:
                duplicitous_witnesses.add(witness_aid)
        else:
            witness_receipts[witness_aid] = event_said
    
    return duplicitous_witnesses

Race Conditions

Concurrent Receipt Processing:

• Use database transactions for atomic receipt storage
• Implement optimistic locking for KERL updates
• Handle witness signature timing variations

Network Partition Handling:

• Implement receipt caching during network splits
• Use exponential backoff for receipt retransmission
• Maintain receipt ordering despite delivery delays

Standards & Specifications

IETF Draft Compliance

Receipts conform to the IETF KERI specification (draft-ssmith-keri):

• Section 7.2: Receipt Message Structure
• Section 11.4: Witness Agreement Algorithm
• Appendix B: Receipt Attachment Formats

CESR Encoding Standards

Receipts use CESR for all cryptographic primitives:

• Counter codes for signature attachments
• Qualified Base64 encoding for binary data
• Round-trip text-binary composability

Version Compatibility

KERI Protocol Versions:

• v1.0: Basic receipt functionality
• v1.1: Indexed signature support
• v1.2: TEL receipt integration
• v2.0: Enhanced duplicity detection

Production Considerations

Deployment Architectures

Witness Pool Deployment:

witness_pool:
  replicas: 5
  threshold: 3
  geographic_distribution: true
  load_balancer:
    algorithm: round_robin
    health_checks: enabled

Receipt Storage Scaling:

• Horizontal partitioning by controller AID
• Read replicas for receipt queries
• Archive old receipts to cold storage

Monitoring and Observability

Key Metrics:

• Receipt generation rate (receipts/second)
• Receipt validation latency (p95, p99)
• Witness availability percentage
• Duplicity detection events

Alerting Thresholds:

• Receipt threshold not met: Critical
• Witness unavailability > 10 minutes: Warning
• Duplicity detected: Critical
• Receipt validation errors > 1%: Warning

Operational Procedures

Receipt Audit Process:

1. Daily receipt count verification
2. Witness signature validation checks
3. KERL consistency verification
4. Duplicity detection log review

Disaster Recovery:

• KERL backup and restoration procedures
• Witness pool failover mechanisms
• Receipt replay from archived logs
• Cross-region receipt synchronization

Testing Strategies

Unit Testing:

• Test receipt generation with various event types
• Verify signature attachment formats
• Test SAID computation consistency
• Validate error handling for malformed receipts

Integration Testing:

• Test witness pool receipt coordination
• Verify KERL storage and retrieval
• Test receipt-based duplicity detection
• Validate threshold-based event acceptance

Performance Testing:

• Benchmark receipt generation rates
• Test signature verification throughput
• Measure KERL query performance
• Load test witness pool coordination

Security Testing:

• Test receipt forgery detection
• Verify signature validation edge cases
• Test duplicity detection accuracy
• Validate witness authority checks