1. About this SDK
2. How to Install
   1. Enviorment requirement
   2. Install from npm/yarn
   3. Quick start
3. Build from source files
   1. Install lerna and typescript globally
   2. Bootstrap and build
   3. Bundle
4. Tests
   1. Unit tests
   2. e2e tests
5. More examples
6. Release Note
   1. Before Release
   2. Publish to npm using dev:publish
   3. Publish to npm with lerna

About this SDK

A Harmony's blockchain javascript library, which provides an easier way to interact with Harmony's blockchain.

This libraries contains a few packages.

1. @harmony-js/core
2. @harmony-js/account
3. @harmony-js/crypto
4. @harmony-js/network
5. @harmony-js/utils
6. @harmony-js/transaction
7. @harmony-js/contract
8. @harmony-js/staking

How to Install

This library works on both nodejs and browser. Please use it according to your use case.

Enviorment requirement

• Nodejs: 10.0+
• Browser: Latest Chrome and Firefox

Install from npm/yarn

Note: we added a @next tag to npm package, please use the following command to install with npm/yarn

# npm
npm install @harmony-js/core@next 

# yarn
yarn add @harmony-js/core@next

# tslib is required, we'd better install it as well
npm install tslib
yarn add tslib

Quick start

1. You need Harmony local testnet running. instruction here:harmony-one/harmony
2. Run this example under nodejs enviorment.

// import or require Harmony class
const { Harmony } = require('@harmony-js/core');

// import or require settings
const { ChainID, ChainType } = require('@harmony-js/utils');

// 1. initialize the Harmony instance

const harmony = new Harmony(
  // rpc url
  'http://localhost:9500',
  {
    // chainType set to Harmony
    chainType: ChainType.Harmony,
    // chainType set to HmyLocal
    chainId: ChainID.HmyLocal,
  },
);

// 2. get wallet ready
// specify the privateKey
const privateKey = '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e';
// add privateKey to wallet
const sender = harmony.wallet.addByPrivateKey(privateKey);

// 3. get sharding info
async function setSharding() {
  // Harmony is a sharded blockchain, each endpoint have sharding structure,
  // However sharding structure is different between mainnet, testnet and local testnet
  // We need to get sharding info before doing cross-shard transaction
  const res = await harmony.blockchain.getShardingStructure();
  harmony.shardingStructures(res.result);
}

// 4. get transaction payload ready

async function transfer() {
  // run set sharding first, if you want to make a cross-shard transaction
  await setSharding();

  const txn = harmony.transactions.newTx({
    //  token send to
    to: 'one166axnkjmghkf3df7xfvd0hn4dft8kemrza4cd2',
    // amount to send
    value: '10000',
    // gas limit, you can use string
    gasLimit: '210000',
    // send token from shardID
    shardID: 0,
    // send token to toShardID
    toShardID: 0,
    // gas Price, you can use Unit class, and use Gwei, then remember to use toWei(), which will be transformed to BN
    gasPrice: new harmony.utils.Unit('100').asGwei().toWei(),
  });

  // sign the transaction use wallet;

  const signedTxn = await harmony.wallet.signTransaction(txn);

  // Now you can use `Transaction.observed()` to listen events

  signedTxn
    .observed()
    .on('transactionHash', (txnHash) => {
      console.log('');
      console.log('--- hash ---');
      console.log('');
      console.log(txnHash);
      console.log('');
    })
    .on('receipt', (receipt) => {
      console.log('');
      console.log('--- receipt ---');
      console.log('');
      console.log(receipt);
      console.log('');
    })
    .on('cxReceipt', (receipt) => {
      console.log('');
      console.log('--- cxReceipt ---');
      console.log('');
      console.log(receipt);
      console.log('');
    })
    .on('error', (error) => {
      console.log('');
      console.log('--- error ---');
      console.log('');
      console.log(error);
      console.log('');
    });

  // send the txn, get [Transaction, transactionHash] as result

  const [sentTxn, txnHash] = await signedTxn.sendTransaction();

  // to confirm the result if it is already there

  const confiremdTxn = await sentTxn.confirm(txnHash);

  // if the transactino is cross-shard transaction
  if (!confiremdTxn.isCrossShard()) {
    if (confiremdTxn.isConfirmed()) {
      console.log('--- Result ---');
      console.log('');
      console.log('Normal transaction');
      console.log(`${txnHash} is confirmed`);
      console.log('');
      process.exit();
    }
  }
  if (confiremdTxn.isConfirmed() && confiremdTxn.isCxConfirmed()) {
    console.log('--- Result ---');
    console.log('');
    console.log('Cross-Shard transaction');
    console.log(`${txnHash} is confirmed`);
    console.log('');
    process.exit();
  }
}

transfer();

Build from source files

Install lerna and typescript globally

yarn global add lerna && yarn global add typescript

Bootstrap and build

yarn bootstrap

Bundle

build umd and esm version javascript for each sub-packages, which can be accessed by import or require

yarn dist

All files are exported in packages/dist folder, use **.esm.js or **.umd.js format

Tests

Unit tests

yarn test:src

e2e tests

Contantly updating now, please get back later

1. edit .env file if you have custom setting

2. run harmony node locally, follow this instruction : https://github.com/harmony-one/harmony)

3. wait for 1-2 mins, and run this:

yarn build && yarn test:e2e

More examples

• dapp-examples

Release Note

Before Release

1. Build source first

    yarn build:ts
   

2. Run unit tests

   yarn test:src
   

3. Run e2e tests

   yarn test:e2e
   

4. Clean and build bundle

   yarn dist
   

Publish to npm using dev:publish

The packages is to be published to npm, using @next tag using script in package.json

Follow steps below to publish a npm verion using @next tag

1. Commit all changes to github master
2. Run publish script

  yarn dev:publish

3. Select version and confirm all prompts with Y
4. See version changes in npmjs.com

This will not change the release version of current npm packages(currently 0.0.7), developers have to use @next to install from npm.

For example.

  npm install @harmony-js/core@next

Publish to npm with lerna

Follow steps below to publish a npm verion with latest version

1. Commit all changes to github master
2. Run lerna publish, lerna is required globally.

  lerna publish

3. Select version and confirm all prompts with Y
4. See version changes in npmjs.com

This will change the release version of current npm packages to the latest version, developers can install from npm directly

For example.

  npm install @harmony-js/core