Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 24 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
An issuance-exchange represents a specialized credential exchange pattern within the IPEX (Issuance and Presentation Exchange Protocol) framework. It is formally defined as a specific case of a presentation exchange where the entity disclosing credential information (the Discloser) is simultaneously the entity that originally issued the credential (the Issuer).
The issuance-exchange process accomplishes several critical functions:
Issuance-exchange is employed in scenarios where:
KEL Management: Issuers must maintain robust KEL infrastructure with properly configured witness pools. The GLEIF vLEI ecosystem requires minimum 5 witnesses with KAACE consensus thresholds. Witness selection should prioritize geographic and organizational diversity to prevent single points of failure.
Registry Anchoring: For registry-backed credentials, issuance transactions must be properly anchored to the Issuer's KEL via seals in interaction or rotation events. The anchoring event must be witnessed and confirmed before credential disclosure to ensure verifiable registry state.
Signature Attachment: CESR proof signatures must be properly attached to ACDC messages. The vLEI ecosystem mandates Ed25519 signatures with CESR encoding. Multi-signature scenarios require indexed signatures with proper threshold configuration.
Disclosure Level Selection: Implement logic to select appropriate graduated disclosure mechanisms based on credential sensitivity. Private ACDCs with PII should include high-entropy UUIDs (≥128 bits). Selective disclosure requires proper blinding of attribute SAIDs.
Comprehensive Verification Pipeline: Implement a multi-stage verification process:
Asynchronous Processing: KEL validation and witness querying may be time-consuming. Implement asynchronous verification patterns with appropriate timeout handling. Consider caching validated KELs with TTL-based refresh strategies.
Error Recovery: Implement graceful degradation when witnesses or registries are temporarily unavailable. Maintain fallback verification strategies and clear error reporting to users.
TEL Querying: Implement efficient TEL querying mechanisms. Public TELs can be queried directly from backers. Blinded registries require proper authorization and state disclosure protocols.
State Monitoring: For high-value credentials, implement real-time monitoring of registry state changes. Subscribe to TEL event streams to detect revocations or transfers.
The issuance-exchange involves specific role relationships:
Issuer/Discloser: The entity that both issued the origin ACDC and is now disclosing it. This role unification is the defining characteristic of issuance-exchange. The Issuer's AID (Autonomic Identifier) appears at the top level of the ACDC structure and controls the KEL (Key Event Log) that establishes cryptographic authority.
Disclosee: The entity receiving the disclosed ACDC. In issuance-exchange, when the origin ACDC includes an Issuee field (the subject of the credential claims), the Disclosee MAY also serve as that origin ACDC's Issuee, creating a direct issuance-to-holder pattern.
Verifiers: Third parties who may later verify the disclosed credentials by validating the cryptographic chain from the Issuer's AID through the KERL (Key Event Receipt Log) and associated witness receipts.
The issuance-exchange follows a structured sequence within the IPEX protocol framework:
ACDC Construction: The Issuer constructs an ACDC with required top-level fields:
v (version string): Specifies ACDC protocol version and serialization formatd (SAID): Self-addressing identifier providing cryptographic bindingi (Issuer AID): The Issuer's autonomic identifiers (schema): JSON Schema defining credential structurea (attributes): Credential claims and data payloadu (UUID): High-entropy nonce for private ACDCsri (registry identifier): Link to TEL (Transaction Event Log) for revocation trackingSchema Validation: The ACDC must conform to its declared JSON Schema, ensuring structural integrity and type safety through the "type-is-schema" principle.
Cryptographic Signing: The Issuer signs the ACDC using CESR (Composable Event Streaming Representation) proof signatures, creating non-repudiable cryptographic commitment to the credential content.
IPEX Message Construction: The Issuer (acting as Discloser) constructs an IPEX exchange message containing:
Graduated Disclosure Selection: The Issuer determines the appropriate disclosure level:
OOBI Resolution: If the Disclosee's endpoint is not known, the Issuer may use OOBI (Out-Of-Band Introduction) to discover the Disclosee's service endpoints and witness configuration.
Message Delivery: The IPEX exchange message is transmitted to the Disclosee through:
Receipt Confirmation: The Disclosee may provide cryptographic receipts acknowledging message reception, though this is not mandatory for issuance-exchange completion.
KEL Validation: The Disclosee verifies the Issuer's AID by:
ACDC Verification: The Disclosee validates:
Registry Checking: If the ACDC includes a registry identifier (ri), the Disclosee queries the TEL to verify:
Credential Storage: The Disclosee stores the received ACDC in their keystore or credential wallet, maintaining:
Subsequent Presentation: The Disclosee may later present the credential to third-party verifiers, transitioning from issuance-exchange to standard presentation-exchange where the Disclosee becomes the Discloser.
The issuance-exchange process involves several critical state transitions:
Issuer State Changes:
Disclosee State Changes:
Registry State Changes (if applicable):
Several critical decision points occur during issuance-exchange:
Disclosure Level Selection: The Issuer must decide which graduated disclosure mechanism to employ based on:
Registry Backing Decision: The Issuer determines whether to:
Chaining Strategy: When constructing DAGs of ACDCs, the Issuer selects appropriate edge operators:
Acceptance Criteria: The Disclosee must decide whether to accept the credential based on:
Issuance-exchange mandates specific cryptographic standards:
Signature Algorithms: All vLEI credentials (a primary use case for issuance-exchange) must use:
Digest Algorithms:
Key Management:
Entropy Requirements:
Witness Confirmation Timing:
Registry Anchoring Timing:
Verification Timing:
Expiration Handling:
Robust error handling is critical for issuance-exchange:
Cryptographic Verification Failures:
Network and Communication Errors:
Schema and Structure Errors:
Registry Errors:
Duplicity Detection:
vLEI Credential Issuance:
The GLEIF vLEI ecosystem represents the primary production use case for issuance-exchange:
QVI to Legal Entity: A Qualified vLEI Issuer (QVI) issues a Legal Entity vLEI Credential to an organization that has obtained an LEI (Legal Entity Identifier)
Legal Entity to Representatives: The legal entity then issues OOR (Official Organizational Role) credentials to authorized representatives
Delegated Authority Chains: Representatives may issue ECR (Engagement Context Role) credentials for specific business contexts
Each step uses issuance-exchange where the issuer directly discloses credentials to the intended holder.
Supply Chain Provenance:
Issuance-exchange enables verifiable supply chain tracking:
Manufacturer Issues Origin Certificate: Product manufacturer issues ACDC certifying product origin and specifications
Distributor Receives and Extends: Distributor receives via issuance-exchange, then issues chained ACDC adding distribution information
Retailer Final Mile: Retailer receives chained credentials, verifies entire provenance chain back to manufacturer
The DAG structure of chained ACDCs creates an authentic provenance chain with cryptographic integrity.
Educational Credentials:
University Issues Degree: Educational institution issues degree credential directly to graduate
Graduate Presents to Employer: Graduate later presents credential (now presentation-exchange, not issuance-exchange)
Employer Verifies: Employer validates credential chain back to university's authoritative AID
Issuer Best Practices:
Maintain KEL Integrity: Ensure robust witness configuration with geographic and organizational diversity
Use Appropriate Disclosure Levels:
Implement Registry Backing: For revocable credentials, anchor issuance to TEL for verifiable revocation status
Schema Versioning: Use immutable schemas with clear versioning strategy, support backward compatibility during transitions
Witness Pool Management: Maintain minimum 5 witnesses with TOAD (Threshold of Accountable Duplicity) configured for Byzantine fault tolerance
Disclosee Best Practices:
Comprehensive Verification: Always validate:
Duplicity Monitoring: Use watcher networks to detect potential KEL forks or conflicting credentials
Secure Storage: Protect received credentials with encryption at rest, implement access controls
Audit Logging: Maintain detailed logs of credential reception, verification results, and usage
Graceful Degradation: Implement fallback verification strategies when witnesses or registries are temporarily unavailable
Verifier Best Practices (for subsequent presentations):
Fresh KEL Validation: Don't rely solely on cached KEL data, periodically refresh from witnesses
Registry Checking: Always verify current revocation status, don't trust stale registry data
Chain Validation: For chained ACDCs, validate entire provenance chain, not just the presented credential
Policy Enforcement: Implement business logic to enforce organizational policies on credential acceptance
KERI Infrastructure Integration:
Issuance-exchange requires integration with core KERI components:
Wallet Integration:
Credential wallets must support:
Registry Integration:
For registry-backed credentials:
Enterprise System Integration:
Integrating issuance-exchange into enterprise systems requires:
Interoperability Considerations:
did:keri or did:webs for broader ecosystem compatibilityIssuance-exchange represents a fundamental pattern in the KERI/ACDC ecosystem, providing a secure, verifiable mechanism for credential issuance that maintains cryptographic integrity from issuer to holder. By unifying issuance and presentation under the IPEX protocol's disclosure model, the architecture achieves elegant simplicity while supporting sophisticated use cases ranging from vLEI credentials to supply chain provenance.
The process's reliance on KERI's autonomic identifier infrastructure, combined with ACDC's flexible disclosure mechanisms and CESR's efficient encoding, creates a powerful foundation for authentic data ecosystems. Proper implementation requires careful attention to cryptographic requirements, timing considerations, error handling, and integration patterns, but the result is a robust, scalable credential issuance system suitable for high-stakes regulatory and business applications.
Caching Strategy: Balance freshness requirements with performance by implementing intelligent caching of registry state. Critical verifications should always query live registry state.
Key Protection: Issuer private keys must be protected with appropriate security measures. HSMs are recommended for high-value issuers. Implement key rotation schedules and pre-rotation commitments for compromise recovery.
Duplicity Detection: Integrate with watcher networks for ambient duplicity detection. Implement alerting mechanisms for detected KEL forks or conflicting credentials.
Audit Logging: Maintain comprehensive audit logs of all issuance and verification activities. Include timestamps, involved AIDs, verification results, and any errors encountered.
Witness Parallelization: Query multiple witnesses in parallel to reduce latency. Implement early termination when sufficient receipts are obtained.
KEL Caching: Cache validated KELs with appropriate TTL. Implement incremental KEL updates rather than full re-validation when possible.
Batch Processing: For high-volume issuance scenarios, implement batch processing of credentials with shared witness confirmation.
DID Method Support: Implement did:keri and did:webs resolution for broader ecosystem compatibility. Support transformation between KERI AIDs and DID representations.
Schema Registry Integration: Coordinate with centralized or decentralized schema registries for schema discovery and validation. Implement schema caching with version management.
Legacy System Bridges: For integration with W3C VC ecosystems, implement transformation layers that convert ACDCs to VC Data Model format while preserving cryptographic integrity.
Test Vectors: Implement comprehensive test suites covering:
Interoperability Testing: Participate in interoperability testing events to validate compatibility with other KERI implementations (KERIpy, KERIox, Signify).
Load Testing: For production deployments, conduct load testing to validate performance under expected transaction volumes. Test witness pool capacity and registry query performance.