update sdk api reference

pull/67/head
Ganesha Upadhyaya 4 years ago
parent c6fbf597a5
commit cc4872a9f9
  1. 2
      README.md
  2. 0
      TYPEDOC.md
  3. 414
      packages/harmony-account/guide.ts
  4. 253
      packages/harmony-contract/src/abi/abiCoder.ts
  5. 243
      packages/harmony-core/src/blockchain.ts
  6. 136
      packages/harmony-crypto/src/errors.ts
  7. 42
      packages/harmony-network/src/rpcMethod/rpc.ts
  8. 89
      packages/harmony-staking/src/stakingTransaction.ts
  9. 228
      packages/harmony-transaction/src/types.ts
  10. 180
      packages/harmony-utils/src/chain.ts

@ -5,6 +5,8 @@
This is the Harmony javascript library which provides an easier way to interact with Harmony's blockchain.
Please read the [documentation](https://harmony-js-sdk-doc.s3-us-west-1.amazonaws.com/index.html) for more.
This libraries contains a few packages.
1. [@harmony-js/core](https://github.com/harmony-one/sdk/tree/master/packages/harmony-core)

@ -1,270 +1,214 @@
/**
## About This Package
# @harmony-js/account
`@harmony-js/account` is dealing with account related features.
This package provides a collection of apis to create accounts and wallets and sign using them. A wallet can hold multiple accounts and account is associated with a unique `one` address. This package also provides facilies to manage account keys.
Developers can use this package to:
- Create `Account` instance
- Create `Wallet` instance
- Sign `Transaction`
- Convert address format
- Manage `privateKey` or `mnemonic phrases` and do the `encrypt` and `decrypt` job
## Installation
There are 2 main classes in this package, `Account` and `Wallet`.
- The `Account` class is basic instance that contains most features mentioned above.
- The `Wallet` class is class that stores all `Account` instance, you can do CRUD on it.
## Usage of Account
### Dependencies
- @harmony-js/network
- @harmony-js/staking
- @harmony-js/transaction
- @harmony-js/utils
```
npm install @harmony-js/account
```
### Examples
## Usage
Create a random account
Creating new account and display hex and bech32 (one) addresses
```javascript
// import the Account class
import {Account} from '@harmony-js/account'
// Messenger is optional, by default, we have a defaultMessenger
// If you like to change, you will import related package here.
import { HttpProvider, Messenger } from '@harmony-js/network';
import { ChainType, ChainID } from '@harmony-js/utils';
// create a custom messenger
const customMessenger = new Messenger(
new HttpProvider('http://localhost:9500'),
ChainType.Harmony, // if you are connected to Harmony's blockchain
ChainID.HmyLocal, // check if the chainId is correct
)
// to create an Account with random privateKey
// and you can setMessenger later
const randomAccount = new Account()
randomAccount.setMessenger(customMessenger)
// or you can set messenger on `new`
const randomAccountWithCustomMessenger = new Account(undefined, customMessenger)
// you can display the account
console.log({randomAccount,randomAccountWithCustomMessenger})
// or you can use static method to create an Account
const staticCreatedAccount = Account.new()
// but you have to set messenger manually after
staticCreatedAccount.setMessenger(customMessenger)
console.log({staticCreatedAccount})
const account = new Account(); // or const account = Account.new()
console.log(account.checksumAddress);
console.log(account.bech32Address);
```
### Import an existing privateKey to create Account
```typescript
// import the Account class
import {Account} from '@harmony-js/account'
// NOTED: Key with or without `0x` are accepted, makes no different
// NOTED: DO NOT import `mnemonic phrase` using `Account` class, use `Wallet` instead
const myPrivateKey = '0xe19d05c5452598e24caad4a0d85a49146f7be089515c905ae6a19e8a578a6930'
const myAccountWithMyPrivateKey = new Account(myPrivateKey)
// you can also import privateKey use static method
const myAccountWithMyPrivateKeyUsingStatic = Account.add(myPrivateKey)
console.log({ myAccountWithMyPrivateKey, myAccountWithMyPrivateKeyUsingStatic })
Creating new account using private key
```javascript
const account = Account.add('45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e');
```
### Encrypt/Export keyStore file, Decrypt/Import keyStore file
```typescript
// import the Account class
import {Account} from '@harmony-js/account'
// suppose we have an account
const myPrivateKey = '0xe19d05c5452598e24caad4a0d85a49146f7be089515c905ae6a19e8a578a6930'
const myAccountWithMyPrivateKey = new Account(myPrivateKey)
// suppose we have a password, and we want to encrypt the account above
const myStrongPassword = '123'
async function encryptAndDecrypt(password) {
// we get the privateKey before encrypted as comparison
const unencryptedPrivateKey = myAccountWithMyPrivateKey.privateKey
// export the account to keyStore string, which will make the privateKey encrpyted
const keyStoreFile = await myAccountWithMyPrivateKey.toFile(password)
// exported keyStoreFile
console.log({ keyStoreFile })
// see if the account is encrypted
console.log(`Is this account encrypted? \n ${myAccountWithMyPrivateKey.encrypted}`)
// keystore file should be equal to encrypted privateKey
console.log(
`Is privateKey equal to keyStore string? \n ${keyStoreFile ===
myAccountWithMyPrivateKey.privateKey}`,
)
}
encryptAndDecrypt(myStrongPassword)
// suppose we have keyStorefile, in this example, we just use same password and keystore string encrypted above
const someKeyStoreFile =
'{"version":3,"id":"62326332-3139-4839-b534-656134623066","address":"1fe3da351d9fc0c4f02de5412ad7def8aee956c5","Crypto":{"ciphertext":"b86ab81682c9f5a35738ad9bd38cd9b46c1b852ef33f16dd83068f79e20d5531","cipherparams":{"iv":"44efb5a514f34968e92cafad80566487"},"cipher":"aes-128-ctr","kdf":"scrypt","kdfparams":{"salt":"d70ae1f311601562113f98c8ebe382f52a332dca1588886e5ea91e2f8a647134","n":8192,"r":8,"p":1,"dklen":32},"mac":"7b63e4e31a75a22b7091291bb58302655b738539ef3e30b30a7a7f170f6163ef"}}'
async function importKeyStoreFileAndDecrypt(keyStoreFile, password) {
// import keyStore string and provide the password, remember to make a new Account first
const importedAccount = await Account.new().fromFile(keyStoreFile, password)
// the account should decypted which `Account.encrypted` is false
console.log(`Is this account encrypted? \n ${importedAccount.encrypted}`)
// see if the privatekey is equal to unencrypted one?
console.log(
`Is the account recovered from keystore? \n ${importedAccount.privateKey === myPrivateKey}`,
)
}
importKeyStoreFileAndDecrypt(someKeyStoreFile, myStrongPassword)
Creating account using private key and custom messenger
```javascript
* const account = new Account(
* '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e',
* new Messenger(
* new HttpProvider('https://api.s0.b.hmny.io'),
* ChainType.Harmony,
* ChainID.HmyTestnet,
* ),
* );
```
### Address format getter
```typescript
// import the Account class
import {Account} from '@harmony-js/account'
// suppose we have an account
const myPrivateKey = '0xe19d05c5452598e24caad4a0d85a49146f7be089515c905ae6a19e8a578a6930'
const myAccountWithMyPrivateKey = new Account(myPrivateKey)
// Account.address is bytes20/base16 address
console.log(myAccountWithMyPrivateKey.address)
// Account.bech32Address is bech32 format address, in Harmony, it's `one1` prefixed
console.log(myAccountWithMyPrivateKey.bech32Address)
// Account.bech32TestNetAddress is bech32 format address, in Harmony, it's `tone1` prefixed, used in testnet
console.log(myAccountWithMyPrivateKey.bech32TestNetAddress)
// Account.checksumAddress is checksumed address from base16
console.log(myAccountWithMyPrivateKey.checksumAddress)
Creating account and setting custom messenger
```javascript
// uses by default http://localhost:9500 as messenger
* const account = new Account();
* const customMessenger = new Messenger(
* new HttpProvider('https://api.s0.b.hmny.io'),
* ChainType.Harmony,
* ChainID.HmyTestnet,
* );
account.setMessenger(customMessenger);
```
Storing the account data to keystore file
```javascript
* const passphrase = '';
* const account = new Account('45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e');
* account.toFile(passphrase).then(keystore => {
* console.log(keystore);
* });
```
### Sign a transaction
```typescript
// import the Account class
import {Account} from '@harmony-js/account'
// import Transaction class from '@harmony-js/transaction'
import {Transaction} from '@harmony-js/transaction'
// Messenger is optional, by default, we have a defaultMessenger
// If you like to change, you will import related package here.
import { HttpProvider, Messenger } from '@harmony-js/network';
import { ChainType, ChainID, Unit } from '@harmony-js/utils';
// create a custom messenger
const customMessenger = new Messenger(
new HttpProvider('http://localhost:9500'),
ChainType.Harmony, // if you are connected to Harmony's blockchain
ChainID.HmyLocal, // check if the chainId is correct
)
// suppose we have an account
const myPrivateKey = '0xe19d05c5452598e24caad4a0d85a49146f7be089515c905ae6a19e8a578a6930'
const myAccountWithMyPrivateKey = new Account(myPrivateKey)
const txnObject = {
// token send to
to: 'one166axnkjmghkf3df7xfvd0hn4dft8kemrza4cd2',
// amount to send
value: '1000000000000000000000',
// gas limit, you can use string or use BN value
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 Unit('100').asGwei().toWei(),
// if you set nonce manually here, and remember, the `updateNonce` of `Account.signTransaction` should be set to false
nonce: 0,
};
Fetching account from keystore file
```javascript
* const passphrase = '';
* const keystore = '{"version":3,"id":"33363566-3564-4264-a638-363531666335","address":"7c41e0668b551f4f902cfaec05b5bdca68b124ce","crypto":{"ciphertext":"9b09380afb742838b32d9afc0ec1a3df35dbd7a41e3a160d08c07a4d0e79b855","cipherparams":{"iv":"1cd0e0522260eef055b9170f4825f4a0"},"cipher":"aes-128-ctr","kdf":"scrypt","kdfparams":{"salt":"bf35e36c45cccefcef73a4c900f41c682c94c28630d94d2d1f764760d245f30b","n":8192,"r":8,"p":1,"dklen":32},"mac":"25b4442972356bea02af57eba3b87803086d90b5e7657a57b528b89b1aa25f2f"}}';
* const account = new Account();
* account.fromFile(keystore, passphrase).then(account => {
* console.log(account.bech32Address);
* });
```
const txn = new Transaction(txnObject, customMessenger);
Get the account balance
```javascript
* const account = new Account(
* '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e',
* new Messenger(
* new HttpProvider('https://api.s0.b.hmny.io'),
* ChainType.Harmony,
* ChainID.HmyTestnet,
* ),
* );
* account.getBalance().then(response => {
* console.log(response);
* });
```
outputs `{ balance: '9126943763247054940484', nonce: 45, shardID: 0 }`
async function signTheTxn() {
// Account.signTransaction(transaction: Transaction, updateNonce?: boolean, encodeMode?: string, blockNumber?: string): Promise<Transaction>
// If the 2nd parameter `updateNonce` is set to true, it will query and update account's nonce before it signs
const signedTxn = await myAccountWithMyPrivateKey.signTransaction(txn, false, 'rlp', 'latest');
Create a transaction and account, and sign it
```javascript
* const account = new Account(
* '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e',
* new Messenger(
* new HttpProvider('https://api.s0.b.hmny.io'),
* ChainType.Harmony,
* ChainID.HmyTestnet,
* ),
* );
* const { TransactionFactory } = require('@harmony-js/transaction');
* const { Unit } = require('@harmony-js/utils');
* const factory = new TransactionFactory();
* const txn = factory.newTx({
* to: 'one166axnkjmghkf3df7xfvd0hn4dft8kemrza4cd2',
* value: new Unit(1).asOne().toWei(),
* // gas limit, you can use string
* gasLimit: '21000',
* // 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 Unit('1').asGwei().toWei(),
* });
* account.signTransaction(txn).then((signedTxn) => {
* console.log(signedTxn);
* });
```
// see if the transaction is signed
console.log(`\n see if transaction is signed: \n ${signedTxn.isSigned()} \n`);
Similarily staking transactions can be created and signed using account.
// get the tranaction bytes
console.log(`\n the signed bytes is: \n ${signedTxn.getRawTransaction()} \n`);
A wallet represents user wallet that can hold one or more user accounts.
return signTheTxn;
}
Creating an empty wallet
```javascript
* const { Wallet } = require('@harmony-js/account')
* const wallet = new Wallet();
```
signTheTxn();
Setting a messenger to be used to send wallet transactions
```javascript
* wallet.setMessenger(
* new Messenger(
* new HttpProvider('https://api.s0.b.hmny.io'),
* ChainType.Harmony,
* ChainID.HmyTestnet,
* ),
* );
```
Create an empty wallet with messenger
```javascript
* const wallet = new Wallet(
* new Messenger(
* new HttpProvider('https://api.s0.b.hmny.io'),
* ChainType.Harmony,
* ChainID.HmyTestnet,
* ),
* );
```
## Usage of Wallet
An account could be added to a wallet using different ways. Adding account using mnemonics
```javascript
const mnemonics = 'horse distance dry brother pretty manual chicken mushroom town swim prize clutch';
const account = wallet.addByMnemonic(mnemonics);
```
### Dependencies
- @harmony-js/crypto
- @harmony-js/network
- @harmony-js/staking
- @harmony-js/transaction
- @harmony-js/utils
Adding account using private key
```javascript
const account = wallet.addByPrivateKey('0x676cd9773dd23a4c1d7f22767c61c7b6723cc6be37b078545f6e0e91433a23dd')
```
```typescript
// constructor
const { Wallet } = require('@harmony-js/account');
const wallet = new Wallet(customMessenger);
Adding account using keystore file
```javascript
* const keystore = '{"version":3,"id":"33363566-3564-4264-a638-363531666335","address":"7c41e0668b551f4f902cfaec05b5bdca68b124ce","crypto":{"ciphertext":"9b09380afb742838b32d9afc0ec1a3df35dbd7a41e3a160d08c07a4d0e79b855","cipherparams":{"iv":"1cd0e0522260eef055b9170f4825f4a0"},"cipher":"aes-128-ctr","kdf":"scrypt","kdfparams":{"salt":"bf35e36c45cccefcef73a4c900f41c682c94c28630d94d2d1f764760d245f30b","n":8192,"r":8,"p":1,"dklen":32},"mac":"25b4442972356bea02af57eba3b87803086d90b5e7657a57b528b89b1aa25f2f"}}';
* const passphrase = '';
* wallet.addByKeyStore(keystore, passphrase).then(account => {
* console.log(account.bech32Address);
* });
```
// get signer
const wallet = new Wallet(customMessenger);
const key_1 = '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e';
console.log(wallet.addByPrivateKey(key_1));
console.log(wallet.signer)
Creating a new account using passphrase
```javascript
* const passphrase = 'harmony-one';
* wallet.createAccount(passphrase).then(account => {
* console.log(account.bech32Address);
* });
```
// createAccount
console.log(wallet.accounts);
wallet.createAccount();
wallet.createAccount();
console.log(wallet.accounts);
Get all accounts in the wallet
```javascript
* wallet.accounts.forEach(addr => {
* const account = wallet.getAccount(addr);
* console.log(account.bech32Address);
* });
```
// encryptAccount
const key_1 = '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e';
wallet.addByPrivateKey(key_1);
wallet.encryptAccount('one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7', '12345').then((value) => {
console.log(value);
})
Set wallet signer when multiple accounts exists in the wallet
```javascript
wallet.setSigner(signerAddr);
```
// decrptAccount
const key_1 = '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e';
wallet.addByPrivateKey(key_1);
wallet.encryptAccount('one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7', '12345').then(() => {
wallet.decryptAccount('one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7', '12345').then((value) => {
console.log(value);
})
});
Sign transaction using wallet, will sign the transaction using the wallet signer
```javascript
* const txn = factory.newTx({
* to: 'one166axnkjmghkf3df7xfvd0hn4dft8kemrza4cd2',
* value: new Unit(1).asOne().toWei(),
* // gas limit, you can use string
* gasLimit: '21000',
* // 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 Unit('1').asGwei().toWei(),
* });
* wallet.signTransaction(txn).then((signedTxn) => {
* console.log(signedTxn);
* });
```
Similarily staking transactions can be signed using `signStaking` api.
*
* @packageDocumentation
* @module harmony-account

@ -1,110 +1,151 @@
/**
* ## About this package
*
* `@harmony-js/contract` makes it easy to interact with smart contract on the Harmony Blockchain. This allows you to interact with smart contracts as if they were JavaScript objects.
*
* ## How to use this package
*
* ### Deploy a contract to blockchain
* ```javascript
* // Step 1: Use Solidity to build a sample contract instance
* contract Inbox {
* string public message;
* constructor() public {
* message = "hello";
* }
* function setMessage(string memory newMessage) public {
* message = newMessage;
* }
* }
*
* // Step 2: Use truffle to compile the contract
* $ truffle compile
*
* // Step 3: Use truffle to deploy the contract (by truffle)
* $ truffle migrate --network local --reset
* $ truffle migrate --network testnet --reset
* ```
* [Tutorial: using truffle to compile and deploy smart-contract](https://github.com/harmony-one/HRC/tree/master/examples/dapp_Lottery)
*
* ### Interact with the contract
* ```javascript
* // Step 1: create a harmony instance
* const { Harmony } = require('@harmony-js/core');
* const { ChainID, ChainType } = require('@harmony-js/utils');
* const hmy = new Harmony(
* // let's assume we deploy smart contract to this end-point URL
* 'https://api.s0.b.hmny.io'
* {
* chainType: ChainType.Harmony,
* chainId: ChainID.HmyLocal,
* }
* )
*
* // Step 2: get a contract instance
* const getContractInstance = (hmy, artifact) => {
* return hmy.contracts.createContract(artifact.abi, address);
* }
* const inbox = getContractInstance(hmy, inboxJson)
*
* // Step 3: interact with the instance
* // Example 1: methods.myMethod.call()
* const message = await inbox.methods.message().call();
* console.log(message);
*
* // Example 2: methods.myMethod.send()
* inbox.methods.setMessage('666').send({
* gasLimit: '1000001',
* gasPrice: new hmy.utils.Unit('10').asGwei().toWei(),
* });
* ```
*
* ### Integrate MathWallet
* Using MathWallet to sign Transaction
* ```javascript
* // Step 0: set up MathWallet extension on Chrome
*
* // Step 1: Create a harmonyExtension instance
* const { Harmony, HarmonyExtension } = require('@harmony-js/core');
* let hmyEx, ExContract;
* export const initExtension = async() => {
* hmyEx = await new HarmonyExtension(window.harmony);
*
* exContract = hmyEx.contracts.createContract(abi, address);
* return exContract;
* };
*
* // Step 2: interact with hmyEx instance
* // wait for hmy inject into window
* async componentDidMount() {
* ...
* await waitForInjected()
* ...
* }
* // Example: methods.myMethod.send()
* onSubmit = async event => {
* const exContract = await initExtension()
* await exContract.methods.Mymethod().send({
* value: new hmy.utils.Unit('1').asOne().toWei(),
* })
* }
*
* // wait for injected
* export const waitForInjected = () => new Promise((resolve) => {
* const check = () => {
* if (!window.harmony) setTimeout(check, 250);
* else resolve(window.harmony);
* }
* check();
* });
* ```
*
* ## [More Examples: HRC repo](https://github.com/harmony-one/HRC/tree/master/examples)
* - Lottery
* - HRC 20
* - HRC 721
* - Node-dao
* - Node-faucet
# @harmony-js/contract
This package provides a collection of apis to create, deploy, and interact with smart contracts. In Harmony, smart contracts all fully EVM compatible and the formats and terminologies match 1-to-1 with EVM smart contracts.
## Installation
```
npm install @harmony-js/contract
```
## Usage
Deploying a contract using `contractConstructor`
```javascript
const { ContractFactory } = require('@harmony-js/contract');
const { Wallet } = require('@harmony-js/account');
const { Messenger, HttpProvider } = require('@harmony-js/network');
const { ChainID, ChainType, hexToNumber } = require('@harmony-js/utils');
* const wallet = new Wallet(
* new Messenger(
* new HttpProvider('https://api.s0.b.hmny.io'),
* ChainType.Harmony,
* ChainID.HmyTestnet,
* ),
* );
* const factory = new ContractFactory(wallet);
* const contractJson = require("./Counter.json");
* const contract = factory.createContract(contractJson.abi);
* const options1 = { gasPrice: '0x3B9ACA00' }; // gas price in hex corresponds to 1 Gwei or 1000000000
* let options2 = { gasPrice: 1000000000, gasLimit: 21000 }; // setting the default gas limit, but changing later based on estimate gas
* const options3 = { data: contractJson.bytecode }; // contractConstructor needs contract bytecode to deploy
* contract.wallet.addByPrivateKey('1f054c21a0f57ebc402c00e14bd1707ddf45542d4ed9989933dbefc4ea96ca68');
* contract.methods.contractConstructor(options3).estimateGas(options1).then(gas => {
* options2 = {...options2, gasLimit: hexToNumber(gas)};
* contract.methods.contractConstructor(options3).send(options2).then(response => {
* console.log('contract deployed at ' + response.transaction.receipt.contractAddress);
* });
* });
```
Instead of `contract.methods.contractConstructor`, `contract.deploy` could be used and it will work.
Loading a contract object using the contract json and contract address for interacting with it
```javascript
* const { Harmony } = require("@harmony-js/core");
* const { ChainID, ChainType } = require("@harmony-js/utils");
* const hmy = new Harmony("https://api.s0.b.hmny.io", {
* chainType: ChainType.Harmony,
* chainId: ChainID.HmyTestnet,
* });
const contractJson = require("./Counter.json");
const contractAddr = "0x19f64050e6b2d376e52AC426E366c49EEb0724B1";
const contract = hmy.contracts.createContract(contractJson.abi, contractAddr);
console.log(contract.methods);
```
Directly loading contract using `ContractFactory`
```javascript
const { ContractFactory } = require('@harmony-js/contract');
const { Wallet } = require('@harmony-js/account');
const { Messenger, HttpProvider } = require('@harmony-js/network');
const { ChainID, ChainType, hexToNumber } = require('@harmony-js/utils');
* const wallet = new Wallet(new Messenger(
* new HttpProvider('https://api.s0.b.hmny.io'),
* ChainType.Harmony,
* ChainID.HmyTestnet,
* ));
const factory = new ContractFactory(wallet);
const contract = factory.createContract(contractJson.abi, contractAddr);
```
Estimate gas for contract methods
```javascript
* const options1 = { gasPrice: '0x3B9ACA00' }; // gas price in hex corresponds to 1 Gwei or 1000000000
* contract.methods.getCount().estimateGas(options1).then(gas => {
* console.log('gas required for getCount is ' + hexToNumber(gas));
* });
```
Call contract read-only methods. Harmony uses 1 Gwei gas price and gas limit of 21000 by default. Use the estimate gas api to correctly set the gas limit.
```javascript
* const options1 = { gasPrice: '0x3B9ACA00' }; // gas price in hex corresponds to 1 Gwei or 1000000000
* let options2 = { gasPrice: 1000000000, gasLimit: 21000 }; // setting the default gas limit, but changing later based on estimate gas
* contract.methods.getCount().estimateGas(options1).then(gas => {
* options2 = {...options2, gasLimit: hexToNumber(gas)};
* contract.methods.getCount().call(options2).then(count => {
* console.log('counter value: ' + count);
* });
* });
```
Invoking contract modification methods using `send` api. Need to add a signing account to the contract wallet, otherwise `send` api will not work.
```javascript
* const options1 = { gasPrice: '0x3B9ACA00' }; // gas price in hex corresponds to 1 Gwei or 1000000000
* let options2 = { gasPrice: 1000000000, gasLimit: 21000 }; // setting the default gas limit, but changing later based on estimate gas
* contract.wallet.addByPrivateKey('1f054c21a0f57ebc402c00e14bd1707ddf45542d4ed9989933dbefc4ea96ca68');
* contract.methods.incrementCounter().estimateGas(options1).then(gas => {
* options2 = {...options2, gasLimit: hexToNumber(gas)};
* contract.methods.incrementCounter().send(options2).then(response => {
* console.log(response.transaction.receipt);
* });
* });
```
All the above apis can also be asynchronously executed using `async` and `await`.
Subscribing to the contract events requires web socket based messenger.
```javascript
* const { ContractFactory } = require('@harmony-js/contract');
* const { Wallet } = require('@harmony-js/account');
* const { Messenger, WSProvider } = require('@harmony-js/network');
* const { ChainID, ChainType, hexToNumber } = require('@harmony-js/utils');
* const ws = new WSProvider('wss://ws.s0.b.hmny.io');
* const wallet = new Wallet(
* new Messenger(
* ws,
* ChainType.Harmony,
* ChainID.HmyTestnet,
* ),
* );
* const factory = new ContractFactory(wallet);
* const contractJson = require("./Counter.json");
* const contractAddr = '0x8ada52172abda19b9838eb00498a40952be6a019';
* const contract = factory.createContract(contractJson.abi, contractAddr);
* contract.events
* .IncrementedBy()
* .on('data', (event) => {
* console.log(event);
* })
* .on('error', console.error);
```
*
* @packageDocumentation
* @module harmony-contract

@ -1,83 +1,168 @@
/**
* ## About this package
*
* `@harmony-js/core` is collection of modules to guide user to interacte with harmony blockchian.
*
* Develops can use this package to:
* - Create a `harmony` instance
* - Create a `harmonyExtension` instance, which support fo `MathWallet`
* - Get block and transaction by hash or blocknumber
* - Send transaction
* - Get balance of address
*
* ## How to use `@harmony-core`
* ### Dependencies
* - @harmony-js/core
* - @harmony-js/utils
*
* ### Step 1: Initialize the Harmony instance
* Before using harmony-core package, you should initialize the Harmony instance
* ```javascript
* // import or require Harmony class
* const { Harmony } = require('@harmony-js/core');
* // import or require settings
* const { ChainID, ChainType } = require('@harmony-js/utils');
*
* // initialize the Harmony instance
* const hmy = new Harmony(
* // rpc url
* 'https://api.s0.b.hmny.io/',
* {
* // chainType set to Harmony
* chainType: ChainType.Harmony,
* // chainType set to HmyLocal
* chainId: ChainID.HmyLocal,
* },
* );
* ```
*
* ### Step 2: Use the instance to call specific functions
* Example 1: get balance
* ```javascript
* // get balance
* hmy.blockchain.getBalance({
* address: 'one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7',
* blockNumber: 'latest'
* }).then((value) => {
* console.log(value.result);
* });
* ```
*
* Example 2: send transaction
* ```
* // add privateKey to wallet
* const privateKey = '45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e';
* hmy.wallet.addByPrivateKey(privateKey);
*
* async function transfer() {
* const txn = hmy.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 hmy.utils.Unit('100').asGwei().toWei(),
* });
*
* // sign the transaction use wallet;
* const signedTxn = await hmy.wallet.signTransaction(txn);
* const txnHash = await hmy.blockchain.sendTransaction(signedTxn);
* console.log(txnHash.result);
* }
*
* transfer();
* ```
# @harmony-js/core
This package provides a collection of apis to interact with Harmony blockchain.
## Installation
```
npm install @harmony-js/core
```
## Usage
Create a Harmony instance connecting to testnet
```javascript
* const { Harmony } = require('@harmony-js/core');
* const {
* ChainID,
* ChainType,
* hexToNumber,
* numberToHex,
* fromWei,
* Units,
* Unit,
* } = require('@harmony-js/utils');
* const hmy = new Harmony(
* 'https://api.s0.b.hmny.io/',
* {
* chainType: ChainType.Harmony,
* chainId: ChainID.HmyTestnet,
* },
* );
```
Getting balance of account `one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7`
```javascript
* hmy.blockchain
* .getBalance({ address: 'one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7' })
* .then((response) => {
* console.log('balance in ONEs: ' + fromWei(hexToNumber(response.result), Units.one));
* });
```
Getting the latest block number
```javascript
* hmy.blockchain.getBlockNumber().then((response) => {
* console.log('current block number: ' + hexToNumber(response.result));
* });
```
Getting the block using block hash
```javascript
* hmy.blockchain
* .getBlockByHash({
* blockHash: '0x08c46ae7249362a7d1f602d44c5a81f33ebdab6a7dcb6068f99610b57911aafd',
* })
* .then((response) => {
* console.log(response.result);
* });
```
Getting the block using block number
```javascript
* hmy.blockchain
* .getBlockByNumber({
* blockNumber: numberToHex(422635),
* })
* .then((response) => {
* console.log(response.result);
* });
```
Getting the transaction using hash
```javascript
* hmy.blockchain
* .getTransactionByHash({
* txnHash: '0x56c73eb993b18dc04baacec5c2e9d1292a090f6a978a4a1c461db5255fcbc831',
* })
* .then((response) => {
* console.log(response.result);
* });
```
Getting the transaction receipt
```javascript
* hmy.blockchain
* .getTransactionReceipt({
* txnHash: '0x56c73eb993b18dc04baacec5c2e9d1292a090f6a978a4a1c461db5255fcbc831',
* })
* .then((response) => {
* console.log(response.result);
* });
```
Getting the cross-shard transaction receipt
```javascript
* hmy.blockchain
* .getCxReceiptByHash({
* txnHash: '0xcd36a90ff5d5373285c2896ba7bbcd3f5324263c0cb8ecfb7cad2f5fc2fbdbda',
* shardID: 1,
* })
* .then((value) => {
* console.log(value.result);
* });
```
Getting the deployed smart contract code
```javascript
* hmy.blockchain
* .getCode({
* address: '0x08AE1abFE01aEA60a47663bCe0794eCCD5763c19',
* blockNumber: 'latest',
* })
* .then((response) => {
* console.log(response.result);
* });
```
Getting the transaction count of an account
```javascript
* hmy.blockchain
* .getTransactionCount({
* address: 'one1pdv9lrdwl0rg5vglh4xtyrv3wjk3wsqket7zxy',
* })
* .then((response) => {
* console.log(hexToNumber(response.result));
* });
```
Getting the shard structure and details
```javascript
* hmy.blockchain.getShardingStructure().then((response) => {
* console.log(response.result);
* });
```
Transferring funds using `sendTransaction`
```javascript
// key corresponds to one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7, only has testnet balance
* hmy.wallet.addByPrivateKey('45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e');
* async function transfer() {
* const txn = hmy.transactions.newTx({
* to: 'one166axnkjmghkf3df7xfvd0hn4dft8kemrza4cd2',
* value: new Unit(1).asOne().toWei(),
* // gas limit, you can use string
* gasLimit: '21000',
* // 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 hmy.utils.Unit('1').asGwei().toWei(),
* });
* // sign the transaction use wallet;
* const signedTxn = await hmy.wallet.signTransaction(txn);
* const txnHash = await hmy.blockchain.sendTransaction(signedTxn);
* console.log(txnHash.result);
* }
* transfer();
```
*
* @packageDocumentation
* @module harmony-core

@ -1,65 +1,79 @@
/**
* ## About this package
*
* `@harmony-js/crypot` provides a series of functions to deal with keys
*
* ## How to use this package
*
* ### Create a Harmony Instance
* ```javascript
* const { Harmony } = require('@harmony-js/core');
* const { ChainID, ChainType } = require('@harmony-js/utils');
*
* const hmy = new Harmony(
* 'http://localhost:9500',
* {
* chainType: ChainType.Harmony,
* chainId: ChainID.HmyLocal,
* },
* );
* ```
*
* ### Some examples
*
* ```javascript
* // randomBytes
* const bytes = hmy.crypto.randomBytes(20);
* console.log(bytes)
*
* // encryptPhrase
* const myPhrase = hmy.wallet.newMnemonic();
* const pwd = '1234';
* hmy.crypto.encryptPhrase(myPhrase, pwd).then((value) => {
* console.log(value);
* })
*
* // decryptThePhrase
* hmy.crypto.encryptPhrase(myPhrase, pwd).then((keystore) => {
* hmy.crypto.decryptPhrase(JSON.parse(keystore), pwd).then((value) => {
* console.log(value);
* })
* })
*
* // generatePrivateKey
* const privateKey = hmy.crypto.generatePrivateKey();
* console.log(privateKey)
*
* // getPubkeyFromPrivateKey
* const publicKey = hmy.crypto.getPubkeyFromPrivateKey(privateKey);
* console.log(publicKey);
*
* // getAddressFromPrivateKey
* const address = hmy.crypto.getAddressFromPrivateKey(privateKey);
* console.log(address);
*
* // getAddressFromPublicKey
* const address = hmy.crypto.getAddressFromPublicKey(publicKey);
* console.log(address);
*
* // toChecksumAddress
* const checksumAddr = hmy.crypto.toChecksumAddress(address);
* console.log(checksumAddr);
* ```
# @harmony-js/crypto
This package provides a collection of apis related to address management, kestore, encoding, and encrypt/decrypt.
## Installation
```
npm install @harmony-js/crypto
```
## Usage
```javascript
* const {
* encode,
* decode,
* randomBytes,
* toBech32,
* fromBech32,
* HarmonyAddress,
* generatePrivateKey,
* getPubkeyFromPrivateKey,
* getAddressFromPublicKey,
* getAddressFromPrivateKey,
* encryptPhrase,
* decryptPhrase
* } = require('@harmony-js/crypto');
* const { isPrivateKey, isAddress, isPublicKey } = require('@harmony-js/utils');
```
Address apis
```javascript
const bytes = randomBytes(20);
const addr = new HarmonyAddress(bytes);
console.log(addr.checksum);
console.log(addr.bech32);
console.log(HarmonyAddress.isValidBech32(addr.bech32));
```
RLP apis
```javascript
const encoded = '0x89010101010101010101';
const decoded = '0x010101010101010101';
console.log(encode(decoded));
console.log(decode(encoded));
```
Keystore apis
```javascript
const prv = generatePrivateKey();
const pub = getPubkeyFromPrivateKey(prv);
const addr = getAddressFromPublicKey(pub);
const addrPrv = getAddressFromPrivateKey(prv);
console.log(isPrivateKey(prv));
console.log(isPublicKey(pub));
console.log(isAddress(addr));
console.log(isAddress(addrPrv));
```
Encrypt/decrypt apis
```javascript
* const { Wallet } = require('@harmony-js/account');
* const myPhrase = new Wallet().newMnemonic();
* console.log(myPhrase);
* const pwd = '1234';
* encryptPhrase(myPhrase, pwd).then((value) => {
* console.log(value);
* decryptPhrase(JSON.parse(value), pwd).then(value => {
* console.log(value);
* });
* });
```
*
* @packageDocumentation
* @module harmony-crypto

@ -1,22 +1,28 @@
/**
* ## About this package
*
* `@harmony-js/network` provides functions to handle messenger, providers and subscriptions...
*
* ## How to use this package
*
* ### 1. Create a Message
* ```javascript
* const { HttpProvider, Messenger } = require('@harmony-js/network');
* const { ChainType, ChainID } = require('@harmony-js/utils');
*
* // create a custom messenger
* const customMessenger = new Messenger(
* new HttpProvider('http://localhost:9500'),
* ChainType.Harmony, // if you are connected to Harmony's blockchain
* ChainID.HmyLocal, // check if the chainId is correct
* )
* ```
# @harmony-js/network
This package provides a collection of apis to create messengers (HTTP, WebSocket) to connect to blockchain networks.
## Installation
```
npm install @harmony-js/network
```
## Usage
```javascript
const { Messenger, HttpProvider, WSProvider } = require('@harmony-js/network');
const { ChainID, ChainType } = require('@harmony-js/utils');
const testnetHTTP = 'https://api.s0.b.hmny.io';
const testnetWS = 'wss://ws.s0.b.hmny.io';
const localHTTP = 'http://localhost:9500/';
const localWS = 'http://localhost:9800/';
const http = new HttpProvider(testnetHTTP); // for local use localHTTP
const ws = new WSProvider(testnetWS); // for local use testnetWS
const customHTTPMessenger = new Messenger(http, ChainType.Harmony, ChainID.HmyTestnet); // for local ChainID.HmyLocal
const customWSMessenger = new Messenger(ws, ChainType.Harmony, ChainID.HmyTestnet); // for local ChainID.HmyLocal
```
*
* @packageDocumentation
* @module harmony-network

@ -1,4 +1,93 @@
/**
* # @harmony-js/staking
This package provides a collection of apis to create, sign/send staking transaction, and receive confirm/receipt.
## Installation
```
npm install @harmony-js/staking
```
## Usage
Create a Harmony instance connecting to testnet
```javascript
* const { Harmony } = require('@harmony-js/core');
* const {
* ChainID,
* ChainType,
* hexToNumber,
* numberToHex,
* fromWei,
* Units,
* Unit,
* } = require('@harmony-js/utils');
* const hmy = new Harmony(
* 'https://api.s0.b.hmny.io/',
* {
* chainType: ChainType.Harmony,
* chainId: ChainID.HmyTestnet,
* },
* );
```
Below, examples show how to send delegate, undelegate, and collect rewards staking transactions. First, set the chainId, gasLimit, gasPrice for all subsequent staking transactions
```javascript
* hmy.stakings.setTxParams({
* gasLimit: 25000,
* gasPrice: numberToHex(new hmy.utils.Unit('1').asGwei().toWei()),
* chainId: 2
* });
```
<span style="color:red">Note: create and edit validator transactions are not fully supported in the sdk</span>
Create delegate staking transaction
```javascript
* const delegate = hmy.stakings.delegate({
* delegatorAddress: 'one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7',
* validatorAddress: 'one1vfqqagdzz352mtvdl69v0hw953hm993n6v26yl',
* amount: numberToHex(new Unit(1000).asOne().toWei())
* });
* const delegateStakingTx = delegate.build();
```
Sign and send the delegate transaction and receive confirmation
```javascript
* // key corresponds to one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7, only has testnet balance
* hmy.wallet.addByPrivateKey('45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e');
* hmy.wallet.signStaking(delegateStakingTx).then(signedTxn => {
* signedTxn.sendTransaction().then(([tx, hash]) => {
* console.log(hash);
* signedTxn.confirm(hash).then(response => {
* console.log(response.receipt);
* });
* });
* });
```
Similarily, undelegate and collect reward transactions can be composed, signed and sent
Create undelegate staking transaction
```javascript
* const undelegate = hmy.stakings.undelegate({
* delegatorAddress: 'one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7',
* validatorAddress: 'one1vfqqagdzz352mtvdl69v0hw953hm993n6v26yl',
* amount: numberToHex(new Unit(1000).asOne().toWei())
* });
* const undelegateStakingTx = undelegate.build();
```
Create collect rewards staking transaction
```javascript
* const collectRewards = hmy.stakings.collectRewards({
* delegatorAddress: 'one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7'
* });
* const collectRewardsStakingTx = collectRewards.build();
```
Also, similar to normal transaction, signing and sending can be performed asynchronously.
* @packageDocumentation
* @module harmony-staking
*/

@ -1,84 +1,152 @@
/**
* ## About this package
*
* `@harmony-js/transaction` provides the functions to build transactions
*
* Develop can use this package to:
* - build a transaction offline!
* - set params of transaction
* -
*
* ## How to use this package
* ### Step 1: create a Harmony Instance
* ```javascript
* const { Harmony } = require('@harmony-js/core');
* const { ChainID, ChainType } = require('@harmony-js/utils');
* const { BN } = require('@harmony-js/crypto');
*
* const hmy = new Harmony(
* 'http://localhost:9500',
* {
* chainType: ChainType.Harmony,
* chainId: ChainID.HmyLocal,
* },
* );
* ```
*
* ### Step 2: build a transaction
* ```javascript
* const txn = hmy.transactions.newTx({
* to: 'one166axnkjmghkf3df7xfvd0hn4dft8kemrza4cd2',
* value: '10000',
* gasLimit: '210000',
* shardID: 0,
* toShardID: 0,
* gasPrice: new hmy.utils.Unit('100').asGwei().toWei(),
* });
* ```
*
* ## some important information
* Transaction Parameters
* ```java
* // interface TxParams
* id: string;
* from: string;
* to: string;
* nonce: number | string;
* gasLimit: number | string | BN;
* gasPrice: number | string | BN;
* shardID: number | string;
* toShardID: number | string;
* data: string;
* value: number | string | BN;
* chainId: number;
* rawTransaction: string;
* unsignedRawTransaction: string;
* signature: Signature;
* receipt?: TransasctionReceipt;
* ```
*
* Transaction Receipt
* ```java
* // interface TransasctionReceipt
* transactionHash: string;
* transactionIndex: string;
* blockHash: string;
* blockNumber: string; // 11
* from: string;
* to: string;
* gasUsed: string;
* cumulativeGasUsed: string; // 13244
* contractAddress?: string | null; // or null, if none was created
* logs: any[];
* logsBloom: string; // 256 byte bloom filter
* v: string;
* r: string;
* s: string;
* responseType?: string;
* byzantium?: boolean;
* status?: string; // post Byzantium will return `0x0` or `0x1`
* root?: string; // pre Byzantium will return `root`
* ```
# @harmony-js/transaction
This package provides a collection of apis to create, sign/send transaction, and receive confirm/receipt.
## Installation
```
npm install @harmony-js/transaction
```
## Usage
Create a Harmony instance connecting to testnet
```javascript
* const { Harmony } = require('@harmony-js/core');
* const {
* ChainID,
* ChainType,
* hexToNumber,
* numberToHex,
* fromWei,
* Units,
* Unit,
* } = require('@harmony-js/utils');
* const hmy = new Harmony(
* 'https://api.s0.b.hmny.io/',
* {
* chainType: ChainType.Harmony,
* chainId: ChainID.HmyTestnet,
* },
* );
```
Creating a new transaction using parameters
```javascript
* const txn = hmy.transactions.newTx({
* to: 'one166axnkjmghkf3df7xfvd0hn4dft8kemrza4cd2',
* value: new Unit(1).asOne().toWei(),
* // gas limit, you can use string
* gasLimit: '21000',
* // 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 hmy.utils.Unit('1').asGwei().toWei(),
* });
```
Recovering transaction from raw transaction hash
```javascript
* const raw = '0xf86d21843b9aca00825208808094d6ba69da5b45ec98b53e3258d7de756a567b6763880de0b6b3a76400008028a0da8887719f377401963407fc1d82d2ab52404600cf7bea37c27bd2dfd7c86aaaa03c405b0843394442b303256a804bde835821a8a77bd88a2ced9ffdc8b0a409e9';
* const tx = hmy.transactions.recover(raw);
```
Getting the RLP encoding of a transaction (rawTransaction), along with raw transaction field values that were encoded
```javascript
* const [encoded, raw] = txn.getRLPUnsigned()
```
Sign the transaction using a wallet and send the transaction, wait for confirmation and print receipt
```javascript
* // key corresponds to one103q7qe5t2505lypvltkqtddaef5tzfxwsse4z7, only has testnet balance
* hmy.wallet.addByPrivateKey('45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e');
* hmy.wallet.signTransaction(txn).then(signedTxn => {
* signedTxn.sendTransaction().then(([tx, hash]) => {
* console.log('tx hash: ' + hash);
* signedTxn.confirm(hash).then(response => {
* console.log(response.receipt);
* });
* });
* });
```
Asynchronous transaction sign, send, and confirm
```javascript
* async function transfer() {
* hmy.wallet.addByPrivateKey('45e497bd45a9049bcb649016594489ac67b9f052a6cdf5cb74ee2427a60bf25e');
* const signedTxn = await hmy.wallet.signTransaction(txn);
* 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('');
* });
* const [sentTxn, txnHash] = await signedTxn.sendTransaction();
* 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('');
* console.log('please see detail in explorer:');
* console.log('');
* console.log('https://explorer.testnet.harmony.one/#/tx/' + txnHash);
* 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('');
* console.log('please see detail in explorer:');
* console.log('');
* console.log('https://explorer.testnet.harmony.one/#/tx/' + txnHash);
* console.log('');
* process.exit();
* }
* }
* transfer();
```
*
* @packageDocumentation
* @module harmony-transaction

@ -1,124 +1,64 @@
/**
* ## About this package
*
* `@harmony-js/util` provides utility functions for Harmony dapps and other `harmony-js` packages
*
* Develop can use this package to:
* - Transform the unit of token (fromWei, toWei...)
* - Convert variable to different type (hexToBN, numberToHex...)
* - Check validators information (isAddress, isPublicKey, isBlockNumber...)
*
* ## How to use this package
*
* ### Step 1: create a Harmony Instance
* ```javascript
* const { Harmony } = require('@harmony-js/core');
* const { ChainID, ChainType } = require('@harmony-js/utils');
* const { BN } = require('@harmony-js/crypto');
*
* const hmy = new Harmony(
* 'http://localhost:9500',
* {
* chainType: ChainType.Harmony,
* chainId: ChainID.HmyLocal,
* },
* );
* ```
*
* ### Step 2: Select and call functions
* Here are some examples:
*
* ```javascript
* // numberToString
* const num = 123;
* const str = hmy.utils.numberToString(num)
* console.log(str);
*
* // add0xToString
* const str = '12345';
* const expected = hmy.utils.add0xToString(str)
* console.log(expected);
*
* // fromWei
* const Wei = new BN('1000000000000000000');
* const expected = hmy.utils.fromWei(Wei, hmy.utils.Units.one);
* console.log(expected);
*
* // toWei
* const one = new BN('1');
* const expected = hmy.utils.toWei(one, hmy.utils.Units.one);
* const num = hmy.utils.numToStr(expected);
* console.log(num);
* ```
*
* ### Step 3: Using unit class to convet the token unit
* ```javascript
* // convert one to Gwei
* const one = new hmy.utils.Unit('1').asOne();
* const oneToGwei = one.toGwei();
* console.log(oneToGwei);
* ```
*
* ## Some Important consts and Enums
* ### Chain Type
* ```javascript
* Harmony = 'hmy',
* Ethereum = 'eth',
* ```
*
* ### Chain ID
* ```javascript
* Default = 0,
EthMainnet = 1,
Morden = 2,
Ropsten = 3,
Rinkeby = 4,
RootstockMainnet = 30,
RootstockTestnet = 31,
Kovan = 42,
EtcMainnet = 61,
EtcTestnet = 62,
Geth = 1337,
Ganache = 0,
HmyMainnet = 1,
HmyTestnet = 2,
HmyLocal = 2,
HmyPangaea = 3,
* ```
*
* ### Default Config
* ```javascript
* export const defaultConfig = {
* Default: {
* Chain_ID: ChainID.HmyLocal,
* Chain_Type: ChainType.Harmony,
* Chain_URL: 'http://localhost:9500',
* Network_ID: 'Local',
* },
* DefaultWS: {
* Chain_ID: ChainID.HmyLocal,
* Chain_Type: ChainType.Harmony,
* Chain_URL: 'ws://localhost:9800',
* Network_ID: 'LocalWS',
* },
* };
* ```
*
* ### Unit Map
* ```
* [Units.wei, '1'], // 1 wei
* [Units.Kwei, '1000'], // 1e3 wei
* [Units.Mwei, '1000000'], // 1e6 wei
* [Units.Gwei, '1000000000'], // 1e9 wei
* [Units.szabo, '1000000000000'], // 1e12 wei
* [Units.finney, '1000000000000000'], // 1e15 wei
* [Units.ether, '1000000000000000000'], // 1e18 wei
* [Units.one, '1000000000000000000'], // 1e18 wei
* [Units.Kether, '1000000000000000000000'], // 1e21 wei
* [Units.Mether, '1000000000000000000000000'], // 1e24 wei
* [Units.Gether, '1000000000000000000000000000'], // 1e27 wei
* [Units.Tether, '1000000000000000000000000000000'], // 1e30 wei
* ```
# @harmony-js/utils
This package provides a collection of utility apis for unit conversions like `fromWei`, `toWei`, `hexToNumber`, `numberToHex`, `isAddress`, etc.
## Installation
```
npm install @harmony-js/utils
```
## Usage
Available units
```
const { Units } = require('@harmony-js/utils');
[Units.wei, '1'], // 1 wei
[Units.Kwei, '1000'], // 1e3 wei
[Units.Mwei, '1000000'], // 1e6 wei
[Units.Gwei, '1000000000'], // 1e9 wei
[Units.szabo, '1000000000000'], // 1e12 wei
[Units.finney, '1000000000000000'], // 1e15 wei
[Units.ether, '1000000000000000000'], // 1e18 wei
[Units.one, '1000000000000000000'], // 1e18 wei
[Units.Kether, '1000000000000000000000'], // 1e21 wei
[Units.Mether, '1000000000000000000000000'], // 1e24 wei
[Units.Gether, '1000000000000000000000000000'], // 1e27 wei
[Units.Tether, '1000000000000000000000000000000'], // 1e30 wei
```
Converting between different units
```javascript
const { Units, Unit, numberToString, add0xToString, fromWei, toWei, numToStr} = require('@harmony-js/utils');
const { BN } = require('@harmony-js/crypto');
const one = new Unit('1').asOne();
const oneToGwei = one.toGwei();
console.log(oneToGwei);
// numberToString
const num = 123;
const str = numberToString(num)
console.log(str);
// add0xToString
const str = '12345';
const expected = add0xToString(str)
console.log(expected);
// fromWei
const Wei = new BN('1000000000000000000');
const expected = fromWei(Wei, Units.one);
console.log(expected);
// toWei
const one = new BN('1');
const expected = toWei(one, hmy.utils.Units.one);
const num = numToStr(expected);
console.log(num);
```
*
* @packageDocumentation
* @module harmony-utils

Loading…
Cancel
Save