@sheldon-vsys/js-v-sdk

JavaScript library for V Systems

Usage no npm install needed!

<script type="module">
  import sheldonVsysJsVSdk from 'https://cdn.skypack.dev/@sheldon-vsys/js-v-sdk';
</script>

README

js-vsystems

JavaScript library for V Systems

Install

  1. install node.js (homebrew or https://nodejs.org/)

  2. clone this project

$ git clone https://github.com/virtualeconomy/js-v-sdk.git
  1. install packages
  $ cd js-v-sdk
  $ npm install
  1. build project and then you can use JS library for V Systems
  $ npm run build

Usage

chain object

  1. For testnet chain:

    const Blockchain = require('../libs/blockchain');
const constants = require("../libs/constants");
const node_address = "http://test.v.systems:9922"; // change to your node address
const network_byte = constants.TESTNET_BYTE;
var chain = new Blockchain(node_address, network_byte);

  2. For mainnet chain:

    const Blockchain = require('../libs/blockchain');
const constants = require("../libs/constants");
const node_address = "https://wallet.v.systems/api"; // change to your node address
const network_byte = constants.TESTNET_BYTE;
var chain = new Blockchain(node_address, network_byte);

  3. Methods in chain object:

    // Get Balance
async function getBalance(chain, address) {
    let result = await chain.getBalance(address);
    console.log(result);
}
getBalance(chain, "<address>");

// Get Balance Detail
async function getBalanceDetail(chain, address) {
    const result = await chain.getBalanceDetail(address);
    console.log(result);
}
getBalanceDetail(chain, "<address>");

// Get transaction history
// num: Specified number of records to be returned
async function getTxHistory(chain, address, num) {
    const result = await chain.getTxHistory(address, num);
    console.log(result);
}
getTxHistory(chain, "<address>", "<num>");

// Get transaction by id
// tx_id: transaction id
async function getTxById(chain, tx_id) {
    const result = await chain.getTxById(tx_id);
    console.log(result);
}
getTxById(chain, "<tx_id>");

// Get unconfirmed transaction by id
// tx_id: transaction id
async function getUnconfirmedTxById(chain, tx_id) {
    const result = await chain.getUnconfirmedTxById(tx_id);
    console.log(result);
}
getUnconfirmedTxById(chain, "<tx_id>");

// Get block height
async function getHeight(chain) {
    const result = await chain.getHeight();
    console.log(result);
}
getHeight(chain);

// Get last block
async function getLastBlock(chain) {
    const result = await chain.getLastBlock();
    console.log(result);
}
getHeight(chain);

// Get block by height
async function getBlockByHeight(chain, height) {
    const result = await chain.getBlockByHeight(height);
    console.log(result);
}
getBlockByHeight(chain, "<height>");

// Get slot information
async function getSlotInfo(chain, slot_id) {
    const result = await chain.getSlotInfo(slot_id);
    console.log(result);
}
getSlotInfo(chain, "<slot_id>");

// Get all slots information
async function getAllSlotsInfo(chain) {
    const result = await chain.getAllSlotsInfo();
    console.log(result);
}
getAllSlotsInfo(chain);

// Get token information
async function getTokenInfo(chain, token_id) {
    const result = await chain.getTokenInfo(token_id);
    console.log(result);
}
getTokenInfo(chain, "<token_id>");

// Get address's token balance
async function getTokenBalance(chain, address, token_id) {
    const result = await chain.getTokenBalance(address, token_id);
    console.log(result);
}
getTokenBalance(chain, "<address>", "<token_id>");

// Get contract information
async function getContractInfo(chain, contract_id) {
    const result = await chain.getContractInfo(contract_id);
    console.log(result);
}
getContractInfo(chain, "<contract_id>");

// Get contract content
async function getContractContent(chain, contract_id) {
    const result = await chain.getContractContent(contract_id);
    console.log(result);
}
getContractContent(chain, "<contract_id>");

// Send payment tx to node
async function sendPaymentTx(chain, tx) {
    const result = await chain.sendPaymentTx(tx);
    console.log(result);
}
sendPaymentTx(chain, tx);

// Send leasing tx to node
async function sendLeasingTx(chain, tx) {
    const result = await chain.sendLeasingTx(tx);
    console.log(result);
}
sendLeasingTx(chain, tx);

// Send cancel leasing tx to node
async function sendCancelLeasingTx(chain, tx) {
    const result = await chain.sendCancelLeasingTx(tx);
    console.log(result);
}
sendCancelLeasingTx(chain, tx);

// Send register contract tx to node
async function sendRegisterContractTxx(chain, tx) {
    const result = await chain.sendRegisterContractTx(tx);
    console.log(result);
}
sendRegisterContractTx(chain, tx);

// Send execute contract tx to node
async function sendExecuteContractTxx(chain, tx) {
    const result = await chain.sendExecuteContractTx(tx);
    console.log(result);
}
sendExecuteContractTx(chain, tx);

account object

  1. Create account by seed

    const Account = require('../libs/account');
const constants = require("../libs/constants");
var acc = new Account(constants.TESTNET_BYTE);
acc.buildFromSeed("<your seed>", 0);

  2. Create account by private key

        const Account = require('../libs/account');
    const constants = require("../libs/constants");
    var acc = new Account(constants.TESTNET_BYTE);
    acc.buildFromPrivateKey("<private key>");

  3. Create account by public key

    const Account = require('../libs/account');
const constants = require("../libs/constants");
var acc = new Account(constants.TESTNET_BYTE);
acc.buildColdWallet("<public key>", '');

  4. Create account by address

    const Account = require('../libs/account');
const constants = require("../libs/constants");
var acc = new Account(constants.TESTNET_BYTE);
acc.buildColdWallet('', "<address>");

  5. Methods in account object

    // acc: your account object

// Get address
let address = acc.getAddress();
console.log(address);

// Get public key
let publicKey = acc.getPublicKey();
console.log(publicKey);

// Get private key
let privateKey = acc.getPrivateKey();
console.log(privateKey);

// Get signature
let signature = acc.getSignature("<data bytes>");
console.log(signature);

// Check address
let is_valid_address = acc.checkAddress("<address>");
console.log(is_valid_address);

// Convert public key to address
// network byte: constants.TESTNET_BYTE or constants.MAINNET_BYTE
let address = acc.convertPublicKeyToAddress("<public key>", "<network byte>");
console.log(address);

// Send transaction tx to node (you can know more details in 'send transaction' part)
async function sendTransaction(acc, tx, node) {
    const result = await acc.sendTransaction(node, tx);
    console.log(result);
}
sendTransaction(acc, "<tx>", "<blockchain object>");

transaction object

  1. Build transaction object

    const Transaction = require('../libs/transaction');
var constants = require("../libs/constants");
const network_byte = constants.TESTNET_BYTE;
var tra = new Transaction(network_byte);

  2. Some methods in transaction object

    // Get bytes of json, but you need to build valid tx first.
let bytes = tra.toBytes();
console.log(bytes);

// Get json for cold signature
let cold_tx = tra.toJsonForColdSignature();
console.log(cold_tx);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx("<signature>");
console.log(send_tx);

// Build transaction id
let bytes = tra.toBytes();
let transaction_id = buildTransactionId(bytes);
console.log(transaction_id);

send transaction

  1. Send Payment transaction

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendPaymentTx(tx) {
    // const result = await chain.sendPaymentTx(tx);
    const result = await acc.sendTransaction(chain, tx);
    console.log(result);
}

// Create Transaction Object
let public_key = acc.getPublicKey();
let timestamp = Date.now() * 1e6;
tra.buildPaymentTx(public_key, "<recipient address>", "<amount>", "<attachment>", timestamp);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendPaymentTx(send_tx);

// You can also get json for cold siganture
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

  2. Send Lease transaction

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendLeasingTx(tx) {
    // const result = await chain.sendLeasingTx(tx);
    const result = await acc.sendTransaction(chain, tx);
    console.log(result);
}

// Create Transaction Object
let public_key = acc.getPublicKey();
let timestamp = Date.now() * 1e6;
tra.buildLeasingTx(public_key, "<recipient address>", "<amount>", timestamp);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendLeasingTx(send_tx);

// You can also get json for cold siganture
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

  3. Send Cancel Lease transaction

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendCancelLeasingTx(tx) {
    // const result = await chain.sendCancelLeasingTx(tx);
    const result = await acc.sendTransaction(chain, tx);
    console.log(result);
}

// Create Transaction Object
let public_key = acc.getPublicKey();
let timestamp = Date.now() * 1e6;
tra.buildCancelLeasingTx(public_key, "<lease_id>", timestamp);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendLeasingTx(send_tx);

// You can also get json for cold siganture
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

contract related

  1. Register contract (Create token)

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
var contract_1 = require("../libs/contract");
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendRegisterContractTx(tx) {
    const result = await chain.sendRegisterContractTx(tx);
    console.log(result);
}

// Necessary data for creating token, init_data should contain 'amount', 'unity', 'token_description' three keys.
let contract = contract_1.TOKEN_CONTRACT; // contract_1.TOKEN_CONTRACT_WITH_SPLIT
let public_key = acc.getPublicKey();
let amount = "<amount>";
let unity = "<unity>";
let token_description = "<description for token>";
let contract_description = "<description for contract>";
let timestamp = Date.now() * 1e6;
let init_data = {amount, unity, token_description};

// Build contract tx
tra.buildRegisterContractTx(public_key, contract, init_data, contract_description, timestamp);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendRegisterContractTx(send_tx);

// You can also get json for cold signature
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

  2. Execute contract

    Issue token

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
var contract_1 = require("../libs/contract");
var constants = require("../libs/constants");
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendExecuteContractTx(tx) {
    const result = await chain.sendExecuteContractTx(tx);
    console.log(result);
}

// Necessary data for issue token, function_data should contain 'amount', 'unity' two keys, and attachment should be undefined
let public_key = acc.getPublicKey();
let amount = "<amount>";
let unity = "<unity of this token>";
let timestamp = Date.now() * 1e6;
let function_data = {amount, unity};
let attachment = undefined;
let function_index = constants.ISSUE_FUNCIDX;

// Build contract tx
tra.buildExecuteContractTx(public_key, "<contract_id>", function_index, function_data, timestamp, attachment);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendExecuteContractTx(send_tx);

// You can also get json for cold signature
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

    Destroy token

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
var contract_1 = require("../libs/contract");
var constants = require("../libs/constants");
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendExecuteContractTx(tx) {
    const result = await chain.sendExecuteContractTx(tx);
    console.log(result);
}

// Necessary data for destroy token, function_data should contain 'amount', 'unity' two keys, and attachment should be undefined
let public_key = acc.getPublicKey();
let amount = "<amount>";
let unity = "<unity of this token>"; // 1e8
let timestamp = Date.now() * 1e6;
let function_data = {amount, unity};
let attachment = undefined;
let function_index = constants.DESTROY_FUNCIDX;

// Build contract tx
tra.buildExecuteContractTx(public_key, "<contract_id>", function_index, function_data, timestamp, attachment);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendExecuteContractTx(send_tx);

// You can also get json for cold signature
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

    Split token

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
var contract_1 = require("../libs/contract");
var constants = require("../libs/constants");
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendExecuteContractTx(tx) {
    const result = await chain.sendExecuteContractTx(tx);
    console.log(result);
}

// Necessary data for split token, function_data should contain 'new_unity' key, and attachment should be undefined
let public_key = acc.getPublicKey();
let new_unity = "<new unity>";
let timestamp = Date.now() * 1e6;
let function_data = { new_unity };
let attachment = undefined;
let function_index = constants.SPLIT_FUNCIDX;

// Build contract tx
tra.buildExecuteContractTx(public_key, "<contract_id>", function_index, function_data, timestamp, attachment);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendExecuteContractTx(send_tx);

// You can also get json for cold signature
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

    Supersede token

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
var contract_1 = require("../libs/contract");
var constants = require("../libs/constants");
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendExecuteContractTx(tx) {
    const result = await chain.sendExecuteContractTx(tx);
    console.log(result);
}

// Necessary data for supersede token, function_data should contain 'new_issuer' key, and attachment should be undefined
let public_key = acc.getPublicKey();
let new_issuer = "<new issuer>";
let timestamp = Date.now() * 1e6;
let function_data = { new_issuer };
let attachment = undefined;
let function_index = constants.SUPERSEDE_FUNCIDX;

// Build contract tx
tra.buildExecuteContractTx(public_key, "<contract_id>", function_index, function_data, timestamp, attachment);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendExecuteContractTx(send_tx);

// You can also get json for cold signature
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

    Send token by function buildSendTokenTx ( )

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
var contract_1 = require("../libs/contract");
var constants = require("../libs/constants");
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendExecuteContractTx(tx) {
    const result = await chain.sendExecuteContractTx(tx);
    console.log(result);
}

// Necessary data for send token
let public_key = acc.getPublicKey();
let token_id = "<token id>";
let recipient = "<recipient address>";
let amount = "<amount>";
let unity = "<unity of this token>"; //1e8
let is_split_supported = "<boolean>";
let attachment = "<attachment>";

// Build contract tx
tra.buildSendTokenTx(public_key, token_id, recipient, amount, unity, is_split_supported, attachment);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendExecuteContractTx(send_tx);

// You can also get json for cold signature
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

    Send token

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
var contract_1 = require("../libs/contract");
var constants = require("../libs/constants");
const node_address = "http://test.v.systems:9922"; // change to your node address

async function sendExecuteContractTx(tx) {
    const result = await chain.sendExecuteContractTx(tx);
    console.log(result);
}

// Necessary data for send token, function_data should contain 'recipient', 'amount', 'unity' three keys, and attachment should not be undefined
let public_key = acc.getPublicKey();
let recipient = "<recipient address>";
let timestamp = Date.now() * 1e6;
let amount = "<amount>";
let unity = "<unity of this token>"; //1e8
let function_data = {recipient, amount, unity}
let attachment = "<attachment>";
let function_index = constants.SEND_FUNCIDX_SPLIT; // constants.SEND_FUNCIDX

// Build contract tx
tra.buildExecuteContractTx(public_key, "<contract_id>", function_index, function_data, timestamp, attachment);

// Get bytes
let bytes = tra.toBytes();

// Get signature
let signature = acc.getSignature(bytes);

// Get json for sending tx
let send_tx = tra.toJsonForSendingTx(signature);

// Send transaction
sendExecuteContractTx(send_tx);

// You can also get json for cold signature
let cold_tx = tra.toJsonForColdSignature();
console.log('Json for cold signature:');
console.log(cold_tx);

Sample Code and Testing

Sample code please refer these files:

// how to build account
test/test_account.js

// how to get information from API
test/test_blockchain.js

// how to register contract and execute contract function
test/test_token.js

// how to send payment、lease、cancel lease transaction and build transaction id
test/test_tx.js

Run these commands to test.

# Test account
$ npm run test_account

# Test blockchain
$ npm run test_blockchain

# Test token
$ npm run test_token

# Test tx
$ npm run test_tx

# Test all
$ npm run test_all

Feel free to modify these test example files. Write your own code as wallet client and integrate into your project.