Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Learn how cheqd's Credential Payments work
Build your knowledge about how cheqd's Credential Payment model works, including setting Access Control Conditions, and privacy-preserving payment flows.
Using cheqd Studio, you can get started setting up your encrypted Status Lists with Access Control Conditions below:
t
Understand how to issue a Verifiable Credential including an encrypted Status List in the body.
Issuers are able to add encrypted Status Lists to the body of the Credential if they have previously created an Encrypted Status List on-ledger.
Make sure you have set up your account with cheqd Studio and are logged in, using our guide below:
Before you can create an encrypted Status List for charging for Credentials, you need to create a DID which is used to link the Status List on-ledger. Use the API in the page below to create a DID:
Follow the tutorial here to create an encrypted Status List with a set of Payment Conditions to unlock:
Follow the instructions within the /credential/create
API below to format and issue a Verifiable Credential.
Ensure that the "statusListName
" and "statusPurpose
" are the same as the Status List created in Step 3. This makes sure that if the Credential Status is changed, for example, if it is revoked or suspended, the correct Status List will be updated.
Creating an encrypted Status List 2021 Resource using cheqd Studio
To create an encrypted Verifiable Credential Status List v2021 with a set of Access Control Conditions, an Issuer will need to follow the steps below:
Make sure you have set up your account with cheqd Studio and are logged in, using our guide below:
Before you can create an encrypted Status List for charging for Credentials, you need to create a DID which is used to link the Status List on-ledger. Use the API in the page below to create a DID:
When creating a Status List, a user will have the following options:
For the purpose of this tutorial, we will assume the user is creating an encrypted Status List. For unencrypted Status Lists, follow the tutorial here.
Using the /credential-status/create/encrypted
API, users have two options for creating an encrypted Status List on-ledger:
Filling out a simple form using the application/x-www-url-form-encoded
option on the Swagger UI.
Compiling a Status List payload yourself using the application/json
option on the Swagger UI.
This is the easiest way to create encrypted Status Lists on cheqd and is recommended for users who are not overly familiar with compiling JSON objects.
Using the application/x-www-url-form-encoded
option on the Swagger UI, users are able to choose between the following variables and options to create an encrypted Status List on-ledger:
From this request, cheqd Studio will automatically create and publish an encrypted Status List to the ledger with set Payment Conditions required to be met to unlock.
Instead of using simple form variables, you can create an encrypted Status List using a JSON payload yourself using the application/json
option on the Swagger UI.
An example of the JSON payload needed to be submitted is below:
The table below expands on some of the required parameters:
"feePaymentAddress"
"cheqd1xl5wccz667lk06ahama26pdqvrkz5aws6m0ztp"
This specifies the cheqd address to which the payment fee should be sent. This address is associated with the User who wants to charge for Credential Status
"feePaymentAmount"
"1000"
This defines the amount of the payment fee in CHEQ which the Issuer will charge for a third party to unlock the Credential Status.
The amount may be up to 2 decimal points, e.g. "1000.25
".
"feePaymentWindow"
"10
"
The amount of time, in minutes, after making the payment in which a Verifier is able to unlock an encrypted resource.
Once the Issuer has populated the requisite information for the encrypted Status List request, they can use the API below to submit it to the ledger.
The following code snippet shows an example of an encrypted Status List response format, which will be published to the ledger:
Note: it is important to save the response, including the "encryptedSymmetricKey
" locally, as this will be used for updating encrypted Status List operations.
Note: 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.
Understand how privacy is protected throughout the payment flow
cheqd's implementation of Credential Payments uses encrypted DID-Linked Resources (such as a Status Lists), with Payment Conditions required to unlock. Learn about cheqd's Access Control Condition logic below:
There are multiple areas within this flow where privacy needs to be maintained:
Status List construction: Credential information within Status List should not constitute Personally Identifiable Information (PII).
Verifier pays Issuer: Any payment for decrypting a Status List should not be correlatable to a Holder presenting or sharing a Credential.
The Status List 2021 Specification, which cheqd encrypts with payment conditions, utilises bitstrings 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 verifiable credential is revoked, if it is 0 (zero) it is not revoked.
This works by tying each issued Credential with a position and index on the bitstring, so that a Verifier will be able to check the value within the Credential against the public bitstring to ascertain whether the Credential has been revoked or not, using a validate algorithm as well as a bitstring expansion algorithm.
As part of the bitstring construction. there is a minimum bitstring length of 131,072 entries (16kb uncompressed). Moreover, in this string, the indexes that are not specified are randomised between revoked and unrevoked. This means that there will never be a bitstring with a single entry, or a small amount of entries.
Using this type of construction, the privacy of the Holder is protected through "Herd Privacy" because there is no way that a third party can externally view the Status List and can correlate indices with a particular individual's credential without direct knowledge of a Holders' credential index.
The Verifiable Credential Status List v2021 specification expands on these privacy considerations.
As part of the Access Control Condition setup, the Issuer can set a single payment fee for meeting the Access Control Conditions and decrypting a particular Status List.
Through setting a flat price for decryption, there is no price variation from checking one persons' credential status versus another's. This means that for a particular Status List, all payments on the network will be made at the same price.
Once again, this creates a layer of "Herd Privacy" for the Holder, since the Credential index itself is decoupled from the payment fee. Therefore. while transactions will be visible on the network, there will be no way for a third party to surveil the network or draw conclusions about who's Credential status is being checked.
If there was a variation in the price per Credential status check within the same status list, this would be more likely to become correlatable, alongside other information, back to a specific individual.
We will continue to improve and assess the privacy considerations as we roll out Credential Payments. Some areas we believe there may be scope for privacy leakage are as follows:
Holders' Credential index is doxxed: If a Holder has a particular Credential index doxxed, as well as a link to the status list, there may be scope to monitor the Credential Status of that individual, through a payment. However, third parties will not know when that Holder is using their Credentials.
Issuer creates single entry Status List with specific unlock price: If an Issuer does not use our preset Status List length and creates their own resource with a single or few entries, they may provide a higher likelihood of doxxing when an individual uses their Credential. This is why cheqd, and the specification, has enforced a minimum Status List length.
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.
Create encrypted Status Lists on-ledger, and pay to unlock the Access Control Conditions in CHEQ, using our cheqd Studio Payments APIs:
Build your understanding of How Credential Payments work, including Access Control Conditions and how the model preserves privacy.
Below are a list of alternatives for using Credential Payments.
Access Control Conditions
Familiarise yourself with how the Payment gating and Access Control Condition logic works.
Privacy Considerations
Understand how privacy is preserved throughout the Credential Payments flow.
Charge for Status List
Set your payment conditions and encrypt a Status List 2021 Resource.
Issue Credential with Encrypted Status List
Issue a Verifiable Credential referencing an encrypted Status List in the Credential body.
Verifier pays Issuer
Pay an Issuer directly in CHEQ, meeting the Access Control Conditions. Verify the Credential to view the Status information.
Set up your account
Set up your account with cheqd Studio and log in to start using the APIs.
Create an Issuer DID
Create a W3C conformant DID on cheqd using the did:cheqd
DID Method.
Charge for Status List
Create an encrypted Status List on-ledger with Payment Conditions to unlock, to charge for unlocking Status Lists.
Issue Credential
Issue a W3C conformant Verifiable Credential using the cheqd Studio APIs.
Set up your account
Set up your account with cheqd Studio and log in to start using the APIs.
Create an Issuer DID
Create a W3C conformant DID on cheqd using the did:cheqd
DID Method.
Why are we payment gating Status Lists?
Learn about the role of cheqd in Trusted Data Markets and why we are payment gating the "reputability" of Credentials.
Charge for Status List
With Credential Payments, Issuers are able to create payment-gated Status Lists in order to charge for the verification of Credential Status information.
Issue Credential with Encrypted Status List
Issue a Verifiable Credential referencing an encrypted Status List in the body, with a specified bitstring index.
Verifier pays Issuer
Understand how a Verifier pays an Issuer in CHEQ to unlock Status List and verify Credential Status.
Bulk Update or Rotate Encryption Keys
Update a set of Credential indices or rotate the encrypted symmetric key for the Status List.
Understanding Credential Payments
Before diving into Credential Payments, developers may want to learn how the Payment gating and Access Control condition logic works.
Veramo SDK Plugin
The Veramo SDK Plugin is an extension of the Veramo SDK, a JavaScript framework for Trusted Data, adding support for cheqd functionality.
/credential-status/update/encrypted
The update action to be performed on the encrypted status list, can be revoke, suspend or reinstate
revoke
, suspend
, reinstate
DID of the StatusList2021 publisher.
The name of the StatusList2021 DID-Linked Resource to be updated.
List of credential status indices to be updated. The indices must be in the range of the status list.
Optional field to assign a human-readable version in the StatusList2021 DID-Linked Resource.
The symmetric key used to encrypt the StatusList2021 DID-Linked Resource.
The cheqd/Cosmos payment address where payments to unlock the encrypted StatusList2021 DID-Linked Resource need to be sent.
cheqd1qs0nhyk868c246defezhz5eymlt0dmajna2csg
Amount in CHEQ tokens to unlock the encrypted StatusList2021 DID-Linked Resource.
Time window (in minutes) within which the payment to unlock the encrypted StatusList2021 DID-Linked Resource is considered valid.
/credential-status/update/encrypted
The update action to be performed on the encrypted status list, can be revoke, suspend or reinstate
revoke
, suspend
, reinstate
DID of the StatusList2021 publisher.
The name of the StatusList2021 DID-Linked Resource to be updated.
List of credential status indices to be updated. The indices must be in the range of the status list.
Optional field to assign a human-readable version in the StatusList2021 DID-Linked Resource.
The symmetric key used to encrypt the StatusList2021 DID-Linked Resource.
The cheqd/Cosmos payment address where payments to unlock the encrypted StatusList2021 DID-Linked Resource need to be sent.
cheqd1qs0nhyk868c246defezhz5eymlt0dmajna2csg
Amount in CHEQ tokens to unlock the encrypted StatusList2021 DID-Linked Resource.
Time window (in minutes) within which the payment to unlock the encrypted StatusList2021 DID-Linked Resource is considered valid.
Access Control Conditions
Understand how cheqd gates encrypted resources using payment conditions and Access Control logic.
How a Verifier pays an Issuer to decrypt an encrypted Status List
cheqd Studio supports payments for verifying Credential Status. This is an innovative feature that is also commonly known as cheqd's Payment Rails. Using the API in this tutorial, there are multiple ways for a Verifier to pay an Issuer to unlock and verify a Credential's status.
A Verifier will need a cheqd Studio account to take advantage of the /credential-status/check
API and easily use cheqd's Credential Payments. Make sure you are set up and are logged in, using our guide below:
Using the /credential-status/check
API, users have two options for checking whether a particular Credential index is revoked or suspended:
Filling out a simple form using the application/x-www-url-form-encoded
option on the Swagger UI.
Compiling the JSON transaction yourself using the application/json
option on the Swagger UI.
This is the easiest way to check whether a particular credential index is revoked or suspended.
Using the application/x-www-url-form-encoded
option on the Swagger UI, users are able to choose between the following variables to compile your DID:
To automatically make a payment to an Issuer in order to verify an encrypted Status List, there is an additional variable:
If there is sufficient CHEQ in the account of the Verifier, this will automatically make a payment to the Issuer and meet the Access Control Conditions.
In the same action, the Credential Service will perform a verification check on the Credential Status and pay the issuer the fee specified in the Payment Conditions.
The response format below will indicate clearly whether the check is successful and whether the Credential index in question is revoked / suspended or not.
If a Verifier does not want to automatically pay the Issuer using the API, they can choose to make a manual payment to unlock the 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 Status List 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.
Using one of cheqd's supported wallets, Verifiers can make a payment of the amount specified in the "feePaymentAmount"
to the "feePayerAddress"
.
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.
cheqd Studio will perform a verification check on the Credential Status and pay the issuer the fee specified in the Payment Conditions.
Note the "intervalInSeconds
" which is the amount of time after making the payment that the Verifier has to hit the API and request access to the encrypted Status List.
The response format below will indicate clearly whether the check is successful and whether the Credential index in question is revoked / suspended or not.
Alternatively, if Verifiers have made the payment manually they can also use the /credential/verify API in the tutorial below:
The /credential-status/update/encrypted
API enables users to update the indices of a Status List or rotate the encryption keys. This may be useful for revoking Credentials in bulk, rather than submitting individual /credential/revoke
requests.
When a new encrypted Status List resource is published, this will also encrypt the latest version with a new set of encryption keys. This may therefore be used to rotate encryption keys, even if the listed indices are kept the same.
Understand how cheqd's Payment Rails work with Access Control Conditions
The Access Control Conditions outlined in this section establish a secure and structured framework for unlocking encrypted Status Lists and other DID-Linked Resource.
By employing a combination of Decentralised Identifiers (DIDs), DID-Linked Resources, encryption, and timed payment mechanisms, these access control conditions safeguard the integrity of the Resource, promote transparency, and control access to its data.
For Credential Payments, the predominant Access Control Condition is a payment made from the Verifier of a Credential back to the Issuer.
The payment conditions outlined in the code snippet below define the payment requirements that must be met to access and interact with an encrypted Resource. These are written into a payload.json
file when a create Status List transaction is made to the ledger ().
These conditions are established to ensure that authorized entities or users contribute a specified fee before gaining access to the Resource.
The parameters within the payment conditions are defined as follows:
By including these payment conditions in the Status List Payload, the ledger enforces a financial gate from verifiers seeking access. Additionally, the timelock mechanism adds a layer of time-based verification to the payment process. With the timelock, the payment can only be made in a specific time-interval from the latest block-time on the cheqd network. This ensures that historical payments cannot be used to meet the access control conditions, and fresh payments need to be made to access the Resource, helping to maintain the integrity of the payment and access process.
If a Payment Condition is set upon creation of a Status List or other Resource, this will populate an Access Control Condition which is broadcasted across series of nodes to monitor whether the conditions have been met. The Access Control Condition uses query language to directly fetch information from the cheqd ledger, and is fully derived from the inputs made into the Payment Condition.
Each of these conditions are defined as follows:
Once an Access Control Condition has been set, the decryption keys are sharded between an array of nodes to prevent any single node or few malicious nodes from decrypting the data. This comprehensive setup ensures secure and controlled access to the specified resource based on specified criteria and events from the cheqd blockchain.
Using cheqd Studio, you can get started setting up your encrypted Status Lists with Access Control Conditions below:
Verify Credential
Verify a W3C Verifiable Credential using the cheqd Studio APIs.
Understanding Access Control Conditions
Learn what different Payment Conditions mean and how they affect a Verifier when verifying Credentials.
"conditionType"
"cosmos"
Specifies the type of condition being employed, indicating that the access control condition is related to the Cosmos blockchain ecosystem
"path"
"/cosmos/tx/v1beta1/txs?events=transfer.recipient='cheqd1xl5wccz667lk06ahama26pdqvrkz5aws6m0ztp'&events=transfer.amount='147603000000000ncheq'&order_by=2&pagination.limit=1"
Defines the query path to retrieve specific transaction events from the cheqd blockchain. It filters transactions with a recipient address and amount matching certain criteria, orders the results, and limits the query to one transaction.
"chain"
"cheqdMainnet"
Specifies the blockchain network (chain) being used, indicating that the condition applies to the cheqd Mainnet.
"method"
"timelock"
Specifies the access control method being utilized, which is a timelock mechanism.
"parameters"
"latest"
Provides parameters for the access control method. In this case, it refers to the "latest" state on the blockchain
"key"
"$.tx_responses.*.timestamp"
Specifies the key path within the transaction responses to extract the timestamp of the transaction.
"comparator"
"<="
This checks if the extracted timestamp is less than or equal to the provided value.
"value"
"3153600000"
Defines the value (in seconds) against which the extracted timestamp is compared. This value represents a time interval.
"type"
"timelockPayment"
Indicates that a timelock payment mechanism is employed. Currently, this is the only type that is supported.
"feePaymentAddress"
"cheqd1xl5wccz667lk06ahama26pdqvrkz5aws6m0ztp"
Specifies the cheqd address to which the payment fee should be sent. This address is associated with the entity managing the Status List (Issuer) and who will receive the payment.
"feePaymentAmount"
"147603000000000ncheq"
Defines the amount of the payment fee. In this case, the fee is specified in the smallest unit of CHEQ, (ncheq).
"intervalInSeconds"
3153600000
Sets the duration of the timelock interval, measured in seconds. The verifier must make the payment within the specified time frame relative to a particular block-time on the cheqd blockchain. If the payment is successfully confirmed within this interval, the Verifier's access to the Resource is granted. However, if the payment claim is made outside of this window, it may be considered invalid, and the verifier's access to the Resource may be denied.
Set up your account
Set up your account with cheqd Studio and log in to start using the APIs.
This endpoint checks a StatusList2021 index for a given Verifiable Credential and reports whether it is revoked or suspended. It offers a standalone method for checking an index without passing the entire Verifiable Credential or Verifiable Presentation.
/credential-status/check
The purpose of the status list. Can be either revocation or suspension.
revocation
, suspension
DID of the StatusList2021 publisher.
The name of the StatusList2021 DID-Linked Resource to be checked.
Credential status index to be checked for revocation or suspension.
Automatically make fee payment (if required) based on payment conditions to unlock encrypted StatusList2021 DID-Linked Resource.
This endpoint checks a StatusList2021 index for a given Verifiable Credential and reports whether it is revoked or suspended. It offers a standalone method for checking an index without passing the entire Verifiable Credential or Verifiable Presentation.
/credential-status/check
The purpose of the status list. Can be either revocation or suspension.
revocation
, suspension
DID of the StatusList2021 publisher.
The name of the StatusList2021 DID-Linked Resource to be checked.
Credential status index to be checked for revocation or suspension.
Automatically make fee payment (if required) based on payment conditions to unlock encrypted StatusList2021 DID-Linked Resource.