Merge pull request #163 from zikriya/develop

Develop

src/README.md

@@ -0,0 +1,85 @@
+# index.ts
+
+1.  Import Statements:
+
+    -   `dotenv`: Module to load environment variables from a `.env` file.
+    -   `app`: The main Express application imported from `./app`.
+    -   `transactionsJob`: A function imported from `./crons/transactionsJob` that likely handles scheduled or recurring tasks related to transactions.
+2.  Environment Configuration:
+
+    -   `dotenv.config();`: This line loads the environment variables from a `.env` file into `process.env`, making them accessible throughout the application.
+3.  Transactions Job Initialization:
+
+    -   A self-invoking asynchronous function is defined and immediately executed to start the `transactionsJob`. If an error occurs during its execution, it is caught and logged to the console.
+4.  Server Initialization:
+
+    -   The Express `app` listens on a port defined by the `PORT` environment variable. Upon successful listening, it logs a message indicating that the server is listening on the specified port.
+
+This file primarily sets up and starts the server along with a job for handling transactions, all while ensuring that the necessary environment variables are loaded.
+
+# app.ts
+
+1.  Importing Modules and Initial Setup:
+
+    typescript
+
+    Copy code
+
+    `import express, { Request, Response, NextFunction, Application } from 'express';
+    import response from './middlewares/response/responseAppender';
+    const app: Application = express();`
+
+    -   `express`: This imports the express framework, which is essential for creating the server.
+    -   `Request, Response, NextFunction, Application`: These are type imports from Express to help with typing of function parameters and the application instance.
+    -   `response`: This imports a middleware function from `responseAppender` module, used to append data or modify the response.
+    -   `app`: An instance of an Express application, used to configure the server.
+2.  Middleware for Parsing JSON and URL-Encoded Request Bodies:
+
+    typescript
+
+    Copy code
+
+    `// parse json request body
+    app.use(express.json());
+
+    // parse urlencoded request body
+    app.use(express.urlencoded({ extended: true }));`
+
+    -   This sets up middleware in the Express app to parse JSON and URL-encoded request bodies. The `extended: true` option allows parsing of rich objects and arrays.
+3.  Custom Middleware - `responseAppender`:
+
+    typescript
+
+    Copy code
+
+    `// responseAppender
+    async function responseAppender(req: any, res: any, next: any) {
+      await response(req, res, next);
+      next();
+    }
+    app.use(responseAppender);`
+
+    -   A custom asynchronous middleware function that processes the request using another `response` middleware imported at the beginning. It ensures that the next middleware is called after its operation completes.
+4.  404 Error Handling for Unknown API Requests:
+
+    typescript
+
+    Copy code
+
+    `// send back a 404 error for any unknown api request
+    app.use((req: Request, res: Response, next: NextFunction) => {
+      next(Error('Not found'));
+    });`
+
+    -   This middleware intercepts any requests that did not match previous routes or middleware and forwards a new error with the message 'Not found', which can be used by error handling middleware to send a 404 response.
+5.  Exporting the Configured App:
+
+    typescript
+
+    Copy code
+
+    `export default app;`
+
+    -   The configured Express application is exported, allowing it to be imported and used in other parts of the application, typically where the server is started.
+
+This breakdown details how the application is structured and handles requests, providing insights into middleware usage and request handling in an Express.js application.

src/constants/README.md

@@ -0,0 +1,204 @@
+# constants.ts
+
+### Constants
+
+-   `NAME`: A string constant representing the name of the fund manager ('FUND_MANAGER').
+-   `VERSION`: A string constant that holds the version number ('000.004').
+-   `CONTRACT_ADDRESS`: Ethereum contract address as a string.
+-   `BEARER`: Prefix for authorization headers as a string ('Bearer ').
+-   `RANDOM_KEY`: A string key used for cryptographic operations.
+-   `CUDOS_CHAIN_ID`: A string representing the chain ID for Cudos network ('cudos-1').
+-   `FOUNDARY`, `ONE_INCH`: String constants representing specific service names.
+-   `NUMBER_OF_VALIDATORS_SHOULD_BE`: Numeric constant defining the required number of validators (1).
+
+### Networks Configuration
+
+-   `NETWORKS`: An array of objects, each containing network-specific addresses and identifiers for different blockchain networks.
+
+### Functions
+
+-   `getAllowedPublicAddress()`: Retrieves a list of allowed public addresses from an environment variable and returns it as an array. If no addresses are provided, it returns an empty array.
+
+-   `isAllowedPublicAddress(nodeAddress: string)`: Checks if a given node address is in the list of allowed addresses. It performs a case-insensitive comparison and returns `true` if the address is allowed, otherwise `false`.
+
+-   `isUniqueAddressesArray(arr: [any])`: Verifies that all addresses in the given array are unique. Returns `true` if all addresses are unique, `false` otherwise.
+
+-   `checkForNumberOfValidators(arr: any)`: Checks if the number of items in the provided array matches the number of allowed validators. Returns `true` if they match, otherwise `false`.
+
+-   `createAuthTokenForMultiswapBackend()`: Generates a time-bound authentication token for the Multiswap backend. It uses cryptographic functions to ensure the token's integrity and confidentiality.
+
+-   `getPrivateKey()`: Retrieves and decrypts a private key stored in environment variables using another security key.
+
+-   `encrypt(data: string, key: String)`: Encrypts the given data using AES with the provided key and returns the ciphertext. If an error occurs during encryption, it logs the error and returns an empty string.
+
+-   `decrypt(data: string, key: string)`: Decrypts the given data using AES with the provided key and returns the original text. If decryption fails, it logs the error and returns an empty string.
+
+-   `delay()`: Returns a promise that resolves after 30 seconds. This function can be used to introduce artificial delays.
+
+-   `getThreshold(threshold: number)`: Calculates and returns twice the value of the provided threshold.
+
+-   `getRpcNodesData()`: Fetches RPC node data from environment variables, parses it from JSON, and returns it.
+
+These constants and functions are essential for the operations of a fund management system on blockchain networks, providing functionalities like authentication, configuration, and data integrity.
+
+# IERC20
+
+The IERC20.json file defines the interface for a standard ERC20 token, adhering to the Ethereum token standard specification. This interface includes essential functionalities for token transactions, including transfers, approvals, and balance checks.
+
+# FiberRouter.json
+Overview
+
+The FiberRouter.json file from the ferrumnet/multiswap-node repository contains a JSON object representing a smart contract interface for a "Fiber Router." This interface is likely used to interact with blockchain networks, facilitating operations such as swapping, liquidity provision, or routing transactions across different platforms.
+
+Interface Details
+
+Contract Name: The JSON is an interface for a contract named FiberRouter.
+
+Compiler Version: The interface was compiled with Solidity version 0.8.0.
+
+Optimization Enabled: Yes, with 200 runs.
+
+EVM Version: The target EVM version for this contract is specified as Default.
+
+Methods
+
+1. swapExactTokensForTokens
+
+Type: Function
+
+Inputs:
+
+amountIn: The amount of input tokens to swap.
+
+amountOutMin: The minimum amount of output tokens that must be received for the transaction not to revert.
+
+path: An array of token addresses used to determine the swap route.
+
+to: The address to send the output tokens to.
+
+deadline: A timestamp by which the transaction must be completed, or it will revert.
+
+Outputs:
+
+Array: Returns an array of numbers indicating the amounts of tokens received for each swap in the path.
+
+State Mutability: Nonpayable
+
+Details: This method facilitates a token swap operation, ensuring that the number of output tokens received is at least the amountOutMin specified, following the swap path provided.
+
+2. swapTokensForExactTokens
+
+Type: Function
+
+Inputs:
+
+amountOut: The exact amount of output tokens to receive.
+
+amountInMax: The maximum amount of input tokens that can be swapped.
+
+path: The route of token addresses for the swap.
+
+to: The recipient address for the output tokens.
+
+deadline: The transaction deadline.
+
+Outputs:
+
+Array: Outputs the amounts of tokens spent for each swap in the path.
+
+State Mutability: Nonpayable
+
+Details: Allows users to specify the exact amount of tokens they want to receive, the method calculates and limits the input to amountInMax.
+
+Events
+
+1. Swap
+
+Inputs:
+
+sender: The address initiating the swap.
+
+amountIn: The amount of input tokens provided for the swap.
+
+amountOut: The amount of output tokens received from the swap.
+
+tokenIn: The address of the input token.
+
+tokenOut: The address of the output token.
+
+to: The recipient address.
+
+Details: This event is emitted after a successful swap operation, detailing the swap amounts and the addresses involved.
+
+Conclusion
+
+The FiberRouter.json file defines an interface for a contract facilitating token swaps on a blockchain network, providing methods for exact or minimum token swaps along specified paths. It also includes an event to log swap operations. This documentation should assist auditors in understanding the contract's functionalities and intended behaviors.
+
+# utils.ts
+
+### Function: `amountToHuman`
+
+-   Purpose: Converts a machine-readable token amount to a human-readable format by adjusting for the token's decimal places.
+-   Parameters:
+    -   `web3`: An instance of a web3 library to interact with Ethereum nodes.
+    -   `token`: The contract address of the token.
+    -   `amount`: The amount in machine format (usually in smallest unit, like wei).
+-   Returns: The human-readable string of the amount, or null if conversion fails.
+
+### Function: `amountToMachine`
+
+-   Purpose: Converts a human-readable token amount to a machine-readable format by accounting for the token's decimal places.
+-   Parameters:
+    -   `web3`: An instance of a web3 library.
+    -   `token`: The contract address of the token.
+    -   `amount`: The amount in human-readable format.
+-   Returns: The machine-readable string of the amount, adjusted for decimals.
+
+### Function: `erc20`
+
+-   Purpose: Creates a new ERC20 contract instance using the provided web3 instance and token address.
+-   Parameters:
+    -   `web3`: An instance of a web3 library.
+    -   `token`: The contract address of the token.
+-   Returns: An instance of the ERC20 contract.
+
+### Function: `decimals`
+
+-   Purpose: Fetches the number of decimal places for a given token using its contract.
+-   Parameters:
+    -   `web3`: An instance of a web3 library.
+    -   `token`: The contract address of the token.
+-   Returns: The number of decimals as a number, or null if unable to fetch.
+
+### Function: `removeExponential`
+
+-   Purpose: Converts a number from exponential format to a plain string without exponential notation.
+-   Parameters:
+    -   `n`: The number in exponential format.
+-   Returns: The formatted number as a string.
+
+### Function: `numberIntoDecimals`
+
+-   Purpose: Converts a number into a string representation with a specified number of decimals.
+-   Parameters:
+    -   `amount`: The number to convert.
+    -   `decimal`: The number of decimal places.
+-   Returns: The number formatted as a string with the specified number of decimals.
+
+### Function: `decimalsIntoNumber`
+
+-   Purpose: Converts a string with decimals into a number format.
+-   Parameters:
+    -   `amount`: The string containing the number.
+    -   `decimal`: The number of decimal places.
+-   Returns: The number as a formatted string based on the specified decimals.
+
+### Function: `withSlippage`
+
+-   Purpose: Adjusts a given value by a specified percentage to account for potential slippage in transactions.
+-   Parameters:
+    -   `value`: The original value.
+    -   `slippage`: The slippage percentage to apply.
+-   Returns: The value adjusted for slippage as a string.
+
+These utility functions are crucial for handling and formatting blockchain-related numerical values, ensuring accurate calculations and displays for end-users.

src/controllers/README.md

@@ -0,0 +1,3 @@
+# index.ts
+
+The `index.ts` file within the `src/controllers` directory of the `ferrumnet/multiswap-node` repository serves as a central point for exporting modules. This file essentially organizes and makes accessible the defined modules in the project for periodic tasks.

src/crons/README.md

@@ -0,0 +1,42 @@
+# index.ts
+
+The `index.ts` file within the `src/crons` directory of the `ferrumnet/multiswap-node` repository serves as a central point for exporting cron job modules. This file essentially organizes and makes accessible the cron jobs defined in the project for periodic tasks.
+
+Here's a detailed documentation of each function in the file `transactionsJob.ts` from the repository:
+
+# transactionsJob.ts
+
+1.  Module Imports and Initializations:
+
+    -   `node-cron` is required for scheduling tasks.
+    -   Services like `axiosService` and `transactionService` are imported from the `../services` directory.
+    -   `isProccessRunning` is a boolean flag to prevent overlapping job executions.
+    -   `localTransactionHashes` stores transaction hashes locally to avoid reprocessing.
+2.  `transactionsJob` Function:
+
+    -   An asynchronous function that triggers the `start` function to initiate the job.
+3.  `start` Function:
+
+    -   Schedules a recurring task every 5 seconds.
+    -   If `isProccessRunning` is false, it calls `triggerJobs` to process transactions.
+    -   Handles errors by logging them.
+4.  `triggerJobs` Function:
+
+    -   Retrieves transactions through `axiosService.getTransactions()`.
+    -   If transactions are present, sets `isProccessRunning` to true, processes each transaction via `handleJob`, and then sets `isProccessRunning` to false.
+5.  `handleJob` Function:
+
+    -   Processes an individual transaction.
+    -   Checks if the transaction hash is in the local list using `isHashInLocalList`.
+    -   If not, adds it to the list with `addTransactionHashInLocalList` and then processes the transaction using `transactionService.prepareObjectsAndVerifySignatures`.
+6.  `addTransactionHashInLocalList` Function:
+
+    -   Adds a new hash to the `localTransactionHashes` array to keep track of processed transactions.
+7.  `removeTransactionHashFromLocalList` Function:
+
+    -   Removes a hash from the `localTransactionHashes` array, used when a transaction no longer needs to be tracked.
+8.  `isHashInLocalList` Function:
+
+    -   Checks if a given hash is already in the `localTransactionHashes` array.
+
+Each function is designed to handle specific aspects of transaction processing within a job that runs every few seconds, ensuring that transactions are not processed multiple times and handling errors gracefully.