Hedera Technical Insights:​ Maintaining a decentralized identity registry with Hedera
Aug 24, 2020
by Paul Madsen
Head of Identity, The HBAR Foundation

Verifiable Credentials (VC) and Decentralized Identifiers (DIDs) are two different but related identity standards progressing in the W3C – both of which allow for a Decentralized Ledger Technology (DLT) to provide supporting infrastructure. A VC is an attestation of a set of identity claims or attributes of a Subject, as asserted by an Issuer. The archetypical VC is a driver’s license – the Subject of the VC is the driver, and the Issuer is the DMV. It is by presenting their license to police or similar that a driver proves they passed the test and have the right to drive.

For a VC to be useful, it will generally need to identify both the Subject (the driver) and the Issuer (the DMV). The VC standard doesn’t mandate a particular format for these identifiers; for instance, they could be email addresses or some other existing format. DIDs offer one option for these identifiers with some notable characteristics. Unlike an email, a DID is resolvable; that is, the identifier itself, like a domain or web address, can be used to retrieve a related set of information. Upon being presented with a DID for Alice, Bob can resolve the DID into a DID Document carrying associated metadata about Alice’s identifier, most notably cryptographic keys and addresses of other endpoints connected to Alice.

VCs and DIDs, used together, enable a useful reusable authentication and authorization pattern. Below is one manifestation:

  1. Alice and Bob initiate an online engagement. Perhaps this is Alice applying for a bank account at BobBank.com, or Bob authenticating to Workforce.Alice.com at the start of a shift to receive his work assignment for the day
  2. Both determine they need certain identity attributes of the other and indicate those requirements
  3. Both determine which of their existing VCs satisfy the requirements of the other
  4. Both deliver the appropriate VC (or some Presentation derived from the VC) to the other, along with a cryptographic Proof that they do indeed control the VC
  5. Both extract the DIDs from within the VC, and resolve the DID into the DID Document metadata. How this resolution manifests depends on how and where the registry is maintained.
  6. Both use the metadata from the DID Document in order to validate the VC of the other. Validation will consist of verifying digital signatures, both that of the Issuer on the VC and that of the Subject on the Proof
  7. Both check that the VC of the other is still valid; that is, was not suspended or revoked since being first issued
  8. Both, confident in the identity of the other, proceed with the engagement

Other identity architectures, such as X.509 certificates or federated models, such as SAML and OpenId Connect, enable the same logical model of Alice and Bob being able to prove identity attributes to the other, but make different assumptions about details such as 1) how tightly bound are the public keys to the VCs, 2) whether the issuer is involved in run time, and 3) which party controls (for instance, can update the metadata for) a given identifier. As such, VCs and DIDs can offer a useful (in that they can offer a different combination of privacy, security, etc) additional option to existing architectures and standards.

It is in steps #5 and #7 that a DLT like Hedera can provide value to the architecture. Fundamentally, a DLT can enable a decentralized (with advantages for trust, security, censorship resistance, fault tolerance, etc) registry of the identity metadata that Alice and Bob require to be able to validate the VCs of the other. Rather than querying some single centralized store of the identity metadata, both Alice and Bob can query any one of the parties that maintain the duplicate copies of the metadata. Or Alice and Bob could even maintain a copy of the registry themselves, giving them even greater confidence that the registry is valid and up to date.

Of course, the characteristics of the consensus algorithm that underlies the DLT will impact the characteristics of any identity registry built on top. If the underlying consensus algorithm is slow, then so will be the registry. For Bob to be able to query the registry for Alice’s metadata requires that the metadata has been previously registered on the registry via the DLT. And DLTs vary widely in the throughput and latency of such write operations.

In order to optimize performance, Hedera’s architecture for DIDs and VCs uses the Hedera Consensus Service (HCS). The registry of identity metadata is not maintained by the mainnet nodes, but rather by the nodes of an application network (appnet). It is against the members of the appnet that DIDs are resolved and VCs have their revocation status checked. In the HCS model, the mainnet nodes only timestamp and order the messages that change the registry; for instance uploading a DID Document or revoking a VC. Because the mainnet nodes do not bear the burden of maintaining the registry, with the associated writes and reads from a database, they can focus solely on their more fundamental role, that of establishing consensus timestamps and order for those messages. Consequently, Hedera can support a very high throughput for the transactions that update the registry.

The registry is updated by appropriately structured HCS messages sent to the mainnet and then subsequently retrieved from a mirror node. The following message will create a new entry in the registry that contains the DID and the corresponding DID Document.

 "mode": "plain",
 "message": {
 "operation": "create",
 "did": "did:hedera:mainnet:7Prd74ry1Uct87nZqL3ny7aR7Cg46JamVbJgk8azVgUm;hedera:mainnet:fid=0.0.123",
 "didDocumentBase64": "ewogICJAY29udGV...9tL3ZjLyIKICAgIH0KICBdCn0=",
 "timestamp": "2020-04-23T14:37:43.511Z"
 "signature": "QNB13Y7Q9...1tzjn4w=="

The above JSON would be sent as the contents of an HCS SubmitMessage transaction to a mainnet node for submission to the rest of the network and subsequent assignment of a consensus timestamp (different from the timestamp in the sample above). The transaction would be submitted to an HCS Topic, necessarily previously created on the mainnet and be assigned a place within that Topic’s order. As for other transactions, the client would pay a fee for the processing of the transaction. For an HCS message this fee is approximately $0.0001. After being assigned a consensus timestamp and order within the above Topic, the message would flow out to the mirrors – from which the members of the appnet would retrieve the message via an existing subscription. The members of the appnet would then add the DID Document from within the message to the identity registry such that the DID Document would then be available to be returned in response to any future resolution queries. From the time the HCS message is sent to the mainnet to the time a member of the appnet retrieves it from a mirror node is typically on the order of 10 seconds.

Because the identity registry is maintained on an appnet and not the mainnet, queries against the registry happen in two steps.

Below is a representative DID registered on a Hedera appnet:


If a client were presented the above DID (for instance if the DID was provided as the Issuer of a VC), then the client would process the DID as follows:

  1. Parse the file identifier of the appnet address book as ‘0.0.1234’ from the DID
  2. Send a HAPI FileGetContents query to a Hedera mainnet node specifying the above file identifier
  3. Retrieve the JSON formatted address book for the appnet
 "appnetName": "My Application Network",
 "didTopicId": "0.0.12345",
 "vcTopicId": "0.0.23456",
 "appnetDidServers": [

4. Choose one of the appnet member addresses from the address book (there are 3 in this example)
5. Send a GET to the chosen appnet member specifying the remaining portion of the DID


The appnet member would do a lookup from the registry for the corresponding DID Document and return it to the client.

The client would use the metadata (such as public keys) within the returned DID Document to help in any signature validation or associated processing.

A revocation registry for VCs is maintained similarly. When a VC is first issued, a hash of that VC is submitted via an HCS message to a particular HCS Topic. As above, the members of the appnet retrieve that hash from a mirror and store it in the registry. If, in the future, a client sends that hash to an appnet node as part of a revocation check of the VC, then the appnet node returns the latest status for that hash; that is whether it is valid or otherwise. If, after that initial issuance, the Issuer determined that it was necessary to revoke or suspend the VC, then they would send another HCS message indicating that and the appnet members would update the status of the VC within the registry accordingly.