In our previous post we introduced the concept of Verifiable Credentials and the problems they exist to solve. If you haven’t read that post, we recommend starting there so that everything in this post will make a lot more sense. As we covered in VCs 101, Verifiable Credentials have 9 key attributes:

• Hard to fake

• Impersonation resistant

• Easier to custody

• Easier to replicate

• Cheap to create, issue, and deliver

• Peer to peer verifiable and validatable

• Privacy preserving

• Censorship resistant

• Portable

That sounds great and all, but how do these things actually work. We’re glad you asked! Let’s start by breaking down the structure of a Verifiable Credential. Don’t worry, we’ll take this one step at a time.

The Structure of VCs

Verifiable Credentials can come in all shapes and sizes. As we have talked about before, a VC can represent a diploma, a medical record, DAO membership, a ticket to an event, etc. For interoperability sake, just like the documents we use in the real world, VCs need to use common templates for common things. The world we want to see (ideally) is one where all DAOs adopt the same template for representing DAO membership. These templates are called schemas. At Disco, when you go to issue a credential to someone else, the first thing you do is select your schema. That schema dictates which fields, such as “name” or “address” or “guild”, that you need to fill out to issue the credential.

Schemas are mainly concerned with defining the claims inside of a credential, but there are 2 other parts of the credential that help round out its overall structure. At the highest level, Verifiable Credentials have 3 main sections: Metadata, Claims, and Proofs. Let’s look at each of these sections individually.

Metadata

The part of a Verifiable Credential that describes the credential itself. The Metadata includes fields such as the “@context”, the issuer DID, the credential’s (optional) unique ID, the credential issuance date, an (optional) expiration date, and the credential “type”.

The “@context” of a credential is the section of a credential that helps verifier software make sense of the structure and language of the credential. This is oftentimes referred to as semantic meaning. Inside of the body of the credential you are likely to see fields such as “name” and “address”. However, not all credentials use the same fields, obviously. So the @context helps us make sense of what the content and structure of the credential should be.

The other pieces of metadata in the credential are relatively straightforward. The Issuer DID is not only the identifier of the issuer, but it is also a pointer to where we can find the public key that was used to sign the credential (this is important for the “proofs” section). The issuance date lets verifiers know when a credential was originally written. This is helpful when performing audits about past events. The expiration date is when the credential is no longer valid according to the issuer. And finally, the credential “type” is sort of like the name of the schema. The @context field and the “type” field work together to tell verifiers what the credential is about and how it should be interpreted.

Claims

The claims are the part of a credential that you are most likely thinking about when you hear about Verifiable Credentials. When you look at a VC you will see a section called “credential subject”, these are the claims. This section’s first field is an ID which contains the credential subject’s DID. This tells verifiers who the credential is about. If you receive a credential from someone else, this is where you should see your own DID.

The claims section then goes on to include human readable fields such as name, address, age, etc. When you or your organization are thinking about what information the credentials you want to issue need to have in them, you are thinking about the “claims”.

Claims can be literally anything and the values of claims can be integers, text strings, images, URLs, etc. Theoretically, we should be able to model anything we could possibly want in this section, the only limit is your imagination!

Proofs

This is the section of the credential that will seem most daunting and that is because it is! This is where all the complicated stuff happens. But as with much of life, the scariest part is the most important part. The proofs section contains all the information to verify the credential. VCs wouldn’t be very useful if it wasn’t for this section.

The proofs section typically contains a single proof mechanism but can have more than one mechanism in some cases. A proof mechanism contains a signature that allows a verifier to know if any of the data in the VC has been tampered with. This is the same as how blockchain transactions work. When you submit a transaction to the blockchain, you sign it with your private key, the same thing is happening here! Without this signature, the subject of the credential could change their birthdate, for instance, and nobody would know. At Disco, we make use of EIP712Signature2021 for signing credentials. So, when you use Disco, and go to issue a credential and get a Metamask signing request, this is the part of the credential you are creating!

Bonus Section: Status

In addition to the three main sections of a credential that we just covered, you might run into a few different bonus sections. The first of these that we will cover is status. The status section exists to allow the issuer of a credential the ability to revoke that credential. Imagine you issue a DAO Membership credential to someone that ends up having less than stellar vibes, you might want to make sure that person can’t continue to use their credential to get into the credential gated parts of your community. This status section is where you can put information for the Verifier to use to find out if you have revoked the credential.

Revocation can be done in a number of ways, however, the preferred way in the Web3 space is to make use of the blockchain. To revoke a credential, an issuer just needs to publish a hash of the credential to an on-chain registry and list that registry address in this status section. That way when a verifier is deciding whether or not to trust a credential, they can take the hash or the credential and then check the on-chain registry to see if the hash exists there (and if it was put there by the same entity that issued the credential) and if it does, they know that the issuer no longer vouches for it.

What’s Next

This was pretty dense. We are getting pretty deep into the world of Verifiable Credentials at this point. You should be proud of making it this far! However, there is still more to learn (we didn’t even cover all the flavors of Verifiable Credentials). In the next part of our series we will cover the lifecycle of a Verifiable Credential which should help you imagine from end to end how a VC actually gets used, where Zero Knowledge Proofs can be used, and what Verifiable Presentations and Selective Disclosure are. Don’t back out now, you’re almost there!

As always, check us out and say “hi” at www.disco.xyz

Jonny Howle

Co-Founder / Head of Strategy

@jonnyhowle

For any comments or questions, please contact ask@disco.xyz, or sign up to schedule a 1:1 feedback session here.