Activeledger - Node SDK

The Activeledger Node SDK has been built to provide an easy way to connect your Node based application with an Activeledger network. This SDK can be used in JavaScript and TypeScript projects.

GitHub

Repository here

Further Documentation

Documentation here

Installation

$ npm i -s @activeledger/sdk

Usage

The SDK currently supports the following functionality

• Connection handling
• Key generation
• Key onboarding
• Transaction building
• Encrypted & unencrypted transaction posting
• SSE Subscriptions

Once the SDK has been installed import the classes and interfaces as you need them.

// Example
import { Connection } from "@activeledger/sdk";

Enums

The Activeledger Node SDK provides an enum to help handle key types.

| Key | Ref | | -------------- | --------------------- | | Elliptic Curve | KeyType.EllipticCurve | | RSA | KeyType.RSA |

Interfaces

The Activeledger Node SDK provides multiple interfaces to provide you with.

| Interface | Description | | ---------------- | ----------------------------------------------------------- | | IKey | For Activeledger keys | | IOnboardTx | Specifically for key onboarding, mainly used internally | | IOnboardTxBody | Used by IOnboardTx for $tx variable | | INodeKeyData | Used to hold the node key data for encrypting a transaction | | IHttpOptions | Internal interface for setting HTTP options | | ILedgerResponse | A helper for the ledger response | | ISummaryObject | Used by ILedgerResponse | | IStreamsObject | Used by ILedgerResponse | | INewObject | Used by IStreamsObject | | IUpdatedObject | Used by IStreamsObject | | IBaseTransaction | Helper for creating transactions | | ITxBody | Used by IBaseTransaction for the $tx variable |

Connection

When sending a transaction, you must pass a connection that provides the information needed to establish a link to the network and specified node.

To do this a connection object must be created. This object must be passed the protocol, address, port, and optionally the encryption flag.

Example

import { Connection } from "@activeledger/sdk";
// Setup the connection object to use localhost over http unencrypted
const connection = new Connection("http", "localhost", 5260);

// Use localhost but encrypt transactions
const connection = new Connection("http", "localhost", 5260, true);

KeyHandler

Note: Generating an RSA key is resource intensive and can take a few seconds.

The Key Handler can be used to generate and onboard a key.

The Key generation function and key onboard function are setup to be used separately as you may not want to immediately onboard a key. Additionally, you will need to store the key as it is used to sign all transactions involving the identity created when you onboard it.

There are two key types that can be generated currently, more are planned and will be implemented into Activeledger first. These types are RSA and Elliptic Curve.

Generating a key

When generating a key you must pass it a name and the key type.

Example

Note: This example uses the IKey interface which provides the structure of the key

import { KeyHandler, IKey, KeyType } from "@activeledger/sdk";

const keyHandler = new KeyHandler();

let key: IKey;

// Generate RSA Key
keyHandler
  .generateKey("keyname", KeyType.RSA)
  .then((generatedKey: IKey) => {
    key = generatedKey;
  })
  .catch();
// or to generate an Elliptic Curve key
// keyHandler.generateKey("keyname", KeyType.EllipticCurve)

Onboarding a key

Once you have a key generated, to use it to sign transactions it must be onboarded to the ledger network

Example

import { Connection, KeyHandler, IKey, KeyType, ILedgerResponse } from "@activeledger/sdk";

const connection = new Connection("http", "localhost", 5260);
const keyHandler = new KeyHandler();

let key: IKey;
keyHandler
  .generateKey("keyname", KeyType.EllipticCurve)
  .then((generatedKey: IKey) => {
    key = generatedKey;
    return keyHandler.onboardKey(key, connection);
  })
  .then((ledgerResp: ILedgerResponse) => {
    resolve(ledgerResp);
  })
  .catch();

Exporting a key

You can use the SDK to export a key in JSON format to the filesystem. This will be in the same structure as the IKey interface.

When exporting a key the required parameters are the Key object and the location to store it. Note that the location should not include the name of the file, this is an optional parameter.

