minter-js-sdk

v0.46.2

Published

a year ago

JS SDK for Minter Blockchain

Downloads

267

0High
0Medium
0Low

shrpne

danil-lashin

minter blockchain sdk

This package aims to provide an easy-to-use JS helping developers communicate with the Minter blockchain through its API.

This package should aid any developer building JS applications on top of the Minter blockchain.

Please note that this SDK is under active development and subject to change.

NOTE: since 0.34.0, SDK supports only v2 versions of node and gate APIs

It is complemented by the following packages:

minterjs-wallet for BIP39 mnemonic phrases, private keys, and addresses
minterjs-util for utility functions

Contents:

Installation

npm install minter-js-sdk

import {Minter, prepareLink} from "minter-js-sdk";

const minter = new Minter({/* ...options, see Usage */});
const link = prepareLink(/* ... */)

or from browser

<script src="https://unpkg.com/minter-js-sdk"></script>
<script>
const minter = new minterSDK.Minter({/* ...options, see Usage */});
const link = minterSDK.prepareLink(/* ... */)
</script>

Usage

Post transaction full example

import {Minter, TX_TYPE} from "minter-js-sdk";

const minter = new Minter({apiType: 'node', baseURL: 'https://node-api.testnet.minter.network/v2/'});
const txParams = {
    nonce: 1,
    chainId: 1,
    type: TX_TYPE.SEND,
    data: {
        to: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
        value: 10,
        coin: 0, // coin id
    },
    gasCoin: 0, // coin id
    gasPrice: 1,
    payload: 'custom message',
};

minter.postTx(txParams, {seedPhrase: 'exercise fantasy smooth enough ...'})
    .then((txHash) => {
        // WARNING
        // If you use minter-node api, successful response would mean that tx just got in mempool but is not on the blockchain yet
        // You have to wait for it to be included in the upcoming block
        // You can use gate api instead, which returns successful response only after tx has appeared on the blockchain
        // WARNING #2 
        // If tx has been included in the block, it may still have failed status
        // Verify that tx.code is `0` to ensure its success
        alert(`Tx created: ${txHash}`);
    }).catch((error) => {
        const errorMessage = error.response.data.error.message
        alert(errorMessage);
    });

Post transaction using SDK features

import {Minter, TX_TYPE} from "minter-js-sdk";

const minter = new Minter({apiType: 'node', baseURL: 'https://node-api.testnet.minter.network/v2/'});
const txParams = {
    // no `nonce` specified, it will be fetched automatically
    // no `gasPrice` specified, "1" will be used by default and in case of error, request will be retried with auto-corrected value
    chainId: 1,
    type: TX_TYPE.SEND,
    data: {
        to: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
        value: 10,
        coin: 'BIP', // coin symbol
    },
    gasCoin: 'MYCOIN', // coin symbol
};

// coin symbols in txParams will be replaced automatically with coin ids
minter.postTx(newTxParams, {
    // seedPhrase can be used to sign transaction instead of privateKey
    seedPhrase: 'air model item valley auction bullet crisp always erosion paper orient fog',
})
    .then((txHash) => {
      // WARNINGs for minter-node api users:
      // #1
      // Successful response would mean that tx just got in mempool but is not on the blockchain yet
      // You have to wait for it to be included in the upcoming block
      // #2 
      // If tx has been included in the block, it may still have failed status
      // Verify that tx.code is `0` to ensure its success
      // Gate api users not affected:
      // Gate will return successful response only after tx has appeared on the blockchain
      // Gate also returns tx data in the response, so SDK will check tx.code automatically and reject promise for non-zero codes
        alert(`Tx created: ${txHash}`);
    }).catch((error) => {
        const errorMessage = error.response.data.error.message
        alert(errorMessage);
    });

SDK instance

Create minter SDK instance from Minter constructor. It contains methods to communicate with API. Minter will accept axios config as params and return axios instance.

One extra field of options object is apiType, which takes either 'gate' or 'node'. It is used to determine which type of API to use.

// specify gate url
const minterGate = new Minter({chainId: 2, apiType: 'gate', baseURL: 'https://gate-api.minter.network/api/v2/'});
// specify node url
const minterNode = new Minter({chainId: 2, apiType: 'node', baseURL: 'https://node-api.testnet.minter.network/v2/'});

Minter constructor has the following options:

apiType: 'gate' or 'node'
baseURL: API URL
chainId: default chain ID, used if no chainId is specified in tx params. 1 = mainnet, 2 = testnet

minter SDK instance has the following methods:

.postTx()

Post new transaction to blockchain.
Accepts the tx params object and makes an asynchronous request to the blockchain API.

txParams.nonce - optional, if no nonce is given, it will be requested by getNonce automatically
txParams.gasPrice - fee multiplier, 1 by default. Should be equal to or greater than mempool's current min gas price
gasRetryLimit - count of repeating request, 2 by default. If the first request fails because of low gas, it will be repeated with an updated gasPrice
mempoolRetryLimit - count of repeating request, 0 by default. If the first request fails because of the "Tx from address already exists in mempool" error, it will be repeated in 5 seconds (average block time), trying to put it into the new block

Returns promise that resolves with:

sent transaction data included in a block (from gate),
or transaction hash included in mempool (from node).

Please note: always verify that transactions you send have no errors (tx in a block should have code: 0). Otherwise, they will not be executed.

/**
 * @typedef {Object} TxParams
 * @property {number} [nonce] - can be omitted, will be received by `getNonce`
 * @property {number} [chainId=1] - 1 = mainnet, 2 = testnet
 * @property {number} [gasPrice=1] - can be updated automatically on retry if gasRetryLimit > 0
 * @property {string} [gasCoin='BIP']
 * @property {string|TX_TYPE|Buffer} type
 * @property {Object|Buffer|TxData} data
 * @property {string} [payload]
 * @property {number} [signatureType=1]
 * @property {number} [signatureData] - can be signed automatically if `privateKey` or `seedPhrase` passed
 */

/**
* @param {TxParams} txParams
* @param {PostTxOptions} txOptions
* @param {number} [txOptions.gasRetryLimit=2] - number of retries if request failed because of low gas
* @param {number} [txOptions.nonceRetryLimit=0] - number of retries if request failed because of invalid nonce
* @param {number} [txOptions.mempoolRetryLimit=0] - number of retries if request failed with error "Tx from address already exists in mempool"
* @param {string|Buffer} [txOptions.seedPhrase] - alternative to txOptions.privateKey
* @param {string|Buffer} [txOptions.privateKey] - to sign tx or get nonce or to make proof for redeemCheck tx
* @param {string} [txOptions.address] - to get nonce (useful for multi-signatures) or to make proof for redeemCheck tx
* @param {ByteArray} [txOptions.password] - to make proof for RedeemCheckTxData
* @param {AxiosRequestConfig} [axiosOptions] - for main request (send tx hash)
* @param {AxiosRequestConfig} [extraAxiosOptions] - for secondary requests (nonce and coin IDs)
* @return {Promise<NodeTransaction|{hash: string}>}
*/
minter.postTx(txParams, {seedPhrase: '...', gasRetryLimit: 2, mempoolRetryLimit: 0})
    .then((tx) => {
        console.log(tx.hash);
        // 'Mt...'
        // Check here that tx in block has no errors (code === 0)
    });

.postSignedTx()

Post new transaction to blockchain.
Accepts signed tx string or Buffer and makes an asynchronous request to the blockchain API.
Returns promise that resolves with:

sent transaction data included in a block (from gate),
or transaction hash included in mempool (from node).

/**
* @param {string|Buffer} signedTx
* @param {AxiosRequestConfig} [axiosOptions]
* @return {Promise<NodeTransaction|{hash: string}>}
*/
minter.postSignedTx('0xf8920102018a4d4e540000000000000001aae98a4d4e5400000000...')
    .then((tx) => {
        console.log(tx.hash);
        // 'Mt...'
    });

.getNonce()

Get nonce for the new transaction from a given address.
Accepts address string and makes an asynchronous request to the blockchain API.
Returns promise that resolves with nonce for the new tx (current address tx count + 1).

minter.getNonce('Mx...')
    .then((nonce) => {
        console.log(nonce);
        // 123
    });

.ensureNonce()

Ensure nonce for the tx params. You should provide an address for which you want to get nonce. Accepts seedPhrase or privateKey as well—the address will be derived from either of them.

/**
 * @param {MinterApiInstance} apiInstance
 * @param {TxParams} txParams
 * @param {Object} txOptions
 * @param {string} [txOptions.seedPhrase]
 * @param {ByteArray} [txOptions.privateKey]
 * @param {string} [txOptions.address]
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<number>}
 */
minter.ensureNonce(txParams, {seedPhrase: '...'})
    .then((nonce) => {
        console.log(nonce);
        // 123
    });

.getMinGasPrice()

Get current minimum gas price.

minter.getMinGasPrice()
    .then((gasPrice) => {
        console.log(gasPrice);
        // 1
    });

.getCoinInfo()

Get coin info by coin ID or symbol.

/**
 * @param {string|number} coin - coind ID or symbol 
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<CoinInfo>}
 */
minter.getCoinInfo(coin)
    .then((coinInfo) => {
        console.log(coinInfo.id, coinInfo.symbol);
    });

.getCoinId()

Get coin ID by coin symbol or array of symbols. Uses getCoinInfo() under the hood.

/**
 * @param {string|Array<string>} symbol - coin symbol or array of symbols
 * @param {number} [chainId]
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<number|Array<number>>}
 */
minter.getCoinId('MNT')
    .then((id) => {
        console.log(id);
        // 0
    });

minter.getCoinId(['MNT', 'MYCOIN'])
    .then((ids) => {
          console.log(ids);
          // [0, 123]
    });

.getCoinSymbol()

Get coin symbol by coin ID or array of IDs. Uses getCoinInfo() under the hood.

/**
 * @param {number|string|Array<number|string>} id - coin ID or array of IDs
 * @param {number} [chainId]
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<string|Array<string>>}
 */
minter.getCoinSymbol(0)
    .then((symbol) => {
        console.log(symbol);
        // 0
    });

minter.getCoinSymbol(['0', '123'])
    .then((symbols) => {
          console.log(symbols);
          // ['MNT', 'MYCOIN']
    });

.replaceCoinSymbol()

Replace coin symbols with coin IDs in txParams object. Mutates original object.

/**
 * @param {TxParams} txParams
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<TxParams>}
 */
const txParams = {
    type: 1,
    data: {
        to: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
        value: 10,
        coin: 'BIP',
    },
    gasCoin: 'MYCOIN',
};
minter.replaceCoinSymbol(txParams)
    .then((newTxParams) => {
        console.log(newTxParams);
        // {
        //     type: 1,
        //     data: {
        //         to: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
        //         value: 10,
        //         coin: 0,
        //     },
        //     gasCoin: 1234,
        // }
    });

.replaceCoinId()

Replace coin IDs with coin symbols in txParams object. Mutates original object.

/**
 * @param {TxParams} txParams
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<TxParams>}
 */
const txParams = {
    type: 1,
    data: {
        to: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
        value: 10,
        coin: 0,
    },
    gasCoin: 123,
};
minter.replaceCoinId(txParams)
    .then((newTxParams) => {
        console.log(newTxParams);
        // {
        //     type: 1,
        //     data: {
        //         to: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
        //         value: 10,
        //         coin: 'BIP',
        //     },
        //     gasCoin: 'MYCOIN',
        // }
    });

.replaceCoinSymbolByPath()

Replace coin symbols with coin IDs in arbitrary object by path list.

const params = {
    foo: {
        bar: {
            coin: 'BIP',
        },
    },
    gasCoin: 'MYCOIN',
};
/**
 * @param {Object} params
 * @param {Array<string>} pathList
 * @param {number} [chainId]
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<TxParams>}
 */
minter.replaceCoinSymbolByPath(params, ['gasCoin', 'foo.bar.coin'])
    .then((newParams) => {
        console.log(newParams);
        // {
        //     foo: {
        //         bar: {
        //             coin: 0,
        //         },
        //     },
        //     gasCoin: 1234,
        // }
    });

