Merge pull request #69 from virtualeconomy/develop

release: v0.2.1

Author: josephzxy

README.md

@@ -2,7 +2,7 @@
 
 [![License](https://img.shields.io/badge/License-BSD_4--Clause-green.svg)](./LICENSE)
 
-> ***Under active maintenance. Contributions are always welcome!***
+> **_Under active maintenance. Contributions are always welcome!_**
 
 The official Javascript SDK for VSYS APIs. The [old Javascript SDK](https://github.com/virtualeconomy/js-v-sdk) is deprecated and will be archived soon.
 
@@ -20,9 +20,11 @@ The official Javascript SDK for VSYS APIs. The [old Javascript SDK](https://gith
 ## Installation
 
 Install from Github
+
 ```bash
 git clone [email protected]:virtualeconomy/js-vsys.git
 ```
+
 Then locate to the folder and run `npm install`.
 
 ## Quick Example
@@ -36,70 +38,67 @@ import * as jv from '@virtualeconomy/js-vsys';
 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))
+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");
+printHeading('Try out NodeAPI');
 // NodeAPI is the wrapper for RESTful APIs
 const api = jv.NodeAPI.new(host);
 // GET /blocks/last
 console.log(await api.blocks.getHeight());
 // GET /node/version
 console.log(await api.node.getVersion());
 
-printHeading("Try out Chain");
+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());
+console.log('Height:', await ch.getHeight());
 // Get chain's last block
-console.log("Last block: \n", await ch.getLastBlock());
+console.log('Last block: \n', await ch.getLastBlock());
 
-printHeading("Try out Account")
+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 nonce'
-console.log("Nonce:", acnt.nonce);
+console.log('Balance:', await acnt.getBal());
 // Get the account's public key
-console.log("Public key:", acnt.keyPair.pub);
+console.log('Public key:', acnt.keyPair.pub);
 // Get the account's private key
-console.log("Private key:", acnt.keyPair.pri);
+console.log('Private key:', acnt.keyPair.pri);
 // Get the account's address
-console.log("Account address:", acnt.addr);
+console.log('Account address:', acnt.addr);
 
-printHeading("Try out Smart Contract");
-const ctrtId = "CF3cK7TJFfw1AcPk74osKyGeGxee6u5VNXD";
+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());
+console.log('Maker:', await ctrt.getMaker());
 // Get the contract's issuer
-console.log("Issuer:", await ctrt.getIssuer());
+console.log('Issuer:', await ctrt.getIssuer());
 // Get the contract's ID
-console.log("Contract id:", ctrt.ctrtId);
+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: 
+Last block:
  {
   version: 1,
   timestamp: 1655457048010768100,
@@ -147,14 +146,17 @@ Contract id: CtrtID { data: 'CF3cK7TJFfw1AcPk74osKyGeGxee6u5VNXD' }
 ## Docs
 
 ### Account & Wallet
+
 - [Account](./doc/account.md)
 - [Wallet](./doc/wallet.md)
 
 ### Chain & API
+
 - [Chain](./doc/chain.md)
 - [Api](./doc/api.md)
 
 ### Smart Contracts
+
 - [NFT Contract V1](./doc/smart_contract/nft_ctrt.md)
 - [NFT Contract V2](./doc/smart_contract/nft_ctrt_v2.md)
 - [Token Contract V1 without split](./doc/smart_contract/tok_ctrt_no_split.md)
@@ -172,30 +174,37 @@ Contract id: CtrtID { data: 'CF3cK7TJFfw1AcPk74osKyGeGxee6u5VNXD' }
 ## 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.
+
 ```bash
 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).
+
 ```bash
 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
+
 ```bash
 npx jasmine './spec/contract_spec/nft_ctrt_spec.js'
 ```
+
 ## Contributing
 
 **Contributions are always welcome!**
 
-See [the development documentation](./doc/dev.md) for more details and please adhere to conventions mentioned in it.
+See [the development documentation](./doc/dev.md) for more details and please adhere to conventions mentioned in it.

doc/account.md

@@ -2,13 +2,13 @@
 
 - [Account](#account)
   - [Introduction](#introduction)
-  - [Usage with Javascript SDK](#usage-with-javascript-sdk)
+  - [Usage with JavaScript SDK](#usage-with-javascript-sdk)
+    - [Create Account](#create-account)
+      - [From Wallet](#from-wallet)
+      - [From Private Key & Public Key](#from-private-key--public-key)
     - [Properties](#properties)
       - [Chain](#chain)
       - [Api](#api)
-      - [Wallet](#wallet)
-      - [Nonce](#nonce)
-      - [Account Seed Hash](#account-seed-hash)
       - [Key Pair](#key-pair)
       - [Address](#address)
       - [VSYS Balance](#vsys-balance)
@@ -33,9 +33,35 @@ There are 2 kinds of accounts:
 
 The key difference between them lies in whether they have a private key.
 
-## Usage with Javascript SDK
+## Usage with JavaScript SDK
 
-In JS SDK we have an `Account` module that represents a user account on the VSYS blockchain.
+In JS SDK we have an `Account` class that represents a user account on the VSYS blockchain.
+
+### Create Account
+
+#### From Wallet
+The `Account` object can be contructed by a `Wallet` object given the `Chain` object & nonce.
+
+```javascript
+import * as jv from '@virtualeconomy/js-vsys';
+// ch // a jv.Chain object
+// wal // a jv.Wallet object
+const acnt0 = wal.getAcnt(ch, 0); // get the account of nonce 0 of the wallet.
+```
+
+#### From Private Key & Public Key
+The `Account` object can be constructed by a private key & opionally along with a public key.
+
+If the public key is omitted, it will be derived from the private key.
+If the public key is provided, it will be verified against the private key.
+
+```javascript
+import * as jv from '@virtualeconomy/js-vsys';
+// ch // a jv.Chain object
+const acnt0 = jv.Account.fromPriKeyStr(ch, 'your_private_key');
+const acnt1 = new jv.Account(ch, new jv.PriKey('your_private_key'));
+const acnt2 = new jv.Account(ch, new jv.PriKey('your_private_key'), new jv.PubKey('your_public_key'));
+```
 
 ### Properties
 
@@ -100,60 +126,6 @@ NodeAPI {
 }
 ```
 
-#### Wallet
-
-The `Wallet` object that represents the wallet that contains this account.
-
-```javascript
-// acnt: Account
-console.log(acnt.wallet);
-```
-
-Example output
-
-```
-Wallet {
-  seed: Seed {
-    data: 'your_seed'
-  }
-}
-```
-
-#### Nonce
-
-The nonce of this account in the wallet.
-
-```javascript
-// acnt: Account
-console.log(acnt.nonce);
-```
-
-Example output
-
-```
-Nonce { data: 0 }
-```
-
-#### Account Seed Hash
-
-Account Seed Hash is the hashing result of
-
-- the seed of the wallet the account is in
-- the nonce of the account that
-
-Account Seed Hash can be used to generate the private/public key pair of the account.
-
-```javascript
-// acnt: Account
-console.log(acnt.acntSeedHash);
-```
-
-Example output
-
-```
-<Buffer 44 d2 3e 1f fc 9d 6b 4b 7b 9c a6 fe 23 26 26 61 c5 54 c0 6d a4 62 5b bb d6 e5 44 d1 43 e9 9f>
-```
-
 #### Key Pair
 
 The private/public key pair of the account.