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 the Veramo SDK Plugin for cheqd, you can get started setting up your encrypted Status Lists with Access Control Conditions below:
t
Understand how privacy is protected throughout the payment flow
There are multiple areas within this flow where privacy needs to be maintained:
Verifier pays Issuer: Any payment for decrypting a Status List should not be correlatable to a Holder presenting or sharing a Credential.
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.
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.
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.
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 the Veramo SDK Plugin for cheqd, you can get started setting up your encrypted Status Lists with Access Control Conditions below:
cheqd's implementation of Credential Payments uses encrypted (such as a Status Lists), with Payment Conditions required to unlock. Learn about cheqd's Access Control Condition logic below:
Status List construction: Credential information within Status List should not constitute .
The , which cheqd encrypts with payment conditions, 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.
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 as well as a .
The .
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 ().
Parameter | Value | Description |
---|
Parameter | Value | Description |
---|
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.
Access Control Conditions
Understand how cheqd gates encrypted resources using payment conditions and Access Control logic.
|
| Indicates that a timelock payment mechanism is employed. Currently, this is the only type that is supported. |
|
| 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. |
|
| Defines the amount of the payment fee. In this case, the fee is specified in the smallest unit of CHEQ, (ncheq). |
|
| 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. |
|
| Specifies the type of condition being employed, indicating that the access control condition is related to the Cosmos blockchain ecosystem |
|
| 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. |
|
| Specifies the blockchain network (chain) being used, indicating that the condition applies to the cheqd Mainnet. |
|
| Specifies the access control method being utilized, which is a timelock mechanism. |
|
| Provides parameters for the access control method. In this case, it refers to the "latest" state on the blockchain |
|
| Specifies the key path within the transaction responses to extract the timestamp of the transaction. |
|
| This checks if the extracted timestamp is less than or equal to the provided value. |
|
| Defines the value (in seconds) against which the extracted timestamp is compared. This value represents a time interval. |
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.
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.
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 bitstring, 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:
Below are a set of examples of how these parameters may be included in Credential payload files for different purposes:
Ensure that the "statusPurpose"
and "statusListName"
is the same as the existing Status List on-ledger, created in Step 1.
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.
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.
Once the Verifier makes a payment of the specified amount in the payment conditions back to the Issuer, the Access Control Conditions will be met.
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.
Parameter | Value | Description |
---|---|---|
Parameter | Value | Optional |
---|---|---|
"kms"
"local"
This indicates that a local Key Management System (KMS) is being used for cryptographic operations, ensuring secure key handling.
"issuerDid"
"did:cheqd:testnet:322761ea-587d-454a-a955-745200301b99"
Specifies the issuer's Decentralized Identifier (DID), uniquely identifying the entity responsible for managing and issuing verifiable credentials.
"statusListName"
"status-list-2021-encrypted"
Names the Verifiable Credential Status List, providing context for its purpose.
"statusPurpose"
"revocation"
Defines the purpose of the status list. This can be either revocation or suspension.
"encrypted"
true
Indicates that the Verifiable Credential Status List, crucially, is encrypted, enhancing data privacy and security. This can be either true or false (unencrypted).
"paymentConditions"
[...]
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.
"returnSymmetricKey"
true
Specifies that the symmetric key for decrypting the status list will be returned.
"chain"
"cheqdTestnet"
Specifies whether the encrypted keys should be broadcast on cheqdMainnet
or cheqdTestnet
"network"
"serrano"
Specifies the network where the sharded decryption keys will be stored (across Lit Protocol)
"statusPurpose"
"revocation"
or "suspension"
No
"statusListName"
string
No
"statusListVersion"
string
Yes
"statusListRangeStart"
number
Yes
"statusListRangeEnd"
number
Yes
"statusListVersion"
number, or set of numbers
Yes
Understanding Credential Payments
Before diving into Credential Payments, developers may want to learn how the Payment gating and Access Control condition logic works.
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
Once an encrypted Status List has been created, it is time to issue a Credential referencing this Status List within the Credential body.
Verifier pays Issuer
Understand how a Verifier can pay an Issuer and how the Verifier receives access to the Status List.
Credential Service
Credential Service is a SaaS product offering the easiest and quickest way to issue Credentials, using REST APIs and very little integration effort.
Create a DID
Create a W3C conformant Decentralised Identifier using cheqd's DID Method (did:cheqd), using the Veramo SDK Plugin.
Charge for Status List
Create an encrypted Status List on cheqd with payment conditions, unlockable on payment of CHEQ
Understanding Access Control Conditions
Learn what different Payment Conditions mean and how they affect a Verifier when verifying Credentials.