1 of 7

cheqd Cosmos CLI for identity

NOTE: The tutorials below are 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.

Get started

Utilise our cheqd Cosmos CLI for identity for testing purposes, following the tutorials listed below:

Alternatives

There are plenty of other places you can go to get started creating . Simply pick the option which is best suited for your needs:

Creating a DID with cheqd Cosmos CLI

The purpose of this document is to describe how a DID (and associated DIDDoc) can be created using .

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 or look at .

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.
1. For testing purposes, CHEQ test tokens can be acquired from .
2. Mainnet CHEQ tokens can be .

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.

<namespace>: Can be testnet or mainnet. For this CLI, we strongly suggest using testnet.
<unique-id>: Unique identifier, created in step #3
<key-alias>: A key alias for the verification method identifier, e.g., #key1
<verification-method-type>: Verification method type slected from step #2 above
<public-key-base58>, <public-key-multibase>, <public-key-jwk>: Any one of the values from the result of step #2 above
<auth-key-alias>: Alias of authentication key. Can be a reference to an existing verification method.
<service-key>: Alias for service property. This is an optional section but useful to understand the power of DIDDocs.
<URI-to-object>: A valid URI that can act as a service endpoint.

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.

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:

Updating existing DIDs with cheqd Cosmos CLI

The purpose of this document is to describe how an existing DID (and associated DIDDoc) can be updated using .

NOTE: The procedures below are only recommended for development purposes!
Using cheqd-node Cosmos CLI for real-world production usage 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 or look at .

Setup

Pre-Requisites

Learn how to
with cheqd Cosmos CLI

Assumptions

Given this procedure below is intended for development/training purposes, we assume that the user stores their public/private keys safely during the DID creation process and has access to it.
Updating a DIDDoc requires the full updated DIDDoc to be sent. Only the updated/changed parts cannot be sent. This accounts for scenarios where the DIDDoc may have been updated on ledger, but the local copy is not synced with the latest changes.

Update an existing DID

1. Update the DIDDoc contents / body

