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

Attribute Value

hip

1219

title

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

author

Jakub Sydor <@Harasz>, Pablo Buitrago <@ChangoBuitrago>

requested-by

THA

type

Standards Track

category

Application

needs-hedera-review

No

needs-hiero-approval

No

status

Draft

created

2025-04-16

updated

2025-06-17

discussions-to

https://github.com/hiero-ledger/hiero-improvement-proposals/discussions/1220

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.

Motivation

Version 1.0 of the Hedera DID Method established a functional DID method on Hedera using HCS but tied DID control rigidly to the key embedded in the identifier (referred to as #did-root-key logic). This deviated from the standard W3C controller model, creating significant limitations:

  1. Deviation from W3C Standard: Hindered interoperability with standard DID tools, libraries, and platforms expecting the controller property to define authority.

  2. Rigid Control: Made rotation of the primary controlling key difficult or impossible without changing the DID identifier itself, complicating security best practices and delegation scenarios. Example: Under v1.0, a compromised <base58-key> requires changing the DID identifier entirely to revoke control, disrupting existing integrations. v2.0 allows key rotation via the controller property without altering the DID.

  3. Limited Multi-Controller Support: The v1.0 model’s focus on a single identifier-linked key made native support for multiple controllers, common in organizational or delegated scenarios, cumbersome.

Hedera DID Method v2.0 aims to rectify these issues by fully adopting the standard W3C controller pattern for authorization. This change occurs while retaining the established v1.0 identifier format to ensure naming continuity for existing DID concepts on Hedera. The result is a more flexible, robust, secure, and interoperable DID method aligned with global standards.

This specification defines a new ruleset (v2.0). Existing v1.0 DIDs remain under v1.0 rules; new DIDs must be created under v2.0 for W3C-aligned control. There is no in-place upgrade path from v1.0 to v2.0 for an existing DID identifier.

Rationale

The transition to v2.0 focuses on aligning the authorization and control logic with W3C DID Core v1.0 principles, separating the identifier string from the control mechanism, while preserving the existing DID identifier structure to avoid disrupting established naming conventions.

Key Design Decisions for v2.0:

  • Retain v1.0 Identifier Format: The DID format remains did:hedera:<network>:<base58-key>_<topic-id>. The <base58-key> provides a stable identifier component linked to the DID’s origin but is explicitly decoupled from ongoing authorization rights in v2.0.

  • W3C Controller Model: Adopt the controller property within the DID Document as the sole mechanism for defining authorization to manage the DID. The v1.0 concept of the embedded key (#did-root-key derived from <base58-key>) having special, inherent control privileges post-creation is removed.

  • Proof-Based Authorization: DID operations (Create, Update, Deactivate) submitted via HCS require a cryptographic proof (following the W3C Data Integrity model [VC-DI-1.0]) included within the HCS message envelope. This proof MUST be verifiable against a verification method authorized by the DID’s designated controller(s).

  • HCS as Transport Layer: HCS remains the underlying transport, providing immutable, timestamped ordering for DID operation messages via the topic identified by topic-id. However, HCS topic permissions (submitKey) are distinct from DID controller authorization.

  • HCS Transport for Large DID Messages: This DID method requires transporting potentially large DID documents or complex cryptographic proofs (like those using verbose formats such as JSON Web Keys - JWKs). Hedera Consensus Service (HCS) provides a suitable transport layer, primarily leveraging the automatic message chunking capabilities built into the official Hedera SDKs. While any single Hedera transaction is limited to 6144 bytes (6 KB), the SDKs automatically handle larger payloads. By default, they segment messages into chunks with 1024-byte (1 KB) payloads, supporting up to 20 chunks per message. This allows for a default maximum total message size of 20 KB, handled transparently by the SDK. This built-in functionality ensures HCS effectively handles the data volumes required for DID documents and associated proofs.

  • Clear Versioning (Ruleset): Explicitly define this as the v2.0 ruleset, which is not backwards compatible with v1.0 rules. Resolvers and applications need to interpret HCS messages according to the ruleset version applicable to the DID. Resolvers MAY infer the DID method version by inspecting the earliest HCS message(s) in the topic. v2.0 messages MUST include a top-level version: "2.0" field to self-identify.

  • Conflict Resolution: HCS consensus timestamp order determines state precedence. Resolvers MUST process messages sequentially within the topic, accepting the latest valid state change or operation according to the timestamp. In cases of simultaneous conflicting messages within the same consensus second, the message with the lower sequence number takes precedence.

User stories

  • As a DID Controller, I want to assign multiple DIDs (belonging to other individuals or organizations) as controllers of my DID so that they can manage it on my behalf according to W3C standards.

  • As a DID Controller, I want to rotate the keys associated with controlling my DID without changing the DID identifier itself, adhering to security best practices.

  • As an application developer, I want to use a Hedera DID method that is fully compliant with the W3C DID Core controller specification for seamless interoperability with standard DID libraries and tools.

  • As a DID Subject, I want my DID identifier to remain stable and persistent, even if the underlying controlling keys or authorities change over time.

Specification

The detailed specification for Hedera DID Method v2.0, including precise message formats, proof requirements, and state transition rules, is currently under development and review. The draft specification can be found in the dedicated repository: Hedera DID Method v2.0 Specification.

Key aspects defined by the v2.0 specification include:

  1. HCS Message Structure: All v2.0 DID operation messages submitted to HCS MUST be JSON objects constituting the immutable message content. They MUST contain at least the following top-level fields:

    • version: MUST be the string "2.0" to identify the ruleset.

    • did: A string containing the full DID to which the operation applies (e.g., "did:hedera:testnet:…​"). This field is mandatory.

    • operation: A string indicating the operation type (e.g., "create", "update", "deactivate").

    • proof: A proof object whose structure and processing model are based on the W3C Verifiable Credential Data Integrity v1.0 specification [VC-DI-1.0]. It MUST conform to a specific Data Integrity cryptosuite specification (e.g., eddsa-jcs-2022, bbs-2023) supported by this DID method. This proof authorizes the operation, MUST be verifiable against a verification method associated with the DID’s current controller, and SHOULD typically use a proofPurpose like "capabilityInvocation" to signify control assertion.

    • Operation Payload Fields: Additional fields specific to the operation (e.g., didDocument required for "create" and "update" operations carries the DID document data).

      // Example Create Message Structure
{
  "version": "2.0",
  "did": "did:hedera:testnet:z6MkipomYgdGz1MXBm5ZJNVNVqTgumeMboAy3fCpd_0.0.645701",
  "operation": "create",
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1",
      "https://w3id.org/security/multikey/v1",
      "https://w3id.org/security/suites/jws-2020/v1"
    ],
    "id": "did:hedera:testnet:z6MkipomYgdGz1MXBm5ZJNVNVqTgumeMboAy3fCpd_0.0.645701",
    "controller": "did:hedera:testnet:z6MkipomYgdGz1MXBm5ZJNVNVqTgumeMboAy3fCpd_0.0.645701",
    "verificationMethod": [
      {
        "id": "did:hedera:testnet:z6MkipomYgdGz1MXBm5ZJNVNVqTgumeMboAy3fCpd_0.0.645701#key-1",
        "type": "Multikey",
        "controller": "did:hedera:testnet:z6MkipomYgdGz1MXBm5ZJNVNVqTgumeMboAy3fCpd_0.0.645701",
        "publicKeyMultibase": "z6MkipomYgdGz1MXBm5ZJNVNVqTgumeMboAy3fCpd"
      }
      // ... other verification methods omitted ...
    ],
    "capabilityInvocation": [
      "did:hedera:testnet:z6MkipomYgdGz1MXBm5ZJNVNVqTgumeMboAy3fCpd_0.0.645701#key-1"
    ]
    // ... other sections like authentication, service omitted ...
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2025-04-30T12:00:00Z",
    "verificationMethod": "did:hedera:testnet:z6MkipomYgdGz1MXBm5ZJNVNVqTgumeMboAy3fCpd_0.0.645701#key-1",
    "proofPurpose": "capabilityInvocation",
    "proofValue": "z5uJVg3hJn5fL8gK1fG5hV6fK8gL3kH7jR9wQ4bD5pT2mN1rS7yZ3xW"
  }
}

  2. Controller Scope: The controller field within a DID Document MUST reference one or more DIDs. These controller DIDs MUST reside on the same Hedera network (e.g., mainnet, testnet) as the DID Document they govern. A did:hedera:testnet:…​ controller cannot manage a did:hedera:mainnet:…​ DID, and vice-versa. Cross-network control is unsupported.

  3. Resolution Process: Defines how resolvers fetch HCS messages, validate version, sequence messages by consensus timestamp, validate proofs against the designated controller(s) at each step, and reconstruct the current DID Document state.

