About this SDK
How to Install
Build from source files
Tests
1. Unit tests
2. e2e tests
More examples
Release Note

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.

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

You need Harmony local testnet running. instruction here:harmony-one/harmony
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

edit .env file if you have custom setting
run harmony node locally, follow this instruction : https://github.com/harmony-one/harmony)
wait for 1-2 mins, and run this:

yarn build && yarn test:e2e

More examples

dapp-examples

Release Note

Before Release

Build source first
```
 yarn build:ts
```
Run unit tests
```
yarn test:src
```
Run e2e tests
```
yarn test:e2e
```
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

Commit all changes to github master
Run publish script
```
yarn dev:publish
```
Confirm all prompt with Y
See version changes in npmjs.com

Publish to npm with `lerna`

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

FireStack-Lab/Harmony-sdk-core