mxw-api

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

Param	Type	Description
fnc	function	Function that will be called on every new transaction (format: (data) => {})

events~onBlock(fnc)

Set the new block handler.

Kind: inner method of events

Param	Type	Description
fnc	function	Function that will be called on every new block (format: (data) => {})

events~removeHandler(type)

Removes a certain handler

Kind: inner method of events

Param	Type	Description
type	string	Handler type ('tx'

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

Param	Type	Description
address	string	Address of the wallet

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

Param	Type	Description
privateKey	string	Private key of the wallet from which we're transfering tokens
address	string	Address of the wallet to which we're transfering 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

Param	Type	Description
privateKey	string	Private key of the wallet from which we're transfering tokens
address	string	Address of the wallet to which we're transfering 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

Param	Type	Description
privateKey	string	Wallet's private key

util~getAddressByPublicKey(publicKey) ⇒ string

Returns wallet address.

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

Param	Type	Description
publicKey	string	Wallet's public key

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

Param	Type	Description
byteArray	Buffer	Wallet's public key as a byte array

util~decodeTx(encoded) ⇒ object

Decodes a tendermint transaction.

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

Param	Type	Description
encoded	string	Base64 encoded transaction

util~getSha256(str) ⇒ string

Get SHA256 hash of a given string.

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

Param	Type	Description
str	string	Arbitrary string

util~getBlock(height) ⇒ Promise

Get a block at given height.

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

Param	Type	Description
height	number	Block height

util~getTxsByHeight(height) ⇒ Promise

Get transactions at given height.

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

Param	Type	Description
height	number	Block height

util~getTx(hash) ⇒ Promise

Get a single transaction by hash.

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

Param	Type	Description
hash	string	Transaction hash

util~getTxs(address) ⇒ Promise

Get transactions by wallet address.

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

Param	Type	Description
address	string	Wallet address

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

Param	Type	Description
privateKey	string	Wallet's private key
alias	string	An alias

alias~removeAlias(privateKey, alias) ⇒ Promise

Remove an alias.

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

Param	Type	Description
privateKey	string	Wallet's private key
alias	string	An alias

alias~getAliasByAddress(address) ⇒ Promise

Gets alias for a given address

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

Param	Type	Description
address	string	Address of a wallet

alias~getAddressByAlias(alias) ⇒ Promise

Gets the address of an alias

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

Param	Type	Description
alias	string	An alias

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

Param	Type	Description
privateKey	string	Private key of the KYC provider
whitelistAddress	string	Address that we're whitelisting

kyc~isWhitelisted(address) ⇒ Promise

Checks if the wallet address is whitelisted.

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

Param	Type	Description
address	string	Address of a wallet

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

Param	Type	Description
address	string	Address of the wallet

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

Param	Type	Description
privateKey	string	Private key of the wallet that's requesting tokens
address	string	Address of the wallet that's receiving tokens (optional)

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

Param	Type	Description
privateKey	string	Private key of the wallet that's creating the new fungible asset class
classId	string	Id of the new asset class
dynamicSupply	bool	A flag that determines if there will be a dynamic supply
initialSupply	number	Initial supply of the new asset class
totalSupply	number	Total supply of the new asset class
dataLink	string	Data link

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

Allows users to approve a fungible asset class.

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

Param	Type	Description
privateKey	string	Private key of the wallet that's approving the asset class
classId	string	Id of the asset class
dataLink	string	Data link

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

Allows users to reject a fungible asset class.

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

Param	Type	Description
privateKey	string	Private key of the wallet that's rejecting the asset class
classId	string	Id of the asset class
dataLink	string	Data link

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

Allows users to freeze a fungible asset class.

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

Param	Type	Description
privateKey	string	Private key of the wallet that's freezing the asset class
classId	string	Id of the asset class
dataLink	string	Data link

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

Allows users to unfreeze a fungible asset class.

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

Param	Type	Description
privateKey	string	Private key of the wallet that's unfreezing the asset class
classId	string	Id of the asset class
dataLink	string	Data link

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

Allows users to issue a fungible asset.

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

Param	Type	Description
privateKey	string	Private key of the wallet that's issuing the asset
classId	string	Id of the asset class
owner	string	Owner of the issued asset
count	number	Number of assets

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

Allows users to transfer fungible assets.

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

Param	Type	Description
privateKey	string	Private key of the wallet that's transferring the asset
classId	string	Id of the asset class
count	number	Number of assets
newOwner	string	New owner of the issued asset

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

Allows users to burn fungible assets.

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

Param	Type	Description
privateKey	string	Private key of the wallet that's burning the asset
classId	string	Id of the asset class
count	number	Number of assets

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

Param	Type	Description
privateKey	string	Private key of the wallet that's freezing the asset account
classId	string	Id of the asset class
owner	string	Owner of the asset account
dataLink	string	Data link

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

Param	Type	Description
privateKey	string	Private key of the wallet that's unfreezing the asset account
classId	string	Id of the asset class
owner	string	Owner of the asset account
dataLink	string	Data link

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

Param	Type	Description
classId	string	Id of the asset class

asset~queryAccount(classId, address) ⇒ Promise

Allows users to query an account with assets

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

Param	Type	Description
classId	string	Id of the asset class
address	string	Account address

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.