Backwards Compatibility

This specification defines the ruleset for Hedera DID Method v2.0. It is intentionally not backwards compatible with the v1.0 ruleset due to the fundamental change in the authorization model (from identifier-linked key to controller property and proofs).

v2.0 is a parallel ruleset; existing v1.0 DIDs cannot be converted to v2.0. New DIDs created under v2.0 will use the same identifier format but follow distinct control rules defined in this specification.

Resolvers and applications interacting with did:hedera DIDs will need to determine the applicable version (v1.0 or v2.0) and apply the corresponding ruleset for interpretation and validation. As noted in Rationale, v2.0 messages self-identify with a version: "2.0" field, aiding this determination. Mechanisms for handling DIDs created before v2.0’s introduction might involve heuristics or rely on the creation context.

Security Implications

The security model for Hedera DID Method v2.0 relies on the inherent security of the Hedera network (via HCS) and the robustness of the W3C controller model and cryptographic proofs.

  1. Identifier Component Roles (v2.0 Rule):

    • Crucial Distinction: The <base58-key> component within the DID identifier string (did:hedera:<network>:<base58-key>_<topic-id>) serves only as part of the unique identifier after the initial creation operation. It does not grant ongoing control authority or authorization privileges for managing the DID document under v2.0 rules. Control is solely determined by the controller property within the DID document and verified via the proof mechanism. Misunderstanding this is a security risk.

  2. Controller Authority & Compromise:

    • Primary Trust Anchor: The security of a v2.0 Hedera DID rests primarily on the security of the DID(s) designated in its controller property and their associated cryptographic keys. Control authority is explicitly defined by this property.

    • Controller Compromise: The most significant threat is the compromise of a designated controller’s keys. An attacker gaining control of a controller gains full authority to modify (including changing the `controller) or deactivate the Hedera DID documents managed by it.

    • Key Management: Robust key management practices (secure generation, storage, rotation, revocation) for all keys associated with controller DIDs are essential for maintaining the security of the Hedera DIDs they control.

  3. HCS Topic Interaction & Access Control:

    • submitKey Role (Network Permission): The HCS topic submitKey controls the network-level permission to submit messages (valid or invalid) to the DID’s associated topic. Compromising the submitKey allows an attacker to potentially disrupt the DID by submitting spam or malformed messages (DoS risk, increased resolution cost).

    • controller Proof Role (Logical Authorization): The submitKey does not grant the ability to submit validly authorized state changes. Logical authorization to modify the DID state requires a valid cryptographic proof generated by the DID’s controller.

    • Distinct Controls: Implementers and users must understand the clear separation between HCS topic write access (submitKey) and DID logical control (controller proof).

    • SubmitKey Mitigation Strategies: To mitigate DoS risks associated with submitKey compromise, operators SHOULD consider:

      • Rotating the HCS topic submitKey periodically, if feasible within their operational model.

      • Implementing monitoring on HCS topics to detect unusual activity or spam.

      • Potentially using HCS topic metadata or application-level logic to flag or ignore messages submitted by known malicious actors (though this is outside the core DID method spec).

  4. Validation Responsibility:

    • Neither Hedera network nodes nor standard mirror nodes validate DID document semantics or controller proofs. This validation must be performed by DID resolvers and client applications according to the v2.0 specification rules (verifying proofs against the controller’s keys). Failure to validate proofs correctly breaks the security model.

    • Resolver Validation Requirements (Anti-Patterns to Avoid): Resolvers MUST:

      • Strictly follow the HCS consensus timestamp ordering for messages.

      • Reject any v2.0 message that lacks a proof field or contains an invalid or unverifiable proof.

      • Validate that the top-level did in the HCS message matches the didDocument.id when didDocument is present.

      • When processing an update that changes the controller property, validate the operation’s proof against the previous (currently authorized) controller’s keys.

      • Reject messages with incorrect version fields or malformed structures.

How to Teach This

Effective education for Hedera DID Method v2.0 should focus on its W3C controller alignment and the separation of identifier from control. Guidance for documentation, tutorials, and client implementations should emphasize:

  • W3C Controller Authority: Clearly state that the controller property in the DID Document exclusively defines who can authorize changes, aligning with W3C DID Core standards.

  • Identifier vs. Control: Explicitly teach that the <base58btc-key> component in the DID string (did:hedera:<network>:<base58btc-key>_<topic-id>) is part of the identifier only and grants no control rights after creation under v2.0 rules. This distinction is crucial and a major change from v1.0.

  • Proof-Based Operations: Explain that DID lifecycle operations (Create, Update, Deactivate) require a cryptographic proof within the HCS message, generated by a key authorized by the designated controller. Detail the purpose and verification of these proofs, noting they follow the W3C Data Integrity model [VC-DI-1.0].

  • HCS Role vs. Controller Role: Define HCS (via topic-id) as the immutable message transport/ordering layer. Explain that the HCS submitKey grants topic write permission, which is separate from the DID’s logical controller authorization required for valid state changes via proofs.

  • Developer Guidance on SDK Message Size Handling: Emphasize to developers that Hedera SDKs automatically and transparently manage the chunking required for large HCS messages. While providing context is helpful—explaining the 6 KB network limit per transaction versus the SDK’s default chunking strategy (1 KB payloads, max 20 chunks, yielding a 20 KB total message default)—the primary message is that the SDK handles this complexity. Developers should be taught to use standard functions (e.g., ConsensusSubmitMessageTransaction().setMessage(…​)) directly, even with potentially large payloads like DID documents or verbose proofs (e.g., JWKs). They can trust the SDK to perform the necessary chunking automatically within these default parameters for reliable HCS transmission.

  • Resolver Logic: Explain the v2.0 resolution process, emphasizing the need for resolvers to fetch HCS messages, validate proofs against the current controller, and reconstruct the DID document state sequentially.

  • Code Examples: Provide practical code examples (e.g., based on the PoC) for core workflows:

    • Creating a DID specifying the initial controller and generating the initial proof.

    • Resolving a DID according to v2.0 logic (including proof validation).

    • Authorizing an Update/Deactivate operation by generating the proof as the controller.

    • Submitting operations via the Hedera SDK (including the full message structure: did, operation, didDocument, and proof).

  • Documentation Clarity: Ensure documentation prominently clarifies the non-controlling role of the <base58btc-key> in v2.0 and highlights the mandatory proof validation step for resolvers. Structure guides around the key principles and lifecycle operations (Create, Resolve, Update, Deactivate).

Reference Implementation

A Proof of Concept (PoC) serves as the initial reference implementation for this specification. It demonstrates and validates the core mechanisms of v2.0, providing runnable examples for key features such as controller-based authorization and key rotation. The PoC can be found in the dedicated repository: Hedera DID Method v2.0 Proof of Concept.

To ensure interoperability and compliance with this specification, implementers (of SDKs, resolvers, or applications interacting with did:hedera) SHOULD validate their implementations against standardized test vectors. These test vectors should cover various scenarios, including:

  • Valid and invalid message structures.

  • Correct and incorrect proof generation and verification (for supported signature types).

  • Single and multi-controller scenarios.

  • Controller rotation operations.

  • Deactivation and resolution of deactivated DIDs.

  • Handling of message ordering and conflict resolution. NOTE: A dedicated repository or section within the specification project should host these test vectors.

References

Copyright/license

This document is licensed under the Apache License, Version 2.0 — see Apache License, Version 2.0