From 74cfb7f77a656f7800b3d6d39d0ae5c07d7fd04e Mon Sep 17 00:00:00 2001 From: clearloop Date: Sun, 27 Sep 2020 13:07:22 +0800 Subject: [PATCH] Complete API docs (#89) * perf(api): complete the inline docs * perf(api): complete docs of shadow api * chore(README): update the usage of dj * perf(listener): get back darwinia listener * perf(listener): move cache.ts outof listener module * fix(lint): the import path of types in cache.ts --- README.md | 46 ++++------------ package.json | 2 +- src/api/darwinia.ts | 107 ++++++++++++++++++++++++++---------- src/api/shadow.ts | 20 ++++--- src/{listener => }/cache.ts | 2 +- src/index.ts | 1 + src/listener/chain/game.ts | 2 +- src/listener/eth/index.ts | 2 +- src/listener/index.ts | 1 + src/listener/redeem.ts | 2 +- src/listener/relay.ts | 2 +- src/util/index.ts | 17 ++---- 12 files changed, 112 insertions(+), 92 deletions(-) rename src/{listener => }/cache.ts (96%) diff --git a/README.md b/README.md index 07c5100..498115a 100644 --- a/README.md +++ b/README.md @@ -40,18 +40,9 @@ yarn global add @darwinia/dj Now you can type `dj` in your command-line: ```bash -> dj -dj - -Commands: - dj balance [address] Get balance of account address - dj config [edit] Show config - dj proposal Submit a relay proposal to darwinia - dj transfer
Transfer RING to darwinia account - -Options: - --help, -h Show help [boolean] - --version, -V Show version number +> dj -h +dj: illegal option -- - +usage: dj [-v verbose-mode] [-c edit-config] ``` ## Usage @@ -59,34 +50,17 @@ Options: By default, `dj` is configured to point to the Infura Ethereum node and the official Darwinia crab network node. So you can immediately start using `dj` to submit Ethereum block headers to the Darwinia crab network and get rewards. ```bash -dj +dj -v ``` When the `dj` command is executed for the first time, you will be asked to input a seed. At this time, you need to enter the seed you have prepared and press Enter to continue. You can see the submission result in a few minutes. If `ok` appears, it means the submission is successful. If `reject` appears, xxx. -### Util subcommands - -- dj proposal - - Submit a proposal to darwinia network. The proposal includes the target block header with its proof. - -- dj balance - - Get the `RING` balance of your seed account. - -- dj transfer
- - Transfor `RING` to `address` from your seed account - -- dj config - - Show your `dj`'s current config. ### Change seed -If you want to change your seed, you need to find the configuration file `/.darwinia/config.json` . Open this file with an editor, replace the original seed and save it. +If you want to change your seed, run `dj -e`, replace the original seed and save it. For more information about configuration, see the configuration section. @@ -137,7 +111,7 @@ As mentioned earlier, `dj` configuration file is `/.darwin ```bash { "node": "ws://127.0.0.1:9944", - "seed": "...", + "seed": "...", "shadow": "..." } ``` @@ -152,7 +126,7 @@ Shadow is a service used by `dj` to retrieve header data and generate proof. Sha `dj` uses the official shadow service by default, if you don’t want to use the official service, you can run the service yourself, and then configure `dj` to use it. -- Install +n- Install ```bash # install rust and cargo @@ -173,7 +147,7 @@ Shadow is a service used by `dj` to retrieve header data and generate proof. Sha ```bash { "node": "...", - "seed": "...", + "seed": "...", "shadow": "http://0.0.0.0:3000/api/v1" } ``` @@ -199,7 +173,7 @@ Shadow is a service used by `dj` to retrieve header data and generate proof. Sha ```json { "node": "ws://0.0.0.0:9944", - "seed": "//Alice", + "seed": "//Alice", "shadow": "http://0.0.0.0:3000/api/v1" } ``` @@ -207,7 +181,7 @@ Shadow is a service used by `dj` to retrieve header data and generate proof. Sha 4. Run dj to submit header to your local dev node ```bash - dj + dj -v ``` ------------ diff --git a/package.json b/package.json index cc5d320..51fbb3d 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "private": false, "name": "@darwinia/dj", - "version": "0.2.5-alpha.3", + "version": "0.2.6-alpha.1", "description": "Darwinia bridge relayer tool", "homepage": "https://github.com/darwinia-network/dj", "repository": { diff --git a/src/api/darwinia.ts b/src/api/darwinia.ts index 14fd7db..463fd24 100644 --- a/src/api/darwinia.ts +++ b/src/api/darwinia.ts @@ -13,6 +13,13 @@ import { IReceiptWithProof, } from "../types"; +/** + * Documentation of substrate error + * + * @property {string} name - error name + * @property {string} section - error section + * @property {string} documentation: error documentation + */ export interface IErrorDoc { name: string; section: string; @@ -22,10 +29,10 @@ export interface IErrorDoc { /** * Extrinsic Result * - * @property {String} isOk - If extrinsic is ok - * @property {String} isErr - If extrinsic is error - * @property {String} blockHash - the hash of the block which contains our extrinsic - * @property {String} exHash - Extrinsic hash + * @property {string} isOk - If extrinsic is ok + * @property {string} isErr - If extrinsic is error + * @property {string} blockHash - the hash of the block which contains our extrinsic + * @property {string} exHash - Extrinsic hash * @property {IErrorDoc | undefined} docs - Extrinsic error doc */ export class ExResult { @@ -38,9 +45,9 @@ export class ExResult { /** * Extrinsic Result * - * @param {String} isOk - if extrinsic is ok - * @param {String} blockHash - the hash of the block which contains our extrinsic - * @param {String} exHash - Extrinsic hash + * @param {string} isOk - if extrinsic is ok + * @param {string} blockHash - the hash of the block which contains our extrinsic + * @param {string} exHash - Extrinsic hash * @param {IErrorDoc | undefined} docs - Extrinsic error doc */ constructor(isOk: boolean, blockHash: string, exHash: string, docs?: IErrorDoc) { @@ -51,6 +58,11 @@ export class ExResult { this.docs = docs; } + /** + * Convert `ExResult` to `string` + * + * @returns {string} `ExResult` string + */ public toString(): string { if (this.docs) { return [ @@ -67,13 +79,18 @@ export class ExResult { * @class API - darwinia api * * @method getBalance - get account balance - * @method reset - reset eth relay header - * @method relay - relay eth relay header - * @method redeem - redeem ring - * @method transfer - transfer ring + * @method setConfirmed - reset the confirmed block in darwinia + * @method submitProposal - submit a proposal to darwinia + * @method redeem - redeem darwinia transactions + * @method approveBlock - approve pending block + * @method rejectBlock - reject pending block + * @method shouldRelay - if a block should relay + * @method isRedeemAble - if a transaction is redeemable * * @property {KeyringPair} account - darwinia account - * @property {ApiPromise} ap - raw polkadot api + * @property {Uint8Array} relayer - darwinia relayer account + * @property {ApiPromise} _ - raw polkadot api + * @property {Record} types - darwinia types.json */ export class API { /** @@ -91,22 +108,13 @@ export class API { * new darwinia account from seed * * @param {String} seed - seed of darwinia account + * @returns {KeyringPair} keyring pair */ - public static async seed(seed: string) { + public static async seed(seed: string): Promise { await cryptoWaitReady(); return new Keyring({ type: "sr25519" }).addFromUri(seed); } - /** - * new darwinia account from mnemonic - * - * @param {String} mnemonic - mnemonic of darwinia account - */ - public static async memrics(mnemonic: string) { - await cryptoWaitReady(); - return new Keyring({ type: "sr25519" }).addFromMnemonic(mnemonic); - } - /** * init darwinia api async * @@ -118,7 +126,7 @@ export class API { * ```js * const cfg = new Config(); * const seed = await API.seed(cfg.seed); - * const api = await API.new(seed, cfg.node, cfg.types); + * const api = await API.new(seed, cfg.node, cfg.relayer, cfg.types); * ``` */ public static async new( @@ -150,6 +158,8 @@ export class API { * * @param {KeyringPair} account - darwinia account * @param {ApiPromise} ap - raw polkadot api + * @param {Uint8Array} relayer - darwinia relayer account + * @param {Record} types - darwinia types.json */ constructor( account: KeyringPair, @@ -165,6 +175,8 @@ export class API { /** * Get last confirm block + * + * @returns {Promise} Ethereum block number */ public async lastConfirm(): Promise { const res = await this._.query.ethereumRelay.confirmedBlockNumbers(); @@ -180,6 +192,7 @@ export class API { * get ring balance by darwinia account address * * @param {string} addr - account address of darwinia + * @returns {Promise} account balance */ public async getBalance(addr: string): Promise { const account = await this._.query.system.account(addr); @@ -188,8 +201,19 @@ export class API { /** * Approve block in relayer game + * + * @description + * + * ## permission + * + 7 for root + * + 5 for council + * + 4 for normal account + * + * @param {number} block - block number + * @param {number} perms - permission + * @returns {Promise} the result of `approveBlock` ex */ - public async approveBlock(block: number, perms = 4): Promise { + public async approveBlock(block: number, perms: number = 4): Promise { let ex = this._.tx.ethereumRelay.approvePendingHeader(block); if (perms === 7) { ex = this._.tx.sudo.sudo(ex); @@ -200,13 +224,24 @@ export class API { } log.event(`Approve block ${block}`); - return await this.blockFinalized(ex, true); + return this.blockFinalized(ex, true); } /** * Approve block in relayer game + * + * @description + * + * ## permission + * + 7 for root + * + 5 for council + * + 4 for normal account + * + * @param {number} block - block number + * @param {number} perms - permission + * @returns {Promise} the result of `rejectBlock` ex */ - public async rejectBlock(block: string | number, perms = 4): Promise { + public async rejectBlock(block: string | number, perms: number = 4): Promise { let ex = this._.tx.ethereumRelay.rejectPendingHeader(block); if (perms === 7) { ex = this._.tx.sudo.sudo(ex); @@ -222,8 +257,13 @@ export class API { /** * Set confirmed block with sudo privilege + * + * @param {IEthereumHeaderThingWithConfirmation} headerThing - The Ethereum headerthing + * @returns {Promise} the result of `setConfirm` ex */ - public async setConfirmed(headerThing: IEthereumHeaderThingWithConfirmation): Promise { + public async setConfirmed( + headerThing: IEthereumHeaderThingWithConfirmation, + ): Promise { log.event(`Set confirmed block ${headerThing.header_thing.header.number}`); const ex = this._.tx.ethereumRelay.setConfirmed(headerThing.header_thing); return await this.blockFinalized(this._.tx.sudo.sudo(ex)); @@ -233,6 +273,7 @@ export class API { * Check if should relay target * * @param {number} target - target header + * @returns {Promise} the result of `shouldRelay` */ public async shouldRelay(target: number): Promise { log("Check if target block less than the last confirmed block"); @@ -286,7 +327,8 @@ export class API { /** * get the specify block * - * @param {IEthHeaderThing} headerThings - Eth Header Things + * @param {IEthereumHeaderThingWithProof[]} headerThings - EthereumHeaderThings + * @returns {Promise} The result of `submitProposal` ex */ public async submitProposal(headerThings: IEthereumHeaderThingWithProof[]): Promise { const latest = headerThings[headerThings.length - 1].header.number; @@ -303,6 +345,9 @@ export class API { /** * Check if a tx is redeemable + * + * @param {ITx} tx - ethereum tx + * @returns {Promise} The result of `isRedeemAble` */ public async isRedeemAble(tx: ITx): Promise { log(`Check if tx ${tx.tx} has been redeemed`); @@ -318,6 +363,7 @@ export class API { * relay darwinia header * * @param {DarwiniaEthBlock} block - darwinia style eth block + * @returns {Promise} The result of `redeem` ex */ public async redeem(act: string, proof: IReceiptWithProof): Promise { log.event(`Redeem tx in block ${proof.header.number}`); @@ -334,10 +380,11 @@ export class API { * * @param {SubmittableExtrinsic<"promise">} ex - extrinsic * @param {Boolean} inBlock - if resolve when inBlock + * @returns {Promise} The result of any ex */ private blockFinalized( ex: SubmittableExtrinsic<"promise">, - inFinialize = false, + inFinialize: boolean = false, ): Promise { const res = new ExResult( false, diff --git a/src/api/shadow.ts b/src/api/shadow.ts index 1a5b051..caef971 100644 --- a/src/api/shadow.ts +++ b/src/api/shadow.ts @@ -16,21 +16,22 @@ process.env.https_proxy = "" /** * Shadow APIs * - * @method getBlock - get raw eth block - * @method getBlockWithProof - get eth header with proof + * @method getHeaderThing - get ethereum headerthing + * @method getReceipt - get ethereum transaction receipt + * @method getProposal - get darwinia proposal */ export class ShadowAPI { constructor(api: string) { axios.defaults.baseURL = api; - // axios.defaults.proxy = false; } /** * Get darwinia block with eth proof * - * @param {number} block | string - block number + * @param {number} block - block number + * @returns {Promise} ethereum headerthing with confirmation */ - async getHeaderThing(block: number | string): Promise { + async getHeaderThing(block: number): Promise { log(`Get header thing of ${block}`); const r: any = await axios.get( "/eth/header/" + block, @@ -44,7 +45,9 @@ export class ShadowAPI { /** * Get darwinia block with eth proof * - * @param {number} block - block number + * @param {string} tx - block number + * @param {number} lastConfirmed - block number + * @returns {Promise} receipt with proof */ async getReceipt(tx: string, lastConfirmed: number): Promise { log(`Get receipt of ${tx}`); @@ -60,7 +63,10 @@ export class ShadowAPI { /** * Get darwinia block with eth proof * - * @param {number} block - block number + * @param {number} member - the block needs to be verified + * @param {number} target - target proposal block + * @param {number} last_leaf - last leaf of blocks + * @returns {Promise} Ethereum headerthing with proof */ async getProposal( member: number, diff --git a/src/listener/cache.ts b/src/cache.ts similarity index 96% rename from src/listener/cache.ts rename to src/cache.ts index 5e2a156..6122a16 100644 --- a/src/listener/cache.ts +++ b/src/cache.ts @@ -1,4 +1,4 @@ -import { IEthereumHeaderThingWithProof, ITx } from "../types"; +import { IEthereumHeaderThingWithProof, ITx } from "./types"; /** * Memory database for relay process diff --git a/src/index.ts b/src/index.ts index 36f0b31..365867f 100755 --- a/src/index.ts +++ b/src/index.ts @@ -27,6 +27,7 @@ export default async function main() { Listener.guard(api, shadow); Listener.relay(api, shadow); Listener.redeem(api, shadow); + Listener.darwinia(api, shadow); Listener.ethereum(conf.eth); } diff --git a/src/listener/chain/game.ts b/src/listener/chain/game.ts index ea36f4b..d473a0e 100644 --- a/src/listener/chain/game.ts +++ b/src/listener/chain/game.ts @@ -1,7 +1,7 @@ import { ShadowAPI, API } from "../../api"; import { log } from "../../util"; import { IEthereumHeaderThingWithProof } from "../../types"; -import Cache from "../cache" +import Cache from "../../cache" /// NewRound handler export default async function game( diff --git a/src/listener/eth/index.ts b/src/listener/eth/index.ts index d58ddc6..8245205 100644 --- a/src/listener/eth/index.ts +++ b/src/listener/eth/index.ts @@ -3,7 +3,7 @@ import { EventParser } from "./EventParser"; import { blockInDB, logInDB } from "./DB"; import { localConfig } from "./Config"; import { log } from "../../util"; -import Cache from "../cache"; +import Cache from "../../cache"; const blockchainState = new BlockchainState(); const eventParser = new EventParser(); diff --git a/src/listener/index.ts b/src/listener/index.ts index 2f2f330..4b9e020 100644 --- a/src/listener/index.ts +++ b/src/listener/index.ts @@ -2,3 +2,4 @@ export { listen as guard } from "./guard"; export { listen as relay } from "./relay"; export { listen as redeem } from "./redeem"; export { listen as ethereum } from "./eth"; +export { listen as darwinia } from "./chain"; diff --git a/src/listener/redeem.ts b/src/listener/redeem.ts index bdc7587..b916871 100644 --- a/src/listener/redeem.ts +++ b/src/listener/redeem.ts @@ -1,6 +1,6 @@ import { ShadowAPI, API } from "../api"; import { delay, log } from "../util"; -import Cache from "./cache"; +import Cache from "../cache"; /// Approved handler export async function listen( diff --git a/src/listener/relay.ts b/src/listener/relay.ts index 84d1623..95154d7 100644 --- a/src/listener/relay.ts +++ b/src/listener/relay.ts @@ -1,6 +1,6 @@ import { ShadowAPI, API } from "../api"; import { log } from "../util"; -import Cache from "./cache"; +import Cache from "../cache"; // Listen and submit proposals export function listen(api: API, shadow: ShadowAPI) { diff --git a/src/util/index.ts b/src/util/index.ts index 266ffe3..e550b97 100644 --- a/src/util/index.ts +++ b/src/util/index.ts @@ -1,14 +1,5 @@ -import { Config } from "./cfg"; -import { log } from "./log"; -import { whereisPj } from "./pj"; -import { delay } from "./delay"; -import chalk from "chalk"; +export { Config } from "./cfg"; +export { log } from "./log"; +export { whereisPj } from "./pj"; +export { delay } from "./delay"; -// exports -export { - Config, - delay, - chalk, - log, - whereisPj, -}