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.
Basic installation and usage instructions are below. Visit the full API Documentation for more.
The Node.js client cannot directly manage chain trees or connect to the notary group, so node applications must instead proxy through an RPC server to work with Tupelo.
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.
You can run the RPC server by invoking tupelo
along with the necessary options.
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.)
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>
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
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
Once you have installed the dependency, require the tupelo-client
module from
your application.
var tupelo = require('tupelo-client');
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 wallet credentials for the wallet you'd like to unlock for each
RPC request. The wallet credentials should be an
WalletCredentials object with
walletName
and passPhrase
keys.
var walletCreds = {
walletName: 'my-wallet',
passPhrase: 'super secret password'
};
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.
var client = tupelo.connect('localhost:50051', walletCreds);
Here is how to create a new key and then a chain tree owned by that key as an example. See the API docs for more information about the full Tupelo.js API.
// save the key address and chain tree id for later use
var keyAddr, chainId;
// register a new wallet, then generate a key and chain tree stored there
client.register()
.then(function(registerResult) {
return client.generateKey()
}, function(err) {
console.log("-----------Error registering wallet:----------");
console.log(err);
}).then(function(generateKeyResult) {
keyAddr = generateKeyResult.keyAddr;
return client.createChainTree(keyAddr);
}, function(err) {
console.log("-----------Error generating key:----------");
console.log(err);
}).then(function(createChainResponse) {
chainId = createChainResponse.chainId;
console.log("----------Chain ID:----------");
console.log(chainId);
return chainId;
}, function(err) {
console.log("-----------Error creating chain tree:----------");
console.log(err);
});
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.