Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 171 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 authentic-data-container (ADC) is a mechanism for conveying data that allows the authenticity of its content to be cryptographically proved, serving as the foundational concept for ACDC (Authentic Chained Data Container) implementations that provide verifiable proof-of-authorship through self-addressing identifiers and digital signatures.
An authentic-data-container (ADC) represents the foundational abstraction for data structures that enable cryptographic verification of content authenticity. The ADC concept serves as the theoretical basis for ACDC (Authentic Chained Data Container) implementations, which extend the basic ADC model with chaining capabilities to create directed acyclic graphs (DAGs) of verifiable credentials.
The primary purpose of an ADC is to provide a verifiable binding between data content and its cryptographic proof of authenticity. This binding ensures that any party receiving an ADC can independently verify:
Within the KERI ecosystem, ADCs serve as the building blocks for verifiable credentials, attestations, and any data requiring cryptographic proof of origin. The W3C Verifiable Credentials specification represents one concrete implementation of the ADC concept, though KERI's ACDC specification provides a more sophisticated approach with additional features like chaining, selective disclosure, and graduated revelation.
The ADC structure follows a field map architecture where data is organized as key-value pairs (called "field maps" in KERI terminology to avoid confusion with cryptographic keys). The fundamental components include:
Core Identity Fields:
Canonical Serialization: All implementations MUST use insertion-ordered field maps and produce byte-identical serializations for the same logical content. Field order is defined by the schema, not lexicographic sorting.
Placeholder Format: Use exactly 44 '#' characters (ASCII 35) for SAID placeholders when computing Blake3-256 digests. Other digest algorithms require different placeholder lengths matching their CESR-encoded output.
Recursive SAID Computation: For nested field maps, compute SAIDs from innermost to outermost. Replace nested SAIDs before computing parent SAIDs to ensure correct cryptographic binding.
CESR Proof Format: Attach signatures using CESR-Proof format, which supports:
Signature Scope: Sign the canonical serialization with SAID placeholders replaced by computed SAIDs. This ensures signatures cover the final container state.
Multi-Sig Coordination: For group multi-sig AIDs, collect threshold-satisficing signatures before considering the container validly issued. Use KERI's witness agreement algorithm (KAACE) for distributed signature collection.
Schema Immutability: Once a schema is published and identified by a SAID, it MUST NOT be modified. Create new schema versions with new SAIDs for changes.
Schema Composition: Use JSON Schema's oneOf, anyOf, and allOf operators to support multiple ACDC variants (compact, expanded) within a single schema definition.
Schema Discovery: Publish schemas at well-known locations or via OOBI resolution. Cache schemas by SAID to avoid redundant retrievals.
UUID Generation: Use cryptographically secure random number generators (CSPRNG) for UUID fields. Minimum 128 bits of entropy required to prevent rainbow table attacks.
Selective Disclosure: When implementing selective disclosure, ensure that:
Content Sections:
Verification Elements:
The ACDC specification extends this basic structure with additional sections for edges (creating credential chains), rules (Ricardian contracts), and selective disclosure mechanisms (compact variants using SAIDs).
The essential components that make a data container "authentic" include:
Self-Addressing Identifiers (SAIDs): The container's identifier is derived from a cryptographic digest of its content, creating a tamper-evident binding. Any modification to the content invalidates the SAID, making tampering immediately detectable.
Issuer Attribution: The container includes the AID of its creator, enabling verification of authorship through the issuer's Key Event Log (KEL). This provides end-to-end verifiable attribution without requiring trusted intermediaries.
Cryptographic Signatures: Digital signatures from the issuer's private keys provide non-repudiable proof of creation. These signatures are verified against the issuer's current authoritative key state as recorded in their KEL.
Schema Validation: The container references a schema (itself identified by a SAID) that defines the expected structure and data types. This enables automated validation and ensures semantic interoperability.
While the abstract ADC concept doesn't mandate specific field names, the ACDC implementation provides a canonical field structure:
Version String (v): Identifies the protocol version and serialization format. Format: ACDCvvSSSShhhhhh_ where vv is version, SSSS is serialization type, and hhhhhh is size.
SAID (d): The self-addressing identifier of the container, computed as a cryptographic digest of the canonical serialization with the SAID field initially set to a placeholder.
UUID (u): Optional high-entropy nonce for privacy protection, preventing rainbow table attacks on compact disclosures.
Issuer AID (i): The autonomic identifier of the entity issuing the container, enabling verification through the issuer's KEL.
Registry Identifier (ri): Optional reference to a Transaction Event Log (TEL) for tracking issuance/revocation state.
Schema (s): Either the SAID of the schema or the schema block itself, defining the container's structure.
Attributes (a): The substantive data payload, either as a SAID reference (compact) or full content (expanded).
ADCs support multiple serialization formats through CESR (Composable Event Streaming Representation):
JSON Serialization: Human-readable text format using URL-safe Base64 encoding for binary data. JSON is the primary format for ACDC examples and documentation.
CBOR Serialization: Compact binary format (RFC 8949) for efficient transmission and storage.
MessagePack (MGPK): Alternative binary serialization with broad language support.
All serializations must maintain insertion-ordered field maps to ensure deterministic SAID computation. The order of fields in the serialization must match the order specified in the schema, enabling consistent hashing across different implementations.
CESR Encoding: Cryptographic primitives (signatures, digests, keys) are encoded using CESR, which provides:
ADC implementations face several size considerations:
SAID Length: Typically 44 characters in Base64 encoding for 256-bit digests (e.g., Blake3-256), providing approximately 128 bits of cryptographic strength.
Signature Overhead: Ed25519 signatures add 88 characters in CESR text encoding, or 64 bytes in binary.
Compact vs. Expanded: Compact variants using SAIDs for undisclosed sections can be orders of magnitude smaller than fully expanded versions, enabling efficient transmission while maintaining verifiability.
Nesting Depth: ACDCs support arbitrary nesting of field maps, though practical implementations should consider parsing complexity and verification overhead.
Attribute Limits: No hard limits on attribute count or size, but implementations should consider:
Creating an authentic-data-container involves several cryptographic operations:
1. Schema Selection: Choose or define a schema that specifies the container's structure. The schema itself should be identified by a SAID for tamper-evidence.
2. Content Population: Fill in all required fields according to the schema, using placeholder values for fields that will contain SAIDs (including the container's own SAID).
3. SAID Computation:
4. Signature Generation:
5. Anchoring (optional):
Authentic-data-containers are fundamentally immutable once issued. The SAID binding ensures any modification invalidates the container. However, several patterns enable "updates":
Revocation: Rather than modifying the container, update its status in a TEL. The container itself remains unchanged, but its validity state changes.
Supersession: Issue a new container with updated content, potentially including an edge reference to the superseded container to maintain provenance.
Chaining: Create a new container that references the original through an edge, building a verifiable chain of related credentials.
Graduated Disclosure: Present different variants (compact, partial, full) of the same container based on disclosure requirements. All variants share the same root SAID, maintaining cryptographic equivalence.
Verifying an authentic-data-container requires multiple validation steps:
1. SAID Verification:
2. Schema Validation:
3. Signature Verification:
4. Provenance Verification:
5. Status Verification (if applicable):
ri fieldAuthentic-data-containers are used throughout the KERI ecosystem:
ACDC Protocol: The primary implementation of ADCs, providing verifiable credentials with chaining, selective disclosure, and graduated revelation capabilities.
IPEX (Issuance and Presentation Exchange): Protocol for exchanging ACDCs between issuers, holders, and verifiers. IPEX treats both issuance and presentation as disclosure operations, unifying the exchange model.
vLEI Ecosystem: GLEIF's verifiable Legal Entity Identifier system uses ACDCs for organizational credentials, role credentials, and data attestations.
Supply Chain Applications: ACDCs enable authentic data supply chains where each transformation or custody transfer is recorded in a verifiable container, creating digital twins of physical supply chains.
Knowledge Graphs: ACDCs serve as nodes in distributed property graphs, with edges creating verifiable relationships between data entities.
The lifecycle of an authentic-data-container includes:
Issuance Phase:
Active Phase:
Revocation Phase:
Archival Phase:
ADCs interact with several related data structures:
Key Event Logs (KELs): Provide the root-of-trust for issuer AIDs. Every ADC verification ultimately depends on the issuer's KEL to establish key authority.
Transaction Event Logs (TELs): Track the lifecycle state of ADCs, particularly for revocable credentials. TELs are themselves anchored to KELs.
Schemas: Define the structure and semantics of ADCs. Schemas are identified by SAIDs and can be chained to create schema hierarchies.
Out-of-Band Introductions (OOBIs): Enable discovery of KELs, TELs, and schemas needed to verify ADCs. OOBIs bootstrap the verification process.
CESR Streams: ADCs are transmitted as CESR-encoded streams, potentially interleaved with other KERI messages in a single stream.
Ricardian Contracts: Legal prose embedded in ADC rules sections, creating contractually-protected disclosure mechanisms.
ADCs support progressive revelation of information through multiple disclosure variants:
Compact Disclosure: Only SAIDs are revealed, providing cryptographic commitments without exposing content. Useful for initial low-trust interactions.
Partial Disclosure: Selected sections are expanded while others remain compact. Enables context-specific disclosure based on verifier requirements.
Selective Disclosure: Individual attributes from selectively-disclosable sets are revealed. Prevents correlation across different disclosure contexts.
Full Disclosure: All content is revealed. Required when complete information is necessary for the transaction.
All variants maintain cryptographic equivalence through consistent SAID computation, enabling verification regardless of disclosure level.
ADCs can reference other ADCs through edges, creating verifiable chains:
I2I (Issuer-to-Issuee): The issuer of a child credential must be the subject of the parent credential. Represents direct delegation of authority.
DI2I (Delegated-Issuer-to-Issuee): Either the root AID or a delegated AID of the parent's issuee can issue the child. Enables flexible delegation patterns.
NI2I (Not-Issuer-to-Issuee): No relationship required between issuer and parent credential. Used for referencing supporting evidence.
These operators enable complex authorization graphs while maintaining cryptographic verifiability of the entire chain.
ADCs incorporate multiple privacy mechanisms:
UUID Blinding: High-entropy nonces prevent rainbow table attacks on compact disclosures, making correlation computationally infeasible.
Selective Disclosure: Unbundled attributes can be revealed independently, minimizing information exposure.
Chain-Link Confidentiality: Contractual obligations bind each party in the disclosure chain, creating legal protections for shared data.
Blinded Revocation Registries: TEL state can be hidden, requiring the holder to disclose revocation status rather than making it publicly queryable.
Implementing authentic-data-containers requires careful attention to:
Deterministic Serialization: Field order must be consistent across implementations to ensure SAID computation produces identical results.
Cryptographic Strength: Use algorithms providing at least 128 bits of security. Blake3-256 is recommended for digests, Ed25519 for signatures.
Schema Management: Schemas should be versioned and immutable. Use SAIDs to reference schemas, enabling verification of schema integrity.
Key Management: Integrate with KERI keystores for secure key generation, storage, and rotation. Never expose private keys outside secure enclaves.
Verification Caching: Cache verified KELs, TELs, and schemas to avoid redundant verification overhead. Implement cache invalidation for key rotations.
Error Handling: Distinguish between verification failures (invalid signatures, mismatched SAIDs) and operational errors (network failures, missing resources).
Performance Optimization: For high-volume scenarios, consider:
Blinded TELs: For privacy-sensitive credentials, use blinded revocation registries with salty nonce blinding factors shared only between issuer and holder.
Verification Caching: Cache verified KELs, TELs, and schemas indexed by SAID. Implement cache invalidation on key rotation events.
Batch Processing: When verifying multiple containers from the same issuer, fetch the issuer's KEL once and reuse for all verifications.
Streaming Parsers: For large containers or high-volume scenarios, implement streaming parsers that can process CESR streams incrementally without loading entire containers into memory.
Verification Failures: Distinguish between:
Revocation Handling: When a container is revoked:
KERI Agent Integration: Integrate with KERIA or similar KERI agents for:
Wallet Integration: For holder applications:
Verifier Integration: For relying parties: