SDK for MXW blockchain
Getting started
mxw-api
package
1. Install 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
-
.main :
object
-
~balance(address) β
Promise
-
~transfer(privateKey, address) β
Promise
-
~signTransfer(privateKey, address) β
Promise
-
~balance(address) β
-
.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
-
~getAddressByPrivateKey(privateKey) β
-
.alias :
object
-
~setAlias(privateKey, alias) β
Promise
-
~removeAlias(privateKey, alias) β
Promise
-
~getAliasByAddress(address) β
Promise
-
~getAddressByAlias(alias) β
Promise
-
~setAlias(privateKey, alias) β
-
.kyc :
object
-
~requestWhitelist(privateKey, whitelistAddress) β
Promise
-
~isWhitelisted(address) β
Promise
-
~requestWhitelist(privateKey, whitelistAddress) β
-
.faucet :
object
-
~getStatus(address) β
Promise
-
~requestCoins(privateKey, address) β
Promise
-
~getStatus(address) β
-
.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
-
~createFungibleAssetClass(privateKey, classId, dynamicSupply, initialSupply, totalSupply, dataLink) β
-
.events :
object
mxw.events : Events
Kind: static namespace of mxw
Example: examples/events.js
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' |
object
mxw.main : Main
Kind: static namespace of mxw
Example: examples/transfer.js
-
.main :
object
-
~balance(address) β
Promise
-
~transfer(privateKey, address) β
Promise
-
~signTransfer(privateKey, address) β
Promise
-
~balance(address) β
Promise
main~balance(address) β 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 |
Promise
main~transfer(privateKey, address) β 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 |
Promise
main~signTransfer(privateKey, address) β 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 |
object
mxw.util : 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
-
~getAddressByPrivateKey(privateKey) β
string
util~getAddressByPrivateKey(privateKey) β Returns wallet address.
Kind: inner method of util
Returns: string
- address - Wallet address
Param | Type | Description |
---|---|---|
privateKey | string |
Wallet's private key |
string
util~getAddressByPublicKey(publicKey) β Returns wallet address.
Kind: inner method of util
Returns: string
- address - Wallet address
Param | Type | Description |
---|---|---|
publicKey | string |
Wallet's public key |
object
util~generateKeyPair() β Generates a new private/public key pair and a wallet address.
Kind: inner method of util
Returns: object
- keyPair - Generated keypair
string
util~getAddressFromPublicKeyByteArray(byteArray) β 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 |
object
util~decodeTx(encoded) β Decodes a tendermint transaction.
Kind: inner method of util
Returns: object
- tx - Decoded transaction
Param | Type | Description |
---|---|---|
encoded | string |
Base64 encoded transaction |
string
util~getSha256(str) β Get SHA256 hash of a given string.
Kind: inner method of util
Returns: string
- hash - Hashed string
Param | Type | Description |
---|---|---|
str | string |
Arbitrary string |
Promise
util~getBlock(height) β Get a block at given height.
Kind: inner method of util
Returns: Promise
- block - Block data
Param | Type | Description |
---|---|---|
height | number |
Block height |
Promise
util~getTxsByHeight(height) β Get transactions at given height.
Kind: inner method of util
Returns: Promise
- txs - Transactions
Param | Type | Description |
---|---|---|
height | number |
Block height |
Promise
util~getTx(hash) β Get a single transaction by hash.
Kind: inner method of util
Returns: Promise
- tx - Transaction data
Param | Type | Description |
---|---|---|
hash | string |
Transaction hash |
Promise
util~getTxs(address) β Get transactions by wallet address.
Kind: inner method of util
Returns: Promise
- txs - Transactions
Param | Type | Description |
---|---|---|
address | string |
Wallet address |
object
mxw.alias : 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
-
~setAlias(privateKey, alias) β
Promise
alias~setAlias(privateKey, alias) β 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 |
Promise
alias~removeAlias(privateKey, alias) β 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 |
Promise
alias~getAliasByAddress(address) β Gets alias for a given address
Kind: inner method of alias
Returns: Promise
- alias - Alias
Param | Type | Description |
---|---|---|
address | string |
Address of a wallet |
Promise
alias~getAddressByAlias(alias) β Gets the address of an alias
Kind: inner method of alias
Returns: Promise
- address - Wallet address
Param | Type | Description |
---|---|---|
alias | string |
An alias |
object
mxw.kyc : KYC module
Kind: static namespace of mxw
Example: examples/kyc.js
-
.kyc :
object
-
~requestWhitelist(privateKey, whitelistAddress) β
Promise
-
~isWhitelisted(address) β
Promise
-
~requestWhitelist(privateKey, whitelistAddress) β
Promise
kyc~requestWhitelist(privateKey, whitelistAddress) β 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 |
Promise
kyc~isWhitelisted(address) β 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 |
object
mxw.faucet : Faucet module
Kind: static namespace of mxw
Example: examples/faucet.js
-
.faucet :
object
-
~getStatus(address) β
Promise
-
~requestCoins(privateKey, address) β
Promise
-
~getStatus(address) β
Promise
faucet~getStatus(address) β 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 |
Promise
faucet~requestCoins(privateKey, address) β 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) |
object
mxw.asset : 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
-
~createFungibleAssetClass(privateKey, classId, dynamicSupply, initialSupply, totalSupply, dataLink) β
Promise
asset~createFungibleAssetClass(privateKey, classId, dynamicSupply, initialSupply, totalSupply, dataLink) β 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 |
Promise
asset~approveAssetClass(privateKey, classId, dataLink) β 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 |
Promise
asset~rejectAssetClass(privateKey, classId, dataLink) β 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 |
Promise
asset~freezeAssetClass(privateKey, classId, dataLink) β 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 |
Promise
asset~unfreezeAssetClass(privateKey, classId, dataLink) β 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 |
Promise
asset~issueFungibleAsset(privateKey, classId, owner, dataLink) β 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 |
Promise
asset~transferFungibleAsset(privateKey, classId, count, newOwner) β 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 |
Promise
asset~burnFungibleAsset(privateKey, classId, count) β 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 |
Promise
asset~freezeFungibleAssetAccount(privateKey, classId, owner, dataLink) β 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 |
Promise
asset~unfreezeFungibleAssetAccount(privateKey, classId, owner, dataLink) β 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 |
Promise
asset~listClasses() β Allows users to list all available asset classes
Kind: inner method of asset
Returns: Promise
- data - All asset classes
Promise
asset~queryClass(classId) β 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 |
Promise
asset~queryAccount(classId, address) β 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.