diff --git a/contracts/OffsetHelper.sol b/contracts/OffsetHelper.sol index 91a2ce8..86c327f 100644 --- a/contracts/OffsetHelper.sol +++ b/contracts/OffsetHelper.sol @@ -15,8 +15,8 @@ import "hardhat/console.sol"; * @notice Helper functions that simplify the carbon offsetting (retirement) * process. * - * Retiring carbon tokens normally requires multiple steps and interactions - * with Toucan Protocol's main contracts: + * Retiring carbon tokens requires multiple steps and interactions with + * Toucan Protocol's main contracts: * 1. Obtain a Toucan pool token such as BCT or NCT (by performing a token * swap). * 2. Redeem the pool token for a TCO2 token. @@ -24,7 +24,7 @@ import "hardhat/console.sol"; * * These steps are combined in each of the following "auto offset" methods * implemented in `OffsetHelper` to allow a retirement within one transaction: - * - `autoOffsetUsingPoolToken()` if the user has already owns a Toucan pool + * - `autoOffsetUsingPoolToken()` if the user already owns a Toucan pool * token such as BCT or NCT, * - `autoOffsetUsingETH()` if the user would like to perform a retirement * using MATIC, @@ -32,19 +32,32 @@ import "hardhat/console.sol"; * using an ERC20 token: USDC, WETH or WMATIC. * * In these methods, "auto" refers to the fact that these methods use - * `autoRedeem` in order to automatically choose a TCO2 token corresponding + * `autoRedeem()` in order to automatically choose a TCO2 token corresponding * to the oldest tokenized carbon project in the specfified token pool. - * There are no fees incurred by the user when using `autoRedeem`. + * There are no fees incurred by the user when using `autoRedeem()`, i.e., the + * user receives 1 TCO2 token for each pool token (BCT/NCT) redeemed. * - * There are two read helper functions `calculateNeededETHAmount()` and - * `calculateNeededTokenAmount()` that can be used before calling - * `autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how MATIC, - * respectively how much of the ERC20 token must be sent to the `OffsetHelper` - * contract in order to retire the specified amount of carbon. + * There are two `view` helper functions `calculateNeededETHAmount()` and + * `calculateNeededTokenAmount()` that should be called before using + * `autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how much + * MATIC, respectively how much of the ERC20 token must be sent to the + * `OffsetHelper` contract in order to retire the specified amount of carbon. */ contract OffsetHelper is OffsetHelperStorage { using SafeERC20 for IERC20; + /** + * @notice Contract constructor. Should specify arrays of ERC20 symbols and + * addresses that can used by the contract. + * + * @dev See `isEligible()` for a list of tokens that can be used in the + * contract. These can be modified after deployment by the contract owner + * using `setEligibleTokenAddress()` and `deleteEligibleTokenAddress()`. + * + * @param _eligibleTokenSymbols A list of token symbols. + * @param _eligibleTokenAddresses A list of token addresses corresponding + * to the provided token symbols. + */ constructor( string[] memory _eligibleTokenSymbols, address[] memory _eligibleTokenAddresses @@ -265,9 +278,9 @@ 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 token to deposit and swap - * @param _toToken token to swap for (will be held within contract) - * @param _amount amount of NCT / BCT wanted + * @param _fromToken The ERC20 oken to deposit and swap + * @param _toToken The token to swap for (will be held within contract) + * @param _amount The required amount of the Toucan pool token (NCT/BCT) */ function swap( address _fromToken, @@ -358,8 +371,8 @@ contract OffsetHelper is OffsetHelperStorage { /** * @notice Swap MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap - * @param _toToken token to swap for (will be held within contract) - * @param _amount amount of NCT / BCT wanted + * @param _toToken Token to swap for (will be held within contract) + * @param _amount Amount of NCT / BCT wanted */ function swap(address _toToken, uint256 _amount) public payable { // check tokens @@ -403,7 +416,7 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice allow users to withdraw tokens they have deposited + * @notice Allow users to withdraw tokens they have deposited. */ function withdraw(address _erc20Addr, uint256 _amount) public { require( @@ -416,8 +429,8 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice allow people to deposit BCT / NCT - * @dev needs to be approved + * @notice Allow users to deposit BCT / NCT. + * @dev Needs to be approved */ function deposit(address _erc20Addr, uint256 _amount) public { require(isRedeemable(_erc20Addr), "Token not eligible"); @@ -427,12 +440,12 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice Redeems the specified amount of NCT / BCT for TCO2 - * @dev needs to be approved on the client side - * @param _fromToken could be the address of NCT or BCT - * @param _amount amount to redeem - * @return tco2s an array of the TCO2 addresses that were redeemed - * @return amounts an array of the amounts of each TCO2 that were redeemed + * @notice Redeems the specified amount of NCT / BCT for TCO2. + * @dev Needs to be approved on the client side + * @param _fromToken Could be the address of NCT or BCT + * @param _amount Amount to redeem + * @return tco2s An array of the TCO2 addresses that were redeemed + * @return amounts An array of the amounts of each TCO2 that were redeemed */ function autoRedeem(address _fromToken, uint256 _amount) public @@ -463,8 +476,9 @@ contract OffsetHelper is OffsetHelperStorage { /** * @notice Retire the specified TCO2 tokens. - * @param _tco2s the addresses of the TCO2s to retire - * @param _amounts the amounts to retire from the matching TCO2 + * @param _tco2s The addresses of the TCO2s to retire + * @param _amounts The amounts to retire from each of the corresponding + * TCO2 addresses */ function autoRetire(address[] memory _tco2s, uint256[] memory _amounts) public @@ -496,9 +510,9 @@ contract OffsetHelper is OffsetHelperStorage { // ---------------------------------------- /** - * @notice you can use this to change or add eligible tokens and their addresses if needed - * @param _tokenSymbol symbol of the token to add - * @param _address the address of the token to add + * @notice Change or add eligible tokens and their addresses. + * @param _tokenSymbol The symbol of the token to add + * @param _address The address of the token to add */ function setEligibleTokenAddress( string memory _tokenSymbol, @@ -508,8 +522,8 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice you can use this to delete eligible tokens if needed - * @param _tokenSymbol symbol of the token to add + * @notice Delete eligible tokens stored in the contract. + * @param _tokenSymbol The symbol of the token to remove */ function deleteEligibleTokenAddress(string memory _tokenSymbol) public @@ -520,8 +534,8 @@ contract OffsetHelper is OffsetHelperStorage { } /** - * @notice you can use this to change the TCO2 contracts registry if needed - * @param _address the contract registry to use + * @notice Change the TCO2 contracts registry. + * @param _address The address of the Toucan contract registry to use */ function setToucanContractRegistry(address _address) public diff --git a/docs/OffsetHelper.md b/docs/OffsetHelper.md index 7a303ec..b6ad78d 100644 --- a/docs/OffsetHelper.md +++ b/docs/OffsetHelper.md @@ -5,8 +5,8 @@ Helper functions that simplify the carbon offsetting (retirement) process. -Retiring carbon tokens normally requires multiple steps and interactions -with Toucan Protocol's main contracts: +Retiring carbon tokens requires multiple steps and interactions with +Toucan Protocol's main contracts: 1. Obtain a Toucan pool token such as BCT or NCT (by performing a token swap). 2. Redeem the pool token for a TCO2 token. @@ -14,7 +14,7 @@ with Toucan Protocol's main contracts: These steps are combined in each of the following "auto offset" methods implemented in `OffsetHelper` to allow a retirement within one transaction: -- `autoOffsetUsingPoolToken()` if the user has already owns a Toucan pool +- `autoOffsetUsingPoolToken()` if the user already owns a Toucan pool token such as BCT or NCT, - `autoOffsetUsingETH()` if the user would like to perform a retirement using MATIC, @@ -22,15 +22,16 @@ implemented in `OffsetHelper` to allow a retirement within one transaction: using an ERC20 token: USDC, WETH or WMATIC. In these methods, "auto" refers to the fact that these methods use -`autoRedeem` in order to automatically choose a TCO2 token corresponding +`autoRedeem()` in order to automatically choose a TCO2 token corresponding to the oldest tokenized carbon project in the specfified token pool. -There are no fees incurred by the user when using `autoRedeem`. +There are no fees incurred by the user when using `autoRedeem()`, i.e., the +user receives 1 TCO2 token for each pool token (BCT/NCT) redeemed. -There are two read helper functions `calculateNeededETHAmount()` and -`calculateNeededTokenAmount()` that can be used before calling -`autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how MATIC, -respectively how much of the ERC20 token must be sent to the `OffsetHelper` -contract in order to retire the specified amount of carbon. +There are two `view` helper functions `calculateNeededETHAmount()` and +`calculateNeededTokenAmount()` that should be called before using +`autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how much + MATIC, respectively how much of the ERC20 token must be sent to the +`OffsetHelper` contract in order to retire the specified amount of carbon. ### constructor @@ -38,6 +39,18 @@ contract in order to retire the specified amount of carbon. constructor(string[] _eligibleTokenSymbols, address[] _eligibleTokenAddresses) public ``` +Contract constructor. Should specify arrays of ERC20 symbols and +addresses that can used by the contract. + +_See `isEligible()` for a list of tokens that can be used in the +contract. These can be modified after deployment by the contract owner +using `setEligibleTokenAddress()` and `deleteEligibleTokenAddress()`._ + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _eligibleTokenSymbols | string[] | A list of token symbols. | +| _eligibleTokenAddresses | address[] | A list of token addresses corresponding to the provided token symbols. | + ### Redeemed ```solidity @@ -222,9 +235,9 @@ _Needs to be approved on the client side_ | Name | Type | Description | | ---- | ---- | ----------- | -| _fromToken | address | token to deposit and swap | -| _toToken | address | token to swap for (will be held within contract) | -| _amount | uint256 | amount of NCT / BCT wanted | +| _fromToken | address | The ERC20 oken to deposit and swap | +| _toToken | address | The token to swap for (will be held within contract) | +| _amount | uint256 | The required amount of the Toucan pool token (NCT/BCT) | ### fallback @@ -266,8 +279,8 @@ Swap MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap | Name | Type | Description | | ---- | ---- | ----------- | -| _toToken | address | token to swap for (will be held within contract) | -| _amount | uint256 | amount of NCT / BCT wanted | +| _toToken | address | Token to swap for (will be held within contract) | +| _amount | uint256 | Amount of NCT / BCT wanted | ### withdraw @@ -275,7 +288,7 @@ Swap MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap function withdraw(address _erc20Addr, uint256 _amount) public ``` -allow users to withdraw tokens they have deposited +Allow users to withdraw tokens they have deposited. ### deposit @@ -283,9 +296,9 @@ allow users to withdraw tokens they have deposited function deposit(address _erc20Addr, uint256 _amount) public ``` -allow people to deposit BCT / NCT +Allow users to deposit BCT / NCT. -_needs to be approved_ +_Needs to be approved_ ### autoRedeem @@ -293,19 +306,19 @@ _needs to be approved_ function autoRedeem(address _fromToken, uint256 _amount) public returns (address[] tco2s, uint256[] amounts) ``` -Redeems the specified amount of NCT / BCT for TCO2 +Redeems the specified amount of NCT / BCT for TCO2. -_needs to be approved on the client side_ +_Needs to be approved on the client side_ | Name | Type | Description | | ---- | ---- | ----------- | -| _fromToken | address | could be the address of NCT or BCT | -| _amount | uint256 | amount to redeem | +| _fromToken | address | Could be the address of NCT or BCT | +| _amount | uint256 | Amount to redeem | | Name | Type | Description | | ---- | ---- | ----------- | -| tco2s | address[] | an array of the TCO2 addresses that were redeemed | -| amounts | uint256[] | an array of the amounts of each TCO2 that were redeemed | +| tco2s | address[] | An array of the TCO2 addresses that were redeemed | +| amounts | uint256[] | An array of the amounts of each TCO2 that were redeemed | ### autoRetire @@ -317,8 +330,8 @@ Retire the specified TCO2 tokens. | Name | Type | Description | | ---- | ---- | ----------- | -| _tco2s | address[] | the addresses of the TCO2s to retire | -| _amounts | uint256[] | the amounts to retire from the matching TCO2 | +| _tco2s | address[] | The addresses of the TCO2s to retire | +| _amounts | uint256[] | The amounts to retire from each of the corresponding TCO2 addresses | ### setEligibleTokenAddress @@ -326,12 +339,12 @@ Retire the specified TCO2 tokens. function setEligibleTokenAddress(string _tokenSymbol, address _address) public virtual ``` -you can use this to change or add eligible tokens and their addresses if needed +Change or add eligible tokens and their addresses. | Name | Type | Description | | ---- | ---- | ----------- | -| _tokenSymbol | string | symbol of the token to add | -| _address | address | the address of the token to add | +| _tokenSymbol | string | The symbol of the token to add | +| _address | address | The address of the token to add | ### deleteEligibleTokenAddress @@ -339,11 +352,11 @@ you can use this to change or add eligible tokens and their addresses if needed function deleteEligibleTokenAddress(string _tokenSymbol) public virtual ``` -you can use this to delete eligible tokens if needed +Delete eligible tokens stored in the contract. | Name | Type | Description | | ---- | ---- | ----------- | -| _tokenSymbol | string | symbol of the token to add | +| _tokenSymbol | string | The symbol of the token to remove | ### setToucanContractRegistry @@ -351,9 +364,9 @@ you can use this to delete eligible tokens if needed function setToucanContractRegistry(address _address) public virtual ``` -you can use this to change the TCO2 contracts registry if needed +Change the TCO2 contracts registry. | Name | Type | Description | | ---- | ---- | ----------- | -| _address | address | the contract registry to use | +| _address | address | The address of the Toucan contract registry to use |