Use a text editor like nano to edit the body of the DIDDoc (the example below assumes it's saved in a file called payload.json).

2. Compile the payload

3. Send an update DID transaction to the ledger

Send the updated DIDDoc to the ledger. This must be signed with the correct identity keys:

Flags

Payload_in_JSON - previously compiled JSON.
--from: Cosmos account key which will pay fees for the transaction to be written to ledger.
--node: IP address or URL of node to send request to
--chain-id: E.g., cheqd-testnet-6
--fees: Set to 25000000000ncheq, which is the fixed fee for updating a DID

Example

Deactivating existing DIDs with cheqd Cosmos CLI

The purpose of this document is to describe how an existing DID (and associated DIDDoc) can be deactivated using .

NOTE: The procedures below are only recommended for development purposes!
Using cheqd-node Cosmos CLI for real-world production usage 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 or look at .

Setup

Pre-Requisites

Learn how to
with cheqd Cosmos CLI

Deactivate an existing DID

1. Compile the payload

As in flow with we need to compile payload.json file with private key inside and pass it to the CLI. The resulting JSON in our example will look liks:

3. Send an deactivate DID transaction to the ledger

Send the updated DIDDoc to the ledger. This must be signed with the correct identity keys:

Flags

Payload_in_JSON - previously compiled JSON.
--from: Cosmos account key which will pay fees for the transaction to be written to ledger.
--node: IP address or URL of node to send request to
--chain-id: E.g., cheqd-testnet-6
--fees: Set to 10000000000ncheq, which is the fixed fee for deactivating a DID

Example

Querying DIDs with cheqd Cosmos CLI

Pre-requisite

An existing did:cheqd entry created using any SDK/CLI. For development purposes, this can be done using the cheqd-node Cosmos CLI.

NOTE: Use the cheqd DID Resolver for production-grade usage
Querying using the Cosmos CLI is useful for development purposes, but the DID Resolver is designed for programmatic usage. Production-grade SDKs such as Veramo SDK for cheqd also rely on the DID Resolver package.

Querying DIDDocs for existing DIDs

Command

cheqd-noded query cheqd did-document <id> --chain-id <chain-id> --node <node-rpc-endpoint>

Example

cheqd-noded query cheqd did-document did:cheqd:mainnet:7urFZAL6hvyfHWjfEmEpnN --node https://rpc.cheqd.net:443

Creating a DID-Linked Resource using cheqd Cosmos CLI

The purpose of this document is to outline how someone can create a Resource on the cheqd network using . The process that's followed is similar to what's described in the .

Pre-requisites

Install the latest stable cheqd-node CLI, either as a or .
Acquire test CHEQ tokens through (if creating it on our testnet), or (if you plan on creating it on mainnet).

Creating a new Resource linked to a DID

1. Create a new DID + DIDDoc

Note: If you already have a DIDDoc and corresponding keys, you can skip this step.

To create a DIDDoc, you can follow the instructions to .

Let's assume the DID for the DIDDoc is as follows:

did:cheqd:mainnet:6h7fjuw37gbf9ioty633bnd7thf65hs1

2. Create a UUID for the Resource

. On Unix systems, the uuidgen tool can be used to generate a new UUID:

3. Prepare a file with Resource content

Resource content should be placed in a file and stored locally.

Command

Understanding Resource Fees

The fee for a resource transaction changes depending on the file type being passed to the ledger. Currently there are three different variations on the fee:

JSON file

Within the payload file the amount should be specified as:

denom: ncheq
amount: 2500000000

This equates to 2.5 CHEQ.

Image file

Within the payload file the amount should be specified as:

denom: ncheq
amount: 10000000000

This equates to 10 CHEQ.

Default (any other) file

Within the payload file the amount should be specified as:

denom: ncheq
amount: 5000000000

This equates to 5 CHEQ.

Parameters

payload-file - file with JSON formatted payload. The format and structure can be found in example
resource-data-file - file which will be sent to the ledger as a data. Can be a picture or an image or whatever you want.
flags - additional parameters like, --gas or --from.

Example input:

where payload.json is:

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

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

4. Check that new Resource version was successfully written to the ledger

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

Parameters

<collection-id>: The same unique identifier as that after the namespace of the corresponding DID created in step 1
<resource-id>: Unique ID of the resource within the collection of resources associated with the DIDDoc

Example input:

Ouput:

Notice that both previous_version_id and next_version_id are empty now cause there is only one resource in such collection c82f2b02-bdab-4dd7-b833-3e143745d612.

5. Additional queries to the ledger

There are also 2 annother commands for getting resource from ledger depending what the actual info is needed.

Get metadata

Here is the command which allows to get only metadata information without getting the whole resource. The format of call is:

Parameters collection-id and resource-id have the same meaning as before.

Example input:

Output:

Get collection of resources

For querying all the resources but only metadata there is a special command:

As the main parameter it requires only collection-id.

Example input:

Ouput:

Congratulations! You've successfully created a resource on cheqd ledger; hopefully, the first of many.

Adding a new Resource version

The purpose of this document is to describe how someone can create a new Resource on under an existing Collection.

This tutorial uses the , similar to the .

Pre-requisites

Install the latest stable cheqd-node CLI, either as a or .
Acquire test CHEQ tokens through (if creating it on our testnet), or (if you plan on creating it on mainnet).
An
Having under this DIDDoc Collection

Adding a new Resource to an existing DIDDoc Collection

1. Generate a new UUID for the new Resource version

. On Unix systems, the uuidgen tool can be used to generate a new UUID:

2. Prepare a file with Resource content

Resource content should be placed in a file and stored locally.

3. Publish the new Resource version to the ledger

Resources with the same Collection ID and name are grouped into version sets. Each resource in such a set has a link to the previous version (except the first version) and the next version (if it's not the most recent version).

To create a resource and mark it as a new version within a particular group, we need to use the same collection-id and name as in the previous version. Links between versions will be created automatically.

New versions have dedicated unique IDs and can be referenced and retrieved as any other resources.

Command

Parameters

payload-file - file with JSON formatted payload. The format and structure can be found in example
resource-data-file - file which will be sent to the ledger as a data. Can be a picture or an image or whatever you want.

Example

where payload.json is:

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

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

4. Check that new Resource version was successfully written to the ledger

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

Parameters

<collection-id>: The same unique identifier as that after the namespace of the corresponding DID created in step 1
<resource-id>: Unique ID of the resource within the collection of resources associated with the DIDDoc

Example

Result

Notice that previous_version_id is not empty and pointing to the previously created resource with id : 3e6bd814-6851-4c8a-b114-c64f035ef590.

Creating a DID with cheqd Cosmos CLI

The purpose of this document is to describe how a DID (and associated DIDDoc) can be created using .

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 or look at .

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.
1. For testing purposes, CHEQ test tokens can be acquired from .
2. Mainnet CHEQ tokens can be .

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:

cheqd-noded debug ed25519 random >> keys.txt

The result should look like the following:

$ cat keys.txt
{"pub_key_base_64":"MnrTheU+vCrN3W+WMvcpBXYBG6D1HrN5usL1zS6W7/k=","pub_key_multibase_58":"",\
"priv_key_base_64":"wNXCJ9Ny0uzCYhnTE3gfQuwgQM4QZCw08+j01QDfoGxMMI9u9GIv/90eH3E3KjHjlSi9hKRQy94PvKVAH1+Rhw=="}

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

cheqd-noded debug encoding base64-base58 <pub_key_base_64>

For example:

$ cheqd-noded debug encoding base64-base58 MnrTheU+vCrN3W+WMvcpBXYBG6D1HrN5usL1zS6W7/k=
4Q41kvWsd1JAuPFBff8Dti7P6fLbPZe3Nmod35uua9TE

Ed25519VerificationKey2020

Encoding to publicKeyMultibase

cheqd-noded debug encoding base64-multibase58 <pub_key_base_64>

For example:

$ cheqd-noded debug ed25519 base64-multibase58 MnrTheU+vCrN3W+WMvcpBXYBG6D1HrN5usL1zS6W7/k=
z6MkhrK4MAmJxYne1t5tME64jofNvEcSoStQ4niYsMsvVNEc

JsonWebKey2020

Encoding to publicKeyJwk

cheqd-noded debug encoding pubkey-base64-to-jwk <pub_key_base_64>

For example:

$ cheqd-noded debug ed25519 pubkey-base64-to-jwk MnrTheU+vCrN3W+WMvcpBXYBG6D1HrN5usL1zS6W7/k=

{"crv":"Ed25519","kty":"OKP","x":"MnrTheU-vCrN3W-WMvcpBXYBG6D1HrN5usL1zS6W7_k"}

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:

uuidgen
b0ca0b75-ca6a-4674-a261-45f6dd0c9c77

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
<key-alias>: A key alias for the verification method identifier, e.g., #key1
<verification-method-type>: Verification method type slected from step #2 above
<public-key-base58>, <public-key-multibase>, <public-key-jwk>: Any one of the values from the result of step #2 above
<auth-key-alias>: Alias of authentication key. Can be a reference to an existing verification method.
<service-key>: Alias for service property. This is an optional section but useful to understand the power of DIDDocs.
<URI-to-object>: A valid URI that can act as a service endpoint.

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

{
  "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
  "verificationMethod": [
    {
      "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
      "publicKeyBase58": "4Q41kvWsd1JAuPFBff8Dti7P6fLbPZe3Nmod35uua9TE"
    }
  ],
  "authentication": [
    "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1"
  ],
  "service": [{
    "id":"did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#linked-domain",
    "type": "LinkedDomains",
    "serviceEndpoint": [
        "https://bar.example.com"
    ]
  }]
}

Ed25519VerificationKey2020

{
  "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
  "verificationMethod": [
    {
      "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
      "publicKeyMultibase": "z2yJuNbhoUpRn7ypAugSLzkCc8QEw146RJ8DD3jzCZQ6A"
    }
  ],
  "authentication": [
    "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1"
  ],
  "service": [{
    "id":"did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#linked-domain",
    "type": "LinkedDomains",
    "serviceEndpoint": [
        "https://bar.example.com"
    ]
  }]
}

JSONWebKey2020

{
  "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
  "verificationMethod": [
    {
      "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "type": "JsonWebKey2020",
      "controller": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
      "publicKeyJwk": {
          "kty": "OKP", // external (property name)
          "crv": "Ed25519", // external (property name)
          "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ" // external (property name)
      }
    }
  ],
  "authentication": [
    "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1"
  ],
  "service": [{
    "id":"did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#linked-domain",
    "type": "LinkedDomains",
    "serviceEndpoint": [
        "https://bar.example.com"
    ]
  }]
}

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.

{
  "payload": {
    ...
  },
  "signInputs": [
    {
      "verificationMethodId": "<verification-method-id>",
      "privKey": "<private key representation>"
    }
  ]
}

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

Ed25519VerificationKey2018

{
  "payload": {
    "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
        "type": "Ed25519VerificationKey2018",
        "controller": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
        "publicKeyBase58": "4Q41kvWsd1JAuPFBff8Dti7P6fLbPZe3Nmod35uua9TE"
      }
    ],
    "authentication": [
      "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1"
    ],
    "service": [{
      "id":"did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#linked-domain",
      "type": "LinkedDomains",
      "serviceEndpoint": [
        "https://bar.example.com"
      ]
    }]
  },
  "signInputs": [
    {
      "verificationMethodId": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "privKey": "wNXCJ9Ny0uzCYhnTE3gfQuwgQM4QZCw08+j01QDfoGxMMI9u9GIv/90eH3E3KjHjlSi9hKRQy94PvKVAH1+Rhw=="
    }
  ]
}

