mxw-api v0.1.4

SDK for MXW blockchain

Getting started

1. Install mxw-api package

If you want the latest, stable version, install the package from NPM.

npm install --save mxw-api

If you want the bleeding edge version which is possibly unstable, you can install the package from this Git repo.

npm install --save git+https://github.com/Sentrylink/mxw-api.git

2. Use it in your project

// Load the SDK (with require)
const MxwApi = require('mxw-api')

// Load the SDK (with import)
// import MxwApi from 'mxw-api'

// Define all nodes from which SDK can choose one
// The following list of nodes represents the current MXW testnet
const NODES = [
    'ws://node-1.testnet.space:26657',
    'ws://node-2.testnet.space:26657',
    'ws://node-3.testnet.space:26657',
    'ws://node-4.testnet.space:26657',
    'ws://node-5.testnet.space:26657',
    'ws://node-6.testnet.space:26657',
    'ws://node-7.testnet.space:26657',
    'ws://node-8.testnet.space:26657',
    'ws://node-9.testnet.space:26657',
    'ws://node-10.testnet.space:26657',
]

// Define the indexing service endpoint
// The provided URL is the Indexing service used by the testnet
const INDEXER = 'http://services.testnet.space:1234'

// Instantiate the SDK
const API = new MxwApi({
    nodes: NODES,
    indexer: INDEXER,
    backend: 'cosmos',
})

Tips

You can find detailed usage examples in the examples folder.

• Assets / examples/assets.js
• Alias / examples/alias.js
• Events / examples/events.js
• Faucet / examples/faucet.js
• KYC / examples/kyc.js
• Transfer / examples/transfer.js
• Utilities / examples/util.js

API reference / Features

MXW SDK module

Kind: global namespace
Version: 0.1.4

• mxw : object
  • .events : object
    • ~onTx(fnc)
    • ~onBlock(fnc)
    • ~removeHandler(type)
  • .main : object
    • ~balance(address) ⇒ Promise
    • ~transfer(privateKey, address) ⇒ Promise
    • ~signTransfer(privateKey, address) ⇒ Promise
  • .util : object
    • ~getAddressByPrivateKey(privateKey) ⇒ string
    • ~getAddressByPublicKey(publicKey) ⇒ string
    • ~generateKeyPair() ⇒ object
    • ~getAddressFromPublicKeyByteArray(byteArray) ⇒ string
    • ~decodeTx(encoded) ⇒ object
    • ~getSha256(str) ⇒ string
    • ~getBlock(height) ⇒ Promise
    • ~getTxsByHeight(height) ⇒ Promise
    • ~getTx(hash) ⇒ Promise
    • ~getTxs(address) ⇒ Promise
  • .alias : object
    • ~setAlias(privateKey, alias) ⇒ Promise
    • ~removeAlias(privateKey, alias) ⇒ Promise
    • ~getAliasByAddress(address) ⇒ Promise
    • ~getAddressByAlias(alias) ⇒ Promise
  • .kyc : object
    • ~requestWhitelist(privateKey, whitelistAddress) ⇒ Promise
    • ~isWhitelisted(address) ⇒ Promise
  • .faucet : object
    • ~getStatus(address) ⇒ Promise
    • ~requestCoins(privateKey, address) ⇒ Promise
  • .asset : object
    • ~createFungibleAssetClass(privateKey, classId, dynamicSupply, initialSupply, totalSupply, dataLink) ⇒ Promise
    • ~approveAssetClass(privateKey, classId, dataLink) ⇒ Promise
    • ~rejectAssetClass(privateKey, classId, dataLink) ⇒ Promise
    • ~freezeAssetClass(privateKey, classId, dataLink) ⇒ Promise
    • ~unfreezeAssetClass(privateKey, classId, dataLink) ⇒ Promise
    • ~issueFungibleAsset(privateKey, classId, owner, count) ⇒ Promise
    • ~transferFungibleAsset(privateKey, classId, count, newOwner) ⇒ Promise
    • ~burnFungibleAsset(privateKey, classId, count) ⇒ Promise
    • ~freezeFungibleAssetAccount(privateKey, classId, owner, dataLink) ⇒ Promise
    • ~unfreezeFungibleAssetAccount(privateKey, classId, owner, dataLink) ⇒ Promise
    • ~listClasses() ⇒ Promise
    • ~queryClass(classId) ⇒ Promise
    • ~queryAccount(classId, address) ⇒ Promise

mxw.events : object

Events

Kind: static namespace of mxw
Example: examples/events.js

• .events : object
  • ~onTx(fnc)
  • ~onBlock(fnc)
  • ~removeHandler(type)

events~onTx(fnc)

Set the new transaction handler.

Kind: inner method of events

events~onBlock(fnc)

Set the new block handler.

Kind: inner method of events

events~removeHandler(type)

Removes a certain handler

Kind: inner method of events

mxw.main : object

Main

Kind: static namespace of mxw
Example: examples/transfer.js

• .main : object
  • ~balance(address) ⇒ Promise
  • ~transfer(privateKey, address) ⇒ Promise
  • ~signTransfer(privateKey, address) ⇒ Promise

main~balance(address) ⇒ Promise

Returns the balance of the given address.

Kind: inner method of main
Returns: Promise - balance - Wallet balance

main~transfer(privateKey, address) ⇒ Promise

Transfer tokens from one address to another.

Kind: inner method of main
Returns: Promise - tx - Transaction result
Params: number amount - Amount of tokens

main~signTransfer(privateKey, address) ⇒ Promise

Signs a transfer transaction without relaying it.

Kind: inner method of main
Returns: Promise - tx - Transaction signature
Params: number amount - Amount of tokens

mxw.util : object

Utilities

Kind: static namespace of mxw
Example: examples/util.js

• .util : object
  • ~getAddressByPrivateKey(privateKey) ⇒ string
  • ~getAddressByPublicKey(publicKey) ⇒ string
  • ~generateKeyPair() ⇒ object
  • ~getAddressFromPublicKeyByteArray(byteArray) ⇒ string
  • ~decodeTx(encoded) ⇒ object
  • ~getSha256(str) ⇒ string
  • ~getBlock(height) ⇒ Promise
  • ~getTxsByHeight(height) ⇒ Promise
  • ~getTx(hash) ⇒ Promise
  • ~getTxs(address) ⇒ Promise

util~getAddressByPrivateKey(privateKey) ⇒ string

Returns wallet address.

Kind: inner method of util
Returns: string - address - Wallet address

util~getAddressByPublicKey(publicKey) ⇒ string

Returns wallet address.

Kind: inner method of util
Returns: string - address - Wallet address

util~generateKeyPair() ⇒ object

Generates a new private/public key pair and a wallet address.

Kind: inner method of util
Returns: object - keyPair - Generated keypair

util~getAddressFromPublicKeyByteArray(byteArray) ⇒ string

Returns wallet address.

Kind: inner method of util
Returns: string - address - Wallet address

util~decodeTx(encoded) ⇒ object

Decodes a tendermint transaction.

Kind: inner method of util
Returns: object - tx - Decoded transaction

util~getSha256(str) ⇒ string

Get SHA256 hash of a given string.

Kind: inner method of util
Returns: string - hash - Hashed string

util~getBlock(height) ⇒ Promise

Get a block at given height.

Kind: inner method of util
Returns: Promise - block - Block data

util~getTxsByHeight(height) ⇒ Promise

Get transactions at given height.

Kind: inner method of util
Returns: Promise - txs - Transactions

util~getTx(hash) ⇒ Promise

Get a single transaction by hash.

Kind: inner method of util
Returns: Promise - tx - Transaction data

util~getTxs(address) ⇒ Promise

Get transactions by wallet address.

Kind: inner method of util
Returns: Promise - txs - Transactions

mxw.alias : object

Aliasing module

Kind: static namespace of mxw
Example: examples/alias.js

• .alias : object
  • ~setAlias(privateKey, alias) ⇒ Promise
  • ~removeAlias(privateKey, alias) ⇒ Promise
  • ~getAliasByAddress(address) ⇒ Promise
  • ~getAddressByAlias(alias) ⇒ Promise

alias~setAlias(privateKey, alias) ⇒ Promise

Set an alias.

Kind: inner method of alias
Returns: Promise - tx - Transaction result

alias~removeAlias(privateKey, alias) ⇒ Promise

Remove an alias.

Kind: inner method of alias
Returns: Promise - tx - Transaction result

alias~getAliasByAddress(address) ⇒ Promise

Gets alias for a given address

Kind: inner method of alias
Returns: Promise - alias - Alias

alias~getAddressByAlias(alias) ⇒ Promise

Gets the address of an alias

Kind: inner method of alias
Returns: Promise - address - Wallet address

mxw.kyc : object

KYC module

Kind: static namespace of mxw
Example: examples/kyc.js

• .kyc : object
  • ~requestWhitelist(privateKey, whitelistAddress) ⇒ Promise
  • ~isWhitelisted(address) ⇒ Promise

kyc~requestWhitelist(privateKey, whitelistAddress) ⇒ Promise

Allows users to request whitelisting from the mock KYC service.

Kind: inner method of kyc
Returns: Promise - tx - Transaction result

kyc~isWhitelisted(address) ⇒ Promise

Checks if the wallet address is whitelisted.

Kind: inner method of kyc
Returns: Promise - whitelist - Boolean

mxw.faucet : object

Faucet module

Kind: static namespace of mxw
Example: examples/faucet.js

• .faucet : object
  • ~getStatus(address) ⇒ Promise
  • ~requestCoins(privateKey, address) ⇒ Promise

faucet~getStatus(address) ⇒ Promise

Allows users to see when they can request new coins from the faucet.

Kind: inner method of faucet
Returns: Promise - state - Query result

faucet~requestCoins(privateKey, address) ⇒ Promise

Allows users to request coins from the faucet if they have less than 100 MXW.

Kind: inner method of faucet
Returns: Promise - tx - Transaction result

mxw.asset : object

Asset module

Kind: static namespace of mxw
Example: examples/assets.js

• .asset : object
  • ~createFungibleAssetClass(privateKey, classId, dynamicSupply, initialSupply, totalSupply, dataLink) ⇒ Promise
  • ~approveAssetClass(privateKey, classId, dataLink) ⇒ Promise
  • ~rejectAssetClass(privateKey, classId, dataLink) ⇒ Promise
  • ~freezeAssetClass(privateKey, classId, dataLink) ⇒ Promise
  • ~unfreezeAssetClass(privateKey, classId, dataLink) ⇒ Promise
  • ~issueFungibleAsset(privateKey, classId, owner, count) ⇒ Promise
  • ~transferFungibleAsset(privateKey, classId, count, newOwner) ⇒ Promise
  • ~burnFungibleAsset(privateKey, classId, count) ⇒ Promise
  • ~freezeFungibleAssetAccount(privateKey, classId, owner, dataLink) ⇒ Promise
  • ~unfreezeFungibleAssetAccount(privateKey, classId, owner, dataLink) ⇒ Promise
  • ~listClasses() ⇒ Promise
  • ~queryClass(classId) ⇒ Promise
  • ~queryAccount(classId, address) ⇒ Promise

asset~createFungibleAssetClass(privateKey, classId, dynamicSupply, initialSupply, totalSupply, dataLink) ⇒ Promise

Allows users to create a new fungible asset class.

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~approveAssetClass(privateKey, classId, dataLink) ⇒ Promise

Allows users to approve a fungible asset class.

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~rejectAssetClass(privateKey, classId, dataLink) ⇒ Promise

Allows users to reject a fungible asset class.

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~freezeAssetClass(privateKey, classId, dataLink) ⇒ Promise

Allows users to freeze a fungible asset class.

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~unfreezeAssetClass(privateKey, classId, dataLink) ⇒ Promise

Allows users to unfreeze a fungible asset class.

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~issueFungibleAsset(privateKey, classId, owner, dataLink) ⇒ Promise

Allows users to issue a fungible asset.

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~transferFungibleAsset(privateKey, classId, count, newOwner) ⇒ Promise

Allows users to transfer fungible assets.

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~burnFungibleAsset(privateKey, classId, count) ⇒ Promise

Allows users to burn fungible assets.

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~freezeFungibleAssetAccount(privateKey, classId, owner, dataLink) ⇒ Promise

Allows users to freeze a fungible asset account

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~unfreezeFungibleAssetAccount(privateKey, classId, owner, dataLink) ⇒ Promise

Allows users to unfreeze a fungible asset account

Kind: inner method of asset
Returns: Promise - tx - Transaction result

asset~listClasses() ⇒ Promise

Allows users to list all available asset classes

Kind: inner method of asset
Returns: Promise - data - All asset classes

asset~queryClass(classId) ⇒ Promise

Allows users to query an asset class by class id

Kind: inner method of asset
Returns: Promise - data - Asset class

asset~queryAccount(classId, address) ⇒ Promise

Allows users to query an account with assets

Kind: inner method of asset
Returns: Promise - data - Account

Notes

• If the SDK loses a connection to one of the blockchain nodes, it'll try to reconnect to a different random node. It'll try to do this 10 times. If the reconnection is not successful, it'll throw an error.
• On MXW testnet, block time is around 5 seconds. This means that it'll take around 5 seconds until you can see commited changes when executing methods that query blockchain state (eg, API.util.balance). So, after executing a transaction, you won't see the changes immediatelly. This lag is normal and it's due to Tendermint implementation.