Skip to main content

Verifiable Credentials for Fan Club Membership

Alice is a long-time fan of one of the biggest pop stars in the world! In this tutorial, we'll learn how to use verifiable credentials (VC) to ensure Alice is recognized as an official member of the exclusive Swifties Fan Club.

Fan Club Membership

Setting the Stage​

Before we start issuing and verifying credentials, let's set up our environment by installing the @web5/credentials and @web5/dids packages:

npm install @web5/credentials@1.1.1
npm install @web5/dids@1.1.5

Import packages​

After installing the packages, we'll import them into our project as shown below:

No snippet found for javascript

The Cast​

There are a few characters involved in our story:

  • The Issuer (Fan Club): This is the entity (us, in this case) responsible for issuing the verifiable credentials. Think of it as the guardian of the Swifties Fan Club.
  • The Holder (Alice): A dedicated fan who wants to join the club. She will be the recipient of the credential, and she uses her Wallet app to show her credentials.
  • The Verifier (Swag Supplier): This company provides free swag to Swiftie Fan Club members, but they have to verify that the person is indeed an official member.

Act 1: Issuing the Credential​

In this section, we'll walk through all of the steps required to create and issue a verifiable credential.

Create DIDs​

As a prerequisite, both the Fan Club and Alice need decentralized identifiers. This is because verifiable credentials use DIDs to identify issuers and holders.

If you need to create DIDs, you can do so with the @web5/credentials package:

No snippet found for javascript

Model Credential​

Now, let's create the SwiftiesFanClub credential. We'll first model it with a class with some basic properties, level and legit:

No snippet found for javascript
NOTE

Note that credentials can be customized to fit various needs and scenarios. In our example, we used level and legit, but you could add more properties like memberSince, favoriteAlbum, or any other relevant data that suits your use case.

Create Credential​

Next, we can create the verifiable credential with an instance of the class:

No snippet found for javascript

Credential Properties​

Let's break down the VerifiableCredential.create() method to understand what each property means and how it contributes to our credential:

  • type: The type of credential being created. In our case, it's SwiftiesFanClub. This helps in categorizing and understanding the purpose of the credential.

  • issuer: The DID of the issuer of the credential. It's crucial for establishing trust and verifying the origin of the credential. In our narrative, the issuer is the fan club itself.

  • subject: The DID of the person or entity the credential is about - in our case, Alice, the fan.

  • data: An instance of our SwiftiesFanClub class. This instance contains the specific information or claims about the subject, such as their fan level and legitimacy as a fan.

Credential JSON​

VerifiableCredential.create() returns a VC as a JSON object:

No snippet found for javascript

Sign Credential​

Last but not least, we must cryptographically sign the VC to make it official:

No snippet found for javascript

Signing the credential returns a VC JSON Web Token, ideal for secure transmission of the credential.

Act 2: Presentation Exchange​

Now that Alice has her credential, she'd like to present it in order to get free merchandise. She can do this via a presentation exchange.

A presentation exchange is the process where the holder of VCs presents them to a verifier in order to prove certain claims or information.

Components of Presentation Exchange​

  • Holder: The individual or entity that possesses one or more verifiable credentials. In our Swifties Fan Club example, Alice is the holder.

  • Verifier: The party requesting to verify the information contained in the holder's credentials. This could be a website, service, or another individual who needs proof of certain claims. In our example, this would be the Swag Supplier.

  • Presentation: A package of information, compiled by the holder, that typically includes the verifiable credentials and possibly additional data required by the verifier. This presentation is what the holder submits to the verifier.

  • Presentation Definition: A set of criteria defined by the verifier detailing what they need to see in the presentation. This can include specific types of credentials, claims, or formats.

Create Presentation Definition​

To kick off the presentation exchange, the Swag Supplier (verifier) will send a request to Alice, which includes a presentation definition, specifying what credentials or claims are needed.

To create and validate this presentation definition, the verifier first needs to import packages from the @web5/credentials library.

No snippet found for javascript

Here's how the verifier can create the presentation definition, and validate that it is properly formed:

No snippet found for javascript

Satisfy Presentation Definition​

Once a presentation definition is presented to Alice, she'd want to make sure that the credentials she has satisfy the requirements before submitting them. This can be done by passing the JWT(s) and the presentation definition to satisfiesPresentationDefinition() method. Typically this step is done by the app that Alice is using to store and present her credentials:

No snippet found for javascript

Create Presentation​

Once Alice's app is confident that her credential satisfies the presentation definition, the presentation would be created:

No snippet found for javascript

Resulting Presentation​

No snippet found for javascript

Act 3: Verifying the Credential​

After receiving the credential, the verifier will want to verify it to ensure that it is valid and has not been tampered with. They can do this with VerifiableCredential.verify(). If verification is unsuccessful, an error will be thrown:

No snippet found for javascript

Parse JWT into VC​

The signed VC JWT is a secure representation of the credential, ideal for transmission or storage.

However, the verifier will likely need to inspect or use the data within the credential. They can use parseJwt() to convert the JWT back into a VerifiableCredential object.

No snippet found for javascript

Parsed VC Data​

No snippet found for javascript

Given Alice's verified credential, she's all set to receive her free merch for being a proud member of the Swifties Fan Club!