@signumjs/http

The Signum Network SDK for Javascript (written in Typescript)

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

---

MODERNIZATION COMPLETED

• Version 2: Changed from lerna and jest to turbo and vitest.
• Version 2: Refactored crypto package (removed crypto-js dependency, using CryptoAdapter pattern)

Due to the removal of crypto-js the crypto adapter must be initialized

Breaking changes:

• Version 3: Deprecated LedgerClientFactory (use createClient instead)
• Version 3: Has improved tree-shaking capabilities, such that bundles can be significantly smaller.
• Version 3: Got the new mobile wallet deeplinking support.

---

Best way to start is with the extensive Online Documentation

---

Packages

The SDK is separated in the following packages

• @signumjs/core The main package providing an extensive 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/wallets This package provides the communication with SIP22 compatible deeplinkable
• @signumjs/standards This package provides the communication with SIP22 compatible deeplinkable

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/wallets (optional)
npm install @signumjs/standards (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/wallets (optional)
yarn add @signumjs/standards (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/wallets/dist/signumjs.wallets.min.js'></script>

<script src='https://cdn.jsdelivr.net/npm/@signumjs/standards/dist/signumjs.standards.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
util	sig$util
wallets	sig$wallets
wallets	sig$standards

Examples:

// using core
const ledger = sig$.createClient({
    nodeHost: "https://europe3.testnet.signum.network",
});

ledger.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.sha256AsHex("test"))

// using util
const value = sig$util.Amount.fromSigna("1000")

// using http
const client = new sig$http.HttpClientFactory.createHttpClient('https://jsonplaceholder.typicode.com/');
client.get('/todos/1').then(console.log)

// using wallets
const wallet = new sig$wallets.GenericExtensionWallet()
const connection = await wallet.connect();
const subscription = connection.listen({
    onAccountChanged: (accountId, publicKey) => { /*...*/ }
})
// ...
subscription.unlisten()

// using standards - depends on ledger
const ledger = sig$.createClient({
    nodeHost: "https://europe3.testnet.signum.network",
});

// create Descriptor data object
const descriptorData = sig$standards.DescriptorDataBuilder
    .create('ohager')
    .setType('hum')
    .setBackground('QmUFc4dyX7TJn5dPxp8CrcDeedoV18owTBUWApYMuF6Koc', 'image/jpeg')
    .setAvatar('QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR', 'image/gif')
    .setSocialMediaLinks(['https://somelink.com'])
    .setDescription('Just a humble dev...')
    .setHomePage('https://digital-independence.dev')
    .build();

// updates account descriptor
const client = new sig$standards.DescriptorDataClient(ledger)
const transaction = await client.setAccountDescriptor({
    descriptorData,
    senderPublicKey: '497d559d18d989b8....ed2716a4b2121902',
    senderPrivateKey: '**********************************'
});

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 {createClient} from '@signumjs/core/createClient'
import {Amount} from '@signumjs/util'

// this self-executing file makes turns this file into a starting point of your app
(async () => {
    try {
        const ledger = createClient({nodeHost: 'https://europe3.testnet.signum.network'});
        const {balanceNQT} = await ledger.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 ledger = sig$.createClient({nodeHost: 'https://europe3.testnet.signum.network'});
ledger.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}`)
    })

Crypto Adapters

The SignumJS SDK uses a crypto adapter pattern to allow for different platform crypto implementations (Web, NodeJS). For NodeJS and Web/Browser signumjs provides the adapters already.

crypto-js is deprecated and has security vulnerabilities in the random number generation. Since version 2.0.0, crypto-js is no longer used and for web and nodejs the native crypto implementation is used. This is why the crypto module needs to be initialized.

Note: For React Native/Expo a custom adapter is available.

WebCryptoAdapter

// somewhere on your apps entry point
import {WebCryptoAdapter} from '@signumjs/crypto/adapters'
import {Crypto} from '@signumjs/crypto'

Crypto.init(new WebCryptoAdapter())

Web bundles (signumjs.min.js) are automatically initialized with the WebAdapter - so, no need to initialize

NodeJSCryptoAdapter

// somewhere on your apps entry point
import {NodeJSCryptoAdapter} from '@signumjs/crypto/adapters'
import {Crypto} from '@signumjs/crypto'

Crypto.init(new NodeJSCryptoAdapter())

Development

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

npm install

That's it!

Building the packages

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

npm run compile

Running Tests

1. Single test run npm run test
2. 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

Versioning and Publishing

All packages share a single version and are published together.

npm run new-version -- patch   # e.g. 3.0.5 → 3.0.6
npm run new-version -- minor   # e.g. 3.0.5 → 3.1.0
npm run new-version -- major   # e.g. 3.0.5 → 4.0.0

The script will:

1. Generate per-package changelogs from git history (commits filtered by package directory)
2. Show a preview and ask for confirmation (with an option to edit changelogs first)
3. Bump all package.json versions and internal dependency ranges
4. Run turbo compile test bundle
5. Commit, tag, and push

Pushing the tag triggers the Publish workflow on GitHub Actions, which builds, tests, publishes all packages to npm, and creates a GitHub Release.

Setup: Add an npm automation token as the NPM_TOKEN secret in your repository settings (Settings → Secrets and variables → Actions → New repository secret)