Authentic Chained Data Containers

ACDCs give us a very powerful way to structure signed data, and create relationships between different identifiers and signed data. You don’t need to use ACDCs to start using KERI to sign data everywhere, and in many cases you might want to avoid them to secure your solution faster. That being said, we strongly recommend taking advantage of ACDCs over time!

As a basic idea, ACDCs are CESR data structures, a bit like JSON which follow a certain schema and are issued by a specific KERI identifier. ACDCs can be used to represent any signed data, including but not limited to Verifiable Credentials.

Primary top-level fields

{
  "v": "ACDC10JSON000197_",
  "d": "EPWcaKebqazTinvxTwBXDwc2Wn5tudinQePQfjsvAOeS",
  "u": "0AG7OY1wjaDAE0qHcgNghkDa",
  "i": "EJ43lGaMyW8Jfyfd8DEKqeJbmufjQf4cmF63FcHZ6eNb",
  "ri": "EAsc5I_gAqiOQ1ZFk147Obtzc_zNmb_XrMJkhmShdRTN",
  "s": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao",
  "a": {
    "d": "EPA-kPyh4i97cHNyoz-R3uy_SkZqwWzTMYxt5l3EhFas",
    "u": "0ADaG7OaDAE0qHcgY1Nghkwj",
    "i": "EA32XMQwdzVBqQIZ6T9ILTCiHK3twjRuzuXTbwyfQWX3",
    "LEI": "5493001KJTIIGC8Y1R17",
    "dt": "2025-03-31T16:36:57.324000+00:00"
  }
}

The v field indicates the version (which you can see includes JSON), and the d field is the SAID, or digest of the ACDC itself.

Schemas

Here, we have QVI credential from the vLEI ecosystem. We know this because the s field determines what schema is being used, and the produced ACDC must follow the rules of the schema.

Schema identifiers are always a SAID of the schema itself. This ensures ACDCs are cryptographically bound to a particular schema, and secure from any vulnerabilities of schema URLs in other ecosystems.

Issuers

This ACDC has been issued by the identifier EJ43lGaMyW8Jfyfd8DEKqeJbmufjQf4cmF63FcHZ6eNb, marked in the i field. This credential won’t be valid unless signed by this identifier, and we’ll shortly cover how exactly it’s signed.

Registries

The ri field represents the registry identifier. We’ll touch on registries in more detail later.

For now, just think of a registry as a place to store the status of a credential, issued or revoked, and control who is allowed issue or revoke ACDCs in that registry. The above ACDC won’t be valid unless the issuing identifier has authority within the registry, EAsc5I_gAqiOQ1ZFk147Obtzc_zNmb_XrMJkhmShdRTN.

Privacy

Many ACDCs that are issued will be considered private, particularly if they contain personal information. The u field is optional, and if present, the ACDC is considered a private ACDC.

This field should contain a randomly generated salt of sufficiently entropy. In case a 3rd party has access to the schema, and SAID of an ACDC, the salt provides sufficient entropy to make it computationally infeasible to discover or calculate the remaining values of the ACDC.

This u field can also appear in any block within the ACDC to protect the privacy of the block when partially or selectively disclosing that information. Each u field within an ACDC should be different — check out this example.

Attributes

The a field contains the attributes block, where you will find any user relevant data.

• a.d: Reserved as the SAID of the attributes block.
• a.i: Issuee or holder field.
• a.dt: Reserved for the issuance timestamp.

The schema defines any custom attributes, and in this case there is only the LEI field. However, since the issuee or holder is an optional feature in ACDCs, the schema decides whether a.i exists or not. In this case, since the QVI ACDC is a credential, it’s required.

Compacting

The above attributes block contains it’s own SAID which allows us to replace the entire block with a SAID to “compact” it. This enables graduated disclosure in presentations, where the contents of the block can be hidden until necessary.

It can also enable caching via the SAID in scenarios where the other party might already know the contents from some other interaction. This caching is particularly useful when dealing with edges when chaining, which we will see shortly.

The following is the compacted form of the QVI credential from earlier.

{
  "v": "ACDC10JSON000197_",
  "d": "EPWcaKebqazTinvxTwBXDwc2Wn5tudinQePQfjsvAOeS",
  "u": "0AG7OY1wjaDAE0qHcgNghkDa",
  "i": "EJ43lGaMyW8Jfyfd8DEKqeJbmufjQf4cmF63FcHZ6eNb",
  "ri": "EAsc5I_gAqiOQ1ZFk147Obtzc_zNmb_XrMJkhmShdRTN",
  "s": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao",
  "a": "EPA-kPyh4i97cHNyoz-R3uy_SkZqwWzTMYxt5l3EhFas"
}

Note that the top-level d field does not change, since SAIDs are always calculated in the compacted form. Secondly, the SAID of the attributes field must be calculated before the top-level SAID.

KEL anchoring

Since the signing keys related to a given identifier can change over time, we cannot trust signatures from old keys that were rotated away. This leaves us with 2 options:

1. The issuer signs the ACDC issuance, and the verifier ensures that the signatures matches the latest, current signing keys of the issuer.
2. We cryptographically relate the order of events between issuances and key rotations.

The first approach is very limiting because if an issuer rotates their keys, the validation of all previously issued ACDCs breaks. This disincentivizes key rotation, which can over-expose the issuer keys and leads to compromise.

In a blockchain based identity system, the second could be achieved by anchoring the digest of the ACDC issuance onto the ledger for strict ordering. KERI does something similar, since a KEL is a mini-blockchain in itself. We simply need to create an interaction event with the digest of the ACDC issuance.

In KERI, this has 2 key advantages:

1. Key rotation doesn’t invalidate previously issued ACDCs.
2. Controllers can “watch” their own identifiers, and if a new event is added to their KEL which seems suspicious (not signed from their wallet, happens outside of business hours, etc), they can be alerted and react instantly.

The second advantage is particularly interesting because all other security systems suffer from not being able to detect key compromise quickly enough, giving an attacker too much time to cause damage while undetected. Often, systems are attacked at the edge and privileges are gradually escalated over time, so time is the last thing we want to gift an attacker. This presentation  covers the topic in more detail.

This approach should be applied when signing anything in KERI that is not ephemeral, whether it involves ACDCs or not.

Chaining

ACDCs as we’ve seen them so far provide a secure way to create Verifiable Statements (untargeted) or Verifiable Credentials (targeted). On top of this, ACDCs can be chained together much like X.509 certificate chains, but with a lot more power and flexibility.

Together, a set of ACDCs can form a property graph, where each ACDC is a node in the graph with edges between nodes. Nodes can have multiple edges, and edges can contain operators and weights.

This enables a way to securely represent provenance over data, backed with credentials, and form relationships between entities. Combined with KERI’s enterprise-grade identifiers, this enables true organizational identity.

Edges

The rules for how ACDCs can be chained together is determined by the schema definitions, as one schema can reference another schema.

The chaining feature of ACDCs has two concepts:

• Edges
• Edge groups

An edge connects two ACDCs together with some operator, and an edge group is a set of related edges which also have an operator.

Validation

To begin with, let’s just imagine one ACDC connecting to another ACDC, so there is an edge between them. For the edge to be valid and cryptographically verify, it must match the rules defined in the schema, which define:

• What other schemas this schema can chain to.
• The operator on the edge (unary operators).

If an edge is not valid, the ACDC issuance is not valid! The ACDC property graph is a type of directed acyclic graph, so if an ACDC does not validate, it won’t impact any previously issued ACDCs up the chain.

Operators

The default operator is called I2I, which means the issuer of one ACDC must be the issuee/holder of the chained ACDC. For example, in the vLEI ecosystem, an LE (Legal Entity) credential may be linked to a QVI (Qualified vLEI Issuer) credential with the I2I operator.

This means the LE credential is only valid if and only if:

1. The ACDC it chains to is a QVI credential, verified by the schema SAID.
2. The LE credential issuer must be the issuee/holder of the QVI credential that it links to. In other words, one QVI cannot chain an LE credential to a different QVI’s credential.

There are other operators too, such as NI2I (opposite of I2I), DI2I (allows for delegated identifiers) and more.

Edge groups

The top-level e field of an ACDC defines the edge group, and it can be an edge group of size 1, like in the previous example. However, as mentioned before, an edge group can contain multiple edges and form a relationship between the edges, and each edge group has its own special operator.

This time the operator is a boolean logic operator, and in fact, edge groups can contain nested edge groups so it’s very flexible! Some of the supported (m-ary) operators are AND, OR, NOR and so on. AND is the default operator for edge groups.

This allows us to model more interesting relationships like requiring two different credentials for proof of authority, or one admin credential.

Weights

Edges can also have optional weights, and they do not impact the cryptographic verifiability of the property graph. Instead weights should influence business logic. The semantics of what a weight means on an edge is determined by the ecosystem itself, and every ecosystem should write an Ecosystem Governance Framework (EGF) to give meaning to ACDCs, schemas and edges.

Example

"e": {
  "d": "EAsc5I_gAqiOQ1ZFk147Obtzc_zNmb_XrMJkhmShdRTN",
  "u": "0AwjaDAE0qHcgNghkDaG7OY3",
  "cred": {
    "d": "EA32XMQwdzVBqQIZ6T9ILTCiHK3twjRuzuXTbwyfQWX3",
    "u": "0ANghkDaG7OY1wjaDAE0qHca",
    "n": "ECJnFJL5OuQPyM5K0neuniccMBdXt3gIXOf2BBWNHdSX",
    "s": "ELIr9Bf7V_NHwY1lkFrn9y2PgveY4-9XgOcLxUdYerzw"
  },
  "data": {
    "d": "EJ43lGaMyW8Jfyfd8DEKqeJbmufjQf4cmF63FcHZ6eNb",
    "u": "0ADAE0qHcgNghkDaG7OY1wjx",
    "n": "EPWcaKebqazTinvxTwBXDwc2Wn5tudinQePQfjsvAOeS",
    "s": "EHwY1lkFrn9y2PgveY4-9XgOcLxUdYerzwLIr9Bf7V_N",
    "o": "NI2I"
  }
}

In this scenario, there are 2 edges which are both required. The issuee of the referenced cred edge must be the issuer of this ACDC. The issue of the referenced data edge cannot be the issuer of this ACDC.

Ricardian contracts

The optional top-level r field defines Ricardian Contracts, or rules to associate with the ACDC. Ricardian Contracts are both machine and human readable legal language.

The rules section enables ACDC’s graduated disclosure to be contractually-protected, though it remains to be seen how these will be enforced on a use case by use case basis.