bitsong-js-sdk v0.1.0
This package aims to provide with an easy-to-use JS helping developers to communicate with the BitSong blockchain through its API.
This package should be an aid to any developer working on JS applications with the BitSong blockchain.
Please note that this SDK is under active development and is subject to change.
It is complemented by the following packages:
- bitsong-js-wallet to create wallet
- bitsong-js-tx create, manipulate and sign transactions
- bitsong-js-util utility functions
Install
npm install bitsong-js-sdk
Usage
Post transaction full example
import {Bitsong, SendTxParams} from "bitsong-js-sdk";
const bitsongSDK = new Bitsong();
const txParams = new SendTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
nonce: 1,
address: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
amount: 10,
coinSymbol: 'BTSG',
feeCoinSymbol: 'ASD',
gasPrice: 1,
message: 'custom message',
});
bitsongSDK.postTx(txParams)
.then((txHash) => {
alert(`Tx created: ${txHash}`);
}).catch((error) => {
const errorMessage = error.response.data.error.log;
alert(errorMessage);
});
Initialization
Create bitsongSDK
instance from Bitsong
constructor
Bitsong
accept axios config as params and return axios instance
One extra field of options object is apiType
, which is one of 'explorer'
or 'node'
. It is used to determine what type of API to use.
// by default use explorer's testnet API
const bitsongSDK = new Bitsong();
// specify explorer url
const bitsongExplorer = new Bitsong({apiType: 'explorer', baseURL: 'https://testnet.explorer.bitsong.network'});
// specify node url
const bitsongNode = new Bitsong({apiType: 'node', baseURL: 'http://node-1.testnet.bitsong.network:8841'});
bitsongSDK
instance has the following methods:
.postTx()
Post new transcation to the blockchain
Accept tx params(#Tx params constructors) object and make asynchronous request to the blockchain API.
txParams.nonce
- optional, if no nonce given, it will be requested by getNonce
automatically.
txParams.gasPrice
- 1 by default, if request failed because of low gas, it will be repeated wi
gasRetryLimit
- count of repeating request, 2 by default. If first request fails because of low gas, it will be repeated with updated gasPrice
Returns promise that resolves with sent transaction hash.
/**
* @typedef {Object} TxParams
* @property {string|Buffer} privateKey
* @property {number} [nonce] - can be omitted, will be received by `getNonce`
* @property {number} [gasPrice=1] - can be updated automatically on retry, if gasRetryLimit > 1
* @property {string} [gasCoin='BTSG']
* @property {string|Buffer} txType
* @property {Buffer} txData
* @property {string} [message]
*/
/**
* @param {TxParams} txParams
* @param {number} [gasRetryLimit=2] - number of retries, if request was failed because of low gas
* @return {Promise<string>}
*/
bitsongSDK.postTx(txParams, {gasRetryLimit: 2})
.then((txHash) => {
console.log(txHash);
// 'Mt...'
})
.catch((error) => {
// ...
})
.getNonce()
Get nonce for the new transaction from given address. Accept address string and make asynchronous request to the blockchain API. Returns promise that resolves with nonce for new tx (current address tx count + 1).
bitsongSDK.getNonce('Mx...')
.then((nonce) => {
console.log(nonce);
// 123
})
.catch((error) => {
// ...
})
.estimateCoinSell()
Estimate how much coins you will get for selling some other coins.
bitsongSDK.estimateCoinSell({
coinToSell: 'BTSG',
valueToSell: '10',
coinToBuy: 'ARTISTCOIN',
})
.then((result) => {
console.log(result.will_get, result.commission);
// 123, 0.1
})
.catch((error) => {
// ...
})
.estimateCoinBuy()
Estimate how much coins you will pay for buying some other coins.
bitsongSDK.estimateCoinBuy({
coinToBuy: 'ARTISTCOIN',
valueToBuy: '10',
coinToSell: 'BTSG',
})
.then((result) => {
console.log(result.will_pay, result.commission);
// 123, 0.1
})
.catch((error) => {
// ...
})
.estimateTxCommission()
Estimate transaction fee. Useful for transactions with gasCoin
different from base coin BTSG.
Accept string with raw signed tx.
Resolves with commission value.
bitsongSDK.estimateTxCommission()
.then((commission) => {
console.log(commission);
// 0.1
})
.catch((error) => {
// ...
})
.issueCheck()
Bitsong Checks are issued offline and do not exist in blockchain before “cashing”.
// Since issuing checks is offline, you can use it standalone without instantiating SDK
import {issueCheck} from "bitsong-js-sdk";
const check = issueCheck({
privateKey: '2919c43d5c712cae66f869a524d9523999998d51157dc40ac4d8d80a7602ce02',
passPhrase: 'pass',
nonce: 1, // must be unique for private key
coinSymbol: 'BTSG',
value: 10,
dueBlock: 999999, // at this block number check will be expired
});
console.log(check);
// => 'Mcf8a002843b9ac9ff8a4d4e5400000000000000888ac7230489e80000b841ed4e21035ad4d56901422c19e7fc867a63dcab709d6d0dcc0b6333cb7365d187519e1291bbc002189e7030dedfbbc4feb733da73f9409de4f01365dd3f5f4927011ca0507210c64b3aeb7c81a2db06204b935814c28482175dee756b1f05414d18e594a06173c7c8ee51ad76e9704a39ffc5c0ab11514d8b68efcbc8df1db194d9e296ee'
// But this method also available on the SDK instance
const check = bitsongSDK.issueCheck({...});
Tx params constructors
Get params object from constructor and pass it to postTx
method to post transaction to the blockchain
Send
import {SendTxParams} from "bitsong-js-sdk";
const txParams = new SendTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
address: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
amount: 10,
coinSymbol: 'BTSG',
feeCoinSymbol: 'ARTISTCOIN',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Sell
import {SellTxParams} from "bitsong-js-sdk";
const txParams = new SellTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
coinFrom: 'BTSG',
coinTo: 'ARTISTCOIN',
sellAmount: 10,
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Sell All
import {SellAllTxParams} from "bitsong-js-sdk";
const txParams = new SellAllTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
coinFrom: 'BTSG',
coinTo: 'ARTISTCOIN',
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Buy
import {BuyTxParams} from "bitsong-js-sdk";
const txParams = new BuyTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
coinFrom: 'BTSG',
coinTo: 'ARTISTCOIN',
buyAmount: 10,
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Create Coin
import {CreateCoinTxParams} from "bitsong-js-sdk";
const txParams = new CreateCoinTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
coinName: 'Artist Coin',
coinSymbol: 'ARTISTCOIN',
initialAmount: 5,
crr: 10,
initialReserve: 20,
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Declare Candidacy
import {DeclareCandidacyTxParams} from "bitsong-js-sdk";
const txParams = new DeclareCandidacyTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
address: 'Mx7633980c000139dd3bd24a3f54e06474fa941e16',
publicKey: 'Mpf9e036839a29f7fba2d5394bd489eda927ccb95acc99e506e688e4888082b3a3',
commission: 10,
coinSymbol: 'BTSG',
stake: 100,
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Delegate
import {DelegateTxParams} from "bitsong-js-sdk";
const txParams = new DelegateTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
publicKey: 'Mpf9e036839a29f7fba2d5394bd489eda927ccb95acc99e506e688e4888082b3a3',
coinSymbol: 'BTSG',
stake: 100,
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Unbond
import {UnbondTxParams} from "bitsong-js-sdk";
const txParams = new UnbondTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
publicKey: 'Mpf9e036839a29f7fba2d5394bd489eda927ccb95acc99e506e688e4888082b3a3',
coinSymbol: 'BTSG',
stake: 100,
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Set Candidate On
import {SetCandidateOnTxParams} from "bitsong-js-sdk";
const txParams = new SetCandidateOnTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
publicKey: 'Mpf9e036839a29f7fba2d5394bd489eda927ccb95acc99e506e688e4888082b3a3',
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Set Candidate Off
import {SetCandidateOffTxParams} from "bitsong-js-sdk";
const txParams = new SetCandidateOffTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
publicKey: 'Mpf9e036839a29f7fba2d5394bd489eda927ccb95acc99e506e688e4888082b3a3',
feeCoinSymbol: 'ASD',
message: 'custom message',
});
bitsongSDK.postTx(txParams);
Redeem Check
import {RedeemCheckTxParams} from "bitsong-js-sdk";
const txParams = new RedeemCheckTxParams({
privateKey: '5fa3a8b186f6cc2d748ee2d8c0eb7a905a7b73de0f2c34c5e7857c3b46f187da',
check: 'Mcf8a002843b9ac9ff8a4d4e5400000000000000888ac7230489e80000b841ed4e21035ad4d56901422c19e7fc867a63dcab709d6d0dcc0b6333cb7365d187519e1291bbc002189e7030dedfbbc4feb733da73f9409de4f01365dd3f5f4927011ca0507210c64b3aeb7c81a2db06204b935814c28482175dee756b1f05414d18e594a06173c7c8ee51ad76e9704a39ffc5c0ab11514d8b68efcbc8df1db194d9e296ee',
password: '123',
feeCoinSymbol: 'BTSG',
});
bitsongSDK.postTx(txParams);
Prepare Signed Transaction
Used under the hood of PostTx, accepts txParams
object as argument
import {prepareSignedTx} from 'bitsong-js-sdk';
const tx = prepareSignedTx(txParams);
console.log('signed tx', tx.serialize().toString('hex'));
// get actual nonce first
bitsongSDK.getNonce('Mx...')
.then((nonce) => {
const tx = prepareSignedTx({...txParams, nonce});
console.log('signed tx', tx.serialize().toString('hex'));
});
License
MIT License
5 years ago