Product Docs
Product DocsTechnical DocsLearning & GovernanceUseful Links
  • Product Docs
  • Node Docs
  • Learning Docs
  • โ„น๏ธGetting Started
    • Product Overview
    • โžก๏ธGet Started with cheqd Studio
      • ๐Ÿ‘‰Set Up Your Account
      • ๐Ÿ—๏ธCreate API Keys
      • ๐Ÿช™Token Top Up
      • ๐Ÿ”„Advanced Configuration Options
    • โ˜‘๏ธUse Trust Registries for AI Agents
      • ๐Ÿ—๏ธBuild an AI Agent Trust Registry
        • Setup AI Agent Trust Registry
          • Issue Verifiable Credentials to AI Agent
        • Setup and Configure MCP Server
          • Create AI Agent DID
          • Import Credential to AI Agent
          • Advanced functionality
            • Issue a Verifiable Credential
            • Verify a Credential
      • ๐ŸคValidate AI Agent Trust Chain
  • ๐ŸŸขStart using cheqd
    • ๐Ÿ†”Create DIDs and Identity Keys
      • Create a DID
      • Create Identity Keys
      • Create a Subject DID
      • Resolve a DID
      • Update a DID
      • Deactivate a DID
    • โœ…Issue Credentials and Presentations
      • Issue a Verifiable Credential
      • Setup Verida Wallet
      • Verify a Verifiable Credential
      • Verify a Verifiable Presentation
      • Revoke a Verifiable Credential
      • Suspend or Unsuspend a Verifiable Credential
    • โ™ป๏ธCharge for Verifiable Credentials
      • Understanding Credential Payments
        • Access Control Conditions
        • Privacy Considerations
      • Charge for Status List
      • Issue Credential with Encrypted Status List
      • Create Verifier Pays Issuer flow
      • Bulk Update or Rotate Encryption Keys
    • ๐ŸคBuild Trust Registries
      • Decentralized Trust Chains (DTCs)
        • Root Authorisations
        • RTAO -> TAO
        • TAO -> SubTAO
        • TAO -> Trusted Issuer (TI)
        • Referencing Trust Registry within a Verifiable Credential
      • Set up Trust Chain
        • Issue a Verifiable Accreditation
        • Verify a Verifiable Accreditation
      • Get Started with TRAIN
        • Deploy TRAIN and Anchor rTAO in DNS
        • Validate Trust Chain
    • ๐ŸŽ‹Create Status Lists
      • Bitstring Status List
        • Create Bitstring Status List
        • Update Bitstring Status List
        • Check Bitstring Status List
        • Search Bitstring Status List
      • Token Status List
        • Create Token Status List
        • Update Token Status List
    • โ†•๏ธCreate DID-Linked Resources
      • Understanding DID-Linked Resources
        • Context for developing DID-Linked Resources
        • Technical composition of DID-Linked Resources
        • Referencing DID-Linked Resources in VCs
      • Create a DID-Linked Resource
      • Search for DID-Linked Resources
  • ๐Ÿ› ๏ธIntegrate an SDK
    • Choosing the right SDK
    • ๐ŸCredo
      • Setup Credo Agent
      • Decentralized Identifiers (DIDs)
        • Create a DID
        • Update a DID
        • Deactivate a DID
      • DID-Linked Resources
        • Create DID-Linked Resource
        • Resolve DID-Linked Resource
        • Create AnonCreds Schema
        • Create AnonCreds Credential Definition
      • Verifiable Credentials and Presentations
        • Issue a Verifiable Credential (AnonCreds)
        • Present a Verifiable Credential (AnonCreds)
    • ๐ŸŠACA-Py
      • Setup ACA-Py Agent
      • Decentralized Identifiers (DIDs)
        • Create a DID
        • Update a DID
        • Deactivate a DID
      • DID-Linked Resources
        • Create AnonCreds Schema
        • Create AnonCreds Credential Definition
      • Verifiable Credentials and Presentations
        • AnonCreds
          • Issue a Verifiable Credential
          • Present a Verifiable Credential
          • Revoke a Verifiable Credential
        • JSON-LD
          • Issue a Verifiable Credential
          • Present a Verifiable Credential
    • ๐ŸˆVeramo
      • Setup Veramo CLI for cheqd
        • Troubleshooting Veramo CLI Setup
      • Decentralized Identifiers (DIDs)
        • Create a DID
        • Querying a DID
        • Update an existing DID
        • Deactivate a DID
        • Create an off-ledger holder DID
        • Managing Identity Keys
        • Troubleshooting
      • Verifiable Credentials and Presentations
        • Issue a Verifiable Credential
        • Verify a Verifiable Credential
        • Create a Verifiable Presentation
        • Verify a Verifiable Presentation
      • Credential Payments
        • Charge for Status List
        • Issue Credential with Encrypted Status List
        • Verifier pays Issuer
      • Bitstring Status List
        • Create Status List
        • Issuing a Verifiable Credential referencing Status List
      • DID-Linked Resources
        • Create a DID-Linked Resource
        • Create a new Resource version within existing Collection
    • ๐ŸซWalt.id Community Stack
  • ๐Ÿ—๏ธArchitecture
    • Architecture Decision Record (ADR) Process
    • List of ADRs
      • ๐Ÿ”ตADR 001: cheqd DID Method
      • ๐ŸŸขADR 002: DID-Linked Resources
      • ๐ŸŸกADR 003: DID Resolver
      • ๐ŸŸ ADR 004: DID Registrar
      • ๐ŸŸฃADR 005: DID Resolution & DID URL Dereferencing
  • ๐Ÿ’ซAdvanced features and alternatives
    • โžก๏ธDID Registrar
      • Setup DID Registrar
      • Create a DID
      • Create a DID-Linked Resource
    • โฌ…๏ธDID Resolver
      • Setup DID Resolver
    • โšกAnonCreds Object Method
      • Schemas
      • Credential Definitions
      • Revocation Registry Definitions
      • Revocation Status Lists
    • ๐ŸŒ Advanced Tooling
      • cheqd Cosmos CLI for identity
        • Create a DID
        • Update a DID
        • Deactivate a DID
        • Query a DID
        • Create a DID-Linked Resource
        • Update a DID-Linked Resource
      • Direct interaction with ledger code
      • VDR Tools CLI with cheqd (deprecated)
      • Demo Wallet for Identity Setup
  • โš›๏ธNetwork
    • Get started with cheqd Network
      • Identity Write Pricing
      • Comparison to Hyperledger Indy
    • โฉSetup your Wallet
      • Setup Leap Wallet
        • Congifure cheqd Testnet for Leap
      • Setup Keplr Wallet
      • Migrate from Keplr to Leap Wallet
    • โ†ช๏ธUseful Tools and APIs
      • Block Explorer
      • Testnet Faucet
      • Validator Status API
      • Cheqd x Cosmos Data APIs
      • Cosmos Airdrop Helpers
      • Cosmos Address Convertor
      • Ethereum Bridge
    • โฌ†๏ธNetwork Upgrades
      • 2021
        • 0.1.x
        • 0.2.x
        • 0.3.x
      • 2022
        • 0.4.x
        • 0.5.x
        • 0.6.x
      • 2023
        • 1.x
      • 2024
        • 2.x
        • 3.x
      • Root Cause Analysis of Outages
        • v1.x upgrade RCA
  • โš–๏ธLegal
    • License
    • Code of Conduct
    • Security Policy
  • ๐Ÿ†˜Support
    • System Status
    • Discord
    • Bugs & Feature Requests
Powered by GitBook
LogoLogo

General

  • Website
  • Blog
  • Get $CHEQ

Product Docs

  • Product Docs
  • cheqd Studio
  • Creds.xyz
  • Bug/Feature Requests

Technical Docs

  • Node Docs
  • GitHub
  • Block Explorer

Learning Docs

  • Learning Docs
  • Governance Docs
  • Governance Forum
  • Governance Explorer
On this page

Was this helpful?

Edit on GitHub
Export as PDF
  1. Start using cheqd
  2. Create Status Lists
  3. Token Status List

Create Token Status List

Create a Token Status List JWT or CWT as a DID-Linked Resource (DLR), using cheqd Studio.

Last updated 25 days ago

Was this helpful?

Users are able to create Token Status List entries on-ledger, which may be used to represent whether a Verifiable Credential is active, inactive or suspended. This implementation on cheqd is a derivation from the core spec made by cheqd to support a more decentralised and resilient approach to storing Token Status Lists.

Step 1: Set up your account

Make sure you have set up your account with cheqd Studio and are logged in, using our guide below:

Step 2: Create a DID

Before you can create a Status List, 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:

Step 3. Create your Status List JWT/CWT and save the file locally

Token Status Lists are JWT or CWT files that reference lists of bits formatted in JSON or CBOR.

Non-normative example for a Status List Token in JWT format
{
  "alg": "ES256",
  "kid": "12",
  "typ": "statuslist+jwt"
}
.
{
  "exp": 2291720170,
  "iat": 1686920170,
  "iss": "https://example.com",
  "status_list": {
    "bits": 1,
    "lst": "eNrbuRgAAhcBXQ"
  },
  "sub": "https://example.com/statuslists/1"
}
Non-normative example for a Status List Token in CWT format (not including the type header yet)
d28453a20126106e7374617475736c6973742b637774a1044231325860a502782168
747470733a2f2f6578616d706c652e636f6d2f7374617475736c697374732f310173
68747470733a2f2f6578616d706c652e636f6d061a648c5bea041a8898dfea19fffe
56a2646269747301636c73744a78dadbb918000217015d58400f2ca3772e10b09d5d
6ed56461f7cba1a816c6234072d1bb693db277048e5db5a4e64444492a9b781d6c7a
c9714db99cc7aadb3812ec90cab7794170bab5b473

Save this file locally and call it something like statusListToken.json

Note that each JWT or CWT must be below ~45kb in size.

Step 4: Encode the file

Prepare a file with resource and encode it into base64, base64url or hex. On Unix systems, you can use the following command input:

$ base64 -w 0 resource.json
<path-to-the-resource-file>

Expected output:

$ base64 -w 0 resource.json
SGVsbG8sIHdvcmxk

Step 5: Set the resource name and type

DID-Linked Resources are grouped by having identical names and types. This means if you want to create a new version of the same Resource, you will need to specify the same name and type in the following request.

For Token Status Lists, the "type" MUST be: "TokenStatusList".

For example:

{
    "data": "SGVsbG8sIHdvcmxk",
    "encoding": "base64url",
    "name": "DegreeCredentialStatus",
    "type": "TokenStatusList"
}

Step 6: Populate the request inputs and hit the API

Ensure that you link this Token Status List to the DID that you created in step 3. This will sign the resource with the same verification method keys in your DID Document, ensuring cryptographic integrity and Controllership of the Status List.

As a DID-Linked Resource, the Token Status List will have a fully resolvable DID URL which can be referenced within the body of Verifiable Credentials, and queried by verification policies to establish the status of the specific credential.

Step 7: Reference the Token Status List

Owing to the design of DID-Linked Resources, following the creation of the Token Status List, users are able to reference the specific version, or create a query to always fetch the latest version of the Token Status List.

Using a DID Resolver or the search DID endpoint, users can find the DID URL and unique resourceId of the Token Status List. The unique resourceId allows users to specify this exact version of the Token Status List.

In the DID Document Metadata, users should find "linkedResourceMetadata", like the following snippet:

"linkedResourceMetadata": [
      {
        "resourceURI": "did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d/resources/4e1104f9-2ee9-4bde-adc2-ab8ba72b124a",
        "resourceCollectionId": "0a5b94d0-a417-48ed-a6f5-4abc9e95888d",
        "resourceId": "4e1104f9-2ee9-4bde-adc2-ab8ba72b124a",
        "resourceName": "DegreeCredentialStatus",
        "resourceType": "TokenStatusList",
        "mediaType": "application/json",
        "resourceVersion": "",
        "created": "2023-03-24T12:13:45Z",
        "checksum": "6819aaecd4073173b159fedf8077c38e14939d03d58e7f4e2a0ddfe034eb2ed4",
        "previousVersionId": null,
        "nextVersionId": null
      } 

Specific version of the Token Status List

Here, the "resourceURI" specifies the DID URL of the specific Token Status List that was created.

Latest version of the Token Status List

In order to reference the latest version of the Token Status List, the following construction needs to be used:

did:cheqd:<namespace>:<resourceCollectionId>?resourceName=<resourceName>&resourceType=<resourceType>

For example:

did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d?resourceName=DegreeCredentialStatus&resourceType=TokenStatusList

Token Status List at specific point in time

In order to reference the Token Status List at a particular point in time, the following construction needs to be used:

did:cheqd:<namespace>:<resourceCollectionId>?resourceName=<resourceName>&resourceType=<resourceType>&resourceVerionTime=<XMLDateTime>

For example:

did:cheqd:testnet:0a5b94d0-a417-48ed-a6f5-4abc9e95888d?resourceName=DegreeCredentialStatus&resourceType=TokenStatusList&resourceVersionTime=2023-02-22T06:58:18.61Z

๐ŸŸข
๐ŸŽ‹

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.

  • Step 1: Set up your account
  • Step 2: Create a DID
  • Step 3. Create your Status List JWT/CWT and save the file locally
  • Step 4: Encode the file
  • Step 5: Set the resource name and type
  • Step 6: Populate the request inputs and hit the API
  • POSTCreate a DID-Linked Resource.
  • Step 7: Reference the Token Status List
  • GETResolve a DID Document.
  • Specific version of the Token Status List
  • Latest version of the Token Status List
  • Token Status List at specific point in time

Create a DID-Linked Resource.

post

This endpoint creates a DID-Linked Resource. As input, it can take the DID identifier and the resource parameters via a form, or the fully-assembled resource itself.

Authorizations
Path parameters
didstringRequired

DID identifier to link the resource to.

Body

Input fields for DID-Linked Resource creation.

datastringRequired

Encoded string containing the data to be stored in the DID-Linked Resource.

encodingstring ยท enumRequired

Encoding format used to encode the data.

Possible values:
namestringRequired

Name of DID-Linked Resource.

typestringRequired

Type of DID-Linked Resource. This is NOT the same as the media type, which is calculated automatically ledger-side.

versionstringOptional

Optional field to assign a human-readable version in the DID-Linked Resource.

publicKeyHexsstring[]Optional

List of key references (publicKeys) which will be used for signing the message. The should be in hexadecimal format and placed in the wallet of current user.

Responses
200
The request was successful.
application/json
400
A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.
401
Access token is missing or invalid
500
An internal error has occurred. Additional state information plus metadata may be available in the response body.
post
POST /resource/create/{did} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 94

"data='SGVsbG8gV29ybGQ='&encoding='base64url'&name='ResourceName'&type='TextDocument'"
{
  "resourceURI": "did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47/resources/398cee0a-efac-4643-9f4c-74c48c72a14b",
  "resourceCollectionId": "55dbc8bf-fba3-4117-855c-1e0dc1d3bb47",
  "resourceId": "398cee0a-efac-4643-9f4c-74c48c72a14b",
  "resourceName": "cheqd-issuer-logo",
  "resourceType": "CredentialArtwork",
  "mediaType": "image/png",
  "resourceVersion": "1.0",
  "checksum": "a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559",
  "created": "2021-09-01T12:00:00Z",
  "nextVersionId": "d4829ac7-4566-478c-a408-b44767eddadc",
  "previousVersionId": "ad7a8442-3531-46eb-a024-53953ec6e4ff"
}

Resolve a DID Document.

get

Resolve a DID Document by DID identifier. Also supports DID Resolution Queries as defined in the .

Authorizations
Path parameters
didstringRequired

DID identifier to resolve.

Example: did:cheqd:mainnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0
Query parameters
metadatabooleanOptional

Return only metadata of DID Document instead of actual DID Document.

versionIdstring ยท uuidOptional

Unique UUID version identifier of DID Document. Allows for fetching a specific version of the DID Document. See cheqd DID Method Specification for more details.

Example: 3ccde6ba-6ba5-56f2-9f4f-8825561a9860
versionTimestring ยท date-timeOptional

Returns the closest version of the DID Document at or before specified time. See DID Resolution handling for did:cheqd for more details.

Example: 1970-01-01T00:00:00Z
transformKeysstring ยท enumOptional

This directive transforms the Verification Method key format from the version in the DID Document to the specified format chosen below.

Possible values:
servicestringOptional

Query DID Document for a specific Service Endpoint by Service ID (e.g., service-1 in did:cheqd:mainnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#service-1). This will typically redirect to the Service Endpoint based on DID Resolution specification algorithm.

Example: service-1
relativeRefstringOptional

Relative reference is a query fragment appended to the Service Endpoint URL. Must be used along with the service query property above. See DID Resolution specification algorithm for more details.

Example: /path/to/file
Responses
200
The request was successful.
application/json
400
A problem with the input fields has occurred. Additional state information plus metadata may be available in the response body.
401
Access token is missing or invalid
500
An internal error has occurred. Additional state information plus metadata may be available in the response body.
get
GET /did/search/{did} HTTP/1.1
Host: 
x-api-key: YOUR_API_KEY
Accept: */*
{
  "@context": "https://w3id.org/did-resolution/v1",
  "didDidResolutionMetadata": {
    "contentType": "application/did+ld+json",
    "retrieved": "2021-09-01T12:00:00Z",
    "did": {
      "didString": "did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47",
      "method": "cheqd",
      "methodSpecificId": "55dbc8bf-fba3-4117-855c-1e0dc1d3bb47"
    }
  },
  "didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0",
    "controller": [
      "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0"
    ],
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#key-1",
        "type": "Ed25519VerificationKey2018",
        "controller": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0",
        "publicKeyBase58": "z6MkkVbyHJLLjdjU5B62DaJ4mkdMdUkttf9UqySSkA9bVTeZ"
      }
    ],
    "authentication": [
      "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#key-1"
    ],
    "service": [
      {
        "id": "did:cheqd:testnet:7bf81a20-633c-4cc7-bc4a-5a45801005e0#service-1",
        "type": "LinkedDomains",
        "serviceEndpoint": [
          "https://example.com"
        ]
      }
    ]
  },
  "didDocumentMetadata": {
    "created": "2021-09-01T12:00:00Z",
    "deactivated": false,
    "updated": "2021-09-10T12:00:00Z",
    "versionId": "3ccde6ba-6ba5-56f2-9f4f-8825561a9860",
    "linkedResourceMetadata": [
      {
        "resourceURI": "did:cheqd:testnet:55dbc8bf-fba3-4117-855c-1e0dc1d3bb47/resources/398cee0a-efac-4643-9f4c-74c48c72a14b",
        "resourceCollectionId": "55dbc8bf-fba3-4117-855c-1e0dc1d3bb47",
        "resourceId": "398cee0a-efac-4643-9f4c-74c48c72a14b",
        "resourceName": "cheqd-issuer-logo",
        "resourceType": "CredentialArtwork",
        "mediaType": "image/png",
        "resourceVersion": "1.0",
        "checksum": "a95380f460e63ad939541a57aecbfd795fcd37c6d78ee86c885340e33a91b559",
        "created": "2021-09-01T12:00:00Z",
        "nextVersionId": "d4829ac7-4566-478c-a408-b44767eddadc",
        "previousVersionId": "ad7a8442-3531-46eb-a024-53953ec6e4ff"
      }
    ]
  }
}
W3C DID Resolution specification