.replaceCoinIdByPath()

Replace coin IDs with coin symbols in arbitrary object by path list.

const params = {
    foo: {
        bar: {
            coin: 0,
        },
    },
    gasCoin: 1234,
};
/**
 * @param {Object} params
 * @param {Array<string>} pathList
 * @param {number} [chainId]
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<TxParams>}
 */
minter.replaceCoinIdByPath(params, ['gasCoin', 'foo.bar.coin'])
    .then((newParams) => {
        console.log(newParams);
        // {
        //     foo: {
        //         bar: {
        //             coin: 'BIP',
        //         },
        //     },
        //     gasCoin: 'MYCOIN',
        // }
    });

.estimateCoinBuy()

Estimate how many coins you will pay to buy some other coins.

/**
 * @param {Object} params
 * @param {string|number} params.coinToBuy - ID or symbol of the coin to buy
 * @param {string|number} params.valueToBuy
 * @param {string|number} params.coinToSell - ID or symbol of the coin to sell
 * @param {ESTIMATE_SWAP_TYPE} [params.swapFrom] - estimate from pool, bancor, or optimal
 * @param {Array<number>} [params.route] - IDs of intermediate coins for pool swaps
 * @param {string|number} [params.gasCoin]
 * @param {string|number} [params.coinCommission] - gasCoin alias
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<EstimateBuyResult>}
 */

/**
 * @typedef {Object} EstimateBuyResult
 * @property {number|string} will_pay - amount of coinToSell
 * @property {number|string} commission - amount of coinToSell to pay fee
 * @property {"pool"|"bancor"} swap_from
 */

minter.estimateCoinBuy({
    coinToBuy: 'MYCOIN',
    valueToBuy: 10,
    coinToSell: 'BIP',
})
    .then((result) => {
        console.log(result.will_pay, result.commission, result.swap_from);
        // 123, 0.1, 'pool'
    });

.estimateCoinSell()

Estimate how many coins you will get for selling some other coins.

/**
 * @param {Object} params
 * @param {string|number} params.coinToSell - ID or symbol of the coin to sell
 * @param {string|number} params.valueToSell
 * @param {string|number} params.coinToBuy - ID or symbol of the coin to buy
 * @param {ESTIMATE_SWAP_TYPE} [params.swapFrom] - estimate pool swap
 * @param {Array<string|number>} [params.route] - IDs of intermediate coins for pool swaps
 * @param {string|number} [params.gasCoin]
 * @param {string|number} [params.coinCommission] - gasCoin alias
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<EstimateSellResult>}
 */

/**
 * @typedef {Object} EstimateSellResult
 * @property {number|string} will_get - amount of coinToBuy
 * @property {number|string} commission - amount of coinToSell to pay fee
 * @property {"pool"|"bancor"} swap_from
 */

minter.estimateCoinSell({
    coinToSell: 'BIP',
    valueToSell: 10,
    coinToBuy: 'MYCOIN',
})
    .then((result) => {
        console.log(result.will_get, result.commission, result.swap_from);
        // 123, 0.1, 'pool'
    });

.estimateCoinSellAll()

Estimate how many coins you will get for selling some other coins by SellAll transaction.

/**
 * @param {Object} params
 * @param {string|number} params.coinToSell - ID or symbol of the coin to sell
 * @param {string|number} params.valueToSell
 * @param {string|number} params.coinToBuy - ID or symbol of the coin to buy
 * @param {ESTIMATE_SWAP_TYPE} [params.swapFrom] - estimate pool swap
 * @param {Array<string|number>} [params.route] - IDs of intermediate coins for pool swaps
 * @param {string|number} [params.gasPrice]
 * @param {AxiosRequestConfig} [axiosOptions]
 * @return {Promise<EstimateSellAllResult>}
 */

/**
 * @typedef {Object} EstimateSellAllResult
 * @property {number|string} will_get - amount of coinToBuy
 * @property {"pool"|"bancor"} swap_from
 */

minter.estimateCoinSellAll({
    coinToSell: 'BIP',
    valueToSell: 10,
    coinToBuy: 'MYCOIN',
})
    .then((result) => {
        console.log(result.will_get, result.swap_from);
        // 123, 'pool'
    });

.estimateTxCommission()

Estimate transaction fee.

First argument txParams can be a TxParams object or raw signed tx hex string.
Second options argument accepts needGasCoinFee, needBaseCoinFee, and needPriceCoinFee fields to customize estimate behaviour. Resolves with object containing fee.

needGasCoinFee

FEE_PRECISION_SETTING.PRECISE (default) - make direct call to estimate_tx_commission/{tx} api method and return commission field
FEE_PRECISION_SETTING.IMPRECISE - if gasCoin same as baseCoin and baseCoinFee is defined (otherwise upgrades to PRECISE), then it makes several requests for blockchain data and approximately calculates the fee relying on that data, but don't take limit orders into account.
Pros: if used with request caching then when users input payload, the fee could be calculated dynamically without extra requests for each payload character.
Cons: less accurate because don't consider limit orders, makes more requests for a single estimate.
FEE_PRECISION_SETTING.OMIT - omits commission field

needBaseCoinFee

FEE_PRECISION_SETTING.IMPRECISE - works only if priceCoinFee is defined, calculates basing on pool data, inaccurate because don't consider limit orders
FEE_PRECISION_SETTING.OMIT (default) - omits baseCoinComission field

needPriceCoinFee

FEE_PRECISION_SETTING.PRECISE - make an API call to the price_commissions method and returns priceCoinCommission and commissionPriceData fields
FEE_PRECISION_SETTING.OMIT (default) - omits priceCoinCommission

Tx params

Tx params object that is passed to postTx or prepareSignedTx methods to post transaction to blockchain.

nonce - unique number for each address, used to prevent transaction replication, starts from 1
chainId - id of the network (1 = mainnet, 2 = testnet)
gasPrice - fee multiplier, should be equal to or greater than current mempool min gas price
gasCoin - coin to pay fee
type - type of transaction (see below)
data - data of transaction (depends on transaction type)
payload (arbitrary bytes) - arbitrary user-defined bytes
serviceData - reserved field
signatureType - 1 = single-signed, 2 = multi-signed
signatureData - digital signature of transaction

/**
 * @typedef {Object} TxParams
 * @property {number} [nonce]
 * @property {number} [chainId=1]
 * @property {number} [gasPrice=1]
 * @property {number|string} [gasCoin='0']
 * @property {string|Buffer|TX_TYPE} type
 * @property {Buffer|TxData|Object} data
 * @property {string} [payload]
 * @property {number} [signatureType]
 * @property {ByteArray|{multisig: ByteArray, signatures: Array<ByteArray>}} [signatureData]
 */

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Installation

Usage

SDK instance

.postTx()

.postSignedTx()

.getNonce()

.ensureNonce()

.getMinGasPrice()

.getCoinInfo()

.getCoinId()

.getCoinSymbol()

.replaceCoinSymbol()

.replaceCoinId()

.replaceCoinSymbolByPath()

.replaceCoinIdByPath()

.estimateCoinBuy()

.estimateCoinSell()

.estimateCoinSellAll()

.estimateTxCommission()

Tx params

Transaction types

Send

Multisend

Buy

Sell

Sell all

Buy from swap pool

Sell to swap pool

Sell all to swap pool

Add limit order

Remove limit order

Create pool

Add liquidity to pool

Remove liquidity from pool

Create coin

Recreate coin

Create token

Recreate token

Edit ticker owner

Mint token

Burn token

Declare candidacy

Edit candidate

Edit candidate public Key

Edit candidate commission

Delegate

Unbond

Move stake

Lock stake

Set candidate on

Set candidate off

Set halt block

Vote for commission price

Vote for network update

Price vote

Redeem check

Lock

Create multisig

Edit multisig

Transaction

Prepare transaction

Prepare single-signed transaction

Make signature

Multi-signatures

Decode transaction

Minter Check

issueCheck()

decodeCheck()

Minter Link

prepareLink()

decodeLink()

Minter Wallet

License

`issueCheck()`

`decodeCheck()`

`prepareLink()`

`decodeLink()`