Tupelo.js

A Node.js API client to both manage Tupelo chain trees and submit chain tree transactions to a notary group for verification, through connecting with a Tupelo RPC server.

Installation and Usage

Basic installation and usage instructions are below. Visit the full API Documentation for more.

RPC Server

The Node.js client cannot directly manage chain trees nor connect to the notary group, so Node.js applications must instead proxy through an RPC server to work with Tupelo.

Installation

To install the server, first contact us to get a Tupelo binary for your platform and save it within your command PATH variable. If you do not wish to save the binary in your PATH, you can still execute it with the fully qualified or relative path to your chosen location for the binary.

Usage

You can run the RPC server by invoking tupelo along with the necessary options.

Connecting to a Local Notary Group

To get started quickly for local development, simply run:

tupelo rpc-server --local-network 3

This will spin up a 3 signer local, in-memory notary group after first generating three random keypairs for the group to use. Then it will start the RPC server and bind it to the local notary group. Note that restarting the server will remove all data stored by the local notary group signers! (You may still have some retained application state.)

Connecting to the Tupelo Alpha Test Network

To connect to the Tupelo alpha test network notary group, contact us to get the public key file corresponding to the running network. Then you can start the server and bind it to the notary group with:

tupelo rpc-server --bootstrap-keys <public key file>

Other Options

tupelo also includes a help command that lists the available options and their descriptions:

% > ./tupelo help rpc-server
Launches a Tupelo RPC Server

Usage:
  tupelo rpc-server [flags]

Flags:
  -k, --bootstrap-keys string   which public keys to bootstrap the notary groups with
  -h, --help                    help for rpc-server
  -l, --local-network int       Run local network with randomly generated keys, specifying number of nodes as argument. Mutually exlusive with bootstrap-*
  -t, --tls                     Encrypt connections with TLS/SSL
  -C, --tls-cert string         TLS certificate file
  -K, --tls-key string          TLS private key file

Node.js Client

Installation

You can install Tupelo.js with npm. Run the following command from your project's directory to add Tupelo.js to the npm project's dependencies.

npm install tupelo-client

Usage

Once you have installed the dependency, require the tupelo-client module from your application.

const tupelo = require('tupelo-client');

Wallet Credentials

The RPC server stores all the chain trees it has access to in an encrypted wallet with a unique name and secret pass phrase. You must initialize the client with the correct credentials for the wallet you'd like to unlock for each RPC request. The wallet credentials should be a WalletCredentials object with walletName and passPhrase keys.

const walletCreds = {
  walletName: 'my-wallet',
  passPhrase: 'super secret password'
};

Obtaining an RPC client connection

The connect function takes the host:port string of the RPC server and the wallet credentials object as arguments and returns an RPC client connection.

const client = tupelo.connect('localhost:50051', walletCreds);

Using the API

See the API docs for full information about the Tupelo.js API.

Here is an example of how to create a new key and then a chain tree owned by that key.

const tupelo = require('tupelo-client');

const createTree = async () => {
  const walletCreds = {
    walletName: 'my-wallet',
    passPhrase: 'super secret password'
  };
  const wallet = tupelo.connect('localhost:50051', walletCreds);

  // register a new wallet, then generate a key and chain tree stored there
  await wallet.register();
  const {keyAddr: walletKey,} = await wallet.generateKey();
  const {chainId,} = await wallet.createTree(walletKey);
  return {wallet, walletKey, chainId,};
};

const main = async () => {
  const {chainId,} = await createTree();
  console.log(chainId);
};

Another example, of how to set data in a tree and resolving it (using the createTree function from the previous example):

const assert = require('assert');

const main = async () => {
  const {chainId, wallet, walletKey,} = await createTree();
  await wallet.setData(chainId, walletKey, 'key', 'value');

  // Resolve the path we just set
  let resp = await wallet.resolveData(chainId, 'key');
  assert.deepStrictEqual(resp.data, ['value']);
  assert.equal(resp.remainingPath, '');

  // Resolve a child path of what we set before; it will resolve, but not for the full path
  resp = await wallet.resolveData(chainId, 'key/child');
  assert.deepStrictEqual(resp.data, ['value']);
  assert.strictEqual(resp.remainingPath, 'child');
};

Tests

There are some RPC integration tests that can be run against a live Tupelo RPC server by running npm test. Note that you will need a working Docker environment setup.

Examples

There are some example apps in the example directory, which should be of help in understanding how to use Tupelo.

transfer-ownership

This example demonstrates Tupelo's feature of transferring the ownership of a chain tree from one party (identified by a public key) to another. See the whitepaper's discussion of the SET_OWNERSHIP transaction type for background on ownership transfer in Tupelo.

timestamper

This is a highly trivial app that simply shows how one may write to chain trees and read back from them.