From 1d37b68d793958fb97d7533321547f283c3faa52 Mon Sep 17 00:00:00 2001 From: Wen Zhang Date: Mon, 10 Feb 2020 19:31:41 -0800 Subject: [PATCH] Finished revamped the package: harmony-core --- package.json | 1 + packages/harmony-account/guide.ts | 2 + packages/harmony-contract/src/abi/abiCoder.ts | 1 + packages/harmony-contract/src/abi/api.ts | 1 + packages/harmony-contract/src/abi/index.ts | 1 + packages/harmony-contract/src/abi/utils.ts | 1 + packages/harmony-core/src/blockchain.ts | 17 +++ packages/harmony-core/src/harmony.ts | 121 ++++++++++++++++++ packages/harmony-core/src/harmonyExtension.ts | 86 +++++++++++-- packages/harmony-core/src/truffleProvider.ts | 13 +- 10 files changed, 220 insertions(+), 24 deletions(-) diff --git a/package.json b/package.json index 6a13ff1..d748d0f 100644 --- a/package.json +++ b/package.json @@ -127,6 +127,7 @@ "tslint-config-prettier": "^1.15.0", "typedoc": "^0.17.0-3", "typedoc-plugin-external-module-name": "^3.0.0", + "typedoc-plugin-no-inherit": "^1.1.10", "typescript": "^3.8.3", "typescript-json-schema": "^0.36.0", "webpack": "^4.20.2", diff --git a/packages/harmony-account/guide.ts b/packages/harmony-account/guide.ts index 6c46276..77531cb 100644 --- a/packages/harmony-account/guide.ts +++ b/packages/harmony-account/guide.ts @@ -259,4 +259,6 @@ The `Wallet` class is class that stores all `Account` instance, you can do CRUD * @packageDocumentation * @module harmony-account */ + +/**@ignore */ export interface README {} diff --git a/packages/harmony-contract/src/abi/abiCoder.ts b/packages/harmony-contract/src/abi/abiCoder.ts index a1fd7fb..d36cf61 100644 --- a/packages/harmony-contract/src/abi/abiCoder.ts +++ b/packages/harmony-contract/src/abi/abiCoder.ts @@ -1,4 +1,5 @@ /** + * * @packageDocumentation * @module harmony-contract */ diff --git a/packages/harmony-contract/src/abi/api.ts b/packages/harmony-contract/src/abi/api.ts index 1293e7c..9ec3cd5 100644 --- a/packages/harmony-contract/src/abi/api.ts +++ b/packages/harmony-contract/src/abi/api.ts @@ -1,6 +1,7 @@ /** * @packageDocumentation * @module harmony-contract + * @hidden */ import { AbiCoder as ABICoder, ParamType, toUtf8Bytes } from './abiCoder'; diff --git a/packages/harmony-contract/src/abi/index.ts b/packages/harmony-contract/src/abi/index.ts index eb7a6ca..e0d08dc 100644 --- a/packages/harmony-contract/src/abi/index.ts +++ b/packages/harmony-contract/src/abi/index.ts @@ -1,6 +1,7 @@ /** * @packageDocumentation * @module harmony-contract + * @hidden */ import { AbiCoderClass } from './api'; diff --git a/packages/harmony-contract/src/abi/utils.ts b/packages/harmony-contract/src/abi/utils.ts index c0433d0..5cab003 100644 --- a/packages/harmony-contract/src/abi/utils.ts +++ b/packages/harmony-contract/src/abi/utils.ts @@ -1,6 +1,7 @@ /** * @packageDocumentation * @module harmony-contract + * @hidden */ import { isObject, isArray } from '@harmony-js/utils'; diff --git a/packages/harmony-core/src/blockchain.ts b/packages/harmony-core/src/blockchain.ts index ea842f9..d660116 100644 --- a/packages/harmony-core/src/blockchain.ts +++ b/packages/harmony-core/src/blockchain.ts @@ -966,6 +966,23 @@ class Blockchain { return this.getRpcResult(result); } + /** + * Executes a message call transaction, + * which is directly executed in the VM of the node, but never mined into the blockchain. + * + * @param payload some data you want put into these fucntions + * @param blockNumber by default it's `latest` + * @param shardID `shardID` is binding with the endpoint, IGNORE it! + * + * @example + * ```javascript + * hmy.blockchain.call({ + * to: "0x08AE1abFE01aEA60a47663bCe0794eCCD5763c19", + * }).then((value) => { + * console.log(value); + * }); + * ``` + */ async call({ payload, blockNumber = DefaultBlockParams.latest, diff --git a/packages/harmony-core/src/harmony.ts b/packages/harmony-core/src/harmony.ts index a716639..7c47ee2 100644 --- a/packages/harmony-core/src/harmony.ts +++ b/packages/harmony-core/src/harmony.ts @@ -15,6 +15,7 @@ import { Blockchain } from './blockchain'; import { HarmonyConfig } from './util'; export class Harmony extends utils.HarmonyCore { + /**@ignore*/ Modules = { HttpProvider, WSProvider, @@ -28,17 +29,57 @@ export class Harmony extends utils.HarmonyCore { Account, Contract, }; + /**@ignore*/ messenger: Messenger; + /**@ignore*/ transactions: TransactionFactory; + /**@ignore*/ stakings: StakingFactory; + /**@ignore*/ wallet: Wallet; + /**@ignore*/ blockchain: Blockchain; + /**@ignore*/ contracts: ContractFactory; + /**@ignore*/ crypto: any; + /**@ignore*/ utils: any; + /**@ignore*/ defaultShardID?: number; + /**@ignore*/ private provider: HttpProvider | WSProvider; + /** + * Create a harmony instance + * + * @param url The end-points of the hmy blockchain + * @param config set up `ChainID` and `ChainType`, typically we can use the default values + * + * @example + * ``` + * // 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: + * // local: http://localhost:9500 + * // testnet: https://api.s0.b.hmny.io/ + * // mainnet: https://api.s0.t.hmny.io/ + * 'http://localhost:9500', + * { + * // chainType set to Harmony + * chainType: ChainType.Harmony, + * // chainType set to HmyLocal + * chainId: ChainID.HmyLocal, + * }, + * ); + * ``` + */ constructor( url: string, config: HarmonyConfig = { @@ -64,28 +105,106 @@ export class Harmony extends utils.HarmonyCore { this.setShardID(this.defaultShardID); } } + + /** + * Will change the provider for its module. + * + * @param provider a valid provider, you can replace it with your own working node + * + * @example + * ```javascript + * const tmp = hmy.setProvider('http://localhost:9500'); + * ``` + */ public setProvider(provider: string | HttpProvider | WSProvider): void { this.provider = new Provider(provider).provider; this.messenger.setProvider(this.provider); this.setMessenger(this.messenger); } + /** + * set the chainID + * + * @hint + * ``` + * 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 + * ``` + * @param chainId + * + * @example + * ``` + * hmy.setChainId(2); + * ``` + */ public setChainId(chainId: utils.ChainID) { this.chainId = chainId; this.messenger.setChainId(this.chainId); this.setMessenger(this.messenger); } + + /** + * Change the Shard ID + * + * @example + * ``` + * hmy.setShardID(2); + * ``` + */ public setShardID(shardID: number) { this.defaultShardID = shardID; this.messenger.setDefaultShardID(this.defaultShardID); this.setMessenger(this.messenger); } + + /** + * set the chainType + * + * @param chainType `hmy` or `eth` + * + * @example + * ``` + * // set chainType to hmy + * hmy.setChainType('hmy'); + * // set chainType to eth + * hmy.setChainType('eth'); + * ``` + */ public setChainType(chainType: utils.ChainType) { this.chainType = chainType; this.messenger.setChainType(this.chainType); this.setMessenger(this.messenger); } + /** + * Set the sharding Structure + * + * @param shardingStructures The array of information of sharding structures + * + * @example + * ```javascript + * hmy.shardingStructures([ + * {"current":true,"http":"http://127.0.0.1:9500", + * "shardID":0,"ws":"ws://127.0.0.1:9800"}, + * {"current":false,"http":"http://127.0.0.1:9501", + * "shardID":1,"ws":"ws://127.0.0.1:9801"} + * ]); + * ``` + */ public shardingStructures(shardingStructures: ShardingItem[]) { for (const shard of shardingStructures) { const shardID = @@ -99,6 +218,8 @@ export class Harmony extends utils.HarmonyCore { } this.setMessenger(this.messenger); } + + /**@ignore*/ private setMessenger(messenger: Messenger) { this.blockchain.setMessenger(messenger); this.wallet.setMessenger(messenger); diff --git a/packages/harmony-core/src/harmonyExtension.ts b/packages/harmony-core/src/harmonyExtension.ts index a0d5cf5..a5d923b 100644 --- a/packages/harmony-core/src/harmonyExtension.ts +++ b/packages/harmony-core/src/harmonyExtension.ts @@ -20,32 +20,24 @@ import { Blockchain } from './blockchain'; import { ContractFactory } from '@harmony-js/contract'; import { HarmonyConfig } from './util'; -/** - * @hidden - */ +/** @hidden */ export enum ExtensionType { MathWallet = 'MathWallet', } -/** - * @hidden - */ +/** @hidden */ export interface ExtensionAccount { address: 'string'; name: 'string'; } -/** - * @hidden - */ +/** @hidden */ export interface ExtensionNetwork { chain_url: string; net_version: number; } -/** - * @hidden - */ +/** @hidden */ export interface ExtensionInterface { signTransaction: ( transaction: Transaction, @@ -61,17 +53,41 @@ export interface ExtensionInterface { } export class HarmonyExtension { + /**@ignore*/ extensionType: ExtensionType | null; + /**@ignore*/ wallet: ExtensionInterface; + /**@ignore*/ provider: HttpProvider | WSProvider; + /**@ignore*/ messenger: Messenger; + /**@ignore*/ blockchain: Blockchain; + /**@ignore*/ transactions: TransactionFactory; + /**@ignore*/ contracts: ContractFactory; + /**@ignore*/ crypto: any; + /**@ignore*/ utils: any; + /**@ignore*/ defaultShardID?: number; + /** + * Create an blockchain instance support wallet injection + * + * @param wallet could be MathWallet instance + * @param config (optional), using default `Chain_Id` and `Chain_Type` + * + * @example + * ```javascript + * // Using Mathwallet instance + * export const initEx = async() => { + * hmyEx = await new HarmonyExtension(window.harmony); + * } + * ``` + */ constructor( wallet: ExtensionInterface, config: HarmonyConfig = { @@ -98,12 +114,31 @@ export class HarmonyExtension { this.crypto = crypto; this.utils = utils; } + + /** + * Will change the provider for its module. + * + * @param provider a valid provider, you can replace it with your own working node + * + * @example + * ```javascript + * const tmp = hmyEx.setProvider('http://localhost:9500'); + * ``` + */ public setProvider(provider: string | HttpProvider | WSProvider): void { this.provider = new Provider(provider).provider; this.messenger.setProvider(this.provider); this.setMessenger(this.messenger); } + /** + * Change the Shard ID + * + * @example + * ``` + * hmyEx.setShardID(2); + * ``` + */ public setShardID(shardID: number) { this.defaultShardID = shardID; this.messenger.setDefaultShardID(this.defaultShardID); @@ -156,12 +191,37 @@ export class HarmonyExtension { } return; } + + /** + * Get the wallet account + * + * @example + * ```javascript + * const account = hmyEx.login(); + * console.log(account); + * ``` + */ public async login() { const account = await this.wallet.getAccount(); // Use address return account; } + /** + * Set the sharding Structure + * + * @param shardingStructures The array of information of sharding structures + * + * @example + * ```javascript + * hmyEx.shardingStructures([ + * {"current":true,"http":"http://127.0.0.1:9500", + * "shardID":0,"ws":"ws://127.0.0.1:9800"}, + * {"current":false,"http":"http://127.0.0.1:9501", + * "shardID":1,"ws":"ws://127.0.0.1:9801"} + * ]); + * ``` + */ public shardingStructures(shardingStructures: ShardingItem[]) { for (const shard of shardingStructures) { const shardID = @@ -175,6 +235,8 @@ export class HarmonyExtension { } this.setMessenger(this.messenger); } + + /**@ignore*/ private setMessenger(messenger: Messenger) { this.blockchain.setMessenger(messenger); this.wallet.messenger = messenger; diff --git a/packages/harmony-core/src/truffleProvider.ts b/packages/harmony-core/src/truffleProvider.ts index 7815587..2a10216 100644 --- a/packages/harmony-core/src/truffleProvider.ts +++ b/packages/harmony-core/src/truffleProvider.ts @@ -1,6 +1,7 @@ /** * @packageDocumentation * @module harmony-core + * @hidden */ import { @@ -13,9 +14,6 @@ import { import { ChainID, ChainType, Unit } from '@harmony-js/utils'; import { HDNode } from '@harmony-js/account'; -/** - * @hidden - */ export interface ArgsResolver { newArgs: any; id: number; @@ -24,27 +22,18 @@ export interface ArgsResolver { callback: (error: any, res?: any) => void; } -/** - * @hidden - */ export interface HDOptions { menmonic?: string; index: number; addressCount: number; } -/** - * @hidden - */ export interface ChainOptions { shardID: number; chainType: ChainType; chainId: ChainID; } -/** - * @hidden - */ export interface TransactionOptions { gasLimit: string; gasPrice: string;