generateUpdateDIDRequest API Reference

This document provides a concise API reference for the generateUpdateDIDRequest function within the Hedera DID SDK for JavaScript.

Function Signature

This function generates a request to update a Decentralized Identifier (DID) on the Hedera network using the Client Managed Secret Mode.

The generateUpdateDIDRequest function is invoked with providers and options parameters. The providers parameter encapsulates configuration parameters for interacting with the Hedera network, while the options parameter enables customization of the DID update procedure and passing required public key.

function generateUpdateDIDRequest(
  options: GenerateUpdateDIDRequestOptions,
  providers: PublisherProviders,
): Promise<UpdateDIDRequest>;

Parameters

The function accepts the following parameters:

  • providers: (Required) An object encapsulating configuration parameters for interacting with the Hedera network.

  • options: (Required) An object containing a public key for DID root key and enabling customization of the DID update procedure.

providers Parameter

The table below details the structure of the providers parameter.

Name Type Description

providers

PublisherProviders

An object containing a Hedera Client or a transaction Publisher (refer to PublisherProviders Type for details).

options Parameter

The table below details the structure of the options parameter.

Name Type Description

options

GenerateUpdateDIDRequestOptions

An object specifying configuration options for DID update request (refer to GenerateUpdateDIDRequestOptions Type for details).

Return Value

Upon successful execution, the function returns a Promise that resolves to a UpdateDIDRequest object.

The table below describes the structure of the UpdateDIDRequest type.

Name Type Description

states

RunnerState<DIDMessage>[]

An array of current states of the DID update process. Each state represents a single operation in the DID update process.

signingRequests

Record<string, SigningRequest>

A map of signing requests to be signed by the client. Each request is associated with a unique key and represents a single operation in the DID update process.

Data Types

This section elaborates on the data types employed within the providers and options parameters.

PublisherProviders Type

To utilize this type, at least one of the following must be defined: client or publisher. If both are provided, publisher takes precedence.

The table below provides a detailed description of the PublisherProviders type.

Name Type Description

clientOptions?

ClientOptions

Configuration options for instantiating a Hedera Client. See a full running example in the source code.

client?

Client

An instance of a Hedera Client. See a full running example in the source code.

publisher?

Publisher

An instance of a Publisher responsible for submitting the DID creation transaction to the Hedera network.

GenerateUpdateDIDRequestOptions Type

The table below provides a detailed description of the GenerateUpdateDIDRequestOptions type.

Name Type Description

did

string

The DID string of the Decentralized Identifier to update.

updates

DIDUpdateOperation | DIDUpdateOperation[]

A DIDUpdateOperation type or an array of DIDUpdateOperation`s (refer to DIDUpdateOperation Type for details). Each `DIDUpdateOperation represents a specific modification to the DID Document. If an array is provided, the operations will be executed in the order they are provided.

topicReader?

TopicReader

An instance of a TopicReader responsible for reading messages from the Hedera network topic.

SigningRequest Type

The table below provides a detailed description of the SigningRequest type.

Name Type Description

payload

object

An object containing the payload of the DID message to be signed.

serializedPayload

Uint8Array

A serialized bytes representation of the DID message payload. Actual bytes to be signed.

multibasePublicKey

string

The public key of the corresponding private key required to sign the request.

alg

string

The algorithm used for signing the request. Currently, only Ed25519 is supported.

DIDUpdateOperation Type

This type represents the different operations you can perform to update a DID Document. Each operation modifies the DID Document in a specific way, such as adding a verification method, removing a service, etc.

AddVerificationMethodOperation Type

Adds a new verification method to the DID Document.

Name Type Description

operation

'add-verification-method'

A constant string representing the operation type.

id

string

A unique identifier for the verification method. Must start with # and be unique within the DID Document, e.g., #key-1.

property

VerificationMethodProperties

A string representing the verification method or relationship property to add. Possible values are: verificationMethod, authentication, assertionMethod, keyAgreement, capabilityInvocation, capabilityDelegation.

controller?

string

The DID that controls the verification method. If not provided, the DID of the DID Document is used.

publicKeyMultibase?

string

The public key in multibase format to add. Optional when adding verification relationship as an alias to an existing verification method. In that case id must be the same as the existing verification method. Otherwise is required. See a full running example in the source code.

AddServiceOperation Type

Adds a new service endpoint to the DID Document.

Name Type Description

operation

'add-service'

A constant string representing the operation type.

id

string

A unique identifier for the service. Must start with # and be unique within the DID Document, e.g., #service-1.

type

string

The type of service to add.

serviceEndpoint

string

The service endpoint to add.

RemoveVerificationMethodOperation Type

Removes an existing verification method from the DID Document.

Name Type Description

operation

'remove-verification-method'

A constant string representing the operation type.

id

string

A unique identifier for the verification method or relationship to remove. Must start with #, e.g., #key-1.

RemoveServiceOperation Type

Removes an existing service endpoint from the DID Document.

Name Type Description

operation

'remove-service'

A constant string representing the operation type.

id

string

A unique identifier for the service to remove. Must start with #, e.g., #service-1.

Errors

The following table enumerates the exceptions that may arise during the execution of the generateUpdateDIDRequest function.

Exception code Description

invalidArgument

Providers must contain client options or client or publisher.

invalidArgument

Hashgraph SDK Client must be configured with a network.

invalidArgument

Hashgraph SDK Client must be configured with an operator account.

invalidArgument

Verification method ID does not exist. Nothing to remove.

invalidArgument

Cannot remove a service using remove-verification-method operation.

invalidArgument

Service id already exists.

invalidArgument

The service endpoint must be a valid URI.

invalidArgument

The ID must be a valid property ID.

invalidArgument

The fragment ID # is already in use for another verification method.

invalidDid

The DID must be a valid Hedera DID.

invalidDid

The controller must be a valid Hedera DID.

notFound

The DID document was not found.

invalidPublicKey

The public key is required for verification methods

invalidPublicKeyLength

Invalid length for the public key.

internalError

DID root key not found in a DID Document.

Function Implementation

The Hashgraph DID SDK provides a generateUpdateDIDRequest function within its registrar package. For further details, refer to the @hashgraph-did-sdk-js/registrar package documentation.