npm package: @iota/is-ict-dpp
Description: Javascript client for the DPP Services API
Latest version: 0.0.9

<!-- This READM is based on the BEST-README-Template (https://github.com/othneildrew/Best-README-Template) -->
<div id="top"></div>
<!--
*** Thanks for checking out the Best-README-Template. If you have a suggestion
*** that would make this better, please fork the repo and create a pull request
*** or simply open an issue with the tag "enhancement".
*** Don't forget to give the project a star!
*** Thanks again! Now go create something AMAZING! :D
-->

<!-- PROJECT SHIELDS -->
<!--
*** I'm using markdown "reference style" links for readability.
*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
*** See the bottom of this document for the declaration of the reference variables
*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
*** https://www.markdownguide.org/basic-syntax/#reference-style-links
-->

[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![Apache 2.0 license][license-shield]][license-url]
[![Discord][discord-shield]][discord-url]
[![StackExchange][stackexchange-shield]][stackexchange-url]

<!-- Add additional Badges. Some examples >
![Format Badge](https://github.com/iotaledger/is-ict-dpp/workflows/Format/badge.svg "Format Badge")
![Audit Badge](https://github.com/iotaledger/is-ict-dpp/workflows/Audit/badge.svg "Audit Badge")
![Clippy Badge](https://github.com/iotaledger/is-ict-dpp/workflows/Clippy/badge.svg "Clippy Badge")
![BuildBadge](https://github.com/iotaledger/is-ict-dpp/workflows/Build/badge.svg "Build Badge")
![Test Badge](https://github.com/iotaledger/is-ict-dpp/workflows/Test/badge.svg "Test Badge")
![Coverage Badge](https://coveralls.io/repos/github/iotaledger/is-ict-dpp/badge.svg "Coverage Badge")


<!-- PROJECT LOGO -->
<br />
<div align="center">
    <a href="https://github.com/iotaledger/is-ict-dpp">
        <img src="banner.png" alt="Banner">
    </a>
    <h3 align="center">IOTA DPP Client Library</h3>
    <p align="center">
        This is the client library written in typescript in association with Integration Services for use for Product Passport for consumer electronics.
        <br />
        <a href="https://wiki.iota.org"><strong>Explore the docs »</strong></a>
        <br />
        <br />
        <a href="https://github.com/iotaledger/is-ict-dpp/labels/bug">Report Bug</a>
        ·
        <a href="https://github.com/iotaledger/is-ict-dpp/labels/request">Request Feature</a>
    </p>
</div>

<details>
  <summary>Table of Contents</summary>
  <ol>
    <li>
      <a href="#about-the-project">About The Project</a>
      <ul>
        <li><a href="#built-with">Built With</a></li>
      </ul>
    </li>
    <li>
      <a href="#getting-started">Getting Started</a>
      <ul>
        <li><a href="#prerequisites">Prerequisites</a></li>
        <li><a href="#installation">Installation</a></li>
      </ul>
    </li>
    <li><a href="#usage">Usage</a></li>
    <ul>
        <li><a href="#create-identity-and-credentials">Create identity and credentials</a></li>
        <li><a href="#create-index-channel-address">Create index channel address</a></li>
        <li><a href="#registering-the-device">Registering the device</a></li>
        <li><a href="#lookup-device-channel">Lookup device channel</a></li>
        <li><a href="#one-shot-write">One shot write</a></li>
        <li><a href="#read-device-channel-as-auditor">Read a device's channel as auditor</a></li>
        <li><a href="#change-of-ownership">Change of ownership</a></li>
      </ul>
    <li><a href="#run-happypath">Run happyPath</a></li> 
  </ol>
</details>

## About The Project

This is the client library written in typescript in integration with Integration Services for use for Product Passport for consumer electronics.

### Built With

- [Typescript](https://www.typescriptlang.org/)
- [@iota/is-client](https://github.com/iotaledger/integration-services)

## Getting Started

Below are the instructions on how to run the DPP client library

## Prerequisites

To install the library you should have the npm package manager to be installed globally

```sh
npm install npm@latest -g
```

### Installation

```sh
npm i @iota/is-ict-dpp
```

you will need also the `@iota/is-client` to interact with IOTA's SSI Bridge and Audit Trail Gateway:

```sh
npm i @iota/is-client
```

## Usage

The following code snippets are showing the way that the DPP client library can be used.

## DppClient

Default configuration format should be in the following format:

```javascript
import { ClientConfig } from "@iota/is-client";

const defaultConfig: ClientConfig = {
  apiKey: "<IS API KEY>",
  isGatewayUrl: "<IS ENDPOINT>",
  apiVersion: "<API VERSION>",
};
```

All the interactions are provided by `DppClient`:

```javascript
import { ClientConfig } from "@iota/is-client";
import { DppClient } from "@iota/is-ict-dpp";

const defaultConfig: ClientConfig = { ... };

let dppClient = new DppClient(defaultConfig);
```

## Create identity and credentials

Internally we use this structure to manage identities:

```javascript
let actorIdentity = {
  did: "<Identity DID>",
  secret: "<Identity Secret>",
};
```

You can easily transform full identities into `IdentityDto` in the following way:

```javascript
import { IdentityJson } from "@iota/is-client";
import { IdentityDto } from "@iota/is-ict-dpp";

function toDppIdentity(identity: IdentityJson): IdentityDto {
  return {
    did: identity.doc.id,
    secretKey: identity.key.secret,
  } as IdentityDto;
}
```

You can import the `toDppIdentity` in the following way:

```javascript
import { toDppIdentity } from "@iota/is-ict-dpp";
```

The code snippet below shows how to create identities:

```javascript
import { ClientConfig, IdentityClient } from "@iota/is-client";

const defaultConfig: ClientConfig = { ... };
let actorIdentity = await new IdentityClient(defaultConfig).create(
  "<Subject Name>"
);
```

The following code snippet shows how to create credentials:

```javascript
import { DppClient } from "@iota/is-ict-dpp";

const defaultConfig: ClientConfig = { ... };

//See the structure to manage identities
let managerIdentity = { ... };

let ownerIdentity = { ... };

let credentialType = "OwnershipCredential";

let claim = { deviceId: "..." }; // Any kind of claim related to the Device

// Use the DppClient defined before
let credential = dppClient
  .identities()
  .createCredential(managerIdentity, ownerIdentity.did, credentialType, claim);
```

Credentials are used to establish a role for the actor in the device's lifecycle: they need to be used to approve `oneShowWrite`.
In case of `changeOwnership` you will need a `OwnershipCredential`: this particular credential is released as output in the device registration process.

## Create index channel address

In the code snippet below you can see how the index channel is created.

```javascript
import { ClientConfig, ChannelClient } from "@iota/is-client";

const defaultConfig: ClientConfig = { ... };

let managerIdentity = { ... };

let channelClient = new ChannelClient(defaultConfig);

await channelClient.authenticate(
  managerIdentity.did,
  managerIdentity.secretKey
)

let indexChannel = await channelClient.create({
  name: "<Device Id: it must be unique>",
  topics: [{ type: "index-channel", source: "dpp" }],
});

let indexChannelAddress = indexChannel.channelAddress;
```

## Registering the device

The code snippet below shows how the device can be registered. Register device accepts some set of parameters indicated in `registerDeviceParams`. As a result it returns the device channel address and the owner's verifiable credential.

```javascript
import { DppClient, RegisterDeviceDto } from "@iota/is-ict-dpp";
import { ClientConfig } from "@iota/is-client";

const defaultConfig: ClientConfig = { ... };

let managerIdentity = { ... };
let ownerIdentity = { ... };

let credentialType = "OwnershipCredential";
let chid = "<Device Id>";

const { channelAddress, verifiableCredential } = await dppClient.devices().registerDevice({
  managerIdentity,
  ownerIdentity,
  credentialType,
  indexChannelAddress,
  type: "e.g proof_of_register" ,
  chId,
  payload: { chid, timestamp: "<Timestamp>" },
} as RegisterDeviceDto);
```

The output of `registerDevice` is the `channelAddress` and the owner's `verifiableCredential`. This credential will be needed to authorize the `changeOwnership` method. The `channelAddress` is also registered in the index channel so it can be retrieved via `lookUpDeviceChannel` from the `chId` (device's identifier)

## Lookup device channel

This function finds the channel of the device based on the provided chId.

```javascript
import { DppClient } from "@iota/is-ict-dpp";
import { ClientConfig } from "@iota/is-client";

const defaultConfig: ClientConfig = { ... };

let dppClient = new DppClient(defaultConfig);

let managerIdentity = { ... };

let chid = "<Device Id>";

let channelAddress = await dppClient
  .events()
  .lookUpDeviceChannel(chid, indexChannelAddress, managerIdentity);
```

## One shot write

The code snippet below writes the one-shot information.

```javascript
import { DppClient } from "@iota/is-ict-dpp";
import { ClientConfig } from "@iota/is-client";

const defaultConfig: ClientConfig = { ... };

let dppClient = new DppClient(defaultConfig);
let eventService = dppClient.events();

await eventService.oneShotWrite(
  managerIdentity: { ... }
  subjectIdentity: { ... }
  channelAddress: "..."
  credential: { <repairer credential> }
  type: "e.g. repair"
  payload: { parts: [ ... ], modified: "..." }
);
```

## Read a device's channel as auditor

Reads the contents of a device's channel by providing an auditor credential.

```javascript
import { DppClient } from "@iota/is-ict-dpp";
import { ClientConfig } from "@iota/is-client";

const defaultConfig: ClientConfig = { ... };

let dppClient = new DppClient(defaultConfig);
let eventService = dppClient.events();

await eventService.auditDeviceChannel(
  managerIdentity: { ... }
  channelAddress: "..."
  credential: { <auditor credential> }
);
```

## Change of ownership

Change ownership revokes the ownership of the previous owner and gives the ownership to the new owner. The `changeOwnership` function as a result returns the verifiable credential of a new owner.

```javascript
import { DppClient, ChangeOwnershipDto } from "@iota/is-ict-dpp";
import { ClientConfig } from "@iota/is-client";

const defaultConfig: ClientConfig = { ... };
let dppClient = new DppClient(defaultConfig);

await dppClient.identities().changeOwnership(
  managerIdentity: { ... },
  credential: { ... },
  ownerIdentity: { ... }
  newOwnerIdentity: { ... }
  channelAddress: "..."
  chid: "<Device ID>"
) as ChangeOwnershipDto;
```

## Run happyPath

This is the example scenario. To run the happyPath:

1. Navigate to examples directory: `cd examples`
2. Install packages: `npm install`
3. Run the happyPath script: `npm run happy-path`

<!-- MARKDOWN LINKS & IMAGES -->
<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->

[contributors-shield]: https://img.shields.io/github/contributors/iotaledger/is-ict-dpp.svg?style=for-the-badge
[contributors-url]: https://github.com/iotaledger/is-ict-dpp/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/iotaledger/is-ict-dpp.svg?style=for-the-badge
[forks-url]: https://github.com/iotaledger/is-ict-dpp/network/members
[stars-shield]: https://img.shields.io/github/stars/iotaledger/is-ict-dpp.svg?style=for-the-badge
[stars-url]: https://github.com/iotaledger/is-ict-dpp/stargazers
[issues-shield]: https://img.shields.io/github/issues/iotaledger/is-ict-dpp.svg?style=for-the-badge
[issues-url]: https://github.com/iotaledger/is-ict-dpp/issues
[license-shield]: https://img.shields.io/github/license/iotaledger/is-ict-dpp.svg?style=for-the-badge
[license-url]: https://github.com/iotaledger/is-ict-dpp/blob/main/LICENSE
[discord-shield]: https://img.shields.io/badge/Discord-9cf.svg?style=for-the-badge&logo=discord
[discord-url]: https://discord.iota.org
[stackexchange-shield]: https://img.shields.io/badge/StackExchange-9cf.svg?style=for-the-badge&logo=stackexchange
[stackexchange-url]: https://iota.stackexchange.com