Comprehensive Explanation

top-level-section

Structure Definition

The top-level section is a fundamental structural component of Authentic Chained Data Containers (ACDCs) that defines the outermost fields of an ACDC when expressed in its compact variant form. According to the IPEX specification, the top-level section serves as the cryptographic anchor point that binds all variants of a given ACDC together through shared field commitments.

Purpose and Role

The primary purpose of the top-level section is to provide a consistent cryptographic commitment surface across all possible representations of an ACDC. When an Issuer signs any variant of an ACDC—whether compact, fully expanded, or any intermediate form—that signature creates a cryptographic commitment to the top-level section fields. This commitment mechanism is what enables graduated disclosure patterns while maintaining verifiable integrity.

The top-level section acts as the structural invariant across ACDC variants. Regardless of how deeply nested sections are expanded or compacted, the top-level fields remain consistent in their cryptographic representation. This design choice enables several critical capabilities:

1. Variant Interoperability: A signature on one variant remains valid for all other variants of the same ACDC
2. Selective Disclosure: Sections can be disclosed progressively without requiring new signatures
3. Cryptographic Binding: All variants are cryptographically bound to the same root commitment
4. Verification Efficiency: Verifiers can validate commitments without requiring full expansion

Structural Organization

The top-level section is organized as a field map containing standardized fields defined by the ACDC specification. According to the W3C TPAC ACDC Overview presentation, the core top-level fields include:

• v: Version string with regex-able format for protocol versioning
• d: Digest (SAID) - the self-referential cryptographic digest of the ACDC
• i: Issuer Identifier (AID) - the autonomic identifier of the issuing entity
• u: UUID for rainbow table attack protection (optional, used in private ACDCs)
• ri: Registry Identifier for issuance/revocation tracking
• s: Schema (SAID or schema block itself)
• a: Attribute (SAID or attribute block)
• e: Edge (SAID or edge block for graph connections)
• r: Rule (SAID or rule block)

Each of these fields can be represented in one of two ways within the top-level section:

1. As a SAID: A Self-Addressing Identifier that cryptographically commits to the content of the associated section without revealing that content
2. As a SAD: The full Self-Addressed Data structure containing the complete content of the section

This dual representation capability is the defining characteristic of the top-level section in compact variants.

Key Components

The top-level section's key components can be categorized into three functional groups:

Identity and Versioning Components:

• The v (version) field establishes protocol compatibility
• The d (SAID) field provides self-referential integrity
• The i (issuer AID) field establishes control authority

Content Reference Components:

• The s (schema) field defines structural constraints
• The a (attribute) field contains or references claim data
• The e (edge) field enables graph fragment chaining
• The r (rule) field specifies governance constraints

Privacy and Registry Components:

• The u (UUID) field provides salty nonce protection
• The ri (registry identifier) field enables revocation tracking

The interaction between these components creates a flexible yet cryptographically rigid structure that supports multiple disclosure patterns while maintaining verifiable integrity.

Data Format

Field Definitions

Each field in the top-level section follows strict formatting rules defined by the CESR (Composable Event Streaming Representation) encoding scheme and JSON Schema constraints.

Version Field (v): The version string follows a specific regex pattern that encodes:

• Protocol identifier (e.g., "ACDC")
• Major version number
• Minor version number
• Serialization format indicator

Example format: "ACDC10JSON000000_" where the trailing underscore and zeros provide padding for fixed-length parsing.

SAID Field (d): The digest field contains a qualified cryptographic primitive in CESR format. This is a self-referential digest computed over the entire ACDC structure with the d field initially set to a placeholder value of the appropriate length. The SAID computation process:

