The Web Wallet's
Architecture

This guide explains the flow of issuance and verification of Verifiable Credentials using Tykn’s REST API.

Generally, Verifiable Credentials flow between 3 parties:

  • The Issuer: You.
  • The Prover: Your users.
  • The Verifier: You, your partner organisations, other users, etc.

 

Let’s consider a scenario where the Issuer is the Hooli Hospital.

The Hospital wants to start issuing Verifiable Credentials to doctors. They want these credentials – called the Doctor ID – to attest that the doctors are licensed practitioners and what their specialty is.

Doctors will be able to use these Credentials to access different services in the Hospital. They will also be able to identify themselves before other doctors and patients. Enabling instant trust (even in digital contexts) and faster onboarding times.

Architecture Overview

In this sequence diagram you have an overview of the entire Verifiable Credential flow using Tykn’s platform. From setting up an Issuer account to, ultimately, request a Verification from a Prover.

In the following sections we’ll dive deeper into each part of the flow.

Initial Setup

During this setup, we will create your account and Public DID.

Your Organization’s Public DID will sign every Credential you issue. That Public DID is stored on the blockchain, an immutable record of data. When someone wants to verify the authenticity/validity of the Credential, they can check the Public DID on the blockchain to see who issued it without having to contact the issuing party (you).

To learn more about DIDs, check out our Guide on Decentralized Identifiers.

To setup your account, please reach out to our team at dev@tykn.tech

Schemas

Before issuing a Verifiable Credential, the Hospital needs to Create a Schema.

A Schema is a template outlining the verified data you can issue to your users.

In this case, the Hospital wants the Doctor ID to contain the following Attribute (Field) Names:

  • Doctor’s Name
  • License Number
  • Specialty

This Schema is published on the ledger. The “id” value is the reference to identify the Schema on the ledger.

The Hospital has now created the Doctor ID Schema.

Note: Creating a Schema is a ledger-write function. Creating one may incur additional costs. Tykn has a library of existing Public Schemas that your organization may use, avoiding the need to create a Schema.

Create a Credential Definition

The next step is to Create a Credential Definition.

A Credential Definition determines that all Credentials issued by your Organization using a certain Schema are going to be signed by your Organization’s Public DID (Decentralized Identifier).

Your Organization’s Public DID is also stored on the blockchain, an immutable record of data. When someone wants to verify the authenticity/validity of the Credential, they can check the Public DID on the blockchain to see who issued it without having to contact the issuing party (you).

The Blockchain acts as a verifiable data registry. A “phonebook” that anyone can consult to verify what organisation a specific Public DID belongs to. Decentralized Identifiers are what enable Verifiable Credentials to be verified anywhere, at any time.

The Hospital now creates a Credential Definition using the Doctor ID Schema.

Create a Prover Wallet

The Doctors will be the Provers, the ones who receive the Credentials and use them to prove something about themselves.

Each doctor needs a Wallet to be able to receive Credentials. The Hospital will now Create a Prover Wallet.

Dr. Gilfoyle will receive an email asking him to verify his email address and consent to the creation of the Web Wallet. Once he does, a Web Wallet will be created for him.

Each Prover gets a unique identifier, a handle (like Twitter’s usernames). This handle will be the main UUID used on the platform. Dr. Gilfoyle will be @Gilfoyle. Each handle has a 1:1 relationship with the Wallet.

Note: handles cannot be changed at the moment.

Issue Credential

The Hospital is now ready to issue the Verifiable Credentials.

They choose the Credential Definition to use, the Prover’s handle and fill in the attributes they want the Credential to include.

cred_def_id: the id you received after creating the Credential Definition

Dr. Gilfoyle receives an email informing that the Hospital wants to issue him a Credential and what Attribute Values are contained in the Credential. The doctor consents to accept the Credential.

Note: Credentials are never stored on the ledger. They are directly issued to the Prover and only stored in the Prover’s Wallet.

Create Proof Request Template

Time to verify a Credential!

To be able to verify Credentials, the Hospital needs to Create a Proof Request Template.

The proof_request_template_json describes what verified data the Verifier wants to request from the Prover.

The Verifier can request attributes like the Doctor’s Name.

Verify Credentials

The Hospital will now verify that Dr. Gilfoyle is a licensed practitioner.

The Hospital will send the Proof Request.

Dr. Gilfoyle receives an email and gives consent to share the information requested by the Verifier. This generates a Proof.

This Proof, the Verification Result, is sent to the Verifier.

nonce: nonce you received after the previous call

This comprises the entire Verifiable Credential flow, from account setup to receiving a Verification Result, using Tykn’s REST API.

If you’d like to read more, you can check out the full API Documentation.

To setup your account, please contact dev@tykn.tech