Options
All
  • Public
  • Public/Protected
  • All
Menu

signumjs - The Javascript SDK for Signum Network

signumjs

The Signum Network SDK for Javascript (written in Typescript)

npm lerna Build Known Vulnerabilities jsDelivr

@signumjs is a modern SDK written in Typescript providing common functionalities for browsers and nodejs to interact with the Signum Network blockchain, an advanced community-driven blockchain technology.

Packages

The SDK is separated in the following packages

  • @signumjs/core The main package providing an extense API for blockchain interaction
  • @signumjs/contracts A package providing Signum relevant functions for smart contracts
  • @signumjs/crypto A package providing Signum relevant crypto functions
  • @signumjs/util A package providing useful functions, e.g. common conversion functions
  • @signumjs/http A package providing a simplified Http layer, with consistent response types, and exception handling
  • @signumjs/monitor A package providing a class to execute recurring async operations with de/serialization feature, good for listening to blockchain transactions

Installation

@signumjs aims modern browsers and nodejs >= v14, but can also be used as bundled JavaScript using <script>

Using with NodeJS and/or modern web frameworks

Install using npm:

npm install @signumjs/core
npm install @signumjs/contracts (optional)
npm install @signumjs/crypto (optional)
npm install @signumjs/util (optional)
npm install @signumjs/http (optional)
npm install @signumjs/monitor (optional)

or using yarn:

yarn add @signumjs/core
yarn add @signumjs/contracts (optional)
yarn add @signumjs/crypto (optional)
yarn add @signumjs/util (optional)
yarn add @signumjs/http (optional)
yarn add @signumjs/monitor (optional)

Using in classic <script>

Each package is available as bundled standalone library using UMD. This way SignumJS 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/@signumjs/core/dist/signumjs.min.js'></script>

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

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

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

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

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

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

Package Variable
core sig$
contracts sig$contracts
crypto sig$crypto
http sig$http
monitor sig$monitor
util sig$util

Examples:

// using core
const api = sig$.composeApi({
    nodeHost: "http://testnet.signum.network",
});

api.network.getBlockchainStatus().then(console.log);
// using contracts
const dataView = new sig$contracts.ContractDataView(contract)
console.log(dataView.getVariable(2))
// using crypto
console.log(sig$crypto.hashSHA256("test"))
// using util
const value = sig$util.Value.fromSigna("1000")
// using http
const client = new sig$http.HttpClientFactory.createHttpClient('https://jsonplaceholder.typicode.com/');
client.get('/todos/1').then(console.log)
 // using monitor

// A method that checks if an account exists
// > IMPORTANT: Do not use closures, when you need to serialize the monitor
async function tryFetchAccount() {
    try {
        const api = composeApi({nodeHost: 'https://testnet.signum.network:6876/'})
        const {account} = await api.account.getAccount('1234')
        return account;
    } catch (e) {
        // ignore error
        return null;
    }
}

// A comparing function to check if a certain condition for the returned data from fetch function
// is true. If it's true the monitor stops
function checkIfAccountExists(account) {
    return account !== null;
}

// Create your monitor
const monitor = new Monitor<Account>({
    asyncFetcherFn: tryFetchAccount,
    compareFn: checkIfAccountExists,
    intervalSecs: 10, // polling interval in seconds
    key: 'monitor-account',
    timeoutSecs: 2 * 240 // when reached timeout the monitor stops
})
    .onFulfilled(() => {
        // called when `checkIfAccountExists` returns true
        console.log('Yay, account active');
    })
    .onTimeout(() => {
        // called when `timeoutSecs` is reached
        console.log('Hmm, something went wrong');
    }).start();

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, preferably index.js or main.js write your entry point like this:

import {composeApi, ApiSettings} from '@signumjs/core'
import {Amount} from '@signumjs/util'

// this self-executing file makes turns this file into a starting point of your app
(async () => {
    try {
        const api = composeApi({nodeHost: 'https://testnet.burstcoin.network:6876'});
        const {balanceNQT} = await api.account.getAccountBalance('13036514135565182944')
        console.log(`Account Balance: ${Amount.fromPlanck(balanceNQT).toString()}`)
    } catch (e) { // e is of type HttpError (as part of @signumjs/http)
        console.error(`Whooops, something went wrong: ${e.message}`)
    }
})()

<script> style

const api = sig$.composeApi({nodeHost: 'https://testnet.burstcoin.network:6876'});
api.account.getAccountBalance('13036514135565182944')
    .then(balance => {
        console.log(`Account Balance: ${sig$util.Amount.fromPlanck(balance.balanceNQT).toString()}`)

    })
    .catch(e => { // e is of type HttpError (as part of @signumjs/http)
        console.error(`Whooops, something went wrong: ${e.message}`)
    })

Development

Contributors are warmly welcome. To start your local build just hit

npm install

That's it!

Building the packages

The SDK is using Lerna to manage all subpackages in a developer friendlier way:

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