diff --git a/src/hooks/useBalance.ts b/src/hooks/useBalance.ts index e6725bba7..76824f1ff 100644 --- a/src/hooks/useBalance.ts +++ b/src/hooks/useBalance.ts @@ -51,11 +51,13 @@ const getBalanceBySymbol = async (params: { }; /** - * @param token - The token to fetch the balance of. - * @param chainId - The chain Id of the chain to execute the query on. If not specified, defaults to the chainId the user is connected to or undefined. + * Retrieves the balance of a specific token for a given account and chain. + * + * @param tokenSymbol - The symbol of the token to retrieve the balance for. If not provided, it will return the Ether (ETH) balance. + * @param chainId - The ID of the chain to execute the query on. If not specified, defaults to the chainId the user is connected to or undefined. * @param account - The account to query the balance of. * @remarks Passing the zero address as token will return the ETH balance. Passing no account will return the balance of the connected account. - * @returns The balance of the account and the UseQueryResult object + * @returns An object containing the balance of the account (as a `BigNumber`) and the `UseQueryResult` object. */ export function useBalanceBySymbol( tokenSymbol?: string, diff --git a/src/hooks/useBridgeFees.ts b/src/hooks/useBridgeFees.ts index d80615bc4..172e39a52 100644 --- a/src/hooks/useBridgeFees.ts +++ b/src/hooks/useBridgeFees.ts @@ -10,6 +10,7 @@ import { AxiosError } from "axios"; * @param toChainId The chain Id of the receiving chain, its timestamp will be used to calculate the fees. * @param inputTokenSymbol - The input token symbol to check bridge fees for. * @param outputTokenSymbol - The output token symbol to check bridge fees for. + * @param recipientAddress - The recipient address for the bridged tokens. * @returns The bridge fees for the given amount and token symbol and the UseQueryResult object. */ export function useBridgeFees( diff --git a/src/utils/bridge.ts b/src/utils/bridge.ts index 27ef1b723..d0b2f27a7 100644 --- a/src/utils/bridge.ts +++ b/src/utils/bridge.ts @@ -46,13 +46,26 @@ export type GetBridgeFeesResult = BridgeFees & { }; /** + * Retrieves the bridge fees for a given token bridging operation. * - * @param amount - amount to bridge - * @param inputTokenSymbol - symbol of the input token to bridge - * @param outputTokenSymbol - symbol of the output token to bridge - * @param fromChain The origin chain of this bridge action - * @param toChain The destination chain of this bridge action - * @returns Returns the `relayerFee` and `lpFee` fees for bridging the given amount of tokens, along with an `isAmountTooLow` flag indicating whether the amount is too low to bridge and an `isLiquidityInsufficient` flag indicating whether the liquidity is insufficient. + * @param amount - The amount of tokens to be bridged. + * @param inputTokenSymbol - The symbol of the input token to be bridged. + * @param outputTokenSymbol - The symbol of the output token to be received after bridging. + * @param fromChainId - The ID of the origin chain for the bridge operation. + * @param toChainId - The ID of the destination chain for the bridge operation. + * @param recipientAddress - The address of the recipient who will receive the bridged tokens. + * @returns An object containing the following properties: + * - `totalRelayFee`: The total relay fee for the bridge operation. + * - `relayerGasFee`: The gas fee paid to the relayer. + * - `relayerCapitalFee`: The capital fee paid to the relayer. + * - `lpFee`: The fee paid to the liquidity provider. + * - `isAmountTooLow`: A boolean indicating whether the provided amount is too low to bridge. + * - `quoteTimestamp`: The timestamp of the bridge fee quote. + * - `quoteTimestampInMs`: The quote timestamp in milliseconds. + * - `quoteBlock`: The block number of the bridge fee quote. + * - `quoteLatency`: The latency of the bridge fee quote request in milliseconds. + * - `limits`: An object containing the minimum and maximum bridge limits. + * - `estimatedFillTimeSec`: The estimated time in seconds for the bridge operation to be filled. */ export async function getBridgeFees({ amount, @@ -154,10 +167,14 @@ type NetworkMismatchHandler = ( ) => void; /** - * Makes a deposit on Across using the `SpokePoolVerifiers` contract's `deposit` function if possible. - * @param signer A valid signer, must be connected to a provider. + * Makes a deposit on the Across protocol using the `SpokePoolVerifiers` contract's `deposit` function, if possible. + * + * @param signer - A valid Ethereum signer, which must be connected to a provider. + * @param spokePool - The `SpokePool` contract instance used for the deposit operation. + * @param spokePoolVerifier - The `SpokePoolVerifier` contract instance used for the deposit operation. + * @param onNetworkMismatch - An optional callback function that will be called if the signer's network does not match the from/to chain IDs. * @param depositArgs - An object containing the {@link AcrossDepositArgs arguments} to pass to the deposit function of the bridge contract. - * @returns The transaction response obtained after sending the transaction. + * @returns The transaction response obtained after sending the deposit transaction. */ export async function sendSpokePoolVerifierDepositTx( signer: ethers.Signer, diff --git a/src/utils/format.ts b/src/utils/format.ts index da0a1c284..6a6fc4cf5 100644 --- a/src/utils/format.ts +++ b/src/utils/format.ts @@ -273,7 +273,9 @@ export function formatWeiPct(wei?: ethers.BigNumberish, precision: number = 3) { /** * Formats a number into a human readable format - * @param num The number to format + * + * @param num - The number to be formatted. + * @param decimals - The number of decimal places to display. Default is 0. * @returns A human readable format. I.e. 1000 -> 1K, 1001 -> 1K+ */ export function humanReadableNumber(num: number, decimals = 0): string { diff --git a/src/utils/notify.ts b/src/utils/notify.ts index 460ac4293..4e2695b47 100644 --- a/src/utils/notify.ts +++ b/src/utils/notify.ts @@ -48,11 +48,15 @@ export const notificationEmitter = async ( /** * Calls and waits on the Notify API to resolve the status of a TX if the chain is supported by Onboard + * + * @param requiredChainId The ID of the chain that the transaction was executed on. * @param tx The transaction to wait for * @param notify The BNC Notify API that is used to handle the UI visualization * @param timingBuffer An optional waiting time in milliseconds to wait to resolve this promise on a successful tx confirmation in Notify (Default: 5000ms) * @param ignoreErrors An optional parameter to ignore tx failure and return successful - **/ + * + * @throws {Error} If the transaction fails and `ignoreErrors` is set to `false`. + */ export const waitOnTransaction = async ( requiredChainId: number, tx: ContractTransaction, diff --git a/src/utils/staking-pool.ts b/src/utils/staking-pool.ts index 961902908..77bb515ba 100644 --- a/src/utils/staking-pool.ts +++ b/src/utils/staking-pool.ts @@ -74,6 +74,8 @@ export type PoolQueryData = { * Calls on-chain data & the Vercel API to resolve information about the AcceleratingDistributor Contract * @param tokenAddress The address of the ERC-20 token on the current chain * @param account A user address to query against the on-chain data + * @param acxPriceInUSD The current price of the ACX token in US dollars + * @returns The staking pool information, or `undefined` if the required data is not available. */ export async function fetchStakingPool( tokenAddress?: string, diff --git a/src/utils/transactions.ts b/src/utils/transactions.ts index 57ac68c3f..7e7d89a96 100644 --- a/src/utils/transactions.ts +++ b/src/utils/transactions.ts @@ -8,7 +8,7 @@ import { parseUnits } from "./format"; /** * This function takes a raw transaction and a signer and returns the result of signing the transaction. - * @param tx The raw transaction to sign. + * @param rawTx The raw transaction to sign. * @param signer A signer used to sign the transaction * @returns The raw transaction signed by the given `signer`. */ @@ -55,6 +55,7 @@ export async function getPaddedGasEstimation( * Pads the gas estimation by a fixed amount dictated in the `REACT_SEND_TXN_GAS_ESTIMATION_MULTIPLIER` env var * @param contract The contract that this transaction will originate from * @param method The specific call method + * @param chainId The chain ID to use for the gas estimation. * @returns A completed or failed transaction */ export function sendWithPaddedGas( diff --git a/src/utils/weiMath.ts b/src/utils/weiMath.ts index 8f9f2889b..82b35e4ae 100644 --- a/src/utils/weiMath.ts +++ b/src/utils/weiMath.ts @@ -11,7 +11,7 @@ export function toWeiSafe( numberToConvertToWei: string, desiredPrecision = DEFAULT_PRECISION ) { - // Try converting just the raw string first to avoid unneccessary stripping of precision. + // Try converting just the raw string first to avoid unnecessary stripping of precision. try { return toWei(numberToConvertToWei, desiredPrecision); } catch (err) {