From 3cd7bce0a3a3c49858917122970a0a6e283fba37 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Tue, 20 Mar 2018 21:41:59 +0000 Subject: Add DocComments to Web3Wrapper --- packages/web3-wrapper/src/index.ts | 133 ++++++++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 1 deletion(-) diff --git a/packages/web3-wrapper/src/index.ts b/packages/web3-wrapper/src/index.ts index 975649a75..895df509a 100644 --- a/packages/web3-wrapper/src/index.ts +++ b/packages/web3-wrapper/src/index.ts @@ -3,12 +3,25 @@ import { BigNumber, promisify } from '@0xproject/utils'; import * as _ from 'lodash'; import * as Web3 from 'web3'; +/** + * A wrapper around the Web3.js 0.x library that provides a consistent, clean promise-based interface. + */ export class Web3Wrapper { - // This is here purely to reliably distinguish it from other objects in runtime (like BigNumber.isBigNumber) + /** + * This is here purely to reliably distinguish it from other objects in runtime + * Similar to: BigNumber.isBigNumber + */ public isZeroExWeb3Wrapper = true; private _web3: Web3; private _defaults: Partial; private _jsonRpcRequestId: number; + /** + * Instantiates a new Web3Wrapper. + * @param provider The Web3 provider instance you would like the Web3Wrapper to use for interacting with + * the Ethereum network. + * @param defaults Override TxData defaults sent with RPC requests to the backing Ethereum node. + * @return An instance of the Web3Wrapper class. + */ constructor(provider: Web3.Provider, defaults?: Partial) { if (_.isUndefined((provider as any).sendAsync)) { // Web3@1.0 provider doesn't support synchronous http requests, @@ -21,32 +34,69 @@ export class Web3Wrapper { this._defaults = defaults || {}; this._jsonRpcRequestId = 0; } + /** + * Get the contract defaults set to the Web3Wrapper instance + * @return TxData defaults (e.g gas, gasPrice, nonce, etc...) + */ public getContractDefaults(): Partial { return this._defaults; } + /** + * Retrieve the Web3 provider + * @return Web3 provider instance + */ public getProvider(): Web3.Provider { return this._web3.currentProvider; } + /** + * Update the used Web3 provider + * @param provider The new Web3 provider to be set + */ public setProvider(provider: Web3.Provider) { this._web3.setProvider(provider); } + /** + * Check if an address is a valid Ethereum address + * @param address Address to check + * @returns Whether the address is a valid Ethereum address + */ public isAddress(address: string): boolean { return this._web3.isAddress(address); } + /** + * Check whether an address is available through the backing provider. This can be + * useful if you want to know whether a user can sign messages or transactions from + * a given Ethereum address. + * @param senderAddress Address to check availability for + * @returns Whether the address is available through the provider. + */ public async isSenderAddressAvailableAsync(senderAddress: string): Promise { const addresses = await this.getAvailableAddressesAsync(); const normalizedAddress = senderAddress.toLowerCase(); return _.includes(addresses, normalizedAddress); } + /** + * Fetch the backing Ethereum node's version string e.g `MetaMask/v4.2.0` + * @returns Ethereum node's version string + */ public async getNodeVersionAsync(): Promise { const nodeVersion = await promisify(this._web3.version.getNode)(); return nodeVersion; } + /** + * Fetches the networkId of the backing Ethereum node + * @returns The networkId + */ public async getNetworkIdAsync(): Promise { const networkIdStr = await promisify(this._web3.version.getNetwork)(); const networkId = _.parseInt(networkIdStr); return networkId; } + /** + * Retrieves the transaction receipt for a given transaction hash + * @param txHash Transaction hash + * @returns The transaction receipt, including it's status (0: failed, 1: succeeded or undefined: not found) + */ public async getTransactionReceiptAsync(txHash: string): Promise { const transactionReceipt = await promisify(this._web3.eth.getTransactionReceipt)(txHash); if (!_.isNull(transactionReceipt)) { @@ -54,57 +104,117 @@ export class Web3Wrapper { } return transactionReceipt; } + /** + * Convert an Ether amount from ETH to Wei + * @param ethAmount Amount of Ether to convert to wei + * @returns Amount in wei + */ public toWei(ethAmount: BigNumber): BigNumber { const balanceWei = this._web3.toWei(ethAmount, 'ether'); return balanceWei; } + /** + * Retrieves an accounts Ether balance in wei + * @param owner Account whose balance you wish to check + * @returns Balance in wei + */ public async getBalanceInWeiAsync(owner: string): Promise { let balanceInWei = await promisify(this._web3.eth.getBalance)(owner); // Rewrap in a new BigNumber balanceInWei = new BigNumber(balanceInWei); return balanceInWei; } + /** + * Check if a contract exists at a given address + * @param address Account address to check + * @returns Whether or not contract code was found at the supplied address + */ public async doesContractExistAtAddressAsync(address: string): Promise { const code = await promisify(this._web3.eth.getCode)(address); // Regex matches 0x0, 0x00, 0x in order to accommodate poorly implemented clients const codeIsEmpty = /^0x0{0,40}$/i.test(code); return !codeIsEmpty; } + /** + * Sign a message with a specific address's private key (`eth_sign`) + * @param address Address of signer + * @param message Message to sign + * @returns Signature string (might be VRS or RSV depending on the Signer) + */ public async signMessageAsync(address: string, message: string): Promise { const signData = await promisify(this._web3.eth.sign)(address, message); return signData; } + /** + * Fetches the latest blockNumber + * @returns Block number + */ public async getBlockNumberAsync(): Promise { const blockNumber = await promisify(this._web3.eth.getBlockNumber)(); return blockNumber; } + /** + * Fetch a specific Ethereum block + * @param blockParam The block you wish to fetch (blockHash, blockNumber or blockLiteral) + * @returns The requested block without transaction data + */ public async getBlockAsync(blockParam: string | Web3.BlockParam): Promise { const block = await promisify(this._web3.eth.getBlock)(blockParam); return block; } + /** + * Fetch a block's timestamp + * @param blockParam The block you wish to fetch (blockHash, blockNumber or blockLiteral) + * @returns The timestamp the block was mined + */ public async getBlockTimestampAsync(blockParam: string | Web3.BlockParam): Promise { const { timestamp } = await this.getBlockAsync(blockParam); return timestamp; } + /** + * Retrieve the user addresses available through the provider + * @returns Available user addresses + */ public async getAvailableAddressesAsync(): Promise { const addresses = await promisify(this._web3.eth.getAccounts)(); const normalizedAddresses = _.map(addresses, address => address.toLowerCase()); return normalizedAddresses; } + /** + * Take a snapshot of the blockchain state on a TestRPC/Ganache local node + * @returns The snapshot Id. This can be used to revert to this snapshot + */ public async takeSnapshotAsync(): Promise { const snapshotId = Number(await this._sendRawPayloadAsync({ method: 'evm_snapshot', params: [] })); return snapshotId; } + /** + * Revert the blockchain state to a previous snapshot state on TestRPC/Ganache local node + * @param snapshotId snapshot Id to revert to + * @returns Whether the revert was successful + */ public async revertSnapshotAsync(snapshotId: number): Promise { const didRevert = await this._sendRawPayloadAsync({ method: 'evm_revert', params: [snapshotId] }); return didRevert; } + /** + * Mine a block on a TestRPC/Ganache local node + */ public async mineBlockAsync(): Promise { await this._sendRawPayloadAsync({ method: 'evm_mine', params: [] }); } + /** + * Increase the next blocks timestamp on TestRPC/Ganache local node + * @param timeDelta Amount of time to add in seconds + */ public async increaseTimeAsync(timeDelta: number): Promise { await this._sendRawPayloadAsync({ method: 'evm_increaseTime', params: [timeDelta] }); } + /** + * Retrieve smart contract logs for a given filter + * @param filter Parameters by which to filter which logs to retrieve + * @returns The corresponding log entries + */ public async getLogsAsync(filter: Web3.FilterObject): Promise { let fromBlock = filter.fromBlock; if (_.isNumber(fromBlock)) { @@ -129,18 +239,39 @@ export class Web3Wrapper { const formattedLogs = _.map(rawLogs, this._formatLog.bind(this)); return formattedLogs; } + /** + * Get a Web3 contract factory instance for a given ABI + * @param abi Smart contract ABI + * @returns Web3 contract factory which can create Web3 Contract instances for the supplied ABI + */ public getContractFromAbi(abi: Web3.ContractAbi): Web3.Contract { const web3Contract = this._web3.eth.contract(abi); return web3Contract; } + /** + * Calculate the estimated gas cost for a given transaction + * @param txData Transaction data + * @returns Estimated gas cost + */ public async estimateGasAsync(txData: Partial): Promise { const gas = await promisify(this._web3.eth.estimateGas)(txData); return gas; } + /** + * Call a smart contract method at a given block height + * @param callData Call data + * @param defaultBlock Block height at which to make the call + * @returns The raw call result + */ public async callAsync(callData: Web3.CallData, defaultBlock?: Web3.BlockParam): Promise { const rawCallResult = await promisify(this._web3.eth.call)(callData, defaultBlock); return rawCallResult; } + /** + * Send a transaction + * @param txData Transaction data + * @returns Transaction hash + */ public async sendTransactionAsync(txData: Web3.TxData): Promise { const txHash = await promisify(this._web3.eth.sendTransaction)(txData); return txHash; -- cgit v1.2.3