@signumjs/util

SignumJS - Javascript SDK for Signum

Showing:

Popularity

Downloads/wk

46

GitHub Stars

7

Maintenance

Last Commit

1mo ago

Contributors

1

Package

Dependencies

2

License

Apache-2.0

Type Definitions

Built-In

Tree-Shakeable

No?

Categories

Readme

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

PackageVariable
coresig$
contractssig$contracts
cryptosig$crypto
httpsig$http
monitorsig$monitor
utilsig$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:

npm run build

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

Publish

To publish all packages (using lerna and same version strategy) just run

npm run publish

Note: Only with a valid npm token

Documentation

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100