@q-dev/q-js-sdk

Q JS SDK

Documentation • System Contracts • Q Blockchain

Typescript Library to interact with Q System Contracts

Installation

Install package as dependency:

npm install --save @q-dev/q-js-sdk

or

yarn add @q-dev/q-js-sdk

Requirements

• Web3 ^1.7.0

Usage

Initialize contract registry:

const contractRegistry = new ContractRegistryInstance(web3)

Retrieve SDK version

import { Web3Adapter, Web3Factory, Web3 } from '@q-dev/q-js-sdk'

const web3 = Web3Factory.createFromMnemonic('<YOUR_RPC_URL>', '<MNEMONIC>')
const adapter = new Web3Adapter(web3)
const SDK_VERSION = adapter.SDK_VERSION

Obtain system contract instances

const validators = await contractRegistry.validators()

Call contract getter

const longList = await validators.getLongList()

Submit contract transaction

To be able to process various transaction events, use PromiEvent

const { promiEvent } = await validators.commitStake({from: '<USER_ADDRESS>', value: '<COMMIT_AMOUNT>'})
/**
 * We do not wait for the transaction to complete. 
 * This gives us the opportunity to subscribe to PromiEvent events
 */
promiEvent
  .once('sending', (payload) => { ... })
  .once('sent', (payload) => { ... })
  .once('transactionHash', (hash) => { ... })
  .once('receipt', (receipt) => { ... })
  .on('confirmation', (confNumber, receipt, latestBlockHash) => { ... })
  .on('error', (error) => { ... })

await promiEvent

Local development

Install packages

npm install

Generate types

npm run generate-types

If generate-types indicates 0 matching files (on Windows machines) you can try the adapted script npm run generate-types-win

Contribute

Make sure to run pre-commit script before commit

npm run pre-commit

You may check conformity between system-contracts and sdk via abi-conformity-check. But remember, we don't need all methods from each contract. Most of them are used by the system.

npm run abi-conformity-check

Update ABI files

Download latest abi files, for a specific system contracts tag:

• Devnet
• Master
• Custom tag: https://gitlab.com/q-dev/system-contracts/-/jobs/artifacts/\<TAG_NAME>/download?job=extract-abi

Then call

./update-abis.sh <path/to/abi.zip>

Run tests

You may run tests via

npm run test

Get access to private Gitlab registry

Log in to GitLab NPM package registry. You need a gitlab personal access token with read_api option enabled. This can be created via GitLab User Settings / Access Tokens.

npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' <YOUR_ACCESS_TOKEN>

Furthermore you need to tell npm that all q-dev packages should be resolved via private gitlab registry. Create a file .npmrc with the following content:

@q-dev:registry=https://gitlab.com/api/v4/packages/npm/

Code of Conduct

This project and everyone participating in it is governed by the Q JS SDK Code of Conduct. By participating, you are expected to uphold this code.

Resources

• Changelog
• Contributing Guide
• System Contracts
• Web3 Documentation

License

LGPL-3.0