@litentry/profiles

Profiles is a use case of Litentry Protocol's Verifiable Credentials that quantifies Verifiable Credentials into a Score.

The Identity Hub project features and uses Profiles.

With this package you can:

1. Evaluate any score used in the Identity Hub.
2. Create your own score.
3. Claim a Litentry Verifiable Credential

Learn more about Litentry Client SDKs

Install

npm install @litentry/profiles

Examples

You can find more elaborated examples about the usage of this package on https://github.com/litentry/client-sdk-examples.

Below you will find some code snippets to guide you through the main functionalities.

Explore Profiles, use available Scores

This package offers all available Profiles which can be accessed via:

import { profiles } from '@litentry/profiles';

// Use Litentry Score
const profile = profiles['litentry-community-score'];

Some important properties are:

• profile.credentials: The list of Credential Definitions that compose the Score.
• profile.score: The Score's resolver that gives the range of the Score and the evaluate function.

This package features type annotations. You can inspect the documentation to learn more about the properties.

A Score is calculated from a collection of Litentry Verifiable Credentials. Following the example above, you can calculate Litentry Score by:

import { profiles } from '@litentry/profiles';

// Use Litentry Score
const profile = profiles['litentry-community-score'];

// -----
const userLitHolderVc: string = `{"@context":["https://www.w3.org...}`;
const userDotHolderVc: string = `{"@context":["https://www.w3.org...}`;

const scoring: number = profile.score.evaluate({
  'lit-holder': { rawCredentialText: userLitHolderVc },
  'dot-holder': { rawCredentialText: userDotHolderVc },
  // ... all other VerifiableCredential that sums up to the score
});
console.log(`Your Litentry Score is: ${scoring}`);

// you can get the range of the score from:
const range = profile.score.range;
console.log(
  `Litentry Score goes from ${range.minimalGain} up to ${range.maximum}`
);

Create your own Score

This package features the Profiles and therefore the Scores that are used in the Litentry Identity Hub. If your project's score is not yet featured, you can still use this package to create your own score the Identity Hub Credential Definitions.

Here as an example that adds constant values to users who claimed all of the Identity Hub OneBlock+ Credentials.

1. Define your Score's credential definitions.

   import { pick } from 'lodash';
   import { credentialDefinitionMap } from '@litentry/profiles';
   
   const myScoreCredentialDefinition = pick(credentialDefinitionMap, [
     'oneblock-course-participation',
     'oneblock-course-completion',
     'oneblock-course-outstanding-student',
   ]);

2. Define your score-builder by quantifying each credential definition.

   import {
     Score,
     credentialDefinitionMap,
     scoreUtils,
   } from '@litentry/profiles';
   import type { ScoreBuilderType } from '@litentry/profiles';
   
   type JsonString = string;
   
   type MyScoreCredentialDefinitionsId =
     keyof typeof myScoreCredentialDefinition;
   
   const myScoreBuilder: ScoreBuilderType<{
     [key in MyScoreCredentialDefinitionsId]: {
       rawCredentialText: JsonString | undefined | null;
     };
   }> = {
     'oneblock-course-participation': scoreUtils.ifClaimed(Score.constant(10), {
       id: 'oneblock-course-participation',
       claimParams: {},
     }),
     'oneblock-course-completion': scoreUtils.ifClaimed(Score.constant(10), {
       id: 'oneblock-course-completion',
       claimParams: {},
     }),
     'oneblock-course-outstanding-student': scoreUtils.ifClaimed(
       Score.constant(15),
       { id: 'oneblock-course-outstanding-student', claimParams: {} }
     ),
   };

3. Create your Score and use it

   import { Score } from '@litentry/profiles';
   
   const myScore = Score.scoreBuilderSum(myScoreBuilder);
   
   // Get the range of the score:
   console.log(
     `MyScore goes from ${myScore.range.minimalGain} up to ${myScore.range.maximum}`
   );
   
   // Evaluate
   const scoring: number = myScore.evaluate({
     'oneblock-course-participation': {
       rawCredentialText: 'participacion.vc.json',
     },
     'oneblock-course-completion': { rawCredentialText: 'completion.vc.json' },
     'oneblock-course-outstanding-student': {
       rawCredentialText: 'outstanding.vc.json',
     },
   });
   console.log(`Your Score is: ${scoring}`);

You can get the Range of a specific credential definition by using the score builder

const courseCompleteScoreFn = myScoreBuilder['oneblock-course-completion'];

if (courseCompleteScoreFn) {
  console.log(
    `OneBlock+ Course Complete goes from ${courseCompleteScoreFn.range.minimalGain} up to ${courseCompleteScoreFn.range.maximum}`
  );

  const scoring: number = courseCompleteScoreFn.evaluate({
    rawCredentialText: 'completion.vc.json',
  });

  console.log(`Your Score on OneBlock+ Course Completion is: ${scoring}`);
}

Learn more by looking into the available Profiles' Scores and the Score utilities.

Validate the claiming of a Litentry Verifiable Credential

This utility helps validating that a Verifiable Credential follows our Credential Definitions.

💡 A Credential Definition, dictates the rules by which the Verifiable Credential assertion is considered valid. This status is called claimed.

You can find all Credential Definitions in:

import { credentialDefinitionMap } from '@litentry/profiles';

Use the claimVc function to validate that a given Verifiable Credential is claimed based on any available definitionId:

import { claimVc } from '@litentry/profiles';

const maybeEvmTransactionCountVc: string =
  '{"@context":["https://www.w3.org...}';

const claimStatus = claimVc({
  definitionId: 'evm-transaction-count',
  verifiableCredential: maybeEvmTransactionCountVc,
  claimParams: {}, // this definition requires no claim params
});

// Whether it checks up with the definition
claimStatus.claimed;

// You can access the parsed credential too (if the definition id is valid)
claimStatus.parsedVc;

// Some definitions may also return helpful data extracted from the VC.
// For example, `evm-transaction-count` will return the lower and upper bound
// of the user transactions as reported by this VC's `$total_txs` clauses.
// However, `payload` would be available if the VC definition is claimed.
if (claimStatus.claimed) {
  const { lowerBound, strictUpperBound } = claimStatus.payload;

  console.log(
    `the VC claims the user has made between ${lowerBound} and ${strictUpperBound} EVM transactions`
  );
}