Ed25519VerificationKey2020

{
  "payload": {
    "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
        "type": "Ed25519VerificationKey2020",
        "controller": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
        "publicKeyMultibase": "z2yJuNbhoUpRn7ypAugSLzkCc8QEw146RJ8DD3jzCZQ6A"
      }
    ],
    "authentication": [
      "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1"
    ],
    "service": [{
      "id":"did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#linked-domain",
      "type": "LinkedDomains",
      "serviceEndpoint": [
        "https://bar.example.com"
      ]
    }]
  },
  "signInputs": [
    {
      "verificationMethodId": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "privKey": "wNXCJ9Ny0uzCYhnTE3gfQuwgQM4QZCw08+j01QDfoGxMMI9u9GIv/90eH3E3KjHjlSi9hKRQy94PvKVAH1+Rhw=="
    }
  ]
}

JsonWebKey2020

{
  "payload": {
    "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
        "type": "JsonWebKey2020",
        "controller": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
        "publicKeyJwk": {
          "kty": "OKP", // external (property name)
          "crv": "Ed25519", // external (property name)
          "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ" // external (property name)
        }
      }
    ],
    "authentication": [
      "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1"
    ],
    "service": [{
      "id":"did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#linked-domain",
      "type": "LinkedDomains",
      "serviceEndpoint": [
        "https://bar.example.com"
      ]
    }]
  },
  "signInputs": [
    {
      "verificationMethodId": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "privKey": "wNXCJ9Ny0uzCYhnTE3gfQuwgQM4QZCw08+j01QDfoGxMMI9u9GIv/90eH3E3KjHjlSi9hKRQy94PvKVAH1+Rhw=="
    }
  ]
}

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:

cheqd-noded tx cheqd create-did \
  --fees 50000000000ncheq \
  --gas auto \
  --gas-adjustment 1.8 \
  --from <alias-to-cosmos-key>  \
  --node https://rpc.cheqd.network:443 \
  --chain-id cheqd-testnet-6 \
  [payload.json]

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:

"code":1201,"data":"","raw_log":"failed to execute message; message index: 0: did:cheqd:testnet:fcbarcelona: DID Doc not found"

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:

cheqd-noded query cheqd did-document "<identifier-of-your-DIDDoc>" --node https://rpc.cheqd.network:443

where:

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

For example:

cheqd-noded query cheqd did "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77" --node https://rpc.cheqd.network:443

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:

cheqd-noded query cheqd did-version [id] [version-id]

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:

cheqd-noded query cheqd did-version did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612 76e546ee-78cd-5372-b34e-8b47461626e1 --node https://rpc.cheqd.net:443 --output json

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.

{
  "value": {
    "did_doc": {
      "context": [],
      "id": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612",
      "controller": [
        "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612"
      ],
      "verification_method": [
        {
          "id": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612#key-1",
          "verification_method_type": "Ed25519VerificationKey2020",
          "controller": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612",
          "verification_material": "z6MkuGoZyDyji4sApi9L79CG484hoQPmtuqJSTbUpdrVQAqB"
        }
      ],
      "authentication": [
        "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612#key-1"
      ],
      "assertion_method": [],
      "capability_invocation": [],
      "capability_delegation": [],
      "key_agreement": [],
      "service": [],
      "also_known_as": []
    },
    "metadata": {
      "created": "2022-11-17T10:29:53Z",
      "updated": "0001-01-01T00:00:00Z",
      "deactivated": false,
      "version_id": "76e546ee-78cd-5372-b34e-8b47461626e1",
      "next_version_id": "",
      "previous_version_id": ""
    }
  }
}

9. Query the all the versions metadata for DID

