§ The Hiero AnonCreds Method
v0.1 / Editor’s Draft

Specification Status: EDITORS DRAFT

Current Specification: Editor’s Draft

Specification Version: v0.1 (see Changelog)

Source of Latest Draft: https://github.com/DSRCorporation/hedera-anoncreds-method/spec

Previous Versions:

None

Authors:: Alexander Shenshin; Renata Toktar
Participate:: GitHub repo; File an issue; Commit history
Implementations:: Hiero DID SDK Python; Hiero DID SDK JS

§ Abstract

The Hiero AnonCreds Method specification defines how [ANONCREDS] objects should be registered (written) and resolved when rooting them in a Hedera DID. This specification parallels other DID-specific AnonCreds methods that are registered in the AnonCreds Methods Registry.

The specification leverages [HCS-1] standard for storing immutable files on Hedera Consensus Service (HCS). All the published AnonCreds objects except for RevRegEntry are treated as HCS-1 files in this AnonCreds method (Schema, CredDef, RevRegDef).

For details about Hedera DIDs and how to write/read them, please see Hedera DID Method specification.

§ Definitions

Schema: A JSON object that defines the schema for an AnonCreds verifiable credential. A schema for a given verifiable credential type rooted to a Hedera DID can be resolved as a HCS-1 File. The AnonCreds schema is defined in the Schema publishing section of the [ANONCREDS] specification.
CredDef: A JSON object that contains the public keys that enables verification of an AnonCreds verifiable presentation derived from a verifiable credential from a specific Issuer. A CredDef for a given verifiable credential type rooted to a Hedera DID can be resolved as a HCS-1 File. An AnonCreds CredDef object is defined in the CredDef generation section of the [ANONCREDS] specification.
RevRegDef: A JSON object that contains the metadata and public key published by the Issuer that enables verification of an AnonCreds non-revocation proof that a holder includes in a presentation of a revocable credential. A RevRegDef for a given AnonCreds CredDef rooted to a Hedera DID can be resolved as a HCS-1 File. An AnonCreds RevRegDef object is defined in the RevRegDef creation section of the [ANONCREDS] specification.
RevRegEntry: A JSON object that contains the accumulator and state “delta” (indexes of revoked and issued credentials) in scope of a single update within an AnonCreds revocation registry. The RevRegEntry data is used by the Holder to create a non-revocation proof. A verifier must get the accumulator from the same RevRegEntry used by the holder to verify the non-revocation proof. A RevRegEntry for a given AnonCreds RevRegDef rooted to a Hedera DID can be resolved as HCS message from a separate “entries topic” (topic ID is included in “hcsMetadata” property in RevRegDef). An AnonCreds RevRegEntry object is defined in the RevRegEntry creation section of the [ANONCREDS] specification.
HCS-1 File: An arbitrary data managed on HCS in accordance with [HCS-1] standard. The data is compressed, encoded and chunked before publishing (with vice versa process for resolution) and resolvable via HCS Topic ID. Separate HCS Topics are created for each HCS-1 File and include a memo with metadata for integrity checks (payload hash, compression algorithm and encoding). Cryptographic integrity checks are based on guarantees provided by HCS. HCS-1 Files are immutable due to HCS Topic control restrictions defined in HCS-1 standard - no topic admin key is specified, so topic memo cannot be changed along with a payload hash.
Hedera Consensus Service: A service provided by Hedera ledger that provides convenient functionality for publishing arbitrary messages (by topics) for consensus, giving each of them trusted timestamp and ordering. High throughput, scalability and low cost are significant advantages of HCS, however the message size is hard-limited to 1024 bytes. HCS is used in various production environments to track provenance across supply chains, log asset transfers between blockchain networks, count votes in a DAO, monitor IoT devices, and more.
HCS Topic: An entity created in HCS to manage the stream of messages.
DID Controller: The entity that controls (create, updates, deletes) a given DID, as defined in the [DID-CORE].

§ Hiero AnonCreds Method Specification

§ Overview

