From a26b834dab425e61b6c465f89b7bdac3840b0a49 Mon Sep 17 00:00:00 2001 From: Richard Ramos Date: Mon, 27 Aug 2018 16:16:00 -0400 Subject: [PATCH] Documentation pt2 --- gas-relayer/.eslintrc | 2 +- gas-relayer/src/contract-settings.js | 54 +++++++++++++++++++ gas-relayer/src/message-processor.js | 26 ++++----- .../src/strategy/AvailabilityStrategy.js | 2 +- gas-relayer/src/strategy/BaseStrategy.js | 18 +++---- gas-relayer/src/strategy/IdentityStrategy.js | 4 +- gas-relayer/src/strategy/SNTStrategy.js | 2 +- 7 files changed, 81 insertions(+), 27 deletions(-) diff --git a/gas-relayer/.eslintrc b/gas-relayer/.eslintrc index 776e80e..13108e4 100644 --- a/gas-relayer/.eslintrc +++ b/gas-relayer/.eslintrc @@ -275,7 +275,7 @@ "error", "never" ], - "valid-jsdoc": "error", + "valid-jsdoc": "off", "vars-on-top": "off", "wrap-iife": "error", "wrap-regex": "error", diff --git a/gas-relayer/src/contract-settings.js b/gas-relayer/src/contract-settings.js index ec50aa4..6bb0744 100644 --- a/gas-relayer/src/contract-settings.js +++ b/gas-relayer/src/contract-settings.js @@ -1,5 +1,13 @@ +/** + * Configuration Settings related to contracts + */ class ContractSettings { + /** + * @param {object} config - Configuration object obtained from `./config/config.js` + * @param {object} web3 - Web3 object already configured + * @param {object} eventEmitter - Event Emitter + */ constructor(config, web3, eventEmitter){ this.tokens = config.tokens; this.topics = []; @@ -12,11 +20,17 @@ class ContractSettings { this.pendingToLoad = 0; } + /** + * Process configuration file + */ process(){ this._setTokenPricePlugin(); this._processContracts(); } + /** + * Set price plugin for token + */ _setTokenPricePlugin(){ for(let token in this.tokens){ if(this.tokens[token].pricePlugin !== undefined){ @@ -26,16 +40,30 @@ class ContractSettings { } } + /** + * Get allowed tokens + * @return {object} - Dictionary with allowed tokens (address as key) + */ getTokens(){ return this.tokens; } + /** + * Get token by address + * @param {string} - Token address + * @return {object} - Token details + */ getToken(token){ const tokenObj = this.tokens[token]; tokenObj.address = token; return tokenObj; } + /** + * Get token by symbol + * @param {string} - Token symbol + * @return {object} - Token details + */ getTokenBySymbol(symbol){ for(let token in this.tokens){ if(this.tokens[token].symbol == symbol){ @@ -46,14 +74,28 @@ class ContractSettings { } } + /** + * Get contract by topicName + * @param {string} topicName - Topic name that represents a contract + * @return {object} - Contract details + */ getContractByTopic(topicName){ return this.contracts[topicName]; } + /** + * Calculate the topic based on the contract's name + * @param {string} contractName - Name of the contract as it appears in the configuration + * @return {string} - Topic + */ getTopicName(contractName){ return this.web3.utils.toHex(contractName).slice(0, 10); } + /** + * Set contract's bytecode in the configuration + * @param {string} topicName - Topic name that represents a contract + */ async _obtainContractBytecode(topicName){ if(this.contracts[topicName].isIdentity) return; @@ -71,6 +113,10 @@ class ContractSettings { } } + /** + * Extract function details based on topicName + * @param {string} topicName - Topic name that represents a contract + */ _extractFunctions(topicName){ const contract = this.getContractByTopic(topicName); @@ -90,6 +136,9 @@ class ContractSettings { this.contracts[topicName] = contract; } + /** + * Process contracts and setup the settings object + */ _processContracts(){ for(let contractName in this.contracts){ // Obtaining the abis @@ -114,6 +163,11 @@ class ContractSettings { } } + /** + * Create strategy object based on source code and topicName + * @param {string} strategyFile - Souce code path of strategy to build + * @param {string} topicName - Hex string that represents a contract's topic + */ buildStrategy(strategyFile, topicName){ const strategy = require(strategyFile); return new strategy(this.web3, this.config, this, this.contracts[topicName]); diff --git a/gas-relayer/src/message-processor.js b/gas-relayer/src/message-processor.js index 676da11..78292ad 100644 --- a/gas-relayer/src/message-processor.js +++ b/gas-relayer/src/message-processor.js @@ -4,10 +4,10 @@ class MessageProcessor { /** - * @param {object} config Configuration object obtained from `./config/config.js` - * @param {object} settings Settings obtained from parsing the configuration object - * @param {object} web3 Web3 object already configured - * @param {object} events Event emitter + * @param {object} config - Configuration object obtained from `./config/config.js` + * @param {object} settings - Settings obtained from parsing the configuration object + * @param {object} web3 - Web3 object already configured + * @param {object} events - Event emitter */ constructor(config, settings, web3, events){ this.config = config; @@ -18,8 +18,8 @@ class MessageProcessor { /** * Validate input message content - * @param {object} contract Contract object obtained from the settings based on the message topic - * @param {object} input Input object obtained from a message. + * @param {object} contract - Object obtained from the settings based on the message topic + * @param {object} input - Object obtained from a message. * @returns {object} State of validation */ async _validateInput(contract, input){ @@ -54,10 +54,10 @@ class MessageProcessor { /** * Process strategy and return validation result - * @param {object} contract Contract object obtained from the settings based on the message topic - * @param {object} input Input object obtained from a message. - * @param {function} reply Reply function to return message - * @param {object} strategy Strategy to apply. If undefined, it will use a strategy based on the contract + * @param {object} contract - Object obtained from the settings based on the message topic + * @param {object} input - Object obtained from a message. + * @param {function} reply - Function to reply a message + * @param {object} strategy - Strategy to apply. If undefined, it will use a strategy based on the contract * @returns {object} State of validation */ async processStrategy(contract, input, reply, strategy){ @@ -87,9 +87,9 @@ class MessageProcessor { /** * Process strategy and based on its result, send a transaction to the blockchain - * @param {object} contract Contract object obtained from the settings based on the message topic - * @param {object} input Input object obtained from a message. - * @param {function} reply Reply function to return message + * @param {object} contract - Object obtained from the settings based on the message topic + * @param {object} input - Object obtained from a message. + * @param {function} reply - function to reply a message * @returns {undefined} */ async processTransaction(contract, input, reply){ diff --git a/gas-relayer/src/strategy/AvailabilityStrategy.js b/gas-relayer/src/strategy/AvailabilityStrategy.js index ab24d95..3f7e557 100644 --- a/gas-relayer/src/strategy/AvailabilityStrategy.js +++ b/gas-relayer/src/strategy/AvailabilityStrategy.js @@ -8,7 +8,7 @@ class AvailabilityStrategy extends Strategy { /** * Process availability strategy - * @param {object} input Input object obtained from an 'availability' request. It expects an object with this structure `{contract, address, action, gasToken, gasPrice}` + * @param {object} input - Object obtained from an 'availability' request. It expects an object with this structure `{contract, address, action, gasToken, gasPrice}` * @returns {object} Status of validation, and minimum price */ execute(input){ diff --git a/gas-relayer/src/strategy/BaseStrategy.js b/gas-relayer/src/strategy/BaseStrategy.js index 8f3860d..6ab5d26 100644 --- a/gas-relayer/src/strategy/BaseStrategy.js +++ b/gas-relayer/src/strategy/BaseStrategy.js @@ -8,10 +8,10 @@ const erc20ABI = require('../../abi/ERC20Token.json'); class BaseStrategy { /** - * @param {object} web3 Web3 object already configured - * @param {object} config Configuration object obtained from `./config/config.js` - * @param {object} settings Settings obtained from parsing the configuration object - * @param {object} contract Contract object obtained from the settings based on the message topic + * @param {object} web3 - Web3 object already configured + * @param {object} config - Configuration object obtained from `./config/config.js` + * @param {object} settings - Settings obtained from parsing the configuration object + * @param {object} contract - Object obtained from the settings based on the message topic */ constructor(web3, config, settings, contract){ this.web3 = web3; @@ -22,8 +22,8 @@ class BaseStrategy { /** * Obtain the balance in tokens or ETH from an address - * @param {string} address ETH address to obtain the balance from - * @param {object} token Token obtained from `settings.getToken(tokenSymbol)` + * @param {string} address - ETH address to obtain the balance from + * @param {object} token - Obtained from `settings.getToken(tokenSymbol)` * @returns {web3.utils.BN} Balance */ async getBalance(address, token){ @@ -39,7 +39,7 @@ class BaseStrategy { /** * Build Parameters Function - * @param {object} input Input object obtained from an `transaction` request. + * @param {object} input - Object obtained from an `transaction` request. * @returns {function} Function that simplifies accessing contract functions' parameters */ _obtainParametersFunc(input){ @@ -51,7 +51,7 @@ class BaseStrategy { /** * Estimate gas using web3 - * @param {object} input Input object obtained from an `transaction` request. + * @param {object} input - Object obtained from an `transaction` request. * @returns {web3.utils.toBN} Estimated gas fees */ async _estimateGas(input){ @@ -66,7 +66,7 @@ class BaseStrategy { /** * Simulate transaction using ganache. Useful for obtaining events - * @param {object} input Input object obtained from an `transaction` request. + * @param {object} input - Object obtained from an `transaction` request. * @returns {object} Simulated transaction receipt */ async _simulateTransaction(input){ diff --git a/gas-relayer/src/strategy/IdentityStrategy.js b/gas-relayer/src/strategy/IdentityStrategy.js index 910f291..a2c86d0 100644 --- a/gas-relayer/src/strategy/IdentityStrategy.js +++ b/gas-relayer/src/strategy/IdentityStrategy.js @@ -9,7 +9,7 @@ class IdentityStrategy extends Strategy { /** * Validates if the contract being invoked represents an Identity instance - * @param {object} input Input object obtained from a `transaction` request. + * @param {object} input - Object obtained from a `transaction` request. * @returns {bool} Valid instance or not */ async _validateInstance(input){ @@ -26,7 +26,7 @@ class IdentityStrategy extends Strategy { /** * Process Identity strategy - * @param {object} input Input object obtained from an 'transaction' request. It expects an object with this structure `{contract, address, action, functionName, functionParameters, payload}` + * @param {object} input - Object obtained from an 'transaction' request. It expects an object with this structure `{contract, address, action, functionName, functionParameters, payload}` * @returns {object} Status of validation and estimated gas */ async execute(input){ diff --git a/gas-relayer/src/strategy/SNTStrategy.js b/gas-relayer/src/strategy/SNTStrategy.js index 6725eab..80476d1 100644 --- a/gas-relayer/src/strategy/SNTStrategy.js +++ b/gas-relayer/src/strategy/SNTStrategy.js @@ -11,7 +11,7 @@ class SNTStrategy extends Strategy { /** * Process SNTController strategy - * @param {object} input Input object obtained from an 'transaction' request. It expects an object with this structure `{contract, address, action, functionName, functionParameters, payload}` + * @param {object} input - Object obtained from an 'transaction' request. It expects an object with this structure `{contract, address, action, functionName, functionParameters, payload}` * @returns {object} Status of validation and estimated gas */ async execute(input){