IDENTITY SDK

This package facilitates the interaction with Identities stored in the BlockChain.

Specifications

Features

• Deploy identities
• List and Manage keys on an Identity
• List and manage Claims on an Identity.
• Issue claims for an Identity.
• Fetch claim data using their URI.

Usage

Installation

Install with npm install @onchain-id/identity-sdk

Then require with:

const { IdentitySDK } = require('@onchain-id/identity-sdk');

Tutorials

• Tutorial Homepage
  • Implement a Claim Issuer service
  • Restrict access to compliant Identities
  • Connect with Identity

BlockChain Provider

To interact with the BlockChain, you will need to instantiate a Provider.

The SDK is using Ethers to connect with Ethereum network. Thus, any provider supported by Ethers can be used with the SDK. This means any standard web3 provider should by supported.

Connect to a default provider:

// You can use any standard network name
//  - "homestead"
//  - "rinkeby"
//  - "ropsten"
//  - "kovan"
const ethers = require('ethers');

const provider = ethers.getDefaultProvider('ropsten');

const identity = await Identity.at('0x...', { provider });

Connect to JSON RPC:

// When using the JSON-RPC API, the network will be automatically detected
// Default: http://localhost:8545
let httpProvider = new ethers.providers.JsonRpcProvider();

Connect to any Web3 Provider:

// When using a Web3 provider, the network will be automatically detected

// e.g. HTTP provider
let currentProvider = new web3.providers.HttpProvider('http://localhost:8545');

let web3Provider = new ethers.providers.Web3Provider(currentProvider);

Connect to metamask:

// The network will be automatically detected; if the network is
// changed in MetaMask, it causes a page refresh.

let provider = new ethers.providers.Web3Provider(web3.currentProvider);

To use a signer instead of a provider (required to sign transactions):

const signer = new ethers.Wallet('PRIVATE_KEY', provider); // Or other signers from EthersJS.

const identity = await Identity.at('0x...', { signer });

Please refer to the Ethers Providers Documentation for more information.

Overriding provider or signer for operation

Every methods that connects to the Blockchain (write or read) accept last options arguments to specify the signer or provider to use for the operation, and for write operation, to override transaction parameters:

const ethers = require('ethers');
const identity = new IdentitySDK.Identity('0xadD92F8Ef0729E969c5a98Ea5740c9b644B362e3', provider);

await identity.addKey('0x..', 1, 3, { signer: someSigner, overrides: { gasPrice: ethers.parseUnits('2.0', 'gwei') } });

Configuration

Providers

By default, unsecured providers are not allowed. The SDK will refuse to fetch data on these endpoints. A claim that has an uri which is not an HTTPS endpoint won't be retrieved.

Allow unsecured endpoints with:

const IdentitySDK = require('@onchain-id/identity-sdk');
IdentitySDK.Config.config({ allowUnsecuredProviders: true });

SignerModule

Many interaction with identities, and especially claims, require to sign a challenge message. Functions requiring these signatures expect a SignerModule as argument.

A SignerModule must expose a .getPublicKey() and a .signMessage(message: string) functions.

This is, for instance, a valid SignerModule:

const jsrasign = require('jsrasign');

const signer = new SignerModule({
    getPublicKey: async () => ({
        key: "-----BEGIN CERTIFICATE----- my_super_public_key -----END CERTIFICATE-----",
        type: "X.509",
        signingMethod: "SHA-256",
    }),
    signMessage: async (message) => {
        const signer = new jsrsasign.Signature({ alg: 'SHA256withRSA' });
        signer.init("-----BEGIN CERTIFICATE----- my_super_PRIVATE_no_really_super_secret_PRIVATE_key -----END CERTIFICATE-----");
        signer.updateString(message);
        return signer.sign();
    },
});

As a convenient method, a SignerModule can be created from an ethers Wallet:

const wallet = new IdentitySDK.Providers.Wallet('PRIVATE_KEY', provider);
const signer = new IdentitySDK.SignerModule(wallet);

Examples

Find examples in the Example folder.

Load a contract

const { IdentitySDK } = require('@onchain-id/identity-sdk');

const provider = new ethers.providers.JsonRpcProvider();

(async () => {
  const identity = new IdentitySDK.Identity(); // Create the Identity Object

  console.log(identity.instantiateAtAddress('0xadD92F8Ef0729E969c5a98Ea5740c9b644B362e3', provider)); // Get the instance of the Identity

  console.log(await identity.instance.getClaimIdsByTopic(1)); // Call directly a function from the Contract.
})();

Get claims of an Identity

const { IdentitySDK } = require('@onchain-id/identity-sdk');

const provider = new ethers.providers.JsonRpcProvider();

(async () => {
  const identity = new IdentitySDK.Identity('0xadD92F8Ef0729E969c5a98Ea5740c9b644B362e3', provider);

  const claims = await identity.getClaimsByTopic(1);

  console.log(claims);
})();

Get keys of an Identity

const { IdentitySDK } = require('@onchain-id/identity-sdk');

const provider = new ethers.providers.JsonRpcProvider();

(async () => {
  const identity = new IdentitySDK.Identity('0xadD92F8Ef0729E969c5a98Ea5740c9b644B362e3', provider);

  const keys = await identity.getKeysByPurpose(IdentitySDK.utils.enums.KeyPurpose.CLAIM);
  
  console.log(keys);
  
  console.log(await identity.getKeyPurposes(keys[0].key));
})();

Deploy an identity

const { IdentitySDK } = require('@onchain-id/identity-sdk');

const provider = new ethers.providers.JsonRpcProvider();

const CLAIM_ISSUER_PRIVATE_KEY = 'issuer_private_key';
const claimIssuerWallet = new IdentitySDK.Providers.Wallet(CLAIM_ISSUER_PRIVATE_KEY, provider);

const DEPLOY_PRIVATE_KEY = 'deploy_private_key';
const deployWallet = new IdentitySDK.Providers.Wallet(DEPLOY_PRIVATE_KEY, provider);

(async () => {
  // Deploy a new Identity
    const identity = await IdentitySDK.Identity.deployNew(
      {
        managementKey: deployWallet.address,
        implementationAuthority: IdentitySDK.constants.implementationAuthorities.kovan,
      },
      { signer: deployWallet }
    );
    await identity.deployed();

  await identity.addKey(IdentitySDK.utils.crypto.keccak256(claimIssuerWallet.address), IdentitySDK.utils.enums.KeyPurpose.CLAIM, IdentitySDK.utils.enums.KeyType.ECDSA);
  
  identity.useProvider(claimIssuerWallet);

  await identity.addClaim(IdentitySDK.utils.enums.ClaimTopic.KYC, IdentitySDK.utils.enums.ClaimScheme.SOME, claimIssuerWallet.address, "a signature", "what a lot of data", "http://localhost:8080/claims/666");
})();

Deploy an implementation

const ethers = require('ethers');
const OnchainID = require('@onchain-id/solidity');

(async () => {
  const provider = ethers.getDefaultProvider('kovan');
  const signer = new ethers.Wallet('<private key>', provider);

  const implementation = await new ethers.ContractFactory(
    OnchainID.contracts.Identity.abi,
    OnchainID.contracts.Identity.bytecode,
    signer
  ).deploy(
    signer.address,
    true,
  );

  await implementation.deployed();

  console.log(implementation.address);
})();

Deploy an implementation authority

const ethers = require('ethers');
const OnchainID = require('@onchain-id/solidity');

(async () => {
  const provider = ethers.getDefaultProvider('kovan');
  const signer = new ethers.Wallet('<private key>', provider);

  const implementationAddress = '<implementation address>';

  const implementationAuthority = await new ethers.ContractFactory(
    OnchainID.contracts.ImplementationAuthority.abi,
    OnchainID.contracts.ImplementationAuthority.bytecode,
    signer
  ).deploy(implementationAddress);

  await implementationAuthority.deployed();

  console.log(implementationAuthority.address);
})();

Get details of a claim

const { IdentitySDK } = require('@onchain-id/identity-sdk');

const provider = new ethers.providers.JsonRpcProvider();

(async () => {
    IdentitySDK.config({ allowUnsecuredProviders: true });

    const identity = new IdentitySDK.Identity('0xadD92F8Ef0729E969c5a98Ea5740c9b644B362e3', provider);

    const claims = await identity.getClaimsByTopic(IdentitySDK.utils.enums.ClaimTopic.KYC);

    const claim = new IdentitySDK.Claim(claims[0]);

    await claim.populate();

    console.log(claim);
    
    /*
    Claim {
      data: '0x65773261724950755a302f626e5a744e327961676676376139462f6a3672744a4e3761666a52414c6871493d',
      id: '0x3c6532cc1f4d1a44de8f58d4bde617bef8e744168bf92d783a0e1b66e7c6a44a',
      issuer: '0x8c78fF753c63ea0e8CA1FcA9997A132bC3e6a8F1',
      scheme: 1,
      topic: 1,
      uri: 'http://localhost:8080/claims/b701e350-2a08-11e9-ac7e-517ddf10b60e',
      issuanceDate: 2019-02-06T12:14:12.996Z,
      emissionDate: 2019-02-06T12:15:02.039Z,
      status: 'PENDING',
      publicData: { result: 'clear' } }
     */
})();

Development

• Install dependencies: yarn.
• Lint code with yarn lint.
• Run unit tests: yarn test:unit. You can run unit tests each time you modify a file with yarn test:unit:watch.
• Build project with yarn build. This will build package into the dist/ folder from the TypeScript sources.
• Run end to end tests against a builded package: yarn test:e2e.
• You can generate type documentation with yarn build:docs. This will build the TypeDoc website into docs/type_doc.