Registry Layer: The issuance event references a management TEL that tracks the registry infrastructure (registrars/backers) supporting the credential ecosystem.

ACDC Layer: The issuance event is associated with a specific ACDC credential structure containing the actual claims and attributes.

Key Components

An issuance event contains several critical components that work together to establish credential provenance:

Event Identifier: A unique identifier for the issuance event itself, typically a SAID (Self-Addressing Identifier) that cryptographically commits to the event's content.

Credential SAID: The SAID of the ACDC credential being issued, creating an immutable binding between the event and the credential content.

Issuer AID: The Autonomic Identifier of the credential issuer, establishing who has authority to issue this credential.

Registry Identifier: Reference to the management TEL that governs the registry infrastructure for this credential type.

Sequence Number: Position in the credential's TEL, which for an issuance event is always the first entry (sequence 0 or 1 depending on implementation).

Timestamp: ISO 8601 formatted datetime indicating when the credential was issued.

Anchoring Seal: Cryptographic commitment linking this TEL event to a specific event in the issuer's KEL.

Data Format

Field Definitions

The issuance event follows the standard KERI event message format with specific fields for credential lifecycle management:

Version String (v): Specifies the protocol version and serialization format (JSON, CBOR, or MGPK). Example: KERI10JSON00011c_ indicates KERI version 1.0, JSON serialization, with size information.

Event Type (t): Identifies this as an issuance event. In TEL terminology, this is typically iss (issue) or bis (backed issue for registry-backed credentials).

Event SAID (d): Self-addressing identifier of the event itself, computed as a cryptographic digest of the event content.

Issuer AID (i): The prefix (AID) of the credential issuer, which must match the controller of the KEL to which this event is anchored.

Sequence Number (s): The position of this event in the credential's TEL. For issuance events, this is the initial sequence number.

Credential SAID (ri): Reference to the credential registry identifier or the credential SAID itself, depending on implementation.

Timestamp (dt): ISO 8601 formatted datetime of issuance.

Anchoring Information: Seal data linking to the KEL event that commits to this issuance.

Encoding Format

Issuance events support multiple serialization formats through CESR (Composable Event Streaming Representation):

JSON Serialization: Human-readable format using UTF-8 encoding with insertion-ordered field maps. Fields must maintain canonical ordering for SAID computation.

CBOR Serialization: Binary format (RFC 8949) providing compact representation while maintaining field ordering requirements.

MessagePack (MGPK) Serialization: Alternative binary format offering similar compactness to CBOR.

CESR Encoding: All cryptographic primitives (SAIDs, signatures, digests) are encoded using CESR, which provides dual text-binary composability. This enables seamless conversion between text and binary domains while maintaining cryptographic integrity.

The encoding must preserve:

• Field ordering: Insertion order must be maintained for SAID computation
• Cryptographic binding: All SAIDs must verify against their content
• Signature attachments: Digital signatures are attached as CESR-encoded primitives

Size and Constraints

Minimum Size: An issuance event must contain at minimum the required fields (v, t, d, i, s, ri, dt), resulting in approximately 200-300 bytes in JSON format or 150-200 bytes in binary formats.

Maximum Size: No hard maximum, but practical limits are imposed by:

• Network transmission constraints (typically under 64KB for efficient routing)
• Database storage considerations
• Witness and watcher processing capabilities

SAID Constraints: All SAIDs must use cryptographic digest algorithms with approximately 128 bits of cryptographic strength (e.g., Blake3-256, SHA3-256).

Timestamp Constraints: Must be in ISO 8601 format with timezone information. While not strictly enforced for ordering (TEL sequence numbers provide ordering), timestamps should be monotonically increasing for operational consistency.

Sequence Number Constraints: Must be a non-negative integer. For issuance events, this is typically 0 or 1 depending on whether the registry inception is counted separately.

Operations

Creation and Initialization

Creating an issuance event involves a multi-step process that coordinates between the issuer's KEL, the credential TEL, and the ACDC structure:

Step 1: ACDC Construction

The issuer first constructs the ACDC credential with all required fields:

• Issuer AID (i)
• Schema reference (s)
• Attributes section (a)
• Optional edges (e) and rules (r)
• Compute the credential's SAID (d)

Step 2: Registry Selection

The issuer identifies or creates a credential registry:

• Reference an existing management TEL for the credential type
• Ensure registrars (backers) are configured and available
• Obtain the registry identifier

Step 3: Issuance Event Construction

Construct the issuance event with:

{
  "v": "KERI10JSON00011c_",
  "t": "iss",
  "d": "",
  "i": "<issuer-AID>",
  "s": "0",
  "ri": "<registry-identifier>",
  "dt": "2024-01-15T10:30:00.000000+00:00"
}

Step 4: SAID Computation

Compute the event's SAID:

• Serialize the event with the d field set to placeholder characters (#)
• Compute the cryptographic digest
• Replace the placeholder with the computed SAID

Step 5: KEL Anchoring

Create an anchoring seal in the issuer's KEL:

• Generate an interaction event (ixn) or rotation event (rot) in the issuer's KEL
• Include a seal referencing the issuance event's SAID
• Sign the KEL event with the issuer's current authoritative keys

Step 6: Witness Receipting

Distribute the KEL event to witnesses:

• Send the signed KEL event to the issuer's designated witnesses
• Collect witness receipts (signatures) confirming observation
• Achieve threshold consensus (TOAD - Threshold of Accountable Duplicity)

Step 7: TEL Publication

Publish the issuance event to registrars:

• Send the issuance event to the credential registry's registrars
• Registrars store the event and make it available for verification
• The credential is now officially issued and verifiable

Updates and Modifications

Issuance events themselves are immutable once created and anchored. However, the credential lifecycle can be modified through subsequent TEL events:

Revocation Events: A separate revocation event (rev or brv for backed revocation) can be added to the credential's TEL to mark the credential as revoked. This does not modify the issuance event but adds a new event to the TEL sequence.

Status Updates: Additional TEL events can track credential status changes without altering the original issuance event.

Registry Updates: The management TEL can be updated to change registrars or registry configuration, but this does not affect individual issuance events.

The immutability of issuance events is critical for:

• Audit trails: Complete history of credential issuance is preserved
• Non-repudiation: Issuers cannot deny having issued a credential
• Cryptographic integrity: SAIDs remain valid throughout the credential lifecycle

Verification and Validation

Verifying an issuance event requires checking multiple layers of cryptographic commitments:

Step 1: Event Structure Validation

Validate the event structure:

• Verify all required fields are present
• Check field types match expected formats
• Validate timestamp format (ISO 8601)
• Ensure sequence number is appropriate for an issuance event

Step 2: SAID Verification

Verify the event's SAID:

• Recompute the SAID by serializing the event with d field as placeholder
• Compare computed SAID with the d field value
• Mismatch indicates tampering or corruption

Step 3: KEL Anchoring Verification

Verify the KEL anchor:

• Retrieve the issuer's KEL
• Locate the KEL event containing the seal for this issuance event
• Verify the seal's SAID matches the issuance event's SAID
• Verify the KEL event is properly signed by the issuer's authoritative keys
• Verify witness receipts meet the TOAD threshold

Step 4: Registry Verification

Verify registry infrastructure:

• Retrieve the management TEL referenced by the registry identifier
• Verify the management TEL is properly anchored to the issuer's KEL
• Verify registrars are properly configured and available

Step 5: ACDC Verification

Verify the associated ACDC:

• Retrieve the ACDC credential using its SAID
• Verify the ACDC's SAID matches the credential reference
• Verify the ACDC's issuer AID matches the issuance event's issuer
• Verify the ACDC's schema and structure
• Verify any chained credentials (edges) if present

Step 6: Temporal Validation

Check temporal constraints:

• Verify the issuance timestamp is reasonable (not in the future)
• Check if the credential has been revoked by examining subsequent TEL events
• Verify the issuer's keys were valid at the time of issuance

Usage Context

In Which Protocols

Issuance events are used across multiple KERI-related protocols:

ACDC Protocol: Issuance events are the primary mechanism for bringing ACDC credentials into existence. Every ACDC credential lifecycle begins with an issuance event.

IPEX Protocol: The Issuance and Presentation Exchange protocol uses issuance events as part of credential issuance workflows. When an issuer grants a credential to a holder, the issuance event is created and the credential is transmitted.

TEL Protocol: Issuance events are the foundational event type in Transaction Event Logs, analogous to inception events in KELs.

vLEI Ecosystem: In GLEIF's verifiable LEI implementation, issuance events track the creation of:

• QVI (Qualified vLEI Issuer) credentials
• Legal Entity vLEI credentials
• OOR (Official Organizational Role) credentials
• ECR (Engagement Context Role) credentials
• Authorization credentials (QVI AUTH)

Lifecycle Management

The issuance event marks the beginning of a credential's lifecycle, which typically follows this progression:

Phase 1: Pre-Issuance

• Issuer and holder establish connection via OOBI
• Holder may request credential (solicited issuance)
• Issuer performs identity verification and authorization checks
• Issuer constructs ACDC with appropriate claims

Phase 2: Issuance (Issuance Event Creation)

• Issuance event is created and anchored to issuer's KEL
• Credential TEL is initialized with the issuance event
• Witnesses receipt the anchoring KEL event
• Registrars store the issuance event

Phase 3: Presentation

• Holder presents credential to verifiers
• Verifiers check issuance event validity
• Verifiers verify KEL anchoring and witness receipts
• Verifiers check for revocation events in the TEL

Phase 4: Revocation (Optional)

• Issuer creates revocation event in the credential's TEL
• Revocation event is anchored to issuer's KEL
• Registrars update credential status
• Subsequent verifications detect the revoked status

Phase 5: Expiration (Optional)

• Credentials may have expiration timestamps in their attributes
• No explicit expiration event is required
• Verifiers check expiration during verification

Related Structures

Issuance events interact with several related KERI data structures:

Key Event Log (KEL): The issuer's KEL provides the root of trust for the issuance event. The KEL contains the anchoring seal that cryptographically commits to the issuance event.

Transaction Event Log (TEL): The credential's TEL contains the issuance event as its first entry, followed by any subsequent status events (revocations, updates).

Management TEL: A higher-level TEL that tracks the registry infrastructure (registrars) supporting a set of credentials. The issuance event references the management TEL via the registry identifier.

ACDC Credential: The actual credential data structure containing claims and attributes. The issuance event references the ACDC via its SAID.

Event Source Seals: Cryptographic commitments in KEL events that anchor TEL events. The seal contains the sequence number and SAID of the TEL event.

Witness Receipts: Signatures from witnesses confirming observation of the KEL event that anchors the issuance event. These receipts are stored in the KERL (Key Event Receipt Log).

Registrar Infrastructure: Backers that store and serve TEL events, analogous to witnesses for KELs. Registrars make issuance events available for verification.

IPEX Messages: Protocol messages that carry issuance events during credential exchange workflows. IPEX grant messages contain the credential and reference the issuance event.

Integration with vLEI Ecosystem

In the GLEIF vLEI ecosystem, issuance events play a critical role in establishing verifiable organizational identity:

QVI Credential Issuance: GLEIF issues QVI credentials to qualified organizations, with each issuance creating an issuance event anchored to GLEIF's root KEL.

Legal Entity Credential Issuance: QVIs issue Legal Entity credentials to organizations with LEIs, creating issuance events anchored to the QVI's KEL.

Role Credential Issuance: Legal Entities or QVIs issue OOR and ECR credentials to individuals, with issuance events establishing the credential lifecycle.

Authorization Credential Issuance: Legal Entities issue authorization credentials to QVIs, enabling solicited issuance of role credentials.

Credential Chaining: Issuance events enable verification of credential chains through ACDC edges, where child credentials reference parent credentials via SAIDs.

Performance and Scalability Considerations

Witness Coordination: Issuance events require witness consensus on the anchoring KEL event, which introduces latency (typically seconds to minutes depending on witness configuration).

Registrar Availability: Verifiers must be able to access registrars to retrieve issuance events, requiring robust registrar infrastructure.

Caching Strategies: Verifiers can cache issuance events and their verification results to reduce repeated verification overhead.

Batch Issuance: Multiple credentials can be issued in a single KEL event by including multiple seals, improving efficiency for bulk issuance scenarios.

Revocation Checking: Verifiers must check for revocation events in the TEL, which requires accessing registrars. Blinded revocation registries can provide privacy while maintaining verifiability.

Replay Protection: In IPEX workflows, implement KRAM (KERI Request Authentication Mechanism) to protect against replay attacks using timestamp-based windows.

Error Handling

Partial Failures: Handle scenarios where KEL anchoring succeeds but registrar publication fails. Implement retry logic with exponential backoff.

Witness Timeout: Set appropriate timeouts for witness receipting. If consensus cannot be achieved, the issuance should be considered failed and potentially retried with a new KEL event.

Verification Failures: When verification fails, provide detailed error messages indicating which verification step failed (SAID mismatch, missing KEL anchor, insufficient witnesses, etc.).

Performance Optimization

Batch Issuance: For bulk credential issuance, include multiple seals in a single KEL event to reduce witness coordination overhead.

Caching: Cache verified issuance events and their associated KEL anchors to avoid repeated verification. Implement cache invalidation when revocation events are detected.

Parallel Verification: Verification steps (SAID computation, KEL retrieval, witness receipt checking) can often be parallelized for improved performance.

Security Considerations

Key Protection: Ensure issuer signing keys are protected according to the security requirements of the credential type. High-stakes credentials (vLEI QVI, Legal Entity) should use HSMs or secure enclaves.

Witness Selection: Choose witnesses that are independent and geographically distributed to prevent collusion and improve resilience.

Revocation Monitoring: Implement mechanisms to monitor for revocation events in the credential's TEL. Verifiers should check revocation status before accepting credentials.

Testing Strategies

Unit Tests: Test SAID computation, seal creation, and event structure validation independently.

Integration Tests: Test the full issuance workflow including KEL anchoring, witness receipting, and registrar publication.

Verification Tests: Test verification logic with both valid and invalid issuance events, including tampered SAIDs, missing KEL anchors, and insufficient witness receipts.

Performance Tests: Measure issuance latency under various witness configurations and network conditions.