Skip to content

Introduction

Jump to bottom
callchain edited this page Apr 1, 2018 · 10 revisions

Introduction

CallChain API is the official client library to the CallChain Ledger. Currently, CallChain API is only available in JavaScript. Using CallChain API, you can:

CallChain API only provides access to validated, immutable transaction data.

Boilerplate

Use the following boilerplate code to wrap your custom code using CallAPI.

const CallAPI = require('call-lib').CallAPI;

const api = new CallAPI({
  server: 'wss://s1.callchain.live' // Public calld server hosted by CallChain Foundation.
});
api.on('error', (errorCode, errorMessage) => {
  console.log(errorCode + ': ' + errorMessage);
});
api.on('connected', () => {
  console.log('connected');
});
api.on('disconnected', (code) => {
  // code - [close code](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent) sent by the server
  // will be 1000 if this was normal closure
  console.log('disconnected, code:', code);
});
api.connect().then(() => {
  /* insert code here */
}).then(() => {
  return api.disconnect();
}).catch(console.error);

CallAPI is designed to work in Node.js version 6.11.3. CallAPI may work on older Node.js versions if you use Babel for ECMAScript 6 support.

The code samples in this documentation are written with ECMAScript 6 (ES6) features, but CallAPI also works with ECMAScript 5 (ES5). Regardless of whether you use ES5 or ES6, the methods that return Promises return ES6-style promises.

All the code snippets in this documentation assume that you have surrounded them with this boilerplate. If you omit the "catch" section, errors may not be visible. The "error" event is emitted whenever an error occurs that cannot be associated with a specific request. If the listener is not registered, an exception will be thrown whenever the event is emitted.

Parameters

The CallAPI constructor optionally takes one argument, an object with the following options:

Name Type Description
authorization string Optional Username and password for HTTP basic authentication to the calld server in the format username:password.
certificate string Optional A string containing the certificate key of the client in PEM format. (Can be an array of certificates).
feeCushion number Optional Factor to multiply estimated fee by to provide a cushion in case the required fee rises during submission of a transaction. Defaults to 1.2.
key string Optional A string containing the private key of the client in PEM format. (Can be an array of keys).
passphrase string Optional The passphrase for the private key of the client.
proxy uri string Optional URI for HTTP/HTTPS proxy to use to connect to the calld server.
proxyAuthorization string Optional Username and password for HTTP basic authentication to the proxy in the format username:password.
server uri string Optional URI for calld websocket port to connect to. Must start with wss:// or ws://.
timeout integer Optional Timeout in milliseconds before considering a request to have failed.
trace boolean Optional If true, log calld requests and responses to stdout.
trustedCertificates array<string> Optional Array of PEM-formatted SSL certificates to trust when connecting to a proxy. This is useful if you want to use a self-signed certificate on the proxy server. Note: Each element must contain a single certificate; concatenated certificates are not valid.

If you omit the server parameter, CallAPI operates offline.

Installation

  1. Install Node.js and Yarn. Most Linux distros have a package for Node.js; check that it's the version you want.
  2. Use yarn to install CallAPI: yarn install call-lib

After you have installed call-lib, you can create scripts using the boilerplate and run them using the Node.js executable, typically named node:

  `node script.js`

Offline functionality

CallAPI can also function without internet connectivity. This can be useful in order to generate secrets and sign transactions from a secure, isolated machine.

To instantiate CallAPI in offline mode, use the following boilerplate code:

const CallAPI = require('call-lib').CallAPI;

const api = new CallAPI();
/* insert code here */

Methods that depend on the state of the CALL Ledger are unavailable in offline mode. To prepare transactions offline, you must specify the fee, sequence, and maxLedgerVersion parameters in the transaction instructions. You can use the following methods while offline:

Clone this wiki locally