npm package: @proton/js
Description: Javascript Interface to the Proton Blockchain
Author: Metallicus
Latest version: 30.1.0

# RPC

This package provides Javascript API for integration with Proton RPC services

## Installation

### NPM

The official distribution package can be found at [npm](https://www.npmjs.com/package/@proton/js).

### 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.

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

### CommonJS

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

```js
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_**

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

### JSON-RPC

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

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

#### Check User Verification

##### validKycProviders

A list of valid KYC Providers are stored here. When the JsonRpc is instantiated, it will check all the kyc providers and remove any blacklisted providers from this list.

It is an array of strings like so:

```
console.log(this.rpc.validKycProviders);

['metal.kyc']
```

###### isLightKYCVerified

This function serves to check a user's verification status by cross-referencing the user's KYC data against a list of valid KYC providers. A light KYC is considered verification with the user's first name, last name, address and birth date.

After instantiating the rpc, it can be called like so:

```
this.rpc.isLightKYCVerified(account)
```

The single argument `account` that this function takes in can accept a string account name or the user data returned from `this.rpc.get_table_rows` for the `usersinfo` table.This function returns the user data object with a flag under the key `isLightKYCVerified`.

### API

```js
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.

```js
(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

```js
...
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](./CONTRIBUTING.md)

[Code of Conduct](./CONTRIBUTING.md#conduct)

## License

[MIT](./LICENSE)