@iota/is-ict-dpp NPM

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

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

npm install npm@latest -g

Installation

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:

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:

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:

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:

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

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

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:

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

The code snippet below shows how to create identities:

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:

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.

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.

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.

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.

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.

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.

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;