Learn

Create a ZKP-enabled JSON-LD Credential

Introduction

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

As ZKPs are experimental and the standards are subject to breaking changes. We recommend researching this option thoroughly before committing to using this feature.

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.

  • If you want to confirm the DID will work for issuing ZKP-enabled credentials, check the DID URL for the assertionMethod matches a publicKey.id that contains "type": "Bls12381G2Key2020".

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://YOUR_TENANT_SUBDOMAIN.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        "CourseCredential"
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.

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

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

Response

json
Copy to clipboard. 
1{
2  "id": "ab42adbc-1139-47f0-9256-3bf5a01fcc7e",
3  "credential": {
4    "type": [
5      "VerifiableCredential",
6      "CourseCredential"
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 object is the credential, with id and issuanceDate shown as meta-data, along with other fields depending on the options chosen.

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 either;

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.