@proton/js

protonjs

Javascript API for integration with Proton

Installation

NPM

The official distribution package can be found at npm.

NodeJS Dependency

yarn add @proton/js

Using with Typescript

If you're using Node (not a browser) then you'll also need to make sure the dom lib is referenced in your tsconfig.json:

{
	"compilerOptions": {
		"lib": [..., "dom"]
	}
}

Browser Distribution

The dist-web folder contains minified bundles ready for production, along with source mapped versions of the library for debugging.

Import

ES Modules

Importing using ES6 module syntax in the browser is supported if you have a transpiler, such as Babel.

import { Api, JsonRpc, RpcError, JsSignatureProvider } from '@proton/js';

CommonJS

Importing using commonJS syntax is supported by NodeJS out of the box.

const { Api, JsonRpc, RpcError, JsSignatureProvider } = require('@proton/js');
const fetch = require('node-fetch'); // node only; not needed in browsers

Basic Usage

Signature Provider

The Signature Provider holds private keys and is responsible for signing transactions.

Using the JsSignatureProvider in the browser is not secure and should only be used for development purposes. Use a secure vault outside of the context of the webpage to ensure security when signing transactions in production

const defaultPrivateKey = "5JtUScZK2XEp3g9gh7F8bwtPTRAkASmNrrftmx4AxDKD5K4zDnr"; // bob
const signatureProvider = new JsSignatureProvider([defaultPrivateKey]);

JSON-RPC

Open a connection to JSON-RPC, include fetch when on NodeJS.

const rpc = new JsonRpc(['http://127.0.0.1:8888'], { fetch });

API

const api = new Api({ rpc, signatureProvider });

Sending a transaction

transact() is used to sign and push transactions onto the blockchain with an optional configuration object parameter. This parameter can override the default value of broadcast: true, and can be used to fill TAPOS fields given expireSeconds and either blocksBehind or useLastIrreversible. Given no configuration options, transactions are expected to be unpacked with TAPOS fields (expiration, ref_block_num, ref_block_prefix) and will automatically be broadcast onto the chain.

(async () => {
  const result = await api.transact({
    actions: [{
      account: 'eosio.token',
      name: 'transfer',
      authorization: [{
        actor: 'useraaaaaaaa',
        permission: 'active',
      }],
      data: {
        from: 'useraaaaaaaa',
        to: 'useraaaaaaab',
        quantity: '0.0001 SYS',
        memo: '',
      },
    }]
  }, {
    blocksBehind: 3,
    expireSeconds: 30,
  });
  console.dir(result);
})();

Error handling

use RpcError for handling RPC Errors

...
try {
  const result = await api.transact({
  ...
} catch (e) {
  console.log('\nCaught exception: ' + e);
  if (e instanceof RpcError)
    console.log(JSON.stringify(e.json, null, 2));
}
...

Contributing

Contributing Guide

Code of Conduct

License

MIT