1. Serialize the ACDC with d set to a placeholder (typically # characters)
2. Compute the cryptographic digest of the serialization
3. Encode the digest using CESR with appropriate derivation code
4. Replace the placeholder with the computed SAID
5. The result is a self-addressing structure where the identifier is derived from the content

Issuer AID Field (i): Contains a CESR-encoded autonomic identifier that identifies the issuing entity. This AID must be verifiable through its associated KEL (Key Event Log). The issuer AID establishes the root-of-trust for the ACDC's authenticity.

Schema Field (s): Can contain either:

• A SAID reference to an immutable JSON Schema document
• The complete schema block itself (in expanded variants)

The schema defines structural constraints using JSON Schema composition operators, enabling composable schemas that can be validated independently.

Attribute Field (a): Represents the claims or assertions made by the ACDC. In the top-level section of a compact variant, this field contains:

• A SAID reference to the attribute section (compact form)
• The complete attribute block (expanded form)

The attribute section itself may contain nested structures supporting selective disclosure through attribute aggregates and blinded blocks.

Edge Field (e): Enables directed acyclic graph (DAG) structures by referencing other ACDCs. The edge field can contain:

• A SAID reference to an edge block defining graph connections
• The complete edge block with operator logic (I2I, NI2I, DI2I)

Edge operators support complex authorization chains and delegation patterns.

Rule Field (r): Contains governance constraints and Ricardian contract clauses. Can be represented as:

• A SAID reference to a rule block
• The complete rule block with legal language and constraints

Encoding Format

The top-level section must be serialized using one of the supported encoding formats:

JSON Encoding: The primary serialization format uses standard JSON with specific ordering requirements. Field ordering follows the canonicalization rules defined in the ACDC specification to ensure deterministic serialization for SAID computation.

CBOR Encoding: Concise Binary Object Representation provides a binary alternative with equivalent semantic structure. CBOR encoding is particularly useful for bandwidth-constrained environments.

MessagePack Encoding: MessagePack offers another binary serialization option with different performance characteristics.

All encoding formats must support bidirectional transformation while preserving the cryptographic integrity of SAIDs. The CESR encoding scheme ensures that primitives (digests, signatures, identifiers) maintain their qualified format across all serialization domains.

Size and Constraints

The top-level section has specific size characteristics:

Compact Variant Size: When all sections are represented as SAIDs rather than full SADs, the top-level section achieves minimal size. A typical compact ACDC top-level section might be:

• Version field: ~16 bytes
• SAID field: ~44 bytes (for 256-bit digest with CESR encoding)
• Issuer AID: ~44 bytes
• Schema SAID: ~44 bytes
• Attribute SAID: ~44 bytes
• Edge SAID: ~44 bytes (if present)
• Rule SAID: ~44 bytes (if present)

Total compact size: approximately 280-350 bytes depending on optional fields.

Expanded Variant Size: When sections are expanded to full SADs, the size grows proportionally to the content of each section. However, the top-level structure remains the same—only the field values change from SAIDs to complete data structures.

Constraint Requirements:

• All SAIDs must use consistent cryptographic strength (typically 256-bit digests)
• Field labels must follow the normative definitions in the ACDC specification
• Version strings must match the regex pattern for the protocol version
• AIDs must be verifiable through their KELs
• Schema SAIDs must resolve to valid JSON Schema documents

Operations

Creation and Initialization

Creating a top-level section involves several cryptographic operations that must be performed in a specific sequence:

Step 1: Schema Selection The issuer selects or creates an appropriate JSON Schema that defines the structure of the ACDC. The schema must be immutable and addressable by its SAID. If creating a new schema:

1. Define the schema structure using JSON Schema composition operators
2. Compute the schema's SAID
3. Store the schema in a retrievable location
4. Use the schema SAID in the top-level section

Step 2: Attribute Construction The issuer constructs the attribute section containing the claims or assertions. For selective disclosure support:

1. Organize attributes into disclosable blocks
2. Compute SAIDs for each block
3. Create an attribute aggregate structure if needed
4. Compute the top-level attribute section SAID

Step 3: Edge Definition (if applicable) For ACDCs that chain to other credentials:

1. Define edge relationships using appropriate operators (I2I, NI2I, DI2I)
2. Reference target ACDCs by their SAIDs
3. Compute the edge section SAID

Step 4: Rule Specification (if applicable) For ACDCs with governance constraints:

1. Define rule blocks with legal language
2. Specify chain-link confidentiality requirements
3. Compute the rule section SAID

Step 5: Top-Level Section Assembly Assemble the top-level section with all required fields:

{
  "v": "ACDC10JSON000000_",
  "d": "############################",
  "i": "<issuer-AID>",
  "s": "<schema-SAID>",
  "a": "<attribute-SAID>",
  "e": "<edge-SAID>",
  "r": "<rule-SAID>"
}

Step 6: SAID Computation Compute the self-referential SAID:

1. Serialize the structure with d field as placeholder
2. Compute cryptographic digest (e.g., Blake3-256)
3. Encode digest with CESR derivation code
4. Replace placeholder with computed SAID

Step 7: Signature Attachment The issuer signs the completed ACDC:

1. Retrieve signing keys from the issuer's KEL
2. Generate indexed signatures using current keys
3. Attach signatures as CESR-encoded primitives
4. The signature commits to the top-level section fields

Updates and Modifications

The top-level section of an ACDC is immutable by design. Once created and signed, the top-level section cannot be modified without invalidating the issuer's signature and the ACDC's SAID. This immutability is a core security property.

However, certain update patterns are supported through the ACDC ecosystem:

Registry-Based Revocation: The ri (registry identifier) field enables revocation without modifying the ACDC itself:

1. The registry identifier points to a TEL (Transaction Event Log)
2. The TEL tracks issuance and revocation events
3. Revocation is recorded as a new event in the TEL
4. The ACDC's top-level section remains unchanged
5. Verifiers check the TEL for current status

This pattern follows the RUN model (Read, Update, Nullify) rather than traditional CRUD operations.

Credential Refresh Through Reissuance: To update claims or attributes:

1. Issue a new ACDC with updated content
2. The new ACDC has a different SAID
3. Optionally revoke the previous ACDC via its registry
4. The new ACDC may reference the previous one via edge relationships

Delegation and Chaining: Updates to authorization chains occur through new ACDCs:

1. A delegating ACDC issues a new delegated ACDC
2. The delegated ACDC's edge section references the delegating ACDC
3. The delegation chain is verifiable through SAID references
4. No modification to existing top-level sections is required

Verification and Validation

Verifying a top-level section involves multiple cryptographic checks:

SAID Verification:

1. Extract the d field value (the claimed SAID)
2. Replace the d field with a placeholder of equal length
3. Serialize the structure using the same encoding as the original
4. Compute the cryptographic digest
5. Encode the digest with CESR
6. Compare the computed SAID with the claimed SAID
7. Verification succeeds if they match

This process confirms the integrity of the entire ACDC structure.

Issuer AID Verification:

1. Extract the i field (issuer AID)
2. Retrieve the issuer's KEL via OOBI discovery
3. Verify the KEL's integrity and consistency
4. Confirm the KEL is not duplicitous
5. Establish the current key state of the issuer

This process confirms the authenticity of the issuer's identity.

Signature Verification:

1. Extract attached signatures from the ACDC message
2. Identify the signing keys from the issuer's KEL
3. Verify each signature against the ACDC content
4. Confirm signatures meet the threshold requirements
5. Check that signing keys were authoritative at issuance time

This process confirms the non-repudiable commitment of the issuer.

Schema Validation:

1. Extract the s field (schema SAID or schema block)
2. If SAID, resolve to the actual schema document
3. Verify the schema's SAID matches the reference
4. Validate the ACDC structure against the schema
5. Confirm all required fields are present
6. Verify field types and constraints

This process confirms structural compliance.

Registry Status Check (if applicable):

1. Extract the ri field (registry identifier)
2. Resolve the registry's TEL
3. Verify the TEL's integrity and anchoring to the issuer's KEL
4. Check the current status (issued, revoked, etc.)
5. Confirm the status is acceptable for the use case

This process confirms the credential's current validity status.

Edge Verification (if applicable):

1. Extract the e field (edge SAID or edge block)
2. Resolve referenced ACDCs by their SAIDs
3. Verify each referenced ACDC independently
4. Confirm edge operator logic is satisfied
5. Validate delegation chains if present

This process confirms authorization chain integrity.

Usage Context

In Which Protocols

The top-level section is used across multiple protocols in the KERI ecosystem:

IPEX (Issuance and Presentation Exchange): The IPEX protocol uses top-level sections to enable graduated disclosure. During an issuance exchange or presentation exchange:

1. The Discloser may initially present a compact variant
2. The top-level section contains SAIDs for undisclosed sections
3. The Disclosee can verify the cryptographic commitment
4. Progressive disclosure expands SAIDs to full SADs as needed
5. The issuer's signature remains valid throughout the exchange

ACDC Specification: The ACDC specification defines the top-level section as the foundational structure for all credential variants. The specification details:

• Field label normative definitions
• SAID computation algorithms
• Serialization requirements
• Signature attachment mechanisms
• Disclosure transformation rules

KERI Protocol: While KERI itself focuses on identifier management through KELs, ACDCs extend KERI by providing a credential layer. The top-level section's i field (issuer AID) creates a cryptographic binding to the KERI infrastructure:

1. The issuer AID is a KERI identifier
2. The issuer's KEL provides the root-of-trust
3. Key rotations in the KEL affect signature verification
4. Delegation in KERI enables delegated issuance in ACDCs

vLEI Ecosystem: The GLEIF vLEI (verifiable Legal Entity Identifier) ecosystem uses top-level sections extensively:

• QVI credentials use top-level sections to establish issuer authority
• Legal Entity credentials chain through edge sections
• OOR and ECR credentials use attribute sections for role assertions
• The entire vLEI credential chain is verifiable through top-level section commitments

Lifecycle Management

The lifecycle of a top-level section follows these phases:

Creation Phase:

• Schema selection and SAID computation
• Attribute construction and SAID computation
• Edge and rule definition (if applicable)
• Top-level section assembly
• ACDC SAID computation
• Issuer signature attachment

Issuance Phase:

• Registry event recording (if using TEL)
• OOBI publication for discoverability
• Initial disclosure to issuee (if applicable)
• Compact variant transmission

Active Phase:

• Presentation exchanges using various disclosure levels
• Progressive expansion from compact to full variants
• Verification by multiple verifiers
• Registry status checks

Revocation Phase (if applicable):

• Registry revocation event recording
• Top-level section remains unchanged
• Verifiers detect revoked status through registry

Archival Phase:

• Long-term storage of ACDC and signatures
• Preservation of issuer KEL for future verification
• Maintenance of schema documents for validation

Related Structures

The top-level section interacts with several related data structures:

Attribute Section: Referenced by the a field, the attribute section contains the actual claims. The relationship:

• Top-level a field contains attribute section SAID (compact) or SAD (expanded)
• Attribute section may contain nested attribute aggregates
• Selective disclosure operates on attribute section structure
• Attribute section SAID provides cryptographic commitment

Edge Section: Referenced by the e field, the edge section defines graph relationships. The relationship:

• Top-level e field contains edge section SAID (compact) or SAD (expanded)
• Edge section contains operator logic and ACDC references
• Edge verification requires resolving referenced ACDCs
• Edge section enables delegation and authorization chains

Rule Section: Referenced by the r field, the rule section specifies governance. The relationship:

• Top-level r field contains rule section SAID (compact) or SAD (expanded)
• Rule section contains legal language and constraints
• Rules may specify chain-link confidentiality requirements
• Rule section enables contractual commitments

Schema Document: Referenced by the s field, the schema defines structure. The relationship:

• Top-level s field contains schema SAID (compact) or schema block (expanded)
• Schema document is immutable and independently verifiable
• Schema uses JSON Schema composition operators
• Schema validation occurs against the entire ACDC structure

Transaction Event Log (TEL): Referenced by the ri field, the TEL tracks status. The relationship:

• Top-level ri field identifies the registry
• TEL contains issuance and revocation events
• TEL is anchored to the issuer's KEL
• TEL provides current status without modifying the ACDC

Key Event Log (KEL): The issuer's KEL provides the root-of-trust. The relationship:

• Top-level i field identifies the issuer's AID
• Issuer's KEL establishes key state for signature verification
• KEL rotations affect which keys are authoritative
• KEL delegation enables delegated issuance

The top-level section serves as the cryptographic nexus that binds all these structures together into a coherent, verifiable credential system. Its design enables flexible disclosure patterns while maintaining strong cryptographic guarantees about integrity, authenticity, and non-repudiation.