README.md

js-vsys

Under active maintenance. Contributions are always welcome!

The official Javascript SDK for VSYS APIs. The old Javascript SDK is deprecated and will be archived soon.

• js-vsys
  • Installation
  • Quick Example
  • Docs
    • Account & Wallet
    • Chain & API
    • Smart Contracts
  • Run Tests
    • Specification Tests
  • Contributing

Installation

Install from Github

git clone [email protected]:virtualeconomy/js-vsys.git

Then locate to the folder and run npm install.

Quick Example

'use strict';

import * as jv from '@virtualeconomy/js-vsys';

// The RESTful API host address to a node in a public test net
const host = 'http://veldidina.vos.systems:9928';

// A test net wallet seed
const seed = new jv.Seed('your seed');

function printHeading(msg) {
  function times(char, num) {
    let ret = '';
    while (num-- > 0) ret += char;

    return ret;
  }
  console.log(times('=', 10), msg, times('=', 10));
}

printHeading('Try out NodeAPI');
// NodeAPI is the wrapper for RESTful APIs
const api = jv.NodeAPI.new(host);
// GET /blocks/height
console.log(await api.blocks.getHeight());
// GET /node/version
console.log(await api.node.getVersion());

printHeading('Try out Chain');
// Chain represents the chain itself
const ch = new jv.Chain(api, jv.ChainID.TEST_NET);
// Get chain's height
console.log('Height:', await ch.getHeight());
// Get chain's last block
console.log('Last block: \n', await ch.getLastBlock());

printHeading('Try out Account');
// Account represents an account in the net
const wal = new jv.Wallet(seed);
const acnt = wal.getAcnt(ch, 0);
// Get the account's balance
console.log('Balance:', await acnt.getBal());
// Get the account's public key
console.log('Public key:', acnt.keyPair.pub);
// Get the account's private key
console.log('Private key:', acnt.keyPair.pri);
// Get the account's address
console.log('Account address:', acnt.addr);

printHeading('Try out Smart Contract');
const ctrtId = 'CF3cK7TJFfw1AcPk74osKyGeGxee6u5VNXD';
const ctrt = new jv.NFTCtrt(ctrtId, ch);
// Get the contract's maker
console.log('Maker:', await ctrt.getMaker());
// Get the contract's issuer
console.log('Issuer:', await ctrt.getIssuer());
// Get the contract's ID
console.log('Contract id:', ctrt.ctrtId);

Example output

========== Try out NodeAPI ==========
{ height: 2767707 }
{ version: 'VSYS Core v0.4.1' }
========== Try out Chain ==========
Height: 2767707
Last block:
 {
  version: 1,
  timestamp: 1655457048010768100,
  reference: '3dRCKVabnC4XdTdv64BB6486uoGypbNSHNiUgBf1WzuCe3GdLCvihgkvFsygNehtA2vQ6PAUBVPcpXs3MEeoG5sC',
  SPOSConsensus: { mintTime: 1655457048000000000, mintBalance: 191899551193920 },
  resourcePricingData: {
    computation: 0,
    storage: 0,
    memory: 0,
    randomIO: 0,
    sequentialIO: 0
  },
  TransactionMerkleRoot: '6Gx217pr8eYcz7Xu4FLexRWi3ufV19t2BtUNkmDUN14q',
  transactions: [
    {
      type: 5,
      id: 'Hs9QaTVZhReBLcGzTqFiLCRPwiGutsN1RbvSVKsHRCWB',
      recipient: 'AU1EWbfR8mTwbvzgnY8wdpLy3vEvF64WSEE',
      timestamp: 1655457048010768100,
      amount: 900000000,
      currentBlockHeight: 2767707,
      status: 'Success',
      feeCharged: 0
    }
  ],
  generator: 'AU1EWbfR8mTwbvzgnY8wdpLy3vEvF64WSEE',
  signature: 'DtMAp1bVCLzSZQAkVkuaDVEyctmydkBH469VmTzqLnrTnBrVxkp9PvWHuWSBJLEyGeqUeJ9TPZYZw6o5ofmEXw9',
  fee: 0,
  blocksize: 330,
  height: 2767707,
  'transaction count': 1
}
========== Try out Account ==========
Balance: VSYS { data: BigNumber { s: 1, e: 13, c: [ 48592200000000 ] } }
Nonce: Nonce { data: 0 }
Public key: PubKey { data: 'FwuW4LhiBFn6uu5id9nZGtp9o1RUG3DoX5MhyZibrjkE' }
Private key: PriKey { data: '2dC1PVfaeWBR6bsT4jpPkp4Zr9PNhXwQThPLEAvKWB37' }
Account address: Addr { data: 'ATse3RcjEzwc5JHDPcduPYe4qA2mWhSNZaV' }
========== Try out Smart Contract ==========
Maker: Addr { data: 'ATse3RcjEzwc5JHDPcduPYe4qA2mWhSNZaV' }
Issuer: Addr { data: 'AUFDmJqrcwphseJccD1vkR7xbRciMijMpw4' }
Contract id: CtrtID { data: 'CF3cK7TJFfw1AcPk74osKyGeGxee6u5VNXD' }

Docs

Account & Wallet

• Account
• Wallet
• Multisign

Chain & API

• Chain
• Api

Smart Contracts

• NFT Contract V1
• NFT Contract V2
• Token Contract V1 without split
• Token Contract V1 with split
• Token Contract V2 without split
• Atomic Swap Contract
• Payment Channel Contract
• Lock Contract
• System Contract
• V Escrow Contract
• V Option Contract
• V Stable Swap Contract
• V Swap Contract

Run Tests

Specification Tests

Specification tests are scripts that simulate the behaviour of a normal user to interact wtih js_vsys(e.g. register a smart contract & call functions of it).

To run it, ensure that you have jasmine properly installed.

First set up the global variables like below.

export JS_VSYS_HOST='http://veldidina.vos.systems:9928'
export JS_VSYS_AVG_BLOCK_DELAY=6
export JS_VSYS_SEED='your_seed'

Then go to the root of the project and run (take NFT contract as an example).

npx jasmine './spec/contract_spec/nft_ctrt_spec.js'

The above command will test each aspect(e.g. function send of NFT contract) individually and have required resources set up before testing(e.g. register a new contract, issue a token, etc). It's good for testing a specific aspect while it might consume too much resources to test every aspect in this way.

Take NFT contract as an example, it will register a contract first and then execute functions like send, transfer, deposit, etc in a pre-orchestrated manner so that some common set up(e.g. register a contract) will be done only once.

To run a single test, say issue, just comment all parts except beforeAll and test method issue, run

npx jasmine './spec/contract_spec/nft_ctrt_spec.js'

Contributing

Contributions are always welcome!

See the development documentation for more details and please adhere to conventions mentioned in it.