1 of 1

Create a DID

Create a Decentralized Identifier (DID) using the cheqd Cosmos CLI.

The purpose of this document is to describe how a DID (and associated DIDDoc) can be created using the cheqd-node Cosmos CLI.

NOTE: The guidance below is only recommended to be used for testing purposes!
Using cheqd-node Cosmos CLI for real-world production environments is not recommended, since the identity keys are passed in raw form to the CLI. This is fine in development/testing usage, but is not recommend for mainnet.
Developers are encouraged to use production-grade CLI tools such as Veramo SDK for cheqd or look at our developer guide on how to integrate custom applications.

Setup

Pre-requisites

Access to a . You can either get this from , or .
Understand how to use cheqd and .
Tokens to pay for identity transactions, since all ledger transactions are metered.

For the remainder of this tutorial, it's assumed that the DID and associated DID Document is being created on testnet. These commands can easily be modified for mainnet.

Creating a new DID and DIDDoc on testnet

1. Generate verification key

First, we'll need to generate a verification key:

The result should look like the following:

Note: Keep this key safe! It is used to create the DIDDoc, and to update it in the future. Normally, you should be careful when cat-ing such keys as it reveals the private key as well.

2. Encode the identity key according to different verification methods

Encode the identity key's public key to one of the formats below according to the verificaiton method type you selected, as this will be later required in the verificationMethod section:

Ed25519VerificationKey2018

Encoding to publicKeyBase58

For example:

Ed25519VerificationKey2020

Encoding to publicKeyMultibase

For example:

JsonWebKey2020

Encoding to publicKeyJwk

For example:

3. Create a unique identifier for the DID

A unique-id should only be a 16-byte encoded base58 string (Indy-style) or a uuid.

For example, we can generate uuid using uuidgen tool:

The result for our example will be b0ca0b75-ca6a-4674-a261-45f6dd0c9c77, so let's use it as our unique-id in our DIDDoc.

4. Populate DIDDoc contents

Copy-paste the template below into your terminal into a blank file (e.g., using nano). We will add additional required information into the blank fields <xxxxx> in the next steps.

You'll need to replace some values (as described in the ):

<namespace>: Can be testnet or mainnet. For this CLI, we strongly suggest using testnet.
<unique-id>: Unique identifier, created in step #3

The examples below show the variation in syntax for different verification method key types in the DIDDoc contents. Note that each key type has a slightly different output.

Ed25519VerificationKey2018

Ed25519VerificationKey2020

JSONWebKey2020

We recommend you save this DIDDoc file (e.g., in a file called diddoc.json) for the following steps.

5. Create payload file

After assembling the DID-Document JSON file we are ready to compile the final payload file with private key inside.

The example of payload.json files with different verification methods:

Ed25519VerificationKey2018

Ed25519VerificationKey2020

JsonWebKey2020

6. Submitting DID creation request to the ledger

Now that we have our DIDDoc prepared, we can send a create DID request to the ledger:

Where:

--from: Should be an alias of a cheqd/Cosmos key, which will be used to pay for the ledger transaction.
--fees: Should equal 50000000000ncheq, which is equivalent to 50 CHEQ, the current price for a create DID transaction on testnet and mainnet.

Note that each of cheqd's on-ledger identity transactions has a fixed fee, . If your account has insufficient balance the transaction will fail.

After you execute the command, you will receive "code": 0" if the DID was successfully written to the ledger.

Otherwise, the raw_logs field in the response can help figure out why something went wrong. For example:

7. Query the DID from ledger after successful creation

Finally, to check that the DID was successfully written to the ledger, we can use the following query:

where:

<identifier-of-your-DIDDoc>: Fully-qualified DID with <unique-id>

For example:

Congratulations! You've created, hopefully, the first of many DIDs on cheqd!

8. Query specific version

Since upgrading to 1.x.y version, we introduced versioning feature for DID Documents. This means that it is possible to get the previous version of a DID Document using the particular versionId of the document.

For querying particular version of the DID-Document the next command can be used:

Where:

id - identifier of your DID-Document. Fully-qualified DID with <unique-id>
version-id - particular id of version you want to get

Example

Command:

Output:

Note that the output here is in snake_case because of how the cheqd ledger represents protobufs. This output would be in spec compliant JSON if queried using our DID resolver.

9. Query the all the versions metadata for DID

For querying all the versions there is a command:

Where:

