Skip to content

README.md

Latest commit

 

History

History
179 lines (120 loc) · 5.87 KB

README.md

File metadata and controls

179 lines (120 loc) · 5.87 KB
Raw

burstjs

The BurstCoin Type/Javascript Reference Library

npm lerna Codacy Badge Build Status Known Vulnerabilities codecov jsDelivr

@burstjs is a modern library written in Typescript providing common functionalities for browsers and nodejs to interact with the BurstCoin blockchain, an advanced community-driven blockchain technology.

Packages

The library is separated in the following packages

  • @burstjs/core The main package providing an extense API for blockchain interaction
  • @burstjs/crypto A package providing BURST relevant crypto functions
  • @burstjs/util A package providing useful functions, e.g. common conversion functions
  • @burstjs/http A package providing a simplified Http layer, with consistent response types, and exception handling

Installation

@burstjs aims modern browsers and nodejs > v10, but can also be used as bundled JavaScript using <script>

Using with NodeJS and/or modern web frameworks

Install using npm:

npm install @burstjs/core
npm install @burstjs/crypto (optional)
npm install @burstjs/util (optional)
npm install @burstjs/http (optional)

or using yarn:

yarn add @burstjs/core
yarn add @burstjs/crypto (optional)
yarn add @burstjs/util (optional)
yarn add @burstjs/http (optional)

Usually, you won't need to install other packages than @burstjs/core, which uses the other packages.

Using in classic <script>

Each package is available as bundled standalone library using IIFE. This way burstJS can be used also within <script>-Tags. This might be useful for Wordpress and/or other PHP applications.

Just import one of the packages using the HTML <script> tag.

<script src='https://cdn.jsdelivr.net/npm/@burstjs/core/dist/burstjs.min.js'></script>

<script src='https://cdn.jsdelivr.net/npm/@burstjs/crypto/dist/burstjs.crypto.min.js'></script>

<script src='https://cdn.jsdelivr.net/npm/@burstjs/http/dist/burstjs.http.min.js'></script>

<script src='https://cdn.jsdelivr.net/npm/@burstjs/util/dist/burstjs.util.min.js'></script>

Due to the way a package is imported following global variables are provided

Package Variable
core b$
crypto b$crypto
http b$http
util b$util

Examples:

// using core
const api = b$.composeApi({
  nodeHost: "http://at-testnet.burst-alliance.org:6876",
  apiRootUrl: "/burst"
});

api.network.getBlockchainStatus().then(console.log);
// using crypto
console.log(b$crypto.hashSHA256("test"))
// using util
const value = b$util.convertNumberToNQTString(1000)
// using http
const client = new b$http.HttpImpl('https://jsonplaceholder.typicode.com/');
client.get('/todos/1').then(console.log)

Usage

The following example shows how to interact with the blockchain, i.e. getting the balance of a specific account

ES6/NodeJS style

In a separate file, preferribly index.js or main.js write your entry point like this:

import {composeApi, ApiSettings} from '@burstjs/core'
import {convertNQTStringToNumber} from '@burstjs/util'

const apiSettings = new ApiSettings('http://at-testnet.burst-alliance.org:6876', 'burst');
const api = composeApi(apiSettings);

// this self-executing file makes turns this file into a starting point of your app

(async () => {
  try{
    const {balanceNQT} = await api.account.getAccountBalance('13036514135565182944')
    console.log(`Account Balance: ${convertNQTStringToNumber(balanceNQT)} BURST`)  
  }
  catch(e){ // e is of type HttpError (as part of @burstjs/http)
    console.error(`Whooops, something went wrong: ${e.message}`)      
  }
})()

<script> style

const apiSettings = new b$.ApiSettings('http://at-testnet.burst-alliance.org:6876', 'burst');
const api = b$.composeApi(apiSettings);


api.account.getAccountBalance('13036514135565182944')
    .then( balance => {
        console.log(`Account Balance: ${b$util.convertNQTStringToNumber(balance.balanceNQT)} BURST`)  
    
    })
    .catch(e => { // e is of type HttpError (as part of @burstjs/http)
        console.error(`Whooops, something went wrong: ${e.message}`)      
    })

Development

When contributing to the Phoenix wallet and updates in burstjs are necessary, simply do

npm install && npm run bootstrap

That's it!

Running Tests

  1. Single test run npm run test
  2. Run in watch mode npm run test:watch
  3. Run end-to-end test npm run test:e2e | Keep in mind that these tests are slow as they run against true servers. And therefore, it cannot be guaranteed that all E2E tests always work

Documentation