Issue a ZKP-enabled JSON-LD Credential

Introduction

This guide will demonstrate how to create a ZKP-enabled credential.

Check out the video:

Prerequisites

You need access to the MATTR VII APIs. If you’re experiencing any difficulties, contact us.

In order to create a credential, you will need the following information:

  • Subject DID

  • Credential type

  • JSON-LD claim names as defined by schema.org

  • Claim values

Create a DID

In order to create a ZKP-enabled credential you first need to create an Issuer DID with a bls12381g2 key type, which supports BBS+ signatures for issuing ZKP-enabled credentials.

Request

Set the keyType in the options to bls12381g2 in order to create a DID with a BLS key type.

json
Copy to clipboard.
1{
2  "method": "key"
3  "options": {
4    "keyType": "bls12381g2"
5  }
6}

Response

  • The resulting DID resides in the did attribute.

  • did:key DIDs will always have a registrationStatus of COMPLETED as they are not stored in any external registry such as a ledger and are instantly available to be used and resolved

json
Copy to clipboard.
1{
2  "did": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
3  "registrationStatus": "COMPLETED",
4  "localMetadata": {
5    "keys": [
6      {
7        "didDocumentKeyId": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
8        "kmsKeyId": "25voPUCTSWXcDLCZNfZeTWuNaDcM3KgQZqwkvuY1s2GNGJ3tJ3UubY8uFR4X8Ykhdb2xTnXkGffugi9rHsM4A3J5FRPCyoAh4ZrdcCWUSEj29pGahY1cUA7uR1ns52JeZBQc"
9      }
10    ],
11    "registered": 1600918030673,
12    "initialDidDocument": {
13      "@context": "https://w3.org/ns/did/v1",
14      "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
15      "publicKey": [
16        {
17          "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
18          "type": "Bls12381G2Key2020",
19          "controller": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
20          "publicKeyBase58": "25voPUCTSWXcDLCZNfZeTWuNaDcM3KgQZqwkvuY1s2GNGJ3tJ3UubY8uFR4X8Ykhdb2xTnXkGffugi9rHsM4A3J5FRPCyoAh4ZrdcCWUSEj29pGahY1cUA7uR1ns52JeZBQc"
21        }
22      ],
23      "authentication": [
24        "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
25      ],
26      "assertionMethod": [
27        "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
28      ],
29      "capabilityDelegation": [
30        "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
31      ],
32      "capabilityInvocation": [
33        "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
34      ]
35    }
36  }
37}

Create a credential

Create a credential by making an API request as follows:

Request

http
Copy to clipboard.
1POST https://tenant.vii.mattr.global/core/v1/credentials
json
Copy to clipboard.
1{
2    "issuer": {
3        "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
4        "name": "tenant"
5    },
6    "@context": [
7        "https://www.w3.org/2018/credentials/v1",
8        "https://schema.org"
9    ],
10    "subjectId": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
11    "type": [
12        "VerifiableCredential",
13        "Course"
14    ],
15    "claims": {
16        "givenName": "Chris",
17        "familyName": "Shin",
18        "educationalCredentialAwarded": "Certificate Name"
19    },
20    "persist": false,
21    "revocable": true
22}

The issuer.id contains the DID of the issuer, as created in the previous step.

When the issuer DID has the “keyType”:“bls12381g2”, the platform will automatically detect this capability and issue a ZKP-enabled BBS+ credential.

The @context must include the reference to the W3C credential definition "https://www.w3.org/2018/credentials/v1" and this example will use a common data vocab https://schema.org which is referenced in the claims field.

The subjectId defines the DID of the subject. The issued credential attests claims about the subject.

type is an array of credential types that must start with VerifiableCredential. It indicates what sort of information a credential holds.

Response

json
Copy to clipboard.
1{
2  "id": "ab42adbc-1139-47f0-9256-3bf5a01fcc7e",
3  "credential": {
4    "type": [
5      "VerifiableCredential",
6      "Course"
7    ],
8    "issuer": {
9      "id": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v",
10      "name": "tenant"
11    },
12    "issuanceDate": "2020-09-24T19:16:33.222Z",
13    "credentialSubject": {
14      "id": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
15      "givenName": "Chris",
16      "familyName": "Shin",
17      "educationalCredentialAwarded": "Certificate Name"
18    },
19    "@context": [
20      "https://www.w3.org/2018/credentials/v1",
21      "https://w3c-ccg.github.io/ldp-bbs2020/context/v1",
22      "https://schema.org",
23      "https://w3id.org/vc-revocation-list-2020/v1"
24    ],
25    "credentialStatus": {
26      "id": "https://tenant.vii.mattr.global/core/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605#0",
27      "type": "RevocationList2020Status",
28      "revocationListIndex": "0",
29      "revocationListCredential": "https://tenant.vii.mattr.global/core/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605"
30    },
31    "proof": {
32      "type": "BbsBlsSignature2020",
33      "created": "2020-11-24T19:16:33Z",
34      "proofPurpose": "assertionMethod",
35      "proofValue": "pVJlfG/Ra9h8WbwqthNsT4lY9Xx5eVxZR6j0GY3yoDNzJq1CuF+nWKgcie3LpAn3UQpzkiODY46kt/WWaqGzyKyX4k5KRsBuSU9pSAL5Y99QFhnrm8t2MeKuZ1NL++ZO1+IelYtNjl6OmajHdphDUA==",
36      "verificationMethod": "did:key:zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v#zUC7KmMGXt7fs9URk9EDqWLfpCjVTtfFMexViLLkPPUfm9j4heqvk9JkLarva3sP54FGjFNLpwc63ZTef2aR2cPssFbyDj75kopYqWL16j7JigA2BAvJcwnaKvKPUybxbroRg1v"
37    }
38  },
39  "credentialStatus": {
40    "id": "https://product-team.vii.staging.mattrlabs.io/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605#0",
41    "type": "RevocationList2020Status",
42    "revocationListIndex": "0",
43    "revocationListCredential": "https://product-team.vii.staging.mattrlabs.io/v1/revocation-lists/dd7ceeaa-a5e0-4ab3-a70c-b7237500c605"
44  },
45  "issuanceDate": "2020-09-24T19:16:33.222Z"
46}

The returned credential attribute contains the VerifiableCredential object.

Because this is a ZKP-enabled credential it contains a BBS+ signature, which enables selective disclosure as defined by the proof type of BbsBlsSignature2020. For more information on this signature suite, check out the specification at the W3C CCG.

Obtain a ZKP-Enabled Credential on the Mobile Wallet

ZKP-enabled credentials provide valuable benefits to the subjects and holders of credentials. In order for them to receive those benefits, issuers must specifically issue them with ZKP-enabled credentials using signature schemes such as BBS+. The MATTR Mobile Wallet is interoperable with ZKP-enabled credentials containing BBS+ signatures. It responds appropriately to privacy-preserving Presentation Requests using JSON-LD Framing.

To set up an Issuer for ZKP-enabled credentials, first create your Issuer DID with a bls12381g2 key type.

Then, follow all the steps in Issue using OIDC Bridge and make sure to use this DID as the issuerDid when you Create a OIDC Credential Issuer.

Once the ZKP-enabled credential is stored in the mobile wallet, you can then move to the Verify tutorials and Create a Presentation Request Template for privacy-preserving requests.