The Hiero AnonCreds Method defines how AnonCreds objects (Schemas, CredDefs, RevRegDefs, and RevRegEntries) are registered (published, written) by a DID Controller using a Hedera DID, and how others can resolve those objects.

The method leverages HCS-1 Files, resources (objects, files) managed on Hedera Consensus Service. For details on how these resources are managed please see [HCS-1].

Initial discussions and proposals for Hiero AnonCreds Method were done in scope of HIP-762: AnonCreds Verifiable Data Registry. While the initial proposal provides a significant part of the general concept for using HCS as Verifiable Data Registry (VDR) for AnonCreds, this specification contradicts with it in several ways as a result of further considerations.

§ Contradictions with HIP-762

Initial proposal for HIP-762 references Cardano AnonCreds Method as a base
This includes implementation of DID-Linked Resources approach for identifiers and objects metadata
In further discussion of HIP proposal, it was suggested to exclude DID-Linked resources usage from Hiero Anoncreds Method
- There is a good amount of conceptual reasoning for such decision, but it can be summarized as redundancy comparing to more straightforward use of HCS
An Indy-like identifier format was proposed as alternative: <did>/<object-family>/<object-family-version>/<object-type>/<object-type-identifier>

§ Hedera Consensus Service (HCS) Overview

Hedera Consensus Service (HCS) provides a decentralized solution for publishing ordered, immutable messages with guaranteed timestamps. See the Hedera HCS documentation for technical details.

Used for:

Publishing AnonCreds objects as HCS-1 Files
Maintaining immutable records with verifiable integrity
Distributing messages via public ledger through Hedera Mirror Nodes

Key HCS features:

Ordered Consensus: Guaranteed timestamps and ordering (Hedera Docs)
Immutable Records: Messages are immutable once published
Mirror Node Access: Historical data available via public APIs
Submit Key Control: SubmitKey enforces publishing rights (SubmitKey Reference)

§ AnonCreds Objects

The identifier for each resource has the following format - <publisher-did>/anoncreds/<anoncreds-version>/<object-type>/<hcs-topic-id>:

<publisher-did>: The Hedera DID
<anoncreds-version>: AnonCreds specification version. For AnonCreds objects published according to this version of specification, this value MUST be v1
<object-type>: AnonCreds object type identifier - SCHEMA, PUBLIC_CRED_DEF or REV_REG
<hcs-topic-id>: ID of HCS Topic that should be used to resolve the AnonCreds object, MUST be equal to HCS-1 File Topic ID

Each Hiero AnonCreds object created by an AnonCred Issuer, except for AnonCreds RevRegEntry, is used to build and publish HCS-1 File payload. HCS Topic is created in a process of publishing HCS-1 File and its Topic ID then used to build a complete object identifier in above-mentioned format. That identifier is embedded into other objects (such as issued verifiable credentials) available to other parties (Holders, Verifiers) that need to resolve the object.

Choosing Hedera network:

Hedera network specified in Issuer DID MUST be used for publishing HCS-1 File and creating HCS Topics associated with an object
Hedera network specified in <publisher-did> MUST be used for resolving HCS-1 File associated with an object
Hedera network used to resolve HCS-1 File MUST be assumed for HCS Topic IDs specified in corresponding HCS-1 File content

The following sections define how each AnonCreds object type is published and resolved.

§ AnonCreds Schema

An AnonCreds Schema is published to Hiero as HCS-1 File. The resulting Schema identifier becomes a part of AnonCreds CredDef based on this particular Schema. Holders and Verifiers retrieve the Schema identifier retrieved from a resolved AnonCreds CredDef.

For AnonCreds Schema identifier:

<publisher-did> MUST be DID of Schema Issuer
<object-type> MUST be SCHEMA

§ Schema creation and publishing

The following process MUST be followed to create and publish AnonCreds Schema rooted to a Hedera DID:

As Issuer, create AnonCreds Schema object
Publish Schema object to HCS as HCS-1 File
Use HCS-1 File Topic ID to build Schema identifier: <issuer-did>/anoncreds/v1/SCHEMA/<hcs1-file-topic-id>

§ Schema resolution

The following process MUST be followed to resolve AnonCreds Schema rooted to a Hedera DID:

Parse Schema identifier and retrieve HCS-1 File Topic ID
Use retrieved Topic ID to resolve Schema object as HCS-1 File

§ Schema example

The following is an example AnonCreds Schema HCS-1 File resolved with the identifier: did:hedera:testnet:z59hbwYATdKtDQHb15rq6wj7BABcToWF4nTA8GH9X6Kf6_0.0.5422052/anoncreds/v1/SCHEMA/0.0.5422053

HCS Topic Memo: 5f42ece40f0151f78f752380fea10b130f50008b181f3319cb262706b6e7baee:zstd:base64

Resolved HCS Messages (raw HCS-1 chunks):

[
  {
    "o": 0,
    "c": "data:application/json;base64,KLUv/SCr7QQA0skjIzDFbAOAv0fuuyVwMoLWjIybWL1fKGTV0nsC2VtBalLQUFCBBf0apzk25TZbP6CZgfRPvJl5cGz70xX1Xn/gex4INq95kUhiRQ2pQhCmi0IHBndl1EQNKF10qdDBqkXhWvKaHB2mSXAg3qfX/o1eX74W5SZloj6AtVsz0z5fyyxz8yV/xTJdwNAc+6fTJggDAAybZ74QJyZQeg=="
  }
]

Resolved HCS-1 content:

{
  "name": "Example demo schema",
  "issuerId": "did:hedera:testnet:z59hbwYATdKtDQHb15rq6wj7BABcToWF4nTA8GH9X6Kf6_0.0.5422052",
  "attrNames": [
    "name",
    "age"
  ],
  "version": "1.0"
}

§ AnonCreds CredDef

An AnonCreds CredDef is published to Hiero as HCS-1 File. The resulting CredDef identifier is placed in the verifiable credentials issued by that Issuer. Holders retrieve the CredDef identifier embedded in an AnonCreds verifiable credential and place the CredDef identifier into verifiable presentations sent to Verifiers. Verifiers retrieve the CredDef identifier from the presentation to resolve the CredDef.

For AnonCreds CredDef identifier:

<publisher-did> MUST be DID of CredDef Issuer
<object-type> MUST be PUBLIC_CRED_DEF

§ CredDef creation and publishing

The following process MUST be followed to create and publish AnonCreds CredDef rooted to a Hedera DID:

As Issuer, create AnonCreds CredDef object
Publish CredDef object to HCS as HCS-1 File
Use HCS-1 File Topic ID to build CredDef identifier: <issuer-did>/anoncreds/v1/PUBLIC_CRED_DEF/<hcs1-file-topic-id>

§ CredDef resolution

The following process MUST be followed to resolve AnonCreds CredDef rooted to a Hedera DID:

Parse CredDef identifier and retrieve HCS-1 File Topic ID
Use retrieved Topic ID to resolve CredDef object as HCS-1 File

§ CredDef example

The following is an example AnonCreds CredDef HCS-1 File (with long values truncated with ellipses) resolved with the identifier: did:hedera:testnet:z59hbwYATdKtDQHb15rq6wj7BABcToWF4nTA8GH9X6Kf6_0.0.5422052/anoncreds/v1/PUBLIC_CRED_DEF/0.0.5422058

HCS Topic Memo: b22489d9d28adc5bc334a34a09bfa72d04f500ca62fce9afa096317c6971d884:zstd:base64

Resolved HCS Messages (raw HCS-1 chunks):

[
  {
    "o": 0,
    "c": "data:application/json;base64,KLUv/WCNHa1yAModSSYqAI22tA2cVM0Y..."
  },
  {
    "o": 1,
    "c": "CBbp/9tenWriJ+dOa+WfTaXFvq3iltrZ6Ke7Z1t4v2rDWbkqb5lNTUyRFOyQW..."
  },
  ...
  (6 chunks in total)
]

Resolved HCS-1 content:

{
  "issuerId": "did:hedera:testnet:z59hbwYATdKtDQHb15rq6wj7BABcToWF4nTA8GH9X6Kf6_0.0.5422052",
  "schemaId": "did:hedera:testnet:z59hbwYATdKtDQHb15rq6wj7BABcToWF4nTA8GH9X6Kf6_0.0.5422052/anoncreds/v1/SCHEMA/0.0.5422053",
  "type": "CL",
  "tag": "default",
  "value": {
    "primary": {
      "n": "10069...",
      "s": "32198...",
      "r": {
        "name": "17428...",
        "age": "10037...",
        "master_secret": "18481..."
      },
      "rctxt": "70839...",
      "z": "52601..."
    },
    "revocation": {
      "g": "1 07435...",
      "g_dash": "1 232F7...",
      "h": "1 19001...",
      "h0": "1 188DC...",
      "h1": "1 0D668...",
      "h2": "1 1111A...",
      "htilde": "1 16C12...",
      "h_cap": "1 15562...",
      "u": "1 03D74...",
      "pk": "1 14C3F...",
      "y": "1 20C8C..."
    }
  }
}

§ AnonCreds RevRegDef

An AnonCreds RevRegDef is published to Hiero as HCS-1 File. The RevRegDef identifier is placed in the revocable verifiable credentials issued by its Issuer. Holders retrieve the RevRegDef identifier embedded in an AnonCreds verifiable credential issued to them. Holders place the RevRegDef identifier into verifiable presentations sent to Verifiers, who retrieve the RevRegDef identifier to resolve the RevRegDef.

For AnonCreds RevRegDef identifier:

<publisher-did> MUST be DID of RevRegDef Issuer
<object-type> MUST be REV_REG_DEF

Unlike other AnonCreds objects published as HCS-1 Files, the RevRegDef HCS-1 File content does not represent the AnonCreds object itself, but contains following fields:

revRegDef - RevRegDef object itself
hcsMetadata - additional HCS-related metadata that needs to be stored outside the RevRegDef

The hcsMetadata field contains entriesTopicId which specifies ID of HCS Topic that can be used to resolve all RevRegEntries associated with the RevRegDef (see the example below). Each new RevRegEntry is published by the Issuer as HCS message in corresponding entries Topic. This approach is described in details in a next section dedicated to RevRegEntries. Notably, since RevRegEntries are stored in a separate HCS Topic, RevRegDef remains unchanged and works well with HCS-1 File immutability concept.

§ RevRegDef creation and publishing

The following process MUST be followed to create and publish AnonCreds RevRegDef rooted to a Hedera DID:

As Issuer, create AnonCreds RevRegDef object
Create HCS Topic that will be used to store associated RevRegEntries
- Use key from Issuer DID Document as Topic submitKey
- Do not set Topic adminKey
Build HCS-1 File content as following (JSON representation): { "revRegDef": <rev-reg-def-object>, "hcsMetadata": { "entriesTopicId": "<entries-topic-id>" } }
Publish the content as HCS-1 File
Use HCS-1 File Topic ID to build RevRegDef identifier: <issuer-did>/anoncreds/v1/REV_REG_DEF/<hcs1-file-topic-id>

§ RevRegDef resolution

The following process MUST be followed to resolve AnonCreds RevRegDef rooted to a Hedera DID:

Parse RevRegDef identifier and retrieve HCS-1 File Topic ID
Use retrieved Topic ID to resolve corresponding HCS-1 File
Retrieve RevRegDef object from revRegDef field of HCS-1 File content

§ RevRegDef example

The following is an example AnonCreds RevRegDef HCS-1 File (with long values truncated with ellipses), with the identifier: did:hedera:testnet:z59hbwYATdKtDQHb15rq6wj7BABcToWF4nTA8GH9X6Kf6_0.0.5422052/anoncreds/v1/REV_REG_DEF/0.0.5422060

HCS Topic Memo: 58fecf1d37955c058b5015f151d3b7c001e900062541f6a939f6529c2f0020b3:zstd:base64

Resolved HCS Messages (raw HCS-1 chunks):

[
  {
    "o": 0,
    "c": "data:application/json;base64,KLUv/WBBBA0aAApErAspEI2oDdySWov/..."
  },
  {
    "o": 1,
    "c": "lxpi5LyaGeCXS9PRZYlVOUxvb51xVtYepzi01Ws83eWH71YzSkaV0+sjMij3k..."
  }
]

Resolved HCS-1 content:

{
  "revRegDef": {
    "issuerId": "did:hedera:testnet:z59hbwYATdKtDQHb15rq6wj7BABcToWF4nTA8GH9X6Kf6_0.0.5422052",
    "type": "CL_ACCUM",
    "credDefId": "did:hedera:testnet:z59hbwYATdKtDQHb15rq6wj7BABcToWF4nTA8GH9X6Kf6_0.0.5422052/anoncreds/v1/PUBLIC_CRED_DEF/0.0.5422058",
    "tag": "0",
    "value": {
      "publicKeys": {
        "accumKey": {
          "z": "1 1D014..."
        }
      },
      "maxCredNum": 1000,
      "tailsLocation": "http://tails:6543/hash/UHfhXnK27vdYML9jgHvb6tPwa5HfDnARgmEFbxNC3cQ",
      "tailsHash": "UHfhXnK27vdYML9jgHvb6tPwa5HfDnARgmEFbxNC3cQ"
    }
  },
  "hcsMetadata": {
    "entriesTopicId": "0.0.5422059"
  }
}

§ AnonCreds RevRegEntry

An AnonCreds RevRegEntry is published to Hiero as HCS message in a separate HCS Topic linked to corresponding RevRegDef.

RevRegEntry is an object that contains the “delta” of the revocation registry state (indexes of revoked and/or issued credentials) and the associated accumulator values (previous and current). Each RevRegEntry, being a separate HCS message, has a consensus timestamp that can be used for restoring revocation registry state for certain moment in time.

Unlike other AnonCreds objects, RevRegEntries are not stored as HCS-1 Files, do not have an identifiers and discovered through associated RevRegDef object. An Issuer publishes RevRegEntry messages to entries HCS Topic specified in the RevRegDef. As noted earlier, since the RevRegDef object does not change, it’s HCS-1 File remains the same.

Holders, when generating a presentation using the revocable verifiable credential, retrieve the RevRegDef identifier from an AnonCreds verifiable credential issued to them. The Holder/Verifier party then resolves RevRegEntries published before appropriate timestamp (based on the requirements in the presentation request) and builds the revocation list state based on state “deltas” from resolved RevRegEntries.

§ RevRegEntry creation and publishing

The following process MUST be followed to create and publish AnonCreds RevRegEntry associated with RevRegDef rooted to a Hedera DID:

As Issuer, create AnonCreds RevRegEntry object containing revocation registry state “delta” and corresponding accumulator values
- Depending on AnonCreds implementation, it may be required to calculate state “delta” from current and previous revocation status lists (as revoked/issued indexes diff)
Resolve associated RevRegDef HCS-1 File using given identifier
- In relevant AnonCreds implementations, AnonCreds RevRegDef identifier is provided for both registration and update operations on revocation list
Retrieve entries HCS Topic ID from hcsMetadata.entriesTopicId value from resolved HCS-1 File
Serialize RevRegEntry object and compress it using zstd compression algorithm
Build RevRegEntry HCS message content as following (JSON representation): { "payload": <compressed-entry-data-base64> }
Publish HCS message to entries HCS Topic

§ RevRegEntry resolution

The following process MUST be followed to resolve AnonCreds RevRegEntries associated with RevRegDef rooted to a Hedera DID:

Resolve associated RevRegDef HCS-1 File using given identifier
Retrieve entries HCS Topic ID from hcsMetadata.entriesTopicId value from resolved HCS-1 File
Use retrieved Topic ID to resolve RevRegEntries HCS messages (all or for a given timestamp)
Decompress (using zstd compression algorithm) and parse payload fields of HCS messages to get RevRegEntries objects
Use state “deltas” to build revocation list state (current or for a given timestamp)

§ RevRegEntry example

The following is an example AnonCreds RevRegEntry associated with AnonCreds RevRegDef with identifier did:hedera:testnet:zDeiGABWuBLu9bbw4NFLSYbB8p14ZPRwTNefow18w7mvC_0.0.6236034/anoncreds/v1/REV_REG_DEF/0.0.6236039

Entry HCS Message:

{
  "payload": "KLUv/WB0AtUJADYcSRtwS9IB5vkHky5rCgEfkYnQ0qRlZDMPQuv/fyVGADwAP..."
}

Entry content:

{
  "ver": "1.0",
  "value": {
    "accum": "21 12001...",
    "prevAccum": "21 12001...",
    "revoked": [
      0,
      9
    ]
  }
}

§ Security Considerations

The security model for Hiero AnonCreds Method relies on the inherent security properties of Hedera DID Method and Hedera network (specifically HCS consensus and finality). Key considerations include:

It’s mandatory to apply strict control over DID and signing keys by following DID Security Guidelines and Hedera DID Method Security section
Object resolvers MUST validate identifiers and signatures against the Issuer’s DID Document
The use of identifiers, particularly public and persistent identifiers like Schema and CredDef identifiers, can create risks of correlation. When the same CredDef identifier is used across multiple contexts or interactions, it allows observing parties (including websites, applications, and resolvers) to link those activities together. This correlation can potentially reveal sensitive information about the behavior or relationships of the party (Issuer/Holder/Verifier) without consent
To mitigate DoS risks associated with open topics or compromised submitKeys, operators SHOULD consider:
- Setting an appropriate submitKey on the HCS Topic and managing it securely
- Rotating the HCS Topic submitKey periodically, if feasible within their operational model
- Implementing monitoring on HCS Topics (e.g., via mirror nodes) to detect unusual activity or spam volume
- Designing resolvers to be resilient to invalid messages (efficiently filtering them out based on proof validation)
It’s recommended to use official mirror nodes for resolving HCS messages (Mirror Node Guide)
Since HCS-1 Files are immutable, creating a new version of AnonCreds object requires a new HCS-1 file to be published in a separate HCS Topic. This means that different versions of the same AnonCreds object (for example, AnonCreds Schema) are not linked to each other and can be resolved only via unique identifiers

§ References

ANONCREDS: AnonCreds. Mike Lodder; Stephen Curran; 2023-01-27. Status: Internet Draft.
DID-CORE: Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.
HCS-1: HCS-1 Standard: File Data Management with Hedera Consensus Service. Michael Kantor; 2024-02-19. Status: Published Hashgraph Standard.

§ Hiero AnonCreds Method Version Changelog

Lists of substantive changes in each version of the specification.

Version 0.1
- Initial version of the specification

§ The Hiero AnonCreds Methodv0.1 / Editor’s Draft

§ Abstract

§ Definitions

§ Hiero AnonCreds Method Specification

§ Overview

§ Contradictions with HIP-762

§ Hedera Consensus Service (HCS) Overview

§ AnonCreds Objects

§ AnonCreds Schema

§ Schema creation and publishing

§ Schema resolution

§ Schema example

§ AnonCreds CredDef

§ CredDef creation and publishing

§ CredDef resolution

§ CredDef example

§ AnonCreds RevRegDef

§ RevRegDef creation and publishing

§ RevRegDef resolution

§ RevRegDef example

§ AnonCreds RevRegEntry

§ RevRegEntry creation and publishing

§ RevRegEntry resolution

§ RevRegEntry example

§ Security Considerations

§ References

§ Hiero AnonCreds Method Version Changelog

§ The Hiero AnonCreds Method
v0.1 / Editor’s Draft