Credential types & concepts
Status: in development
We propose various types of verifiable credentials (VC). The user can choose which properties of the VC are the most suitable for her. The VC standard is built on top of the NEAR NFT specifications, and all the credential data contains in NFT metadata. We store most of the credential data on-chain and also provide the majority of the credential management options on-chain.
Basic VC
The basic VC type is the simplest type of credentials. This type is the foundation for more complicated VCs. Such credentials can be useful when there is no need for strict approval, credential usability, or additional signatures. It also can be a self-issued credential (when the holder matches the issuer) for the holder's personal needs, such as a credential minted from an existing digital document.
The basic data fields consist of the following:
token context: credential settings set by vSelf.
They depend on the data type presented in the credential and are defined by the issuer's needs and preferences.
token type: set by vSelf.
It's the vSelf parsing settings of the credential, which are processed inside the vSelf application and defined by the issuer's needs and preferences.
token name: set by the issuer.
token issuer id: set by vSelf.
The NEAR id of the issuer.
token description: set by the issuer.
token issuance date: set by vSelf.
The minting date of the credential.
token expiration date: set by the issuer.
It defines the durability of the credential, which can be undefined if there is no time limitation.
token holder id: set by the issuer.
The NEAR id of the holder.
token holder info map: set by the issuer
It defines additional information about the holder, includes key and value fields with any facts about the holder, and can be undefined.
token attributes list: can be set by the issuer, by vSelf from the credential description, or be undefined.
It is a list of hashtags associated with credential information, which is used to classify holders' interests, skills, or reputation categories.
token evidence: set by the issuer.
It contains additional information about issuer status or documents with a hash link used for external content. Can be undefined.
token subjects id list: set by the issuer.
Defines the list of entities connected with a credential, NEAR ids of credential subjects, or the names of the subjects if they have no ids (can be undefined in case of credential subject matches with credential holder).
token subjects info list: set by the issuer.
Includes additional information about credential subjects and key and value fields about some facts for each subject. Note that it can be defined only if the subject list is filled or can be undefined.
token use terms: set by the issuer.
It is a type of user agreement that can be chosen from the vSelf predefined list or by the hash link for external content (can be undefined in case of default user agreement: use without any restrictions).
token spectrum of privacy: set by vSelf.
Defines the status of the information presented in the credential and depends on the value in the token type field.
token claim list: set by the issuer
Stands for the list of additional statuses of the issuer, holder or subjects, including key and value for each status, the map with key, and value fields of this status properties (can be undefined).
There are several methods to operate with the basic type of verifiable credentials:
Issue: allows the issuer to set up a credential and mint it for the holder's NEAR wallet;
Revoke: allows the issuer to revoke the credential from the holder;
Update: allow the issuer to update the details of the credential;
Delete: allows the holder to delete the unnecessary credential from her wallet;
It is not allowed to transfer the credential to someone else. Therefore, only the credential holder can own the credential.
VC source file
Some types of verifiable credentials require illustrated source file. It means that we include the hash link to the original file (document or image) and the hash of data from the file in the credential metadata. It allows for validating that the corresponding file hasn't been changed.
token source file: set by vSelf, the link is set by the issuer, and the hash is calculated from the source file.
Contains the link to the original file, file SHA256 hash.
It allows for private verifiable credentials that are more resilient against disclosure of the holder's personality.
The information about the source file's existence is contained in the token type field as one of the credential parsing parameters.
In the case of VC with source file validation, it is necessary to validate the hash link. If the source file has been changed, the hash link won't be valid anymore.
VC status
The token status is a complicated structure with information about credential management, which is required to validate or verify credentials. The data included in the token status depends on the credential type. This part of the credential metadata differs from the part provided below: it is mutable and can be changed by different participants after the credential is minted.
token status: the structure consists of mutable data, which helps to validate or verify the credential.
In the case of the basic VC, it includes the revoked status of the credential. If the issuer revokes the credential, the revoked status will be switched to True.
token revoke status: boolean flag in the token status structure, which can be changed by the issuer.
VC validation & verification
The variety of information in the credential metadata that can be checked includes NEAR ids, current credential status, credential ownership, issuance and estimated date, existence and validity of signatures, quality of the information presented in credential claims, hash links validity, satisfaction of subject description and it's "real world" entity, and more other options.
Some of these tests can be provided automatically, but other ones require manual checks by experts. Besides, if some of the credentials parameters may change over time, the process of interaction with credentials should involve recurrent checks.
We divide actions in this process into two groups: VC validation & VC verification. VC verification consists of simple checking actions, including:
Check the token status: process depends on the type of the credential. For basic VC, we check that the token revoke status is False.
Check the credential ownership: the credential owner should match the credential holder.
Check the issuance date and the estimated date: the current timestamp should be more than the issuance date and less than the estimated date.
Check the hash link of the source file: the link to the source file should be valid, and the hash of the source file should match the file hash.
There are two view methods available for everyone:
View: allow everyone to view the credential metadata;
Verify: allows everyone to verify the credential;
For more complicated actions, we use the term "validation". The validation process requires an expert validator with appropriate competence (see the details described here).
Private VC
All the public credential metadata is available for everyone to view in NEAR explorer. But sometimes credentials contain sensitive information about the holder or the subject, and it is necessary to hide it. For this reason, the issuer can mint a private VC for the holder. It means that a required transaction is provided for the holder's implicit NEAR wallet and presented in the NEAR explorer with encrypted metadata. We use the ECC algorithm to encrypt this data with the holder's public key (the main NEAR id of the holder). This approach ensures that only the issuer or the holder can parse the metadata of this type of credential.
In this case, it is preferable not to include personal information about the holder in the illustrated source file. It helps to avoid the risk of disclosing the holder's personality using this source file.
The information if the credential is private or public is presented in the token type field as one of the parsing settings. There is no need to provide additional functionality to the credential on-chain structure. But additional steps with the encryption and the decryption of the metadata will be provided by the issuer's and the holder's side.
View and verify options for this type of credential aren't available. However, the holder is able to construct a verifiable presentation from her credential to provide chosen information to a third party.
Multi-signature VC
This VC type contains additional signatures provided by the credential authorities. In this case, the vSelf VC toolkit allows the issuer to define individuals affiliated with the credential.
The multi-signature credential can be implemented, to name some examples, in the following use cases:
Educational credentials with signatures of several lecturers;
Business agreements that require signatures from multiple parties;
Sensitive information in credentials that require holder's consent;
Credentials that require subjects' consent, e.d. feedback or endorsements.
The list of authorities and their signatures is presented in the VC metadata:
token authority list: this list contains the information about NEAR authorities' ids and the map of properties for each authority with key & value fields set by the issuer;
token signature status: this map contains NEAR authority ids and their signatures in ED-25519 standard, which can be changed by the authority and is contained in the token status.
If some signatures of the authorities aren't provided, the credential validation process returns a negative result.
This credential type requires the additional methods to support:
Signature request: allows the issuer to set up the list of the credential authorities and send signature requests to them;
Sign: allows the authority to provide her signature for the credential.
The information about the multi-signature property is presented in the token type field as one of the parsing settings.
The signature request token is minted for all the authorities after the credential is minted. The request tokens are described in detail here.
Community VC
The community credential is the credential, which is issued inside the community toolkit. The issuer is able to define the list of curators to update the credential metadata. The curator role has a more general definition and variety of implementations, but in this case, the issuer rights are the same as the curators rights.
Community toolkit functionality allows the community owner to set up the list of administrators. The owner or any of administrator are able to be the community VC issuer. And the community owner and all of the community administrators stay the curators automatically. The information, which community issued VC is stored in the token claim list field with the key community and value community_id.
token curators list: the curators' NEAR ids, set by vSelf;
The information about usability of the credential is presented in the token type field as one of the parsing settings.
Usable VC
The usable credential type allows the holder to exchange her credential for some benefit (a product or service). The issuer is able to define the list of curators to update the credential status. The curator role has a more general definition and variety of implementations, but in our model, we are focused on this use case only.
token curators list: the curators' NEAR ids, set by the issuer;
token use status: state of the credential contained in the token status field; it can be changed by the issuer or curators.
If the token use status value is True, credential validation returns a corresponding result.
Curators from the token curators list or the credential issuer are allowed to change the user status and provide some benefits to the credential holder.
Use request: allows the holder to send the user request to the curator;
Use: allows the issuer or curator to switch the token use status for True.
The information about usability of the credential is presented in the token type field as one of the parsing settings.
The use request token is minted by the holder for the curator. The request tokens are described in detail here.
Proofed VC
The proofed credential types include the option to set up a credential validation process. It is expected that validators have the appropriate expertise to check the information consisted in the credential.
There are several proofed VC types supported in our toolkit. They differ in validation processes, methods for choosing validators, and data provided for the validation. The token status contains validation status.
token validation status: this status contains NEAR validators' ids, validation results, and validates' signatures in the ED-25519 standard and can be changed by the validators.
There are different ways to calculate the joint validation result that corresponds to the validation results provided by the validators. For this reason, the issuer is able to choose which validation mode is more suitable for her use case.
token validation mode: one of the ways to calculate the joint validation result based on the results of the validators is to take the total number of required approvals and add the calculation method: single, majority, all; set by the issuer.
The data in token validation status and token validation mode is used to identify the joint validation result. As soon as all the necessary approvals from the validators are received according to chosen token validation mode, the validation process is passed. After that, the verifiable credential is expected to stay proofed, and the validation process returns a positive result.
All of the proofed VCs contain the method to request validation and execute validation, but they work differently for different proofed VC types.
Request validation: allows the issuer or holder to construct a validation request token and send this request for the given validator's NEAR id;
Validate: allows the validator to provide her validation result and her signature.
The information about the proofed type of the credential is presented in the token type field as one of the parsing settings.
Fixed-validator proofed VC
The fixed-validator proofed credential requires the list of validators. The issuer is the one who should provide this list of trusted contacts (NEAR ids).
token validator list: this list contains the information about NEAR validators' ids and the map of properties for each validators with the key & value fields set by the issuer.
The request for validation, in this case, can be sent to the validator from the token validator list only. The fixed-validator property of the credential is also presented in the token type structure.
Flexible-validator proofed VC
A preferable option for the issuer might be to have validator with expertise without providing a pre-defined list of validators. A possible solution is to set up a rule for choosing suitable validators. In this case, the list of validators will be constructed according to the chosen rule. The rule can contain all the desired properties of the validators. For example, it is comfortable to choose validators according to their community reputation or claims from the verifiable presentation. But such a use case requires additional R&D and is not included in our roadmap at the moment. There is a more specific but useful case in our toolkit. It can be suitable for different guilds, communities and talent hubs. In this case, it is able to validate membership credentials with the flexible list of validators. The requirement for validators looks like this: "I own the proofed membership credential, or I am the credential issuer (owner of this community)". Firstly the issuer can validate several membership credentials, and after that, the holders of the proofed membership credentials can stay validators for other membership credentials.
Therefore, it is necessary for the issuer to provide an example of the credential which the community member should own. The validation process is the comparison of the membership credential metadata with the metadata from this example.
token membership example: contains the metadata to compare with, set by the issuer.
The validate method and validation request token has additional variables: the holder token id and the validator token id. The holder token should satisfy the membership example, and the validator token should be the proofed membership credential. This type of VC is called community-validator proofed VC, and the type information is also presented in the token type field.
Verifiable presentation
The holder is able to generate the new credential from existing ones. This credential type is named verifiable presentation. The verifiable presentation can be affiliated with one or several source credentials. The holder can choose which data from the source credentials she wants to add to her presentation. For this reason, the verifiable presentation contains only necessary information (instead of the information from the source credentials) to share with the third party.
The list of the source credential ids and the chosen information is presented in the presentation metadata:
presentation token list: the list of the source credentials set by the issuer;
token metadata list: a chosen subset of the metadata from each source credential set by the issuer.
After the presentation has been constructed, the holder is able to create the self-minted credential. This presentation credential can be used by the holder as her Web3 portfolio inside the single token.
The verifiable presentation type of the credential contains in the token type field.
Zero-knowledge proofs verification
Sometimes there is the need for the holder to hide her personality and not disclose unnecessary data, even for a verifier. There are a lot of options for zero-knowledge proof implementation to guarantee privacy during the verification process.
We are focused on the single-use case: proof-of-ownership of the credential. This credential type is named private ownership-verified VC. In this case, the issuer mints the credential for different holders and writes the commitments (hashed token id) to the special list, which is stored on-chain. The verification requires the holder to provide this proof: "I have the input (credential id) for one of the commitments from the commitment set". In this case, the holder doesn't provide her credential id to the verifier. This process evaluates the risk for the holder to disclosing her personality.
We use Bulletproofs to provide the proof "My token id contains in the given set" and R1CS circuit to provide the proof "I have an input for this hashed output". The combination of these two proofs is used to construct the proof provided for the verifier. We use MiMC hash to construct the commitment from the token id.
After a new commitment is added (new credential is minted), all the proofs provided before stay invalid. For this reason, the user should receive the new proof just before the verification is started. The verification result isn't written for the credential metadata.
There are two new methods required for the verification process:
Get proof: allows the holder to get the proof-of-ownership for her credential;
Verify proof: allows the verifier to verify the given proof-of-ownership.
The type of this credential is stored in the token type field.
Request tokens
This kind of tokens illustrates the rights to manage the credential - make some changes in the credential metadata. They have the same properties as the common credential types, such as non-transferability. Their metadata matches the source credential (similar to the public VCs). The credential issuer or holder only are able to mint such a token using source credential metadata.
There are three different types of request tokens supported in our toolkit:
Signature request: illustrates the right of the credential authority to change the token signature status data by adding her signature;
Use request: illustrates the right of the credential curator to switch the token use status value for true;
Validation request: illustrates the right of the credential validator to change the token validation status data by adding her id, validation result and signature.
So, this token type contains the following fields:
source token id: the source credential;
request type: signature, use, validation options;
The request type of the credential is presented in the token type field to parse this token as an appropriate request.
Private request tokens
The metadata of the private credential is hidden for authorities, curators or validators (let's name all of them as an actor). But the actors should have access to this data.
Instead of parsing the credential metadata from NEAR Explorer, our toolkit constructs the token request from the original metadata of the source credential on the issuer or holder side. Therefore, the issuer or holder has the option to decrypt the source credential metadata. After that, the request token includes hashed metadata about all the credential actors and other credential metadata encrypted using this actor's public key. All the changes in the source credential metadata are encrypted using the implicit holder's public key.
Last updated