For querying all the versions there is a command:

cheqd-noded query cheqd did-metadata [id] [flags]

Where:

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

Example

cheqd-noded query cheqd did-metadata did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612 --node https://rpc.cheqd.net:443 --output json

Output:

{
  "versions": [
    {
      "created": "2022-11-17T10:29:53Z",
      "updated": "0001-01-01T00:00:00Z",
      "deactivated": false,
      "version_id": "76e546ee-78cd-5372-b34e-8b47461626e1",
      "next_version_id": "",
      "previous_version_id": ""
    }
  ],
  "pagination": null
}

Updating existing DIDs with cheqd Cosmos CLI

The purpose of this document is to describe how an existing DID (and associated DIDDoc) can be updated using .

NOTE: The procedures below are only recommended for development purposes!
Using cheqd-node Cosmos CLI for real-world production usage 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 or look at .

Setup

Pre-Requisites

Learn how to
with cheqd Cosmos CLI

Assumptions

Given this procedure below is intended for development/training purposes, we assume that the user stores their public/private keys safely during the DID creation process and has access to it.
Updating a DIDDoc requires the full updated DIDDoc to be sent. Only the updated/changed parts cannot be sent. This accounts for scenarios where the DIDDoc may have been updated on ledger, but the local copy is not synced with the latest changes.

Update an existing DID

1. Update the DIDDoc contents / body

Use a text editor like nano to edit the body of the DIDDoc (the example below assumes it's saved in a file called payload.json).

nano payload.json

For example, we can and change the Service Endpoint from bar.example.com to foo.example.com:

{
  "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
  "verificationMethod": [
    {
      "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "type": "Ed25519VerificationKey2018",
      "controller": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
      "publicKeyBase58": "4Q41kvWsd1JAuPFBff8Dti7P6fLbPZe3Nmod35uua9TE"
    }
  ],
  "authentication": [
    "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1"
  ],
  "service": [{
    "id":"did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#linked-domain",
    "type": "LinkedDomains",
    "serviceEndpoint": [
      "https://foo.example.com"
    ]
  }]
}

2. Compile the payload

As in flow with we need to compile payload.json file with private key inside and pass it to the CLI. The result JSON in our example will look liks:

{
  "payload": {
    "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
        "type": "Ed25519VerificationKey2018",
        "controller": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
        "publicKeyBase58": "4Q41kvWsd1JAuPFBff8Dti7P6fLbPZe3Nmod35uua9TE"
      }
    ],
    "authentication": [
      "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1"
    ],
    "service": [{
      "id":"did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#linked-domain",
      "type": "LinkedDomains",
      "serviceEndpoint": [
        "https://foo.example.com"
      ]
    }]
  },
  "signInputs": [
    {
      "verificationMethodId": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "privKey": "wNXCJ9Ny0uzCYhnTE3gfQuwgQM4QZCw08+j01QDfoGxMMI9u9GIv/90eH3E3KjHjlSi9hKRQy94PvKVAH1+Rhw=="
    }
  ]
}

3. Send an update DID transaction to the ledger

Send the updated DIDDoc to the ledger. This must be signed with the correct identity keys:

cheqd-noded tx cheqd update-did <Payload_in_JSON>  \
  --from <cosmos_account> --node <url> --chain-id <chain> --fees <fee>

Flags

Payload_in_JSON - previously compiled JSON.
--from: Cosmos account key which will pay fees for the transaction to be written to ledger.
--node: IP address or URL of node to send request to
--chain-id: E.g., cheqd-testnet-6
--fees: Set to 25000000000ncheq, which is the fixed fee for updating a DID

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

Example

cheqd-noded tx cheqd update-did "payload.json" \
  --from my_account --node http://rpc.cheqd.network:443 --chain-id cheqd-testnet-6 --fees 25000000000ncheq

Adding a new Resource version

The purpose of this document is to describe how someone can create a new Resource on under an existing Collection.

This tutorial uses the , similar to the .

Pre-requisites

Install the latest stable cheqd-node CLI, either as a or .
Acquire test CHEQ tokens through (if creating it on our testnet), or (if you plan on creating it on mainnet).
An
Having under this DIDDoc Collection

Adding a new Resource to an existing DIDDoc Collection

1. Generate a new UUID for the new Resource version

. On Unix systems, the uuidgen tool can be used to generate a new UUID:

2. Prepare a file with Resource content

Resource content should be placed in a file and stored locally.

3. Publish the new Resource version to the ledger

New versions have dedicated unique IDs and can be referenced and retrieved as any other resources.

Command

cheqd-noded tx resource create [payload-file] [resource-data-file] [flags]

Parameters

payload-file - file with JSON formatted payload. The format and structure can be found in example
resource-data-file - file which will be sent to the ledger as a data. Can be a picture or an image or whatever you want.
flags - additional parameters like, --gas or --from. --fees should match the price of the .

Example

cheqd-noded tx resource create \
--chain-id cheqd \
--keyring-backend test \
--output json \
--fees 10000000000ncheq \
--gas auto \
--gas-adjustment 1.8 \
--from base_account \
[payload.json] [resource.jpeg]

where payload.json is:

{
  "payload": {
    "data": null,
    "collectionId": "b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
    "id": "c8ef6d88-ee0c-4ca4-9fd6-f9e17f6f8f3f",
    "name": "TestResource",
    "version": "1.0",
    "resourceType": "TestType",
    "alsoKnownAs": []
  },
  "signInputs": [
    {
      "verificationMethodId": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "privKey": "y4B5qis9BXUq/mODsrWtS3q5ejOk/okSIXlX1/a9HvuG3PgYmekfQmq3QhJ4JSzN/rkiGCQDNKoTXMmxuXDHbg=="
    }
  ]
}

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

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

{
  "code": 1201,
  "data": "",
  "raw_log": "failed to execute message; message index: 0: id:cheqd:testnet:fcbarcelona: DID Doc not found"
}

4. Check that new Resource version was successfully written to the ledger

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

cheqd-noded query resource specific-resource \
    <collection-id> \
    <resource-id> \
    --node https://rpc.cheqd.network:443

Parameters

<collection-id>: The same unique identifier as that after the namespace of the corresponding DID created in step 1
<resource-id>: Unique ID of the resource within the collection of resources associated with the DIDDoc

Example

cheqd-noded query resource specific-resource \
    c82f2b02-bdab-4dd7-b833-3e143745d612 \
    c8ef6d88-ee0c-4ca4-9fd6-f9e17f6f8f3f \
    --node https://rpc.cheqd.net:443 --output json

Result

{
  "resource": {
    "resource": {
      "data": "..."
    },
    "metadata": {
      "collection_id": "c82f2b02-bdab-4dd7-b833-3e143745d612",
      "id": "c8ef6d88-ee0c-4ca4-9fd6-f9e17f6f8f3f",
      "name": "EventBrite Logo",
      "version": "",
      "resource_type": "image/png",
      "also_known_as": [
        {
          "uri": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612/resources/c8ef6d88-ee0c-4ca4-9fd6-f9e17f6f8f3f",
          "description": "did-url"
        }
      ],
      "media_type": "image/svg+xml",
      "created": "2022-11-17T10:35:23Z",
      "checksum": "a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559",
      "previous_version_id": "3e6bd814-6851-4c8a-b114-c64f035ef590",
      "next_version_id": ""
    }
  }
}

Notice that previous_version_id is not empty and pointing to the previously created resource with id : 3e6bd814-6851-4c8a-b114-c64f035ef590.

Creating a DID-Linked Resource using cheqd Cosmos CLI

The purpose of this document is to outline how someone can create a Resource on the cheqd network using . The process that's followed is similar to what's described in the .

Pre-requisites

Install the latest stable cheqd-node CLI, either as a or .
Acquire test CHEQ tokens through (if creating it on our testnet), or (if you plan on creating it on mainnet).

Creating a new Resource linked to a DID

1. Create a new DID + DIDDoc

Note: If you already have a DIDDoc and corresponding keys, you can skip this step.

To create a DIDDoc, you can follow the instructions to .

Let's assume the DID for the DIDDoc is as follows:

did:cheqd:mainnet:6h7fjuw37gbf9ioty633bnd7thf65hs1

2. Create a UUID for the Resource

. On Unix systems, the uuidgen tool can be used to generate a new UUID:

3. Prepare a file with Resource content

Resource content should be placed in a file and stored locally.

Command

cheqd-noded tx resource create [payload-file] [resource-data-file] [flags]

Understanding Resource Fees

The fee for a resource transaction changes depending on the file type being passed to the ledger. Currently there are three different variations on the fee:

JSON file

Within the payload file the amount should be specified as:

denom: ncheq
amount: 2500000000

This equates to 2.5 CHEQ.

Image file

Within the payload file the amount should be specified as:

denom: ncheq
amount: 10000000000

This equates to 10 CHEQ.

Default (any other) file

Within the payload file the amount should be specified as:

denom: ncheq
amount: 5000000000

This equates to 5 CHEQ.

Parameters

payload-file - file with JSON formatted payload. The format and structure can be found in example
resource-data-file - file which will be sent to the ledger as a data. Can be a picture or an image or whatever you want.
flags - additional parameters like, --gas or --from.
fees - the specific fee for the transaction, depending on the

Example input:

cheqd-noded tx resource create \
  --chain-id cheqd \
  --keyring-backend test \
  --output json \
  --fees 2500000000ncheq \
  --gas auto \
  --gas-adjustment 1.8 \
  --from base_account \
  [payload.json] [resource.json]

where payload.json is:

{
  "payload": {
    "data": null,
    "collectionId": "b0ca0b75-ca6a-4674-a261-45f6dd0c9c77",
    "id": "5e16a3f9-7c6e-4b6b-8e28-20f56780ee25",
    "name": "TestResource",
    "version": "1.0",
    "resourceType": "TestType",
    "alsoKnownAs": []
  },
  "signInputs": [
    {
      "verificationMethodId": "did:cheqd:testnet:b0ca0b75-ca6a-4674-a261-45f6dd0c9c77#key1",
      "privKey": "y4B5qis9BXUq/mODsrWtS3q5ejOk/okSIXlX1/a9HvuG3PgYmekfQmq3QhJ4JSzN/rkiGCQDNKoTXMmxuXDHbg=="
    }
  ]
}

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

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

{
  "code": 1201,
  "data": "",
  "raw_log": "failed to execute message; message index: 0: id:cheqd:testnet:fcbarcelona: DID Doc not found"
}

4. Check that new Resource version was successfully written to the ledger

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

cheqd-noded query resource specific-resource \
    <collection-id> \
    <resource-id> \
    --node https://rpc.cheqd.network:443

Parameters

<collection-id>: The same unique identifier as that after the namespace of the corresponding DID created in step 1
<resource-id>: Unique ID of the resource within the collection of resources associated with the DIDDoc

Example input:

cheqd-noded query resource specific-resource \
    c82f2b02-bdab-4dd7-b833-3e143745d612 \
    3e6bd814-6851-4c8a-b114-c64f035ef590 \
    --node https://rpc.cheqd.net:443 --output json

Ouput:

{
  "resource": {
    "resource": {
      "data": "..."
    },
    "metadata": {
      "collectionId": "c82f2b02-bdab-4dd7-b833-3e143745d612",
      "id": "3e6bd814-6851-4c8a-b114-c64f035ef590",
      "name": "EventBrite Logo",
      "version": "",
      "resourceType": "image/png",
      "alsoKnownAs": [
        {
          "uri": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612/resources/3e6bd814-6851-4c8a-b114-c64f035ef590",
          "description": "did-url"
        }
      ],
      "mediaType": "image/svg+xml",
      "created": "2022-11-17T10:35:23Z",
      "checksum": "a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559",
      "previousVersionId": "",
      "nextVersionId": ""
    }
  }
}

Notice that both previous_version_id and next_version_id are empty now cause there is only one resource in such collection c82f2b02-bdab-4dd7-b833-3e143745d612.

5. Additional queries to the ledger

There are also 2 annother commands for getting resource from ledger depending what the actual info is needed.

Get metadata

Here is the command which allows to get only metadata information without getting the whole resource. The format of call is:

cheqd-noded query resource metadata [collection-id] [resource-id] [flags]

Parameters collection-id and resource-id have the same meaning as before.

Example input:

cheqd-noded query resource metadata \
    c82f2b02-bdab-4dd7-b833-3e143745d612 \
    3e6bd814-6851-4c8a-b114-c64f035ef590 \
    --node https://rpc.cheqd.net:443 --output json

Output:

{
  "resource": {
    "collection_id": "c82f2b02-bdab-4dd7-b833-3e143745d612",
    "id": "3e6bd814-6851-4c8a-b114-c64f035ef590",
    "name": "EventBrite Logo",
    "version": "",
    "resource_type": "image/png",
    "also_known_as": [
      {
        "uri": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612/resources/3e6bd814-6851-4c8a-b114-c64f035ef590",
        "description": "did-url"
      }
    ],
    "media_type": "image/svg+xml",
    "created": "2022-11-17T10:35:23Z",
    "checksum": "a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559",
    "previous_version_id": "",
    "next_version_id": ""
  }
}

Get collection of resources

For querying all the resources but only metadata there is a special command:

cheqd-noded query resource collection-metadata [collection-id] [flags]

As the main parameter it requires only collection-id.

Example input:

cheqd-noded query resource collection-metadata c82f2b02-bdab-4dd7-b833-3e143745d612  --node https://rpc.cheqd.net:443 --output json

Ouput:

{
  "resources": [
    {
      "collection_id": "c82f2b02-bdab-4dd7-b833-3e143745d612",
      "id": "3e6bd814-6851-4c8a-b114-c64f035ef590",
      "name": "EventBrite Logo",
      "version": "",
      "resource_type": "image/png",
      "also_known_as": [
        {
          "uri": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612/resources/3e6bd814-6851-4c8a-b114-c64f035ef590",
          "description": "did-url"
        }
      ],
      "media_type": "image/svg+xml",
      "created": "2022-11-17T10:35:23Z",
      "checksum": "a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559",
      "previous_version_id": "",
      "next_version_id": ""
    },
    {
      "collection_id": "c82f2b02-bdab-4dd7-b833-3e143745d612",
      "id": "9447c669-0ba1-4989-bd10-a85cc298aace",
      "name": "Discord Logo",
      "version": "",
      "resource_type": "image/png",
      "also_known_as": [
        {
          "uri": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612/resources/9447c669-0ba1-4989-bd10-a85cc298aace",
          "description": "did-url"
        }
      ],
      "media_type": "image/png",
      "created": "2022-11-17T10:35:51Z",
      "checksum": "b2939df5a48f422fc9d62f270c182f07b5fd5a7a334478ea73af4fdb5eb12d3b",
      "previous_version_id": "",
      "next_version_id": ""
    },
    {
      "collection_id": "c82f2b02-bdab-4dd7-b833-3e143745d612",
      "id": "ba4d1a8b-6395-4b96-8492-aaf2800d5727",
      "name": "Twitter Logo",
      "version": "",
      "resource_type": "image/png",
      "also_known_as": [
        {
          "uri": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612/resources/ba4d1a8b-6395-4b96-8492-aaf2800d5727",
          "description": "did-url"
        }
      ],
      "media_type": "image/png",
      "created": "2022-11-17T10:36:26Z",
      "checksum": "aeb8f203a6a21cca668c5c8983dfe86b3cf95add102305da8208100595d69800",
      "previous_version_id": "",
      "next_version_id": ""
    },
    {
      "collection_id": "c82f2b02-bdab-4dd7-b833-3e143745d612",
      "id": "cb3f5f64-c138-4309-b9ea-8d658b0ae28e",
      "name": "IIW Event Logo",
      "version": "",
      "resource_type": "image/png",
      "also_known_as": [
        {
          "uri": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612/resources/cb3f5f64-c138-4309-b9ea-8d658b0ae28e",
          "description": "did-url"
        }
      ],
      "media_type": "image/png",
      "created": "2022-11-17T10:36:37Z",
      "checksum": "d48e158b915eae31ba2db640bd4aac7f82179ee5ca0263a8fe99012d4b02cf48",
      "previous_version_id": "",
      "next_version_id": ""
    },
    {
      "collection_id": "c82f2b02-bdab-4dd7-b833-3e143745d612",
      "id": "e2651dd2-7ca7-44f1-9ba5-57a77747d9b4",
      "name": "GitHub Logo",
      "version": "",
      "resource_type": "image/png",
      "also_known_as": [
        {
          "uri": "did:cheqd:mainnet:c82f2b02-bdab-4dd7-b833-3e143745d612/resources/e2651dd2-7ca7-44f1-9ba5-57a77747d9b4",
          "description": "did-url"
        }
      ],
      "media_type": "image/png",
      "created": "2022-11-17T10:36:09Z",
      "checksum": "22ed95ff774cee8427c86b60288af4077b3b26424c758bec95a34aa8b7a88937",
      "previous_version_id": "",
      "next_version_id": ""
    }
  ],
  "pagination": null
}

Congratulations! You've successfully created a resource on cheqd ledger; hopefully, the first of many.