docs(vc): improve verifiable credential service documentation

energywebfoundation · May 11, 2022 · f7191f1 · f7191f1
1 parent 48cb347
commit f7191f1
Show file tree

Hide file tree

Showing 5 changed files with 269 additions and 95 deletions.
diff --git a/.../api/classes/modules_verifiable_credentials.VerifiableCredentialsServiceBase.md b/.../api/classes/modules_verifiable_credentials.VerifiableCredentialsServiceBase.md
@@ -2,6 +2,16 @@
 
 [modules/verifiable-credentials](../modules/modules_verifiable_credentials.md).VerifiableCredentialsServiceBase
 
+Service responsible for managing verifiable credentials and presentations.
+You can read more about verifiable credentials data model [here](https://www.w3.org/TR/vc-data-model/).
+
+```typescript
+const { connectToCacheServer } = await initWithPrivateKeySigner(privateKey, rpcUrl);
+const { connectToDidRegistry } = await connectToCacheServer();
+const { verifiableCredentialsService } = await connectToDidRegistry();
+verifiableCredentialsService.createRoleVC(...);
+```
+
 ## Table of contents
 
 ### Constructors
@@ -36,76 +46,118 @@
 
 ▸ **createPresentation**(`verifiableCredential`, `options?`): `Presentation`
 
+Create a presentation with given verifiable credentials. Allow create presentation for a given presentation definition.
+
+```typescript
+verifiableCredentialsService.createPresentation([...credentials]);
+```
+
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `verifiableCredential` | `VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>[] |
-| `options?` | [`CreatePresentationParams`](../interfaces/modules_verifiable_credentials.CreatePresentationParams.md) |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `verifiableCredential` | `VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>[] | role credential parameters |
+| `options?` | [`CreatePresentationParams`](../interfaces/modules_verifiable_credentials.CreatePresentationParams.md) | presentation options |
 
 #### Returns
 
 `Presentation`
 
+presentation
+
 ___
 
 ### createRoleVC
 
 ▸ **createRoleVC**(`credentialParams`, `proofOptions?`): `Promise`<`VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>\>
 
+Create a Energy Web role verifiable credential with EIP712 signature.
+
+```typescript
+verifiableCredentialsService.createRoleVC({
+     id: 'did:ethr:volta:0x00...0',
+     namespace: 'root.roles.energyweb.iam.ewc',
+     version: '1',
+});
+```
+
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `credentialParams` | [`RoleCredentialSubjectParams`](../interfaces/modules_verifiable_credentials.RoleCredentialSubjectParams.md) |
-| `proofOptions?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `credentialParams` | [`RoleCredentialSubjectParams`](../interfaces/modules_verifiable_credentials.RoleCredentialSubjectParams.md) | role credential parameters |
+| `proofOptions?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | proof options |
 
 #### Returns
 
 `Promise`<`VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>\>
 
+verifiable credential object
+
 ___
 
 ### createVerifiablePresentation
 
 ▸ **createVerifiablePresentation**(`verifiableCredential`, `options?`): `Promise`<`VerifiablePresentation`\>
 
+Create a verifiable presentation with given verifiable credentials and EIP712 signature.
+
+```typescript
+verifiableCredentialsService.createVerifiablePresentation([...credentials]);
+```
+
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `verifiableCredential` | `VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>[] |
-| `options?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `verifiableCredential` | `VerifiableCredential`<[`RoleCredentialSubject`](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)\>[] | role credential parameters |
+| `options?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | proof options |
 
 #### Returns
 
 `Promise`<`VerifiablePresentation`\>
 
+verifiable presentation
+
 ___
 
 ### initiateExchange
 
-▸ **initiateExchange**(`__namedParameters`): `Promise`<`any`[]\>
+▸ **initiateExchange**(`options`): `Promise`<[`InitiateExchangeResults`](../interfaces/modules_verifiable_credentials.InitiateExchangeResults.md)[]\>
+
+Initialize credential exchange. Only vc-api exchanges currently supported.
 
-**`description`** The type of the exchange. Only vc-api exchanges currently supported.
+```typescript
+verifiableCredentialsService.initiateExchange({
+    type: VC_API_EXCHANGE,
+    url: 'http://localhost:3000',
+});
+```
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `__namedParameters` | `ExchangeInvitation` |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `options` | `ExchangeInvitation` | object with options |
 
 #### Returns
 
-`Promise`<`any`[]\>
+`Promise`<[`InitiateExchangeResults`](../interfaces/modules_verifiable_credentials.InitiateExchangeResults.md)[]\>
 
 credentials query with matching verifiable presentations
 
 ___
 
 ### verify
 
-▸ **verify**<`T`\>(`vp`, `options?`): `any`
+▸ **verify**<`T`\>(`vp`, `options?`): `Promise`<`boolean`\>
+
+Verify a given credential or presentation. Throws an error if the credential or presentation proof is not valid.
+
+```typescript
+await verifiableCredentialsService.verify(credential);
+await verifiableCredentialsService.verify(presentation);
+```
 
 #### Type parameters
 
@@ -115,14 +167,16 @@ ___
 
 #### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `vp` | `VerifiablePresentation` \| `VerifiableCredential`<`T`\> |
-| `options?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `vp` | `VerifiablePresentation` \| `VerifiableCredential`<`T`\> | verifiable presentation or credential |
+| `options?` | [`ProofOptions`](../interfaces/modules_verifiable_credentials.ProofOptions.md) | proof options |
 
 #### Returns
 
-`any`
+`Promise`<`boolean`\>
+
+true if the proof is valid
 
 ___
 

diff --git a/docs/api/interfaces/modules_verifiable_credentials.InitiateExchangeResults.md b/docs/api/interfaces/modules_verifiable_credentials.InitiateExchangeResults.md
@@ -0,0 +1,22 @@
+# Interface: InitiateExchangeResults
+
+[modules/verifiable-credentials](../modules/modules_verifiable_credentials.md).InitiateExchangeResults
+
+## Table of contents
+
+### Properties
+
+- [presentationDefinition](modules_verifiable_credentials.InitiateExchangeResults.md#presentationdefinition)
+- [selectResults](modules_verifiable_credentials.InitiateExchangeResults.md#selectresults)
+
+## Properties
+
+### presentationDefinition
+
+• **presentationDefinition**: `PresentationDefinition`
+
+___
+
+### selectResults
+
+• **selectResults**: `SelectResults`
diff --git a/docs/api/modules/modules_verifiable_credentials.md b/docs/api/modules/modules_verifiable_credentials.md
@@ -9,6 +9,7 @@
 ### Interfaces
 
 - [CreatePresentationParams](../interfaces/modules_verifiable_credentials.CreatePresentationParams.md)
+- [InitiateExchangeResults](../interfaces/modules_verifiable_credentials.InitiateExchangeResults.md)
 - [IssuerFields](../interfaces/modules_verifiable_credentials.IssuerFields.md)
 - [ProofOptions](../interfaces/modules_verifiable_credentials.ProofOptions.md)
 - [RoleCredentialSubject](../interfaces/modules_verifiable_credentials.RoleCredentialSubject.md)

diff --git a/src/modules/verifiable-credentials/types/verifiable-credentials.types.ts b/src/modules/verifiable-credentials/types/verifiable-credentials.types.ts
@@ -1,4 +1,5 @@
-import { IPresentationDefinition } from '@sphereon/pex';
+import { PresentationDefinition } from '@ew-did-registry/credentials-interface';
+import { IPresentationDefinition, SelectResults } from '@sphereon/pex';
 import { IssuerFields } from './role-credential.types';
 
 /*
@@ -7,20 +8,31 @@ import { IssuerFields } from './role-credential.types';
  */
 export interface RoleCredentialSubjectParams {
   /*
+   * DID of the subject
    * https://www.w3.org/TR/vc-data-model/#identifiers
    */
   id: string;
+
+  /* Role namespace */
   namespace: string;
+
+  /* Role version */
   version: string;
+
+  /* Role issuer fields */
   issuerFields?: IssuerFields[];
 }
 
 export interface ProofOptions {
+  /* Proof verification method */
   verificationMethod?: string;
+
+  /* Proof purpose */
   proofPurpose?: string;
 }
 
 export interface CreatePresentationParams {
+  /* Presentation definition from which pick the credentials */
   presentationDefinition?: IPresentationDefinition;
 }
 
@@ -29,3 +41,8 @@ export interface VerifyVerifiableCredentialResults {
   warnings: string[];
   errors: string[];
 }
+
+export interface InitiateExchangeResults {
+  presentationDefinition: PresentationDefinition;
+  selectResults: SelectResults;
+}