cheqd StudioSupport / Bug Reports
Edit

Create Status List

Create a Bitstring Status List on cheqd, stored as a DID-Linked Resource (DLR), using Veramo.

The Bitstring Status List Specification indicates that it may be desirable to store the actual StatusList using something like a Content Distribution Network 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 benefits of using the cheqd Resource module over traditional centralised architecture are detailed here.

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 the Trust over IP Foundation within a specification called DID URLs for Digital Resources.

Creating a StatusList Resource using Veramo SDK for cheqd

Using the cheqd Resource module, the same content and semantics of Bistring Status List can be replicated, with additional benefits of enabling DID Resolvers to fetch the contents of the StatusList.

Step 1: Create a DID and DID Document with keys to manage the StatusList

You can follow the tutorial to create a DID and DID Document here.

Let's assume that the following DID is created.

"didDocument": {
    "@context": [
      "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
    "controller": [
      "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY"
    ],
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY#verkey-1",
        "type": "Ed25519VerificationKey2020",
        "controller": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
        "publicKeyMultibase": "zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpYAZPD1M9tvwyzE"
      },
    ],
    "authentication": [
      "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY#verkey-1"
    ]
  }

Step 2: Compiling a Bitstring Status List Payload file

Below are is an example of unencrypted Status List Payload file:

BitstringStatusList
{
    "kms": "local",
    "issuerDid": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
    "statusListName": "status-list-unencrypted",
    "statusPurpose": ["revocation", "suspension", "message"],
    "statusSize": 2,
    "statusMessages": [
		    { "status": "0x0", "message": "valid" },
		    { "status": "0x1", "message": "revoked" },
		    { "status": "0x2", "message": "suspended" },
		    { "status": "0x3", "message": "unknown" }
	    ],
    "encrypted": false,
    "statusListEncoding": "base64url"
}

The code snippet above shows a Bitstring Status List Payload file which supports both Revocation and Suspension. With Bitstring Status List with statusSize as 2, the same list can be used for revocation, suspension or any other message as determined by the statusMessages . The payload indicates to the ledger that the Resource should is unencrypted.

For encrypted status list example, check Charge for Status List

Where the fields within the payload have the following meaning:

Parameter
Value
Description

"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:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY

Specifies the issuer's Decentralized Identifier (DID), uniquely identifying the entity responsible for managing and issuing verifiable credentials.

"statusListName"

"status-list-unencrypted"

Names the Bitstring Status List, providing context for its purpose.

"statusPurpose"

["revocation", "suspension", "message"]

Defines the purposes of the status list as Bitstring status list supports multiple purposes.

"statusSize"

2

Defines the size of each bit in the Bitstring Status List.

"statusMessages"

[{ "status": "0x0", "message": "valid" },
{ "status": "0x1", "message": "revoked" },
{ "status": "0x2", "message": "suspended" },
{ "status": "0x3", "message": "unknown" }]

Array of "status" and "message" which defines the message for each bit value. Must be 2^StatusSize

"encrypted"

false

Indicates that the Verifiable Credential Status List, crucially, is unencrypted. This can be either true (encrypted) or false (unencrypted).

"statusListEncoding"

base64url

The default encoding for BitStringStatusList

Note: If an issuer wants to create multiple StatusLists under the same DID, they must have unique and distinct names.

Step 3: Submit a create Status List transaction to the ledger

Once an Issuer has compiled the Payload file, they can submit this to the ledger using the following transaction:

veramo execute -m cheqdCreateStatusList --argsFile path/to/payload.json

The ledger will acknowledge that this Bitstring status list is created and published.

Note association between DID and Resource

Once created, the BitstringStatusList Resource will be associated with the parent DID, and referenced in the DID Document Metadata as follows:

{
  "didDocument": {
    "@context": ["https://www.w3.org/ns/did/v1"],
    "id": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
    "controller": ["did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY"],
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY#verkey-1",
        "type": "Ed25519VerificationKey2020",
        "controller": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
        "publicKeyMultibase": "zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpYAZPD1M9tvwyzE"
      }
    ],
    "authentication": [
      "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY#verkey-1"
    ]
  },
  "didDocumentMetadata": {
    "created": "2022-09-16T11:15:20Z",
    "versionId": "204e296f-d55b-4552-9fec-0b242a689f96",
    "linkedResourceMetadata": [
      {
        "resourceURI": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY/resources/4a71319b-00b1-4db9-bc05-56dc426f7062",
        "resourceCollectionId": "zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
        "resourceId": "4a71319b-00b1-4db9-bc05-56dc426f7062",
        "resourceName": "status-list-unencrypted",
        "resourceType": "BitstringStatusListCredential",
        "mediaType": "application/json",
        "created": "2022-09-16T11:15:52Z",
        "checksum": "0f503dfbff29de9ac74fd07f1720ba560eb388e28062367884890c311736ec9d",
        "previousVersionId": "",
        "nextVersionId": ""
      }
    ]
  }
}

Creating new BitstringStatusList Resource Version

An issuer may want to regularly update the bitstring whenever there is a certain amount of revocation/suspension status updates. The issuer will therefore need to create a new version for the initial BitstringStatusList 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:

{
  "kms": "local",
  "payload": {
    "collectionId": "zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY", // Same Collection ID
    "id": "6922ae19-777e-4e05-8b10-8a2f0a2d418d", // New unique ID
    "name": "status-list-unencrypted", // Same name
    "resourceType": "BitstringStatusListCredential", // Same Resource Type
    "data": "hwbWB8FnRwXxmxk...." // New base 64 encoded value with updated bitstring
  },
  "signInputs": [
    {
      "verificationMethodId": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY#verkey-1", // Same Verification key
      "keyType": "Ed25519",
      "privateKeyHex": "0f5c124886178037952e87e0cdc55d185732577fca19ae877e64ac9ab24a0cc534e5326e70f1a42d785d93048aee806c359ec75a7b06f39253befd1746708438"
    }
  ]
}

Resulting in the following metadata syntax:

{
  "didDocument": {
    "@context": ["https://www.w3.org/ns/did/v1"],
    "id": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
    "controller": ["did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY"],
    "verificationMethod": [
      {
        "id": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY#verkey-1",
        "type": "Ed25519VerificationKey2020",
        "controller": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
        "publicKeyMultibase": "zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpYAZPD1M9tvwyzE"
      }
    ],
    "authentication": [
      "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY#verkey-1"
    ]
  },
  "didDocumentMetadata": {
    "created": "2022-09-16T11:15:20Z",
    "versionId": "204e296f-d55b-4552-9fec-0b242a689f96",
    "linkedResourceMetadata": [
      {
        "resourceURI": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY/resources/4a71319b-00b1-4db9-bc05-56dc426f7062",
        "resourceCollectionId": "zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
        "resourceId": "4a71319b-00b1-4db9-bc05-56dc426f7062",
        "resourceName": "status-list-unencrypted",
        "resourceType": "BitstringStatusListCredential",
        "mediaType": "application/json",
        "created": "2022-09-16T11:15:52Z",
        "checksum": "0f503dfbff29de9ac74fd07f1720ba560eb388e28062367884890c311736ec9d",
        "previousVersionId": "",
        "nextVersionId": "6922ae19-777e-4e05-8b10-8a2f0a2d418d"
      },
      {
        "resourceURI": "did:cheqd:testnet:zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY/resources/6922ae19-777e-4e05-8b10-8a2f0a2d418d",
        "resourceCollectionId": "zGgLTsq96mTsFcFBUCxX6k4kc5i5RNpY",
        "resourceId": "6922ae19-777e-4e05-8b10-8a2f0a2d418d",
        "resourceName": "status-list-unencrypted",
        "resourceType": "BitstringStatusListCredential",
        "mediaType": "application/json",
        "created": "2022-10-16T09:04:17Z",
        "checksum": "0f503dfbff29de9ac74fd07f1720ba560eb388e28062367884890c311736ec9d",
        "previousVersionId": "4a71319b-00b1-4db9-bc05-56dc426f7062",
        "nextVersionId": ""
      }
    ]
  }
}

Last updated

Was this helpful?