id - identifier of your DID-Document. Fully-qualified DID with <unique-id>

Example

Output:

Create a DID

Create a Decentralized Identifier (DID) using the cheqd Cosmos CLI.

The purpose of this document is to describe how a DID (and associated DIDDoc) can be created using the cheqd-node Cosmos CLI.

NOTE: The guidance below is only recommended to be used for testing purposes!
Using cheqd-node Cosmos CLI for real-world production environments is not recommended, since the identity keys are passed in raw form to the CLI. This is fine in development/testing usage, but is not recommend for mainnet.
Developers are encouraged to use production-grade CLI tools such as Veramo SDK for cheqd or look at our developer guide on how to integrate custom applications.

Setup

Pre-requisites

Access to a . You can either get this from , or .
Understand how to use cheqd and .
Tokens to pay for identity transactions, since all ledger transactions are metered.

For the remainder of this tutorial, it's assumed that the DID and associated DID Document is being created on testnet. These commands can easily be modified for mainnet.

Creating a new DID and DIDDoc on testnet

1. Generate verification key

First, we'll need to generate a verification key:

The result should look like the following:

Note: Keep this key safe! It is used to create the DIDDoc, and to update it in the future. Normally, you should be careful when cat-ing such keys as it reveals the private key as well.

2. Encode the identity key according to different verification methods

Encode the identity key's public key to one of the formats below according to the verificaiton method type you selected, as this will be later required in the verificationMethod section:

Ed25519VerificationKey2018

Encoding to publicKeyBase58

For example:

Ed25519VerificationKey2020

Encoding to publicKeyMultibase

For example:

JsonWebKey2020

Encoding to publicKeyJwk

For example:

3. Create a unique identifier for the DID

A unique-id should only be a 16-byte encoded base58 string (Indy-style) or a uuid.

For example, we can generate uuid using uuidgen tool:

The result for our example will be b0ca0b75-ca6a-4674-a261-45f6dd0c9c77, so let's use it as our unique-id in our DIDDoc.

4. Populate DIDDoc contents

Copy-paste the template below into your terminal into a blank file (e.g., using nano). We will add additional required information into the blank fields <xxxxx> in the next steps.

You'll need to replace some values (as described in the ):

<namespace>: Can be testnet or mainnet. For this CLI, we strongly suggest using testnet.
<unique-id>: Unique identifier, created in step #3

The examples below show the variation in syntax for different verification method key types in the DIDDoc contents. Note that each key type has a slightly different output.

Ed25519VerificationKey2018

Ed25519VerificationKey2020

JSONWebKey2020

We recommend you save this DIDDoc file (e.g., in a file called diddoc.json) for the following steps.

5. Create payload file

After assembling the DID-Document JSON file we are ready to compile the final payload file with private key inside.

The example of payload.json files with different verification methods:

Ed25519VerificationKey2018

Ed25519VerificationKey2020

JsonWebKey2020

6. Submitting DID creation request to the ledger

Now that we have our DIDDoc prepared, we can send a create DID request to the ledger:

Where:

--from: Should be an alias of a cheqd/Cosmos key, which will be used to pay for the ledger transaction.
--fees: Should equal 50000000000ncheq, which is equivalent to 50 CHEQ, the current price for a create DID transaction on testnet and mainnet.

Note that each of cheqd's on-ledger identity transactions has a fixed fee, . If your account has insufficient balance the transaction will fail.

After you execute the command, you will receive "code": 0" if the DID was successfully written to the ledger.

Otherwise, the raw_logs field in the response can help figure out why something went wrong. For example:

7. Query the DID from ledger after successful creation

Finally, to check that the DID was successfully written to the ledger, we can use the following query:

where:

<identifier-of-your-DIDDoc>: Fully-qualified DID with <unique-id>

For example:

Congratulations! You've created, hopefully, the first of many DIDs on cheqd!

8. Query specific version

For querying particular version of the DID-Document the next command can be used:

Where:

id - identifier of your DID-Document. Fully-qualified DID with <unique-id>
version-id - particular id of version you want to get

Example

Command:

Output:

Note that the output here is in snake_case because of how the cheqd ledger represents protobufs. This output would be in spec compliant JSON if queried using our DID resolver.

9. Query the all the versions metadata for DID

For querying all the versions there is a command:

Where:

id - identifier of your DID-Document. Fully-qualified DID with <unique-id>

Example

Output: