Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
If you're looking to use the Veramo CLI with cheqd or develop a proof-of-concept application, use the official Veramo CLI setup guide.
Node version recommended Nodev16. You can install Node here
This step is exactly as described in Veramo CLI docs:
Note: Depending on your system permissions, you might be prompted for additional permissions. Add sudo to the beginning of the command in case that happens.
Verify the installation was correct. Command below should output latest version of veramo you installed.
did-provider-cheqd packageInstall the did-provider-cheqd NPM package in a similar fashion:
You can check all of your NPM package versions by running the command:
agent.yml configuration fileDownload the agent.yml file that contains the configuration for cheqd network to be used with Veramo CLI.
You can do this in terminal through:
Note: Alternatively, you can also fetch this by cloning the did-provider-cheqd repository.
agent.yml file in an editor to customise the configYou can open the agent.yml in a text editor/IDE of your choice to edit a few mandatory settings.
In terminal, you can edit the agent.yml file using an editor like nano:
Make sure you provide the actual relative/absolute path to the file.
By default, the did-provider-cheqd package has a default SQLite database password, but it's a good idea to modify and change this to a new key unique to your install.
Take the key generated and replace the value under dbEncryptionKey in the agent.yml file.
In order to be able to read/query did:cheqd entries from the ledger, you need to configure a REST API endpoint for a cheqd DID Resolver instance.
The default value is set to resolver.cheqd.net, which is an instance of the cheqd DID Resolver hosted by the cheqd team. This DID Resolver instance can handle requests for did:cheqd:mainnet as well as did:cheqd:testnet namespaces.
If you want, you can replace the url property with a different REST API endpoint for a different instance of the cheqd DID Resolver.
Note: This configuration is an advanced step and not recommended for most users. Skip it and continue to the next step in most cases, unless you know why you want to switch the resolver interface.
If you plan on interacting with multiple DID methods using Veramo CLI, you can alternatively query did:cheqd using a Universal Resolver instance instead. This allows your CLI configuration to handle any DID method supported by Universal Resolver.
Firstly, comment out the custom did-cheqd-resolver entry and uncomment the universal-resolver entry. This tells Veramo CLI to use the Universal Resolver interface for did:cheqd.
Also comment out this section for the did-cheqd-resolver:
Finally, uncomment and configure the universal-resolver interface:
In order to add cheqd-testnet to your Keplr extension, please follow the following instructions:
Go to Axelar to add a custom network, then replace everything with cheqd-testnet json configuration below.
While reading/querying from the cheqd ledger incurs no cost, if you want to create/update a DID to cheqd ledger, you need to pay transaction fees for the ledger writes.
You need to configure this in under didManager section as shown above, where you'll need to edit:
cosmosPayerMnemonic: Mnemonic associated with your cheqd/Cosmos SDK account. This is only stored locally, and the mnemonic is used to reconstitute the account address and keys used to pay for the transaction.
rpcUrl: For both did:cheqd:mainnet: as well as did:cheqd:testnet: sections, you can specify a Cosmos SDK RPC endpoint. This endpoint is where transactions are sent to. By default, this is populated with rpc.cheqd.net (for mainnet) and rpc.cheqd.network (for testnet), but you can can modify this to a different hosted RPC endpoint for cheqd or even your own local/private RPC endpoint.
defaultProvider: The default cheqd network is set to did:cheqd:testnet to allow developers to test out network functionality. However, if you prefer, you can switch this out to did:cheqd:mainnet instead.
agent.yml file and exitMake sure all your edits above are persisted and saved to a file that you can access.
Once you've completed Step 2 above, verify that your Veramo configuration is accurate using the following command. If your configuration is correct, you should get a success message like the one below.
If the
config checkthrows an error, check out our troubleshooting guide for Veramo CLI setup to see common errors and fixes.
Now that your Veramo CLI installation is successfully set up to work with cheqd, try following our tutorials for creating a new DID or querying existing DIDs.
Veramo SDK plugin for cheqd identity functionality
Veramo SDK is a modular and pluggable client app SDK for decentralised identity and SSI applications. Our Veramo plugin - the @cheqd/did-provider-cheqd NPM package - enables developers to interact with the cheqd ledger using Veramo SDK.
This package includes Veramo SDK Agent methods for use with the Veramo CLI NPM package. It can also be consumed as an NPM package outside Veramo CLI for building your own applications with NPM.
The package's core functionality is borrowed from Veramo Core NPM package and extends this to include cheqd ledger functionality, such as creating and managing DIDs.
Utilise cheqd's identity functionality through the Veramo SDK Plugin by installing the Veramo CLI and getting started below:
We chose to build a cheqd plugin into Veramo SDK for a few key reasons.
Design Principles — The Veramo SDK was designed to be highly flexible and modular making it highly scalable and fit for a lot of complex workflows. As a result, we felt it offered a route to minimise how much needs to be built from scratch. Through its flexible plug-in system, it’s easy to pick and choose which plug-ins are most beneficial, plus it’s possible to add in our custom packages where required which we knew would be necessary from Cosmos-based transactions.
Developer Experience — The Veramo SDK has been designed in a way that offers a fast end-to-end process. Ultimately, at cheqd, we want to reduce the amount of time our team spends on SDKs and so we can maintain our focus on building ledger functionality (i.e. building our implementation of the revocation registry and the credentials payment rails).
Attractive & Simple CLI — The Veramo core API is exposed by its CLI which makes it easy to create DIDs and VCs directly from a terminal or local cloud agent.
Platform Agnostic — The Veramo packages run on Node, Browsers and React & React Native right out of the box.
Veramo provides an excellent foundation for clients that want to build verifiable data applications. This is because Veramo Core, the Veramo CLI and any specific plugins are available as NPM packages, enabling:
Identity functionality to be carried out through a native CLI interface; or
Identity functionality to be integrated directly into client applications through NPM packages.
Using the DID-Provider-cheqd package, we have also been able to reuse identity functionality and abstract the complexity of cheqd/SDK and cheqd Network in less complex packages.
did:cheqd-specific functionalitydid-provider-cheqd is the first Veramo SDK plug-in that utilises the DID Manager Update method to offer a full-body DIDDoc update for a DID on cheqd ledger, rather than individual field update transactions used more commonly in other DID methods such as did:ethr.
New DID creation can also be done by passing a full-body DIDoc payload in JSON, rather than having to assemble the document field-by-field.
Learn how to configure and setup Veramo CLI for working with cheqd network
Our Veramo CLI setup guide provides step-by-step instructions on how to configure your installation for cheqd network
Figure 1: Veramo SDK for cheqd architecture with components (editable Draw.io version)
did-provider-cheqd consumes functionality that exists within the @cheqd/sdk NPM package in a way that complies to the Veramo AbstractIdentifierProvider. (You don't need to call this package separately as it's already included as a dependency in package.json.)
This package works alongside other base Veramo packages:
The @cheqd/sdk package adds Cosmos SDK specific functionality such as signing transactions, paying for ledger fees, etc.
For identity-related keys, this plugin uses Veramo's Key Management System (KMS) to manage keys for create and update operations.
Find out about other Veramo plug-ins in their official documentation.
Our Veramo SDK Plugin natively supports the following Credential formats:
We provide a quick-start setup guide for working with cheqd network using Veramo CLI.
You can use our Veramo plugin in non-CLI contexts as well, for example, for integrating into custom applications
Depending on the type of application you are looking to develop, you will need to install a different set of packages.
For other applications, see:
Follow these instructions to update an existing did:cheqd entry on cheqd ledger.
⚠️ Before you begin...
Make sure you've correctly for Veramo CLI
Before updating the DID, you will need to prepare the updated DIDDoc and parameters for the transaction in an payload.json file.
This file can be saved whereever you choose, but the location must be specified in the . (By default, it will be saved under the project root directory.)
kms (default local): Key Management System (KMS) to be used for storage.
did: The did that resolves to your DIDDoc.
alias: A human-friendly alias for the DID. Only used locally when referencing operations in Veramo CLI.
document: Full body of the DID Document including updated sections.
versionId: (optional) Custom versionId for the DID Document. If this is not set manually, then a UUID will be automatically generated for the DID Document version.
keys: Keys used to sign the DIDDoc. These must match the ones specified in the DIDDoc, otherwise an error will be thrown.
fee
amount: An array of coins, coins are represented as an object with 2 fields
denom: ncheq (smallest denomination classification)
amount: 25000000000 (This is 25 CHEQ by default and will not work with a different value)
gas: Each transaction must specify the maximum amount of gas it may consume.
payer (optional): The cheqd fee payer address
granter (optional): The cheqd fee granter address, Provided the grantee has an allowance by the granter
Use the command below to construct and broadcast update transaction.
So, let's try to update service section of our DIDDoc. Then, your payload.json file will look like this.
Note, that we are updating a service section of in our DIDDoc.
After you have updated the payload.json file, run the command below to update the did:
Note that transaction fees are paid by the cheqd account set in the agent.yml configuration file, . Each of cheqd's on-ledger identity transactions has a fixed fee, . If your account has insufficient balance the transaction will fail.
If you would like to fetch the updated DIDDoc body following the successful DID update result, execute the resolve command as outlined . You can check if service section of DIDDoc has been updated.
DID update operations can be complicated, especially when changing or updating keys, using multiple keys etc. Understand the and to understand the logic that is applied in these scenarios.
Setup Veramo CLI
Set up the Veramo CLI and required packages to use the Veramo SDK Plugin for cheqd.
Create Decentralised Identifiers (DIDs)
Create fully W3C conformant Decentralised Identifiers (DIDs) on cheqd.
Issue Credentials and Presentations
Issue fully W3C conformant Verifiable Credentials and Presentations
Charge for Credentials
Gate encrypted Status Lists with CHEQ using Payment Conditions.
Create Status Lists
Create Verifiable Credential Status List v2021 on-ledger, using DID-Linked Resources
Create DID-Linked Resources
Create a variety of DID-Linked Resources, including schemas, status lists and trust registries on cheqd.
JSON (JWT)
JSON Web Token (JWT) Credentials are a simple way to transmit Trusted Data as a JSON object.
JSON-LD
JSON-LD (Linked Data) Credentials are a richer data format, allowing applications to follow embedded links to other pieces of Linked Data across the web.
Follow these instructions to update an existing did:cheqd entry on cheqd ledger.
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
Construct your payload.json file like this:
Where importantly:
denom: ncheq (smallest denomination classification)
amount: 10000000000 (This is 10 CHEQ by default and will not work with a different value)
Then try running the command below to deactivate the did:
If you would like to fetch the deactivated DIDDoc, execute the resolve command as outlined here. You can check if didDocumentMetadata has the deactivated flag set to true.
Follow these instructions to query a DID from cheqd ledger.
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
Use veramo did resolve <did> to resolve a DID. For example:
TIp: If you have followed along the process of creating a did. You can put your did instead.
The output should look like the following:
DID queries are passed and handled using the cheqd DID Resolver. You can also check out the API endpoints exposed by the DID Resolver to understand how this can be fetched/consumed outside Veramo CLI.
This guide provides common errors and potential fixes for them if you encountered errors when setting up Veramo CLI.
@cheqd/did-provider-cheqdThis error typically happens when the version of did-provider-cheqd is incompatible with the version of Veramo CLI being used.
This can happen if you didn't use the npm -g ("global") flag when installing the packages, and have a conflicting package version for any of the required packages in the folder where you executed this command from.
To verify if this is the case, check the version number of globally-installed NPM packages. Your list may be shorter or longer than this list, but pay close attention to the @cheqd/did-provider-cheqd and @veramo/cli versions.
Compare and contrast this from the output from the same folder where the command failed without the --global / -g flag:
In this example above, you'll see that the version of the @veramo/cli package is not the same one as the global one. This could equally happen with the @cheqd/did-provider-cheqd version.
Doing a global install for both packages will ensure that you've got the correct packages, regardless of which folder the agent.yml file is kept in.
This error is thrown if the cosmosPayerMnemonic value is set to an incorrect number of words (it should either be 12 or 24 words), or if it's left to the default value of 'your cosmos payer mnemonic'.
Note: You can use the same mnemonic for both mainnet and testnet, since the same account address has separate balances on different networks.
Heads-up: Even if you're trying it on testnet you still need to put cosmosPayerMnemonic for your mainnet (You can use the same cosmosPayerMnemonic). Otherwise, you will still be getting the same error as above when you run veramo config check -f agent.yml.
wget -c https://raw.githubusercontent.com/cheqd/did-provider-cheqd/main/agent.yml command is giving you errorsFirst, create agent.yml file at root directory level.
Second, go to this url, copy everything from there and paste it in your agent.yml file. And you're good to go. 😉
This tutorial offers step-by-step guidance on how to verify a JSON credential, encoded as a JWT (JSON Web Token), a W3C compliant proof format.
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
This tutorial assumes you have already issued a JSON/JWT Verifiable Credential so that it can be cryptographically verified as untampered.
credential verify functionIf you have the issued Verifiable Credential stored in a file, say, cred.json, pass it to the credential verify function:
Instead of piping the file like above, you can also verify the credential using the raw credential or JWT as follows:
Then enter the JWT or entire JSON credential including the JWT.
If the credential can be verified correctly, the response will be:
Credential verification is done by decoding the JWT proof and checking if it's tampered or not. Feel free to test this yourself by tampering with the jwt contents in the credential:
If you belive you did everything right(created a verifiable credential and you did not tamper it), and for some reason you're getting
First, make sure you are using a node with version 16 or above.
Second, change Veramo CLI version to @veramo/cli@latest -g as previous versions cause few issues in verification. This will override the previous version you have installed.
Run command below to verify your JWT credential.
Look into how this credential can be shown to others through Verifiable Presentations.
This tutorial offers step-by-step guidance on how to verify a Verifiable Presentation.
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
The cryptographic verification in this tutorial will be based on JWT proof of a previously-created Verifiable Presentation.
presentation verify functionIf you have the generated Verifiable Presentation stored, pass it to the presentation verify function:
If the verification is successful, you'll receive this response:
If you belive you did everything right(created a verifiable presentation and you did not tamper it), and for some reason you're getting
First, make sure you are using a node with version 16 or above.
Second, Change veramo cli version to @veramo/cli@latest -g as previous versions cause few issues in verification. This will override the previous version you have installed.
Run command below to verify your JWT presentation.
Follow these instructions to create a new DID and publish the associated DID Document on cheqd ledger.
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
The first step is generating a template for your DID Document, including a new DID and associated public/private key pair. This process also aligns with method 1 in the key management guide.
It is important to note that this step does not create your DID on ledger, but it generates your identity keys as a draft DID Document for you to use in the on-ledger transaction in Step 3.
You can use the following command in your CLI to create your DIDDoc and associated identity keys:
You can pass the payload of the inputs and arguments as a file rather than inline using:
You can reuse this example file:
Within this command, you are able to choose from the following inputs below to produce different types of DIDDocs:
Once you have submitted the command above, you should receive a DID Document draft template, including a set of identity keys, including your chosen inputs and arguments. You can find an example of this output below:
You can then use this template to populate your payload.json file in Step 2.
After running the above command, if you see an unexpected error, follow our DID Operations Troubleshooting Guide to fix it. A common error is:
Once you have created a template for your DIDDoc and generated your keys, and before creating a DID on-ledger, you will need to prepare the payload.json file. This file can be saved where ever you choose, but the location must be specified in the create DID command used in Step 3. (By default, it will be saved under the project root directory.)
You should copy and paste the output of Step 1 as an initial starting template for your payload.json file.
payload.json filesThe below examples show the variation in syntax for different verification method key types in the DIDDoc payload file itself. Note that each key type has a slightly different output.
kms (default local): Key Management System (KMS) to be used for storage.
alias: A human-friendly alias for the DID. Only used locally when referencing operations in Veramo CLI.
document: Full body of the DID Document
versionId: (optional): Custom versionId for the DID Document. If this is not set manually, then a UUID will be automatically generated for the DID Document version.
keys: Keys used to sign the DIDDoc. These must match the ones specified in the DIDDoc, otherwise an error will be thrown.
fee
amount: An array of coins, coins are represented as an object with 2 fields
denom: ncheq (smallest denomination classification)
amount: 50000000000 (This is 50 CHEQ by default and will not work with a different value)
gas: Each transaction must specify the maximum amount of gas it may consume.
payer (optional): The cheqd fee payer address
granter (optional): The cheqd fee granter address, Provided the grantee has an allowance by the granter
Note that transaction fees are paid by the cheqd account set in the
agent.ymlconfiguration file, setup here. Each of cheqd's on-ledger identity transactions has a fixed fee, the pricing for cheqd DIDs and DID-Linked Resources can be found here. If your account has insufficient balance the transaction will fail.
If you do not specify the --argsFile, you can also paste a JSON inline argument object by using the --argsJSON flag followed by the JSON payload.
If your transaction is successful, you'll receive a success message along with the transaction details. You can query your DID using the instructions here to see the representation of your DID Document on-ledger.
If you are using testnet, you can top-up your testnet balance using our testnet faucet.
You can also configure your Keplr wallet to support cheqd testnet using the instructions here.
If you are using mainnet, you can purchase CHEQ tokens here.
Check out our troubleshooting guide for DID Operations to see common errors and fixes.
This tutorial offers step-by-step guidance on how to create a subject DID to be used for a holder that will receive a Verifiable Credentials.
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
We chose to use did:key for the holder because the did:key specification has a lot synergy with cheqd did method, did:cheqd.
Using did:key also keeps holder DIDs off-ledger. This is very important for the privacy and data protection of the holder. If holder DIDs and DIDDocs were stored on-ledger, this could constitute a risk where data written within the DIDDoc could not be removed in line with a holder's right to be forgotten.
It is also easily managable by a client agent as a full ledger backup for the writing of a DID / DID Doc is not required, thereby making it easily reproducable in a client environment.
Creating a subject did:key DID can be achieved through both the Veramo CLI, or directly through an application that has been setup to read and write to the cheqd ledger, using the Veramo SDK for cheqd.
This off-ledger DID, of type did:key, is used for the recipient of the Verifiable Credential and Verifiable Presentation using:
did:key provider and KMSSelect did:key as the provider when prompted as well as a key management system (KMS) to use (default is local).
The agent.yml file used for the Veramo SDK for cheqd has a preloaded local key management system which is bootstrapped along with the CLI.
The KMS is stored in a local SQLite database.
This is the nickname for your DID, which will be managed by Veramo KMS. Providing a memorable alias will help reference this for future uses, e.g., Alice off ledger DID.
Once you have entered this, you will receive a response in a table, e.g:
If you got the table above, your off-ledger did:key has been created
Follow these instructions to:
Generate identity keys on-the-fly WITH a draft DIDDoc
Generate standalone identity public/private keypairs
Convert identity key pairs generated using Veramo agent to other key encoding formats
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
Instead of creating identity keys standalone, you can generate them along with a DIDDoc template. This makes it far easier to handle different inputs and arguments, such as generating DID Docs with different key types.
You can use the following command in your CLI to create your DIDDoc and associated identity keys:
You can pass the payload of the inputs and arguments as a file rather than inline using:
You can reuse this example file:
Within this command, you are able to choose from the following inputs below to produce different types of DIDDocs:
Once you have submitted the command above, you should receive a DID Document draft template, including a set of identity keys, including your chosen inputs and arguments. You can find an example of this output below:
After running the above command, if you see an unexpected error, follow our DID Operations Troubleshooting Guide to fix it. A common error is:
You can generate identity keys standalone in a plug-and-play format for future use in create DID or update DID transactions.
If you want to use identity keys outside of Veramo CLI, you can convert keys from one format to another.
For example, if you would like to convert from hex to base64, you can use the following generic approach:
This works with other encoding conversion libraries (i.e. multiformats).
Learn about DIDs If you want to learn about what DIDs are, please go over to our learning site here.
A Decentralized Identifier "DID" is a globally unique identifier that does not require a centralized registration authority because it is registered with distributed ledger technology or other form of decentralized network.
Learn about DIDs If you want to learn about what DIDs are, please go over to our learning site here.
Below are a list of alternatives for creating cheqd DIDs.
To create an encrypted Verifiable Credential Status List v2021 with a set of Access Control Conditions, an Issuer will need to:
Compile a payload.json file with requisite Access Control Conditions;
Submit a create Status List transaction the the ledger.
Below are examples of encrypted Status List Payload files:
The provided code snippets above show two Status List Payload files for both Revocation and Suspension.
The Payload files are a crucial configuration element that establishes Payment Conditions for unlocking a Status List Resource. Let's break down the components of this code to understand how it achieves this access control mechanism:
Once an Issuer has compiled the Payload file, they can submit this to the ledger using the following transaction:
The ledger will acknowledge that this StatusList bitstring should be This indicates to the ledger that the Resource should be fully encrypted and only be decrypted upon the set conditions being met.
The following code snippet shows an example of an encrypted Status List broadcast on-ledger as a DID-Linked Resource:
Importantly, the only encrypted element is the "encodedList" element. This provides the Verifier sufficient information to be able to make the payment back the the Issuer and to fulfill the Access Control Conditions, without being able to see the contents of the Status List itself.
By utilizing cryptographic operations, specifying payment requirements, and ensuring data encryption, this configuration enhances the security, integrity, and controlled access to the Status List, aligning with the principles of decentralized and secure identity management.
Getting started with Payment Rails for Verifiable Credentials
Credential Payments brings a significant evolution to the Verifiable Credentials landscape, allowing verifiers to directly pay issuers to unlock Credential Status information. Underneath the hood, we've engineered a robust and secure payment flow that streamlines the end-to-end payment process, with accuracy, speed, and cryptographic integrity.
Below are a list of alternatives for using Credential Payments.
Learn about Verifiable Credentials and Presentations
If you want to learn more about what
Veramo SDK plugin supports two major digital Credential types. Below you can learn about these Credential formats:
Below are a list of alternatives for using Credentials with cheqd support. Each offers a different set of protocols and underlying technical capabilities.
This tutorial offers step-by-step guidance on how to create a .
⚠️ Before you begin... Make sure you've correctly for Veramo CLI
A Verifiable Presentation is a way a credential holder can generate cryptographicall-verifiable proof that they are in posession of the identity keys (e.g., did:key) the credential was issued to.
This is important because , on its own, is susceptible to where intercepted Verifiable Credentials could be played back.
The process of creating a Verifiable Presentation is one way of addressing these security concerns.
Begin the process of creating a Verifiable Presentation using:
Specify the subject identity key to be used for signing Verifiable Presentation, e.g., chosen holder did:key.
Tag for the Verifiable PresentationHit Enter to accept the default at this step
Select how many verifiers will need to be able to verify the presentation.
This can be the same as the Verifiable Credential, or a sub-section of it. Choose Enter for default.
Select the DID of the verifier from the options presented. In a very simplistic scenario, the verifier could be the same as the issuer, e.g., a scenario where the holder returns a period of time to show they were issued a credential.
You can select one or more Verifiable Credentials to bundle up into the Verifiable Presentation.
After these choices are made, the Verifiable Presentation will be displayed in JSON format along with JWT proof.
Save this output in the folder you have been using throughout, saving as pres.txt.
You will need to call on this to verify the presentation in the next step.
In a real-world usage scenario, the Verifiable Presentation output generated above would be electronically (e.g., as API messages) or non-electronically (e.g., encoded to a QR code) shared with the verifier/recipient.
The is a working document from the W3C to support a privacy-preserving, space-efficient, and high-performance mechanism for publishing status information such as suspension or revocation of JSON and JSON-LD Verifiable Credentials.
Using DID-Linked Resources, we have been able to natively support Status List 2021 on cheqd directly.
The utilises to represent whether a Verifiable Credential has been suspended/revoked or not. A bitstring can be thought of as a long list of 1s and 0s, where, if the binary value of the position in the list is 1 (one), the is revoked, if it is 0 (zero) it is not revoked.
Figure 1: Graphic showing the StatusList2021 bitstring
The issuer keeps a bitstring list of all Verifiable Credentials it has issued. The StatusList is usually published by the issuer in the format of its own Verifiable Credential. This Verifiable Credential is generally hosted publicly on a centralised server or domain to enable third-party read-access.
Below are a list of alternatives for creating cheqd Status Lists.
This guide provides common errors and potential fixes for them if you encountered errors when .
When you try to generate keys along with DIDDoc template using command below
If you encounter an error below
Unexpected token v in JSON at position 1
Create a .json file (e.g. name it something like identity-keys-on-the-fly-with-did-docs.json in same working directory level).
Copy and paste the content from below into your newly created .json file. You can choose from any of the inputs and arguments below:
For example:
Then, instead of passing it as argument, we'll pass it as a file. Use command below to do it.
The above command will output something like this (i.e. a template DID DOC with the keys)
Then you can go back to your payload.json file (if you didn't have one you can simply create one manually, and paste content below as template) which should be something like this at first.
Then you're going to update keys and document section of it (payload.json) with keys and didDoc you generated in above step.
After populating keys and document section. Your payload.json file should look something like this:
Assuming you have enough ncheq tokens inside your wallet, you can now run the command below to create your DID.
If the above cmd resulted something like this:
Account does not exist on chain. Send some tokens there before trying to query sequence.
This means you don't have enough tokens in your wallet.
After successfully creating your DID, you should see something like this:
Notice, controllerKeyId is now the publicKeyHex you generated the firstly. i.e did is know associated to you via publickKeyHex or you're the controller of this the DID you created. 😄
Follow the , including the credentialStatus information, as shown in the example below:
Where the values within the credentialSubject field are as follows:
The following process, or one generating the exact output, MUST be followed when validating a verifiable credential that is contained in a cheqd StatusList Resource.
Let credentialToValidate be a verifiable credentials containing a credentialStatus entry that is a StatusList2021Entry, associated with an entry in a bitstring.
Let status purpose be the value of statusPurpose in the credentialStatus entry in the credentialToValidate.
Verify all proofs associated with the credentialToValidate. If a proof fails, return a validation error.
Verify that the status purpose matches the resourceType value in the StatusList2021 Resource.
Let compressed bitstring be the value of the encodedList property of the StatusList2021 Resource.
Let credentialIndex be the value of the statusListIndex property of the bitstring in the StatusList2021 Resource.
Let status be the value of the bit at position credentialIndex in the revocation bitstring.
Return true if status is 1, false otherwise.
This tutorial offers step-by-step guidance on how to issue a verifiable credential
⚠️ Before you begin...
Make sure you've correctly for Veramo CLI
The subject (holder) of this credential will be an off-ledger DID. The rationale for using off-ledger DIDs when issuing a credential is because the fact that they aren't persisted on ledger means they cannot be correlated or tracked to specific users/individuals.
This allows a user to have multiple did:key identities, and the identifier/handle they reveal when sharing a is context-dependent and better for privacy.
The issuer of the credential, on the other hand, uses since this needs to be publicly-accessible and cryptographically verifiable.
did:key subject DIDNormally, the credential holder will provide a did:key DID they have generated themselves (usually done in the background by apps they are using). So, this step typically isn't done by a credential issuer.
For the purpose of this tutorial though, we recommend you for the later steps.
Start credential generation using:
You'll be presented with an multiple options select:
Select which Issuer DID stored in your local storage you'd like to issue the credential from, e.g., did:cheqd:mainnet:zAXwwqZzhCZA1L77ZBa8fhVNjL9MQCHX
Select which subject DID from your local agent storage the credential should be issued to, e.g., did:key:z6Mkktr27VZ7TTFoTsD9p79JwtGnQDgJWKGrxJ79quE7M5Yx.
This could the subject DID created in Step 1.
This is currently free-text. However, you can hit Enter to use VerifiableCredential as the default credential context.
The claim type can be thought of as the label in a form field. It can denote the purpose/attribute being stored in the credential.
For example, the claim type name could refer to the name of an individual.
Enter the value of the claim type. For example, you specified name as the claim type, the value could be Alice.
In this tutorial, we will create a credential with only a single name-value pair.
JSON/JWT credentials with DIDs anchored on cheqd are currently not revocable, so please choose No at this step.
At this last step, Veramo CLI generates the credential based on the inputs above.
Note: The human-readable JSON body below is purely for easier parsing by developers/applications. The proof is encoded as JWT or JWS at the bottom of the credential, which can be decoded to reconstruct the entire credential.
Note that the JSON is unordered so the output of the fields could be in a different order
Create Verifiable Credential Status List v2021 on cheqd
The indicates that it may be desirable to store the actual StatusList using something like a to lessen the load on the server maintained by the issuer to return a result in real-time.
Using cheqd's Resource Module, the same benefits may be achieved. In fact, storing a StatusList as an on-ledger Resource is a much better application of technology than using a Verifiable Credential for the same purpose.
By storing a StatusList on the cheqd Network as a Resource, it creates a much more resilient and decentralised mechanism for storing and maintaining the revocation/suspension status of Verifiable Credentials. The .
Moreover, cheqd's Resource Module enables individual Resources to be referenced and retrieved using a DID URL in conformance with DID Core. This is being standardized at within a specification called .
Using the cheqd Resource module, the same content and semantics of StatusList2021 can be replicated, with additional benefits of enabling DID Resolvers to fetch the contents of the StatusList.
You can follow the .
Let's assume that the following DID is created.
Note: The uncompressed bitstring MUST be at least 16KB in size to maintain herd privacy for the holder.
Where the fields within the payload have the following meaning:
Note: If an issuer wants to create multiple StatusLists within the same Collection, they must have unique and distinct names.
Once created, the StatusList2021 Resource will be associated with the parent DID, and referenced in the DID Document Metadata as follows:
An issuer may want to regularly update the bitstring whenever there is a certain amount of revocation status updates. The issuer will therefore need to create a new version for the initial StatusList2021 Resource.
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, it is necessary to use the same collection-id, name and type 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.
For example:
Resulting in the following metadata syntax:
Issue Verifiable Credential with Encrypted Status List 2021 and index
There is a specific transaction type for issuing Verifiable Credentials that reference encrypted Status List Resources.
Follow the tutorial here to create an encrypted Status List 2021 Resource on cheqd.
Each encrypted Status List is a , where each bit represents a Credential which is either revoked or unrevoked (or suspended or unsuspended).
Users should maintain and manage a list of which Credentials match with which specific bitstring indices to be able to revoke or suspend Credentials in the future, and to avoid collisions.
When issuing a Credential, you have the choice of whether to manually specify an index for the Credential within the bitstring, or randomly generate an index number anywhere in the bitstring, or within a given range.
As mentioned above, when constructing the payload for your Credential, including the encrypted Resource, you have a choice of how you would like to specify the index.
The following parameters may be included:
| Parameter | Value | Optional |
|---|
Below are a set of examples of how these parameters may be included in Credential payload files for different purposes:
Once you have constructed your payload file, and have saved it as a JSON file, use the transaction below to issue the Verifiable Credential.
If the transaction is successful, you will get returned a formatted Verifiable Credential, including a populated "credentialStatus" section.
Paying an Issuer to unlock a Credential Status
A Verifier may need to pay an Issuer to unlock Status information about the presented Credential. Without meeting the payment conditions, the Verifier will not be able to ascertain whether the Credential has been revoked (or suspended) or not.
A Verifier can choose to make a payment to the Issuer if they want to obtain this extra Credential Status information to build a higher level of trust within the Credential presented to them.
If a Verifier wants to unlock access to the Resource, to gain access to additional information about a Credential presented to them, such as the Credential Status, firstly, the Verifier will be presented Credential, including a link to the StatusList within the "credentialStatus" section of the Credential body.
Through following the link in"credentialStatus" section of the Credential body. the The Verifier will be directed to an on-ledger Resource, identifiable through a DID URL, for example:
This on-ledger Resource will contain:
An encrypted potion of the Resource, such as a Status List bitstring. identified by the "encodedList" property.
Unencrypted metadata about the Resource, including the issuers' payment address "feePayerAddress" and and the Payment Conditions, "feePaymentAmount" and "intervalInSeconds".
This gives the verifier requisite information they need in order to pay the Issuer to unlock the Credential Status. You can learn more about Access Control Conditions below.
This payment should be made in CHEQ.
Note that the "feePaymentAmount" may be specified in ncheq. This is lowest denomination of the CHEQ token, "nano" CHEQ which is 1 x 10^-9 CHEQ.
Note the "intervalInSeconds" which indicates how long after making the payment the Verifier has to verify the Credential.
The Verifier should input the presented Credential into a payload file, including the parameter:
"fetchList": true
This indicates that the Verifier wants to claim that they have met the Access Control Conditions, and for the nodes to query whether the Access Control Condition has been met. For example:
Using the Veramo CLI. Verifiers can submit the following transaction, alongside the payload file to verify the Credential:
If successful, the Verifier will obtain the keys to decrypt the Status List and access the Credential Status information. The Verifier will receive a response indicating whether the Credential:
Is verified and untampered
Has been revoked (or suspended) or not
This provides the Verifier the full information to make a trust decision, having paid the Issuer for the Credential Status information.
| provider | alias | did | |
|---|---|---|---|
| Parameter | Value | Description |
|---|
Verifiers/recipients would then be able to to check cryptographically the contents are untampered.
Each issued Credential correlates with a position and index on the bitstring, so that a verifier will be able to correlate the value within the Credential against the public bitstring to ascertain whether the Credential has been revoked or not, using a as well as a .
cheqd stores each Status List and subsequent entries on-ledger as versions. This has notable benefits, including the provenance, legitimacy and security of the Status List. For a full list of benefits, see .
You can go to cheqd's to get your account some test tokens.
| Property | Description |
|---|
Generate a revocation bitstring by passing compressed bitstring to the .
jwt for , encoded as a , a
lds for , encoded as a , a
Learn about different types of Verifiable Credentials
If you want to learn more about different types of verifiable credentials
The assumption here is that you've either or .
is a major element of cheqd's roadmap.
You can save the generated Verifiable Credential, as you can later use it to or to others.
Prepare a file with the StatusList2021 bitstring encodedList and encode it into base64, following the .
. On Unix systems, the uuidgen tool can be used to generate a new UUID.
| Parameter | Description |
|---|
Ensure that the "statusPurpose" and "statusListName" is the same as the existing Status List on-ledger, .
Using one of , Verifiers can make a payment of the amount specified in the "feePaymentAmount" to the "feePayerAddress".
Once the Verifier makes a payment of the specified amount in the payment conditions back to the Issuer, the will be met.
did:key
Alice off ledger DID
did:key:z6MkjxdqDUWoudesywsGYbzGozUeVYiYVArdoqPcMV6m6MG4
Create DID
Create an Issuer DID using the did:cheqd DID method over REST API.
Create Subject DID
Create a Subject DID using the did:key or did:vda DID methods.
Resolve DID
Resolve a DID to retrieve the associated DID Document.
cheqd Studio
Our API product enables users to use cheqd's functionality with minimal complexity and easily integrate APIs into existing apps.
DID Registrar
Simple setup for building cheqd DIDs into existing applications using REST APIs, building into the Universal Registrar.
Credo
Credo is an SDK which supports the European Architecture and Reference Framework (ARF) standards as well as AnonCreds with full cheqd support for DIDs.
Walt.id SSI Kit
Walt.id SSI Kit is an SDK that supports the European Architecture and Reference Framework (ARF) standards for identity, with full cheqd support.
cheqd Cosmos CLI
Cosmos CLI which directly communicates with the cheqd network. This should only be used for testing environments.
|
| This indicates that a local Key Management System (KMS) is being used for cryptographic operations, ensuring secure key handling. |
|
| Specifies the issuer's Decentralized Identifier (DID), uniquely identifying the entity responsible for managing and issuing verifiable credentials. |
|
| Names the Verifiable Credential Status List, providing context for its purpose. |
|
| Defines the purpose of the status list. This can be either revocation or suspension. |
|
| Indicates that the Verifiable Credential Status List, crucially, is encrypted, enhancing data privacy and security. This can be either true or false (unencrypted). |
|
| Describes the payment conditions required for accessing the status list. In this case, a timelock payment mechanism is used, specifying the fee payment address, amount, and interval. |
|
| Specifies that the symmetric key for decrypting the status list will be returned. |
|
| Specifies whether the encrypted keys should be broadcast on |
|
| Specifies the network where the sharded decryption keys will be stored (across Lit Protocol) |
| A specific DID URL dereferencing to the actual status of the Credential |
type | The |
| The purpose of the status entry MUST be a string. While the value of the string is arbitrary, the following values MUST be used for their intended purpose: revocation or suspension |
| The |
| The |
collectionId | The unique identifier of the parent DID, to link the Resource to a particular DID |
id | A UUID for the resource, to enable it to be specifically referenced and fetched |
name | This must be a unique name indicating the |
resourceType | This must indicate the |
data | Base 64 encoded file containing the full bitstring for the StatusList |
|
| No |
| string | No |
| string | Yes |
| number | Yes |
| number | Yes |
| number, or set of numbers | Yes |
Follow these instructions to create a new DID and publish the associated DIDDoc on cheqd ledger.
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
Follow this tutorial to generate keys and create a DID.
Follow this tutorial to create the first version of the resource.
Follow exactly the same steps as the first resource. Note that to create a new resource version which belongs to the same set as a previous resource, in the you must specify the same:
collectionId
name
resourceType
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).
New versions have dedicated unique IDs and can be referenced and retrieved as any other resources.
Follow the same tutorial as for resource creation, but use the same collectionId, name and resourceType as for the previous Resource version.
Follow these instructions to create a new DID-Linked Resource on cheqd mainnet or testnet.
⚠️ Before you begin...
Make sure you've correctly configured the cheqd plugin's agent settings for Veramo CLI
Follow this tutorial to generate keys and create a DID.
DID-Linked Resources can be any type of file or content that is below ~200kb in size.
For the purpose of an example, lets use an AnonCreds schema (JSON file) as the resource:
Save this file locally and call it something like resource.json.
UUIDs are used to identify DID-Linked Resources. On Unix systems, the uuidgen tool can be used to generate a new UUID:
Prepare a file with resource and encode it into base64. On Unix systems, you can use the following command input:
Expected output:
You will need to paste the output of the Base64 into the data field of the payload.json file as shown in step 5.
Once you have saved your Resource file locally, you can copy the path and enter it in the file field of the payload.json file as shown in step 5.
Before carrying out a Resource transaction, you will need to prepare the payload.json file. This file can be saved wherever you choose, but the location must be specified in the create Resource command. (By default, it will be saved under the project root directory.)
kms (default local): Key Management System (KMS) to be used for storage;
payload: Resource definition
collectionId: The last fragment of the corresponding DIDDoc
id: Use output from the previous step here
name: Arbitrary human-readable string used to identify the resource
resourceType: Resource type, such as CL-Schema, JSONSchema2020, etc
version: (Optional) client-given resource version
alsoKnownAs: (Optional) alternative URI(s) provided for the resource
data: (Optional) base64 encoded data of resource file
signInputs: Keys used to sign the corresponding DIDDoc. These must match the ones specified in the DIDDoc, otherwise an error will be thrown
verificationMethodId: Verification method ID from DIDDoc where key is published
keyType should match values that you used to create the DIDDoc
privateKeyHex should match values that you used to create the DIDDoc
file: (Optional) path to resource file
fee:
amount: An array of coins, coins are represented as an object with 2 fields
denom: ncheq (smallest denomination classification)
amount: See section below on fees
gas: Each transaction must specify the maximum amount of gas it may consume.
payer (Optional): The cheqd fee payer address
granter (Optional): The cheqd fee granter address, Provided the grantee has an allowance by the granter
The Payload file can include a Resource passed either as a file or a base64 encoded string:
The maximum file size for a resource is roughly 46KB which may require a gas fee of up to 2000000.
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:
Note that transaction fees are paid by the cheqd account set in the
agent.ymlconfiguration file, setup here. If you do not specify a fee in the transaction, the ledger will automatically deduct the appropriate fee from the account set in youragent.ymlconfiguration. Each of cheqd's on-ledger identity transactions has a fixed fee, the pricing for cheqd DIDs and DID-Linked Resources can be found here. If your account has insufficient balance the transaction will fail.
If you do not specify the --argsFile in the previous step, you can also paste a JSON inline argument object by using the --argsJSON flag followed by the JSON payload.
"DID-Linked Resources" are identified with a did:cheqd Decentralized Identifier with a Universally Unique Identifier (UUID) that acts as a permanently-accessible link to fetch the resources from the cheqd ledger. We refer to this as the "resource ID". Through the "resource ID" or a set of DID URL query parameters, applications are able to persistently access a digital resource on the cheqd network.
Below are a list of alternatives for creating cheqd DID-Linked Resources.
Simple setup for building cheqd DIDs into existing applications using REST APIs, building into the .
Create DID-Linked Resource
Create a custom DID-Linked Resource for a schema, Trust Registry or other persistent data file.
Create Status List
Create an on-ledger Status List associated with a DID.
Understanding DID-Linked Resources
Detailed guide explaining the context and technical composition of DID-Linked Resources on cheqd.
DID Resolution and DID URL Dereferencing
Architecture decision record explaining the different parameters for fetching DID Document data on cheqd, including DID-Linked Resources
cheqd Cosmos CLI
Cosmos-native CLI for creating transactions on cheqd. Should be used for testing purposes only.
cheqd Studio
Our API product enables users to use cheqd's functionality with minimal complexity and easily integrate APIs into existing apps.
DID Registrar
Simple setup for building cheqd DIDs into existing applications using REST APIs, building into the Universal Registrar.
Credo
Credo is an SDK which supports the European Architecture and Reference Framework (ARF) standards as well as AnonCreds with full cheqd support for DIDs.
