@iota/is-ict-dpp
v0.0.9
Published
Javascript client for the DPP Services API
Downloads
34
Readme
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;
Run happyPath
This is the example scenario. To run the happyPath:
- Navigate to examples directory:
cd examples
- Install packages:
npm install
- Run the happyPath script:
npm run happy-path