Skip to content
This repository has been archived by the owner on Jun 14, 2022. It is now read-only.

virtualeconomy/js-v-sdk

Repository files navigation

js-vsystems

DEPRECATED. Please use the new JavaScript SDK js-vsys instead.

JavaScript library for V Systems

Install from npm (recommended)

  1. install packages
$ npm i @virtualeconomy/js-v-sdk

Install from git

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

  2. clone this project as a submodule

$ git submodule add https://github.com/virtualeconomy/js-v-sdk.git js-v-sdk
$ git submodule update --init --recursive

Usage

Here we briefly introduce how to use this package installed from npm. If you want more details on how to use it, please refer to JSVSYSTEMS User Guide Specification

chain object

  1. For testnet chain:

    const vsys = require("@virtualeconomy/js-v-sdk");
    const constants = vsys.constants;
    const node_address = "https://test.v.systems/api"; // change to your node address
    const network_byte = constants.TESTNET_BYTE;
    var chain = new vsys.Blockchain(node_address, network_byte);
  2. For mainnet chain:

    const vsys = require("@virtualeconomy/js-v-sdk");
    const constants = vsys.constants;
    const node_address = "https://wallet.v.systems/api"; // change to your node address
    const network_byte = constants.MAINNET_BYTE;
    var chain = new vsys.Blockchain(node_address, network_byte);
  3. Some methods in chain object:

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

account object

  1. Create account by seed

    const vsys = require("@virtualeconomy/js-v-sdk");
    const constants = vsys.constants;
    var acc = new vsys.Account(constants.TESTNET_BYTE);
    acc.buildFromSeed("<your seed>", 0);
  2. Some 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);

transaction object

  1. Build transaction object

    const vsys = require("@virtualeconomy/js-v-sdk");
    var constants = vsys.constants;
    const network_byte = constants.TESTNET_BYTE;
    var tra = new vsys.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);

send transaction

  1. Send Payment transaction

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
    const node_address = "https://test.v.systems/api"; // 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 = "https://test.v.systems/api"; // 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);

contract related

  1. Register contract

    Token Contract (Create token)

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
    const vsys = require("@virtualeconomy/js-v-sdk");
    const contract_1 = vsys.Contract;
    const node_address = "https://test.v.systems/api"; // change to your node address
    let data_generator = new vsys.TokenContractDataGenerator();
    
    async function sendRegisterContractTx(tx) {
        const result = await chain.sendRegisterContractTx(tx);
        console.log(result);
    }
    
    // Necessary data for creating token, use vsys.TokenContractDataGenerator.createInitData(amount,unity,token_description) to generate init_data.
    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 = data_generator.createInitData(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

    Get necessary function_index when preparing contract function data.

    const vsys = require("@virtualeconomy/js-v-sdk");
    const ContractType = vsys.ContractType;
    let function_index = vsys.getContractFunctionIndex('<contract type>', '<function name>');
    
    /* The types of contracts and related functions currently supported are as follows
    
    const variable `ContractType` includes TOKEN, SPLITTABLE_TOKEN, SYSTEM, LOCK, PAYMENT_CHANNEL, NFT
    usage: ContractType.TOKEN
    
    <'Contract Type'> : <'Function Type'>, <'Function Name'>, ...
    TOKEN : SUPERSEDE, ISSUE, DESTROY, SEND, TRANSFER, WITHDRAW, DEPOSIT
    SPLITTABLE_TOKEN: SUPERSEDE, ISSUE, DESTROY, SPLIT, SEND, TRANSFER, WITHDRAW, DEPOSIT
    SYSTEM : SEND, TRANSFER, WITHDRAW, DEPOSIT
    LOCK : LOCK
    PAYMENT_CHANNEL : CREATEANDLOAD, EXTENDEXPIRATIONTIME, LOAD, ABORT, UNLOAD, COLLECTPAYMENT
    NFT : SUPERSEDE, ISSUE, SEND, TRANSFER, WITHDRAW, DEPOSIT
    */

    Send token

    // tra: your transaction object, acc: your account object, chain: your blockchain object, build them first!
    const vsys = require("@virtualeconomy/js-v-sdk");
    const contract_1 = vsys.Contract;
    const constants = vsys.constants;
    const node_address = "https://test.v.systems/api"; // change to your node address
    let data_generator = new vsys.TokenContractDataGenerator();
    
    async function sendExecuteContractTx(tx) {
        const result = await chain.sendExecuteContractTx(tx);
        console.log(result);
    }
    
    // Necessary data for send token, use vsys.TokenContractDataGenerator.createSendData(recipient, amount, unity) to generate function_data.
    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 = data_generator.createSendData(recipient, amount, unity);
    let attachment = "<attachment>";
    let function_index = vsys.getContractFunctionIndex(vsys.ContractType.SPLITTABLE_TOKEN, 'SEND'); // 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 system contract
$ npm run test_system_contract

# Test payment channel contract
$ npm run test_payment_channel_contract

# Test lock contract
$ npm run test_lock_contract

# Test non fungible contract
$ npm run test_nft_contract

# 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.