createDID Function

The createDID function is a core component of the Hashgraph DID SDK, responsible for generating new DIDs for the Hedera DID method. It provides a flexible and user-friendly interface, allowing you to customize various aspects of the DID creation process.

Features

  • DID Creation: Generates and registers new DIDs on the Hedera network with customizable options.

  • Key Management: Supports various key types and formats for DID controllers and verification methods.

  • DID Document Generation: Automatically generates DID Documents conforming to the DID specification.

  • Hedera Network Support: Supports DID creation on the Hedera mainnet and testnet.

  • Error Handling: Provides robust error handling for invalid input, network issues, and other potential problems.

  • TypeScript Support: Built with TypeScript to enhance developer experience and type safety.

Creating a DID Document

The following examples demonstrate how to use the createDID function in different scenarios.

With Client Options

You can customize the Hedera network and account used for creating the DID by providing clientOptions to the createDID function.

const clientOptions = {
  privateKey: "0x...", // Replace with your Hedera account private key
  accountId: "0.0.0....", // Replace with your Hedera account ID
  network: "testnet",
};

const { did, didDocument, privateKey } = await createDID({
  clientOptions,
});

In this example, a Hedera Client instance is configured with essential parameters, including the Hedera account private key, account ID, and network. The function then returns the generated private key, the newly created DID, and its corresponding DID document.

See a full running example in the source code.

With a Hedera Client

You can provide a Hedera Client instance directly to the createDID function. This allows for more fine-grained control over the client configuration and network interaction.

const privateKey = "0x..."; // Replace with your Hedera account private key
const accountId = "0.0.0...."; // Replace with your Hedera account ID

const client = Client.forTestnet();
client.setOperator(accountId, privateKey);

const { did, didDocument } = await createDID({
  client,
});

In this example, a pre-configured Hedera Client instance is passed to the createDID function.

See a full running example in the source code.

With a Custom Controller

To modify the controller of a newly created DID, you can specify the desired controller as an argument to the createDID function. However, the provided controller must be a valid DID according to the Hedera method and must be active.

const { did, didDocument } = await createDID({
  controller: "did:hedera:mainnet:...", // Replace with your desired DID controller
}, { client });

In this example, the controller property is used to specify the desired controller for the newly created DID.

See a full running example in the source code.

With a Topic-Specific DID

In certain cases, it may be desirable to create a DID associated with a specific topic. This can be achieved by providing the relevant topic ID to the createDID function. It is important to ensure that the Client or Publisher being passed has the necessary permissions to submit content to that topic.

const { did, didDocument } = await createDID({
  topicId: "0.0.0...", // Replace with your desired topic ID
}, { client });

See a full running example in the source code.

Using Client Managed Secret Mode

In certain instances, keys are managed in a fashion that does not allow direct or indirect access by the SDK. Or you prefer to manage your keys yourself. In such a scenario, Client Managed Secret Mode can be utilized. In this mode, the DID SDK generates a signing request for you, so you can handle the signing process yourself. From it’s design, the process is divided into two steps: generateCreateDIDRequest and submitCreateDIDRequest.

The signing request contains all the necessary information about the algorithm of the signing and data to be signed. The serialized payload of the request is signed by the client and submitted to the SDK. The SDK then processes the request and creates the DID Document.

In order to create a DID using Client Managed Secret Mode, you need to provide a public key in multibase format to the generateCreateDIDRequest function. The public key is used as a DID root key.

const { state, signingRequest } = await generateCreateDIDRequest(
  {
    multibasePublicKey: publicMultibaseRootKey,
  },
  {
    client,
  },
);

const signature = await wallet.sign(signingRequest.serializedPayload);

const { did, didDocument } = await submitCreateDIDRequest(
  { state, signature },
  {
    client,
  },
);

See a full running example in the source code.

You can learn more about the Client Managed Secret Mode in the Key Management Modes Guide.

References