UniChain-JS API
The following describes the UinChain-JS, a Javascript library for working with UniChain network.
Set up
Install UniChain JS
npm install @uniworld/unichain-js
Construct the library
const Unichain = require('@uniworld/unichain-js')
const host = 'https://testnet-node.unichain.world' // or your local full node, mainet full node ...
const relayHost = 'https://testnet-relay-node.unichain.world' // or your local relay node, mainet relay node ...
const unichain = new Unichain({fullHost: host, solidityNode: relayHost})
Check if the node is connected
unichain.isConnected((err, data) => {
if (err) console.log('Error: ', err)
else console.log('UniChain node is connected, info:', data)
})
Static method
Validate an address
const address = 'UZQWseP7WEN1R3nukDtLksukSduCvB19ef'
const result = Unichain.isAddress(address)
console.log(result) //true
Calculate address from private key
const privateKey = 'ba63ac2b53976497386410adb85b7cd563e6316b5d47c97def69275635b150d1'
const address = unichain.address.fromPrivateKey(privateKey)
console.log(address)
//UjYDcuewthU4HL9t5EiPfhWNuAzHAXuHsU
Convert address to hex format
const address = 'UjYDcuewthU4HL9t5EiPfhWNuAzHAXuHsU'
const hexAddress = unichain.address.toHex(address)
console.log(hexAddress)
//44ec71b063e96fee1777f973e9f8f41852ddc249b2
Convert address from hex format
const hexAddress = '44ec71b063e96fee1777f973e9f8f41852ddc249b2'
const address = unichain.address.fromHex(hexAddress)
console.log(address)
//UjYDcuewthU4HL9t5EiPfhWNuAzHAXuHsU
Convert UTF8 string to hex format
const utf8String = 'MyToken'
const hexString = unichain.fromUtf8(utf8String)
console.log(hexString)
//0x4d79546f6b656e
Convert hex string to UTF8 format
const hexString = '0x4d79546f6b656e'
const utf8String = unichain.toUtf8(hexString)
console.log(utf8String)
//MyToken
Convert to UNW from Ginza
const ginzaAmount = 1000000
const unwAmount = unichain.fromGinza(ginzaAmount)
console.log(unwAmount)
//1
Convert to Ginza from UNW
const unwAmount = 5
const ginzaAmount= unichain.toGinza(unwAmount)
console.log(ginzaAmount)
//5000000
Transaction builder
This module is for building the raw transaction such as transfer balance, vote for witness, purchase for token or lock/unlock balance ... The transactions are actually built from connected node and need to be signed before broadcasting to blockchain network
Create token
function createToken(tokenSpec, ownerAddress)
Full example of creating a new token
const privateKey = 'your_private_key'
const ownerAddress = 'your_address'
const tokenSpec = {
name: 'TestToken',
abbreviation: 'TEST',
description: 'Test Token',
url: 'https://testtoken.org',
totalSupply: 1000000000000, //precision = 6 => 1.000.000 Token
unxRatio: 1, // How much UNX will `tokenRatio` cost?
tokenRatio: 1, // How many tokens will `unxRatio` afford?
saleStart: Date.now() + 5*1000, //5 second from now
saleEnd: Date.now() + 60*60*24*365*1000, //1 year
precision: 6
}
const createToken = async (tokenSpec) => {
const unsingedTx = await unichain.transactionBuilder.createToken(tokenSpec, ownerAddress)
console.log(unsingedTx)
const signedTx = await unichain.unx.signTransaction(unsingedTx, privateKey, 0)
const res = await unichain.unx.sendRawTransaction(signedTx)
console.log('create token done: ', res)
}
Apply for witness
function applyForWitness(witnessAddress, witnessURL)
Full example
const witnessAddress = 'Your_witness_address'
const witnessPrivateKey = 'Your_witness_private_key'
const applyWitness = async () => {
let unsingedTx = await unichain.transactionBuilder.applyForWitness(witnessAddress, 'https://witness-test.org')
let signedTx = await unichain.unx.signTransaction(unsingedTx, witnessPrivateKey, 0)
let res = await unichain.unx.sendRawTransaction(signedTx)
console.log('Apply for witness transaction: ', res)
}
Lock/Freeze balance
function freezeBalance(numberOfCoin, timeToLock, resourceType, ownerAddress)
Full example
const coinToLock = 100
const ownerAddress = 'Your_address'
const privateKey = 'Your_private_key'
const lockBalance = async () => {
let unsingedTx = await unichain.transactionBuilder.freezeBalance(unichain.toGinza(coinToLock), 3, 'BANDWIDTH', ownerAddress)
console.log('lockBalance unsingedTx :', unsingedTx)
let signedTx = await unichain.unx.signTransaction(unsingedTx, privateKey, 0)
let res = await unichain.unx.sendRawTransaction(signedTx)
console.log('Lock coin transaction: ', res)
}
Vote for witness
function vote(witnessToVote, voterAdress)
Full example
const witnessAddress = 'Witness_address'
const voterAdress = 'Your_voter_address'
const voterPrivateKey = 'Your_voter_key'
const voteForWitness = async () => {
let voteCount = 30
let witnessToVote = {[witnessAddress]: voteCount} //can be many witness. format address:voteCount
let unsingedTx = await unichain.transactionBuilder.vote(witnessToVote, voterAdress)
let signedTx = await unichain.unx.signTransaction(unsingedTx, voterPrivateKey, 0)
let res = await unichain.unx.sendRawTransaction(signedTx)
console.log('Vote tx ', res)
}
Create a proposal
Only witness can perform this operation
function createProposal(proposalParam, witnessAddress)
Approve a proposal
Only witness can perform this operation
function voteProposal(proposalID, isApprove, witnessAddress)
Delete a proposal
Only proposal owner can perform this operation
function deleteProposal(proposalID, ownerAddress)
Withdraw reward balance
function withdrawBlockRewards(ownerAddress)
APIs
APIs to communicate with UniChain network are wrapped into unx class. You can use either callback or async/await syntax to call the apis. For example, to get the current block, the getCurrentBlock is called as below
//callback style
unichain.unx.getCurrentBlock(data => {
console.log('Current block data:', data)
})
//async/await style
const data = await unichain.unx.getCurrentBlock()
console.log('Current block data:', data)
Get current block
Get current block information
function getCurrentBlock()
Get block
Get block information by block hash
function getBlockByHash(blockHash)
Get block by ID
Get block information by block ID (block number)
function getBlockByNumber(blockNumber)
Get number of transaction in a block
Get number of transaction in a block. If blockHash is empty, the API return the number of transaction in current block
function getBlockTransactionCount(blockHash)
Get Transaction
Get transaction detail by transaction hash
function getTransaction(txid)
Get account
Get account information from an address
function getAccount(address)
Get balance
Get balance of an address
function getBalance(address)
Get bandwidth
Get bandwidth of an address
function getBandwidth(address)
Get token issued by an address
Get token issued by an address
function getTokensIssuedByAddress(address)
Get token by name
Get token by token name
function getTokenFromID(tokenID)
Get connected node
Get connected nodes
function listNodes()
Get witness list
Get list of witness
function listWitnesses()
Get token list
List the token in the network with limit and offset
function listTokens(limit, offset)
Get next maintenance time
Get next maintenance time
function timeUntilNextVoteCycle()
Get contract
Get contract information from contract address
function getContract(contractAddress)
Sign transaction
Sign transaction offline with private key
function sign(unsignedTransaction, privateKey)
Send raw transaction
Broadcash signed transaction into network
function sendRawTransaction(signedTransaction)
Send token
This API return the unsigned transaction. To send the token, You need to sign on the return transaction, then broadcast to network
function sendToken(to, amount, tokenID)
List proposal
List all proposal from network
function listProposals()
Get proposal by ID
Get proposal by proposal ID
function getProposal(proposalID)
Get network parameters
Get network parameters
function getChainParameters()
Get account resource
Get account resource of an address
function getAccountResources(address)
Get node infomation
Get node information
function getNodeInfo()
Get reward
Get accumulated reward of an address (witness or voters)
function getReward(address)