BlockApps REST JS SDK

Introduction

The BlockApps-REST library is a Node.js server-side SDK library for BlockApps STRATO. It provides all the necessary abstractions and utility functions that can be used to interact with the STRATO platform and perform the following operations:

1. Creating and managing keys
2. Creating and managing transactions
3. Creating and managing private chains
4. Querying for contract state
5. Integrating with Identity Providers using OAuth 2.0 protocol

BlockApps-REST expects that the user will use an OAuth server to authenticate. BlockApps-REST cannot be used without a third party Identity Provider instance.

Installation

blockapps-rest can be installed as an NPM package: https://www.npmjs.com/package/blockapps-rest

npmyarnpackage.json

npm install blockapps-rest --save

yarn add blockapps-rest

"dependencies": {
  "blockapps-rest": "^8.0.5"
}

Source Code

The source code can be found on GitHub at https://github.com/blockapps/blockapps-rest.

Mirror Repository

This is a mirror repository for user reference only. BlockApps does not accept pull requests on this repository.

Usage

For usage examples, refer to the corresponding documentation on this website, e.g. API Basics

For information about BlockApps REST's modules, functions and classes, see BlockApps REST JSDoc

Configuration

The blockapps-rest library needs a configuration file to initialize it. This configuration file tells the blockapps-rest library which nodes it should interact with and what kind of authentication settings it should use. By default, blockapps-rest will look for config.yaml in the application root folder. The template for this configuration file is:

apiDebug: true
timeout: 600000

nodes:
  - id: 0
    url: "https://<strato_address>"
    publicKey: "<public_key>"
    port: 30303
    oauth:
      appTokenCookieName: "ba_rest_example_session"
      scope: "email openid"
      appTokenCookieMaxAge: 7776000000 # 90 days: 90 * 24 * 60 * 60 * 1000
      openIdDiscoveryUrl: "https://<openid_discovery_url>"
      clientId: "<client_id>"
      clientSecret: "<client_secret>"
      redirectUri: "https://<strato_address>/callback"
      logoutRedirectUri: "https://<strato_address>"

The above configuration defines the following settings:

1. apiDebug: This flag controls if blockapps-rest will output the backend calls its making to the various STRATO APIs to the console. This is useful during development, but should be set to false for production environments.
2. timeout: The query wait timeout used by blockapps-rest internally. Some operations in blockapps-rest wait on a transaction to be final. The time it takes for finality on a STRATO network depends on its configuration, so this value may need to be tweaked based on your environment. But for most situations, the default value of 60000 milli-seconds should be good enough.
3. nodes: The nodes array defines a set of nodes that this process can connect to and the OAuth details for the connection. These details are:
4. id: This id is used by the blockapps-rest calls to identify which node to connect to. This id should be a unique integer.
5. url: The base url at which the STRATO apis are available for the given node.
6. publicKey: The public key of the STRATO node (execute ./strato --get-pubkey on the host to obtain STRATO node's public key).
7. port: The port at which the STRATO node is listening for connections from other STRATO nodes in this network.
8. oauth: This section describes the oauth configuration for this node. These details are:
   • appTokenCookieName: This sets the name of the cookie that the app will set in the case of a frontend.
   • scope: The oauth scope to use when requesting tokens.
   • appTokenCookieMaxAge: The age of the cookie.
   • openIdDiscoveryUrl: The OAuth 2.0 OpenID discovery url (also known as the "well-known url").
   • clientId: The OAuth client id to use.
   • clientSecret: The OAuth client secret to use.
   • redirectUri: The redirect url after a successful login on the OAuth server. This URI should be allowed for the client in identity provider's configuration.
   • logoutRedirectUri: The redirect url after a user is logged out by the OAuth server

Basic Usage

// import blockapps-rest
import { rest, fsUtil, util, assert } from 'blockapps-rest';

// read config. See section on configuration
const config = fsUtil.getYaml(`config.yaml`);

// create an options object (optional)
const options = { config, logger: console };

// Create and faucet a user (keys) corresponding to an oauth identity (passed into the environment)
const user = await rest.createUser({token: process.env.USER_TOKEN}, options);

// Create a contract
const contractArgs = {
  name: 'TestContract',
  source: 'contract TestContract { uint a; constructor(uint _a) { a = _a; } function add(uint b) returns(uint) { return a+b; } }',
  args: { _a: 10 }
};
const contract = await rest.createContract(user, contractArgs, options);
assert.equal(contract.name, contractArgs.name, "name");
assert.isOk(util.isAddress(contract.address), "address");

// Get contract state
const state = await rest.getState(user, contract, options);
assert.equal(state.a, contractArgs.args._a);

// Call a method on a contract
const callArgs = {
  contract,
  method: 'add',
  args: {
    b: 10
  }
};
const [result] = await rest.call(user, callArgs, options);
assert.equal(result, contractArgs.args._a + callArgs.args.b);