zilliqa-js


Introduction

zilliqa-js is a Javascript library that allows you to interact with the Zilliqa network nodes - create wallets, deploy contracts, and invoke transitions to interact with smart contracts.

Source Code

The Github repository can be found at https://github.com/Zilliqa/Zilliqa-JavaScript-Library

Releases

All releases of zilliqa-js can be found at https://www.npmjs.com/package/@zilliqa-js/zilliqa

Release note can be found at https://github.com/Zilliqa/Zilliqa-JavaScript-Library/releases

Installation

It is recommended that developers install the JavaScript client by making use of the umbrella package @zilliqa-js/zilliqa. This takes care of bootstrapping the various modules, which are then accessible as members of the Zilliqa class.

yarn add @zilliqa-js/zilliqa
# you may also need to install the tslib package.
yarn add tslib
# bn.js should be added with the above package. if it is not, install it manually.
yarn add bn.js

Methods and APIs

The following table provides a description of each module of zilliqa-js and what you may want to use it for. Visit the relevant link of each module to find the detailed description about the methods and apis supported by that module.

packagedescriptiondependencies
@zilliqa-js/coreCore abstractions and base classes, such as HTTPProvider and network logic for interfacing with the Zilliqa JSON-RPC.none
@zilliqa-js/accountWallet, Account and Transaction abstractions live in this package.@zilliqa-js/core, @zilliqa-js/crypto, @zilliqa-js/util, @zilliqa-js/proto
@zilliqa-js/blockchainMain interface to the Zilliqa JSON-RPC.none
@zilliqa-js/contractExposes a Contracts module that takes care of smart contract deployment and interaction.@zilliqa-js/account, @zilliqa-js/blockchain, @zilliqa-js/core, @zilliqa-js/util
@zilliqa-js/cryptoExposes several loosely-coupled cryptographic convenience functions for working with the Zilliqa blockchain and its cryptographic primitives, such as Schnorr signatures.@zilliqa-js/util
@zilliqa-js/protoProtobuf source files and corresponding generated JS modules.none
@zilliqa-js/utilMiscellaneous functions that take care of serialisation/deserialisation and validation.none
@zilliqa-js/viewblockLibrary interfacing with ViewBlock's APIs@zilliqa-js/crypto

Demo - ZRC2 Wallet

For this demo, we'll be looking at the zilliqa-js related code of a simple ZRC2 wallet, ZRC2 is a standard for fungible tokens on Zilliqa. The full code can be found at ZRC2 Wallet Repository. This repository is written in React but the zilliqa-js methods & APIs can be used with any javascript framework.

Generating Private Key and Address from Encrypted Wallet and a Passphrase

import { decryptPrivateKey, getAddressFromPrivateKey} from '@zilliqa-js/crypto';
let keystore = JSON.parse(this.state.encryptedWallet);
const pk = await decryptPrivateKey(this.state.passphrase, keystore);
const address = getAddressFromPrivateKey(pk);

Getting User's $ZIL Balance

const {Zilliqa} = require('@zilliqa-js/zilliqa');
const zilliqa = new Zilliqa('https://dev-api.zilliqa.com');
let balanceState = await zilliqa.blockchain.getBalance(userAddress);
if(balanceState){
let balance = balanceState.result.balance;
balance = units.fromQa(new BN(balance), units.Units.Zil);// user's $zil balance
}

Getting User's Token Balance

let userAddress = localStorage.getItem("userAddress");//userAddress is retrieved from localStorage in this example
const {Zilliqa} = require('@zilliqa-js/zilliqa');
const zilliqa = new Zilliqa('https://dev-api.zilliqa.com');
let smartContractState = await zilliqa.blockchain.getSmartContractState(tokenContractAddress);
if(smartContractState){
let balances_map = smartContractState.result.balances_map;
userAddress = userAddress.toLowerCase();
let userTokenBalance = balances_map[userAddress];//user's token balance
}

Sending Tokens to Another Address by Calling 'Transfer' Transition of the ZRC2 Contract

sendTransaction = async() => {
const {Zilliqa} = require('@zilliqa-js/zilliqa');
const zilliqa = new Zilliqa('https://dev-api.zilliqa.com');
const {BN, Long, bytes, units} = require('@zilliqa-js/util');
const {toBech32Address, fromBech32Address} = require('@zilliqa-js/crypto');
//You can set the value of the following variables according to your liking
let contractAddress = localStorage.getItem("token_contract_address");
let recipientAddress = this.state.sendingAddress;
let sendingAmount = this.state.sendingAmount;
let privkey = localStorage.getItem("private_key");
zilliqa.wallet.addByPrivateKey(privkey);
const CHAIN_ID = 333;
const MSG_VERSION = 1;
const VERSION = bytes.pack(CHAIN_ID, MSG_VERSION);
const myGasPrice = units.toQa('1000', units.Units.Li); // Gas Price that will be used by all transactions
contractAddress = contractAddress.substring(2);
recipientAddress = fromBech32Address(recipientAddress);//converting to ByStr20 format
const ftAddr = toBech32Address(contractAddress);
try {
const contract = zilliqa.contracts.at(ftAddr);
const callTx = await contract.call(
'Transfer',
[
{
vname: 'to',
type: 'ByStr20',
value: recipientAddress,
},
{
vname: 'amount',
type: 'Uint128',
value: sendingAmount,
}
],
{
// amount, gasPrice and gasLimit must be explicitly provided
version: VERSION,
amount: new BN(0),
gasPrice: myGasPrice,
gasLimit: Long.fromNumber(10000),
}
);
} catch (err) {
console.log(err);
}
}