| Parameter | Description | Type | Required | | --------- | ------------------------------------ | ------- | -------- | | key | The Key object | IKey | Yes | | location | The storage location | string | Yes | | createDir | Create directory if it doesn't exist | boolean | No | | overwrite | Overwrite a file with the same name | boolean | No | | name | The name of the file | string | No |

Example

import { KeyHandler } from "@activeledger/sdk";

const keyHandler = new KeyHandler();

const key: IKey = await keyHandler.generateKey("Key Name", KeyType.EllipticCurve);
keyHandler.exportKey(key, "./").then(() => {
  // Now export is finished do something
});

Importing a key

You can also use the SDK to import a key from the file system. Note that this key file must follow the same structure as the IKey interface.

The import function requires that the location parameter includes the file name with .json extension.

| Parameter | Description | Type | Required | | --------- | -------------------- | ------ | -------- | | location | The storage location | string | Yes |

Example

import { KeyHandler } from "@activeledger/sdk";

const keyHandler = new KeyHandler();
keyHandler.importKey(`./${key.name}.json`).then((importedKey: IKey) => {
  // Do something with the key
});

TransactionHandler

The Transaction Handler is used to sign and send transactions.

You can use the IBaseTransaction as a helper when building a transaction to be sent to the ledger.

Signing a transaction

When signing a transaction you must send the finished version of it. No changes can be made after signing as this will cause the ledger to reject it.

You must pass the transaction and the correct key to this function. The key must be one that has been successfully onboarded to the ledger which the transaction is being sent to.

It is also possible to send the transaction to be signed as a string, the signing function will then return just the signature as a string.

Example

import { TransactionHandler, IBaseTransaction } from "@activeledger/sdk";

// Connection and key code goes here if needed

// Create a transaction. In this example a namespace onboarding transaction
const txHandler = new TransactionHandler();
const tx: IBaseTransaction = {
  $sigs: {},
  $tx: {
    $contract: "namespace",
    $i: {},
    $namespace: "default",
  },
};

// The identity of the key that the namespace will be linked to
tx.$tx.$i[key.identity] = {
  namespace: "example-namespace",
};

// Sign the transaction
txHandler
  .signTransaction(tx, key)
  .then((signedTx: IBaseTransaction) => {
    tx = signedTx;
  })
  .catch();

// Sign a string transaction
txHandler
  .signTransaction("Hello world", key)
  .then((signature: string) => {
    // Do something with the signature
  })
  .catch();

Sending a transaction

Example

import { TransactionHandler, IBaseTransaction } from "@activeledger/sdk";

// Connection setup, Transaction building and signing here

// Send the transaction
txHandler
  .sendTransaction(tx, connection)
  .then((response: ILedgerResponse) => {
    // Do something with the response
  })
  .catch();

Events

The event class of the SDK provides the caller with easy access to the server side events provided by ActiveCore.

Example usage

Initialise

import { LedgerEvents } from "@activeledger/sdk";

const events = new LedgerEvents("{ActiveCore URL}");

Subscribe to all Activities

const reference = events.subscribeToActivity(eventData => {
  // Do something with event data
});

Subscribe to a specific Activity

const reference = events.subscribeToActivity("{activityStream}", eventData => {
  // Do something with event data
});

Subscribe to all events

const reference = events.subscribeToEvent(eventData => {
  // Do something with event data
});

Subscribe to all events of a specific contract

const config: IEventConfig {
  contract: "{contractId}"
};

const reference = events.subscribeToEvent(eventData => {
    // Do something with event data
  },
  config
);

Subscribe to a specific event of a specific contract

const config: IEventConfig {
  contract: "{contractId}",
  event: "{contractId}"
};

const reference = events.subscribeToEvent(eventData => {
    // Do something with event data
  },
  config
);

Unsubscribe from an event

This is the same for both Activity events and Events

// Create a subscription and store the returned reference number
const reference = events.subscribeToActivity(eventData => {
  // Do something with event data
});

// Unsubscribe
events.unsubscribe(reference);

Further Documentation

You can read further documentation here.

Activeledger

Visit Activeledger.io

Read Activeledgers documentation

License

This project is licensed under the MIT License