diff --git a/contracts/OffsetHelper.sol b/contracts/OffsetHelper.sol index 9113b3c..dd5ef50 100644 --- a/contracts/OffsetHelper.sol +++ b/contracts/OffsetHelper.sol @@ -17,7 +17,7 @@ import "./interfaces/IToucanContractRegistry.sol"; * * Retiring carbon tokens requires multiple steps and interactions with * Toucan Protocol's main contracts: - * 1. Obtain a Toucan pool token e.g., NCT (by performing a token + * 1. Obtain a pool token e.g., NCT (by performing a token * swap on a DEX). * 2. Redeem the pool token for a TCO2 token. * 3. Retire the TCO2 token. @@ -66,7 +66,7 @@ contract OffsetHelper is OffsetHelperStorage { * pool token e.g., NCT. * * @param sender The sender of the transaction - * @param poolToken The address of the Toucan pool token used in the + * @param poolToken The address of the pool token used in the * redemption, e.g., NCT * @param tco2s An array of the TCO2 addresses that were redeemed * @param amounts An array of the amounts of each TCO2 that were redeemed @@ -148,7 +148,7 @@ contract OffsetHelper is OffsetHelperStorage { * * This function: * 1. Swaps the ERC20 token sent to the contract for the specified pool token. - * 2. Redeems the pool token for the poorest quality TCO2 tokens available. + * 2. Redeems the pool token for the oldest TCO2 tokens available. * 3. Retires the TCO2 tokens. * * Note: The client must approve the ERC20 token that is sent to the contract. @@ -159,7 +159,7 @@ contract OffsetHelper is OffsetHelperStorage { * * @param _fromToken The address of the ERC20 token that the user sends * (e.g., cUSD, cUSD, USDC, WETH, WMATIC) - * @param _poolToken The address of the Toucan pool token that the + * @param _poolToken The address of the pool token that the * user wants to use, e.g., NCT * @param _amountToOffset The amount of TCO2 to offset * @@ -185,11 +185,12 @@ contract OffsetHelper is OffsetHelperStorage { * @notice Retire carbon credits using the oldest TCO2 * tokens available from the specified Toucan token pool by sending ERC20 * tokens (cUSD, USDC, WETH, WMATIC). All provided token is consumed for - * offsetting. + * offsetting. Use `calculateExpectedPoolTokenForToken()` to calculate the expected amount + * of Pool token that can be acquired by swapping the provided amount of ERC20 token. * * This function: * 1. Swaps the ERC20 token sent to the contract for the specified pool token. - * 2. Redeems the pool token for the poorest quality TCO2 tokens available. + * 2. Redeems the pool token for the oldest TCO2 tokens available. * 3. Retires the TCO2 tokens. * * Note: The client must approve the ERC20 token that is sent to the contract. @@ -200,7 +201,7 @@ contract OffsetHelper is OffsetHelperStorage { * * @param _fromToken The address of the ERC20 token that the user sends * (e.g., cUSD, cUSD, USDC, WETH, WMATIC) - * @param _poolToken The address of the Toucan pool token that the + * @param _poolToken The address of the pool token that the * user wants to use, e.g., NCT * @param _amountToSwap The amount of ERC20 token to swap into Toucan pool * token. Full amount will be used for offsetting. @@ -235,7 +236,7 @@ contract OffsetHelper is OffsetHelperStorage { * * This function: * 1. Swaps the Matic sent to the contract for the specified pool token. - * 2. Redeems the pool token for the poorest quality TCO2 tokens available. + * 2. Redeems the pool token for the oldest TCO2 tokens available. * 3. Retires the TCO2 tokens. * * @dev If the user sends too much native tokens , the leftover amount will be sent back @@ -271,10 +272,12 @@ contract OffsetHelper is OffsetHelperStorage { * @notice Retire carbon credits using the oldest TCO2 * tokens available from the specified Toucan token pool by sending native tokens e.g., MATIC. * All provided native tokens is consumed for offsetting. + * Use `calculateExpectedPoolTokenForETH()` to calculate the expected amount of + * Pool token that can be acquired by swapping the provided amount of native tokens e.g., MATIC. * * This function: * 1. Swaps the Matic sent to the contract for the specified pool token. - * 2. Redeems the pool token for the poorest quality TCO2 tokens available. + * 2. Redeems the pool token for the oldest TCO2 tokens available. * 3. Retires the TCO2 tokens. * * @dev This function is only available on Polygon, not on Celo. @@ -305,10 +308,10 @@ contract OffsetHelper is OffsetHelperStorage { /** * @notice Retire carbon credits using the oldest TCO2 - * tokens available by sending Toucan pool tokens, e.g., NCT. + * tokens available by sending pool tokens, e.g., NCT. * * This function: - * 1. Redeems the pool token for the poorest quality TCO2 tokens available. + * 1. Redeems the pool token for the oldest TCO2 tokens available. * 2. Retires the TCO2 tokens. * * Note: The client must approve the pool token that is sent. @@ -404,6 +407,14 @@ contract OffsetHelper is OffsetHelperStorage { } } + /** + * @notice Swap eligible ERC20 tokens for pool tokens (BCT/NCT) on SushiSwap + * @dev Needs to be approved on the client side + * @param _fromToken The address of the ERC20 token used for the swap + * @param _poolToken The address of the pool token to swap for, + * e.g., NCT + * @param _toAmount The required amount of the pool token (NCT/BCT) + */ function swapExactOutToken( address _fromToken, address _poolToken, @@ -445,14 +456,14 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice Swap eligible ERC20 tokens for Toucan pool tokens (BCT/NCT) on + * @notice Swap eligible ERC20 tokens for pool tokens (BCT/NCT) on * SushiSwap. All provided ERC20 tokens will be swapped. * @dev Needs to be approved on the client side. * @param _fromToken The address of the ERC20 token used for the swap * @param _poolToken The address of the pool token to swap for, * @param _fromAmount The amount of ERC20 token to swap * e.g., NCT - * @return amountOut Resulting amount of Toucan pool token that got acquired for the + * @return amountOut Resulting amount of pool token that got acquired for the * swapped ERC20 tokens. */ function swapExactInToken( @@ -495,11 +506,11 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice Swap native tokens e.g., MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap. + * @notice Swap native tokens e.g., MATIC for pool tokens (BCT/NCT) on SushiSwap. * Remaining native tokens that was not consumed by the swap is returned. * @param _poolToken The address of the pool token to swap for, * e.g., NCT - * @param _toAmount The required amount of the Toucan pool token (NCT/BCT) + * @param _toAmount The required amount of the pool token (NCT/BCT) */ function swapExactOutETH( address _poolToken, @@ -530,11 +541,11 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice Swap native tokens e.g., MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap. All + * @notice Swap native tokens e.g., MATIC for pool tokens (BCT/NCT) on SushiSwap. All * provided native tokens will be swapped. * @param _poolToken The address of the pool token to swap for, * e.g., NCT - * @return amountOut Resulting amount of Toucan pool token that got acquired for the + * @return amountOut Resulting amount of pool token that got acquired for the * swapped native tokens . */ function swapExactInETH( @@ -595,7 +606,7 @@ contract OffsetHelper is OffsetHelperStorage { /** * @notice Return how much of the specified ERC20 token is required in - * order to swap for the desired amount of a Toucan pool token, for + * order to swap for the desired amount of a pool token, for * example, e.g., NCT. * * @param _fromToken The address of the ERC20 token used for the swap @@ -626,7 +637,7 @@ contract OffsetHelper is OffsetHelperStorage { /** * @notice Return how much native tokens e.g, MATIC is required in order to swap for the - * desired amount of a Toucan pool token, e.g., NCT. + * desired amount of a pool token, e.g., NCT. * @param _poolToken The address of the pool token to swap for, for * example, NCT * @param _toAmount The desired amount of pool token to receive @@ -647,7 +658,7 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice Calculates the expected amount of Toucan Pool token that can be + * @notice Calculates the expected amount of pool token that can be * acquired by swapping the provided amount of ERC20 token. * * @param _fromToken The address of the ERC20 token used for the swap @@ -676,16 +687,7 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice Swap eligible ERC20 tokens for Toucan pool tokens (BCT/NCT) on SushiSwap - * @dev Needs to be approved on the client side - * @param _fromToken The address of the ERC20 token used for the swap - * @param _poolToken The address of the pool token to swap for, - * e.g., NCT - * @param _toAmount The required amount of the Toucan pool token (NCT/BCT) - */ - - /** - * @notice Calculates the expected amount of Toucan Pool token that can be + * @notice Calculates the expected amount of pool token that can be * acquired by swapping the provided amount of native tokens e.g., MATIC. * * @param _fromTokenAmount The amount of native tokens to swap @@ -798,9 +800,9 @@ contract OffsetHelper is OffsetHelperStorage { // ---------------------------------------- /** - * @notice Checks whether an address is a Toucan pool token address + * @notice Checks whether an address is a pool token address * @param _erc20Address address of token to be checked - * @return True if the address is a Toucan pool token address + * @return True if the address is a pool token address */ function isRedeemable(address _erc20Address) private view returns (bool) { for (uint i = 0; i < poolAddresses.length; i++) { diff --git a/docs/OffsetHelper.md b/docs/OffsetHelper.md index 6ae4e66..997a197 100644 --- a/docs/OffsetHelper.md +++ b/docs/OffsetHelper.md @@ -157,7 +157,7 @@ specified quantity of TCO2. This function: 1. Swaps the ERC20 token sent to the contract for the specified pool token. -2. Redeems the pool token for the poorest quality TCO2 tokens available. +2. Redeems the pool token for the oldest TCO2 tokens available. 3. Retires the TCO2 tokens. Note: The client must approve the ERC20 token that is sent to the contract. @@ -195,7 +195,7 @@ offsetting. This function: 1. Swaps the ERC20 token sent to the contract for the specified pool token. -2. Redeems the pool token for the poorest quality TCO2 tokens available. +2. Redeems the pool token for the oldest TCO2 tokens available. 3. Retires the TCO2 tokens. Note: The client must approve the ERC20 token that is sent to the contract. @@ -233,7 +233,7 @@ MATIC is required to retire the specified quantity of TCO2. This function: 1. Swaps the Matic sent to the contract for the specified pool token. -2. Redeems the pool token for the poorest quality TCO2 tokens available. +2. Redeems the pool token for the oldest TCO2 tokens available. 3. Retires the TCO2 tokens. _If the user sends much MATIC, the leftover amount will be sent back @@ -266,7 +266,7 @@ All provided MATIC is consumed for offsetting. This function: 1. Swaps the Matic sent to the contract for the specified pool token. -2. Redeems the pool token for the poorest quality TCO2 tokens available. +2. Redeems the pool token for the oldest TCO2 tokens available. 3. Retires the TCO2 tokens. #### Parameters @@ -293,7 +293,7 @@ tokens available by sending Toucan pool tokens, for example, BCT or NCT. This function: -1. Redeems the pool token for the poorest quality TCO2 tokens available. +1. Redeems the pool token for the oldest TCO2 tokens available. 2. Retires the TCO2 tokens. Note: The client must approve the pool token that is sent.