HIP 1219: Hedera DID Method v2.0 - W3C Controller Alignment

[ChangoBuitrago]

Hello everyone,

This is the official discussion thread for the new Hedera Improvement Proposal (HIP) that defines Hedera DID Method v2.0.

The full draft of the HIP can be found here.

We believe this HIP represents a critical step forward for decentralized identity on Hedera. By fully aligning the did:hedera method with the W3C DID Core standard for controller-based authorization, this proposal unlocks greater interoperability with the global self-sovereign identity (SSI) ecosystem. It enables robust security practices like on-demand key rotation and flexible governance models such as multi-controller DIDs, making Hedera a more powerful and standards-compliant platform for identity solutions.

---

Abstract

This HIP proposes version 2.0 of the Hedera DID Method (did:hedera), designed for full alignment with the W3C Decentralized Identifiers (DIDs) v1.0 specification regarding controller management. While retaining the existing v1.0 DID identifier format (did:hedera:<network>:<base58-key>_<topic-id>), v2.0 fundamentally changes the authorization model. The <base58-key> component, typically derived from the initial creation key, serves strictly as part of the unique identifier and does not grant ongoing control authority under v2.0 rules. Instead, v2.0 mandates the use of the controller property within the DID document as the sole source of authority. Control operations (like updates or deactivations) are authorized via W3C-compliant cryptographic proofs generated by keys associated with the designated controller(s) and included in Hedera Consensus Service (HCS) messages. This enhances flexibility, enables multi-controller scenarios, simplifies key rotation, increases interoperability, and aligns Hedera DIDs with global standards. This version's ruleset is intentionally not backwards compatible with the v1.0 Hedera DID Method specification.

---

We welcome and encourage feedback, questions, and suggestions from the community. Please read through the full HIP linked above and share your thoughts in this thread.

[AlexanderShenshin]

Hi @ChangoBuitrago, great job on v2.0 specification!
Changes and clarifications regarding DID Controller and better alignment with W3C DID Core spec in general are significant improvements.

I have some questions/comments on the HIP and the spec itself:

1. Proposed spec uses full DID Document state in HCS messages (for 'create' and 'update' operations) and it's reasonable as we're introducing W3C Data Integrity proofs.
   It's quite significant change that affects approach for HCS storage and I think it makes sense to focus more attention here:

   • There is no universal size limit for DID Documents
   • The HIP addresses implications of transporting large DID messages over HCS and suggests to rely on built-in chunking functionality of Hiero SDKs
     • It also has some focus on default parameters of chunking: They [developers] can trust the SDK to perform the necessary chunking automatically within these default parameters for reliable HCS transmission
     • Does it mean that max payload size of 20KB defined by default settings in SDKs is considered sufficient for most cases?
     • Do we know of any SDKs limitations for chunking functionality?
       • I think it's possible to define chunking settings per transaction based on DID Documents size, but I'm wondering if there are guarantees that such "dynamic" approach will work for general case

2. Another thought that I got while reading the spec - it would be good to mention/describe performance and cost implications regarding Topic Association Models:
   Shared HCS Topic vs HCS Topic per DID -> worse read operations performance vs additional costs for Topics creation

[ChangoBuitrago]

Hi @AlexanderShenshin,

Thank you for the kind words on the v2.0 specification! It was a true collaborative effort between my THA team mate, @sydor-leocode, and myself.

We really appreciate your excellent feedback and insightful questions! It's great to get this kind of detailed input, especially given the important work you and the DSR team are doing on Hiero to bring robust ACA-Py support to the Hedera identity ecosystem.

You've hit on two very practical operational considerations that are crucial for real-world implementation. Let's address your points directly:

---

DID Document Size & HCS Chunking

You are correct. The shift to including the full didDocument state and a cryptographic proof object in each message makes total message size a key consideration. The specification is designed to rely on the Hedera SDK's chunking functionality to handle this.

On the 20KB Default Payload Size

Does it mean that max payload size of 20KB defined by default settings in SDKs is considered sufficient for most cases?

Yes, that is the core assumption. A 20KB limit for the combined DID Document and its proof is quite generous and should be sufficient for the vast majority of common use cases. A typical DID document, even with several keys and services, combined with a compact proof type like Ed25519Signature2020, is usually well under this limit. This default provides a reliable "out-of-the-box" experience.

However, we acknowledge that for DID documents containing large amounts of data (like many embedded JWKs) or those using proof suites that generate larger proofs (like BBS+), the total message size can grow, making the SDK's configurability essential.

On SDK Chunking Limitations and Dynamic Settings

Do we know of any SDKs limitations for chunking functionality? I think it's possible to define chunking settings per transaction... I'm wondering if there are guarantees that such "dynamic" approach will work for general case

You are spot on here. The key points are:

• The main "limitation" is the maximum number of chunks the network accepts for a single logical message, which the SDKs default to 20.
• This is configurable. The Hedera SDKs (e.g., ConsensusMessageSubmitTransaction) allow developers to override the defaults on a per-transaction basis by using methods like setMaxChunks() and setChunkSize().
• This "dynamic" approach is a standard feature of the SDKs and is the intended solution for handling edge cases with exceptionally large payloads. If an application anticipates submitting a large DID document, it can and should adjust the chunking parameters for that specific transaction, provided it stays within the absolute network limits.

Topic Association Models: Performance & Cost Implications

That's a great suggestion, and you've perfectly summarized the trade-off. We agree that making this explicit in the specification will benefit implementers. We will add a more detailed note to the specification to clarify these implications, and the thinking is as follows:

Dedicated Topic Model (One Topic per DID)

• Cost: This model requires a distinct ConsensusCreateTopicTransaction for each DID, incurring the associated network fee for every DID created. This can become a significant factor for applications needing to provision thousands or millions of DIDs.
• Resolution Performance: This approach offers optimal resolution performance. When a resolver queries the topic associated with a specific DID, it can be confident that every message on that topic is relevant. This leads to faster lookup times, lower data transfer from mirror nodes, and reduced computational load.
• Isolation: It provides strong logical isolation. The activity on one DID's topic does not interfere with another's, simplifying monitoring and reducing the "noise" a resolver must process.

Shared Topic Model (Many DIDs per Topic)

• Cost: This is the primary benefit. A single HCS topic can be created once, and its ID can be reused in the identifiers of many DIDs. This dramatically reduces on-chain creation costs, making it highly suitable for applications that manage large volumes of DIDs (e.g., for IoT devices or customers).
• Resolution Performance: The trade-off is a potential decrease in resolution performance. A resolver must fetch all messages from the shared topic and perform a critical first filtering step by inspecting the top-level did property on every message, discarding those not relevant to the target DID. This can increase data transfer, memory usage, and CPU load on the resolver, especially for topics with very high message throughput.
• Use Case: This model is ideal for systems where cost-efficiency for DID provisioning at scale is a higher priority than per-resolution performance, and where a single entity manages the related cohort of DIDs.

---

Thank you again for the valuable feedback; please keep the questions coming.

[AlexanderShenshin]

@ChangoBuitrago Thank you for great in-depth answers!

Both points are addressed very well and clear, I will let you know if me or someone from our team will have other questions or thoughts to share.

And regarding performance & costs implications - this is exactly what I was thinking about.
Such implications and use cases comparison is a valuable guidance for implementors. It can be extensive, of course - if you or Sydor start thinking that it will "bloat" the specification, I think it will be good enough if we have this in appendix or a separate section.

[ChangoBuitrago]

Hi @AlexanderShenshin,

Thanks for the follow-up! That's a really sharp point about document structure and avoiding bloat in the core specification, and we agree.

To be transparent, our initial thinking was to place detailed guidance on cost and performance trade-offs in the documentation for the reference implementation, which is the approach we took for the v1.0 SDK. We actually have specific guides there covering both topic models and transaction costs:

• v1.0 SDK Guide: Single vs. Shared Topic Guide
• v1.0 SDK Guide: Transaction Costs Guide

However, you raise a good point that this information is too important to leave out of the main specification entirely. We think the right balance is to include a more concise, non-normative note about the Topic Association Models directly in the v2.0 spec to ensure all implementers are aware of the trade-offs, as you suggested.

We will proceed with adding that concise note to the spec. Thanks again for helping us improve the document!

Best regards.