Skip to content

Commit 5e5ad46

Browse files
danceratopzdanceratopz
committed
docs: document constructor and minor improvements
1 parent bde4014 commit 5e5ad46

File tree

2 files changed

+93
-66
lines changed

2 files changed

+93
-66
lines changed

‎contracts/OffsetHelper.sol

Lines changed: 47 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -15,36 +15,49 @@ import "hardhat/console.sol";
1515
* @notice Helper functions that simplify the carbon offsetting (retirement)
1616
* process.
1717
*
18-
* Retiring carbon tokens normally requires multiple steps and interactions
19-
* with Toucan Protocol's main contracts:
18+
* Retiring carbon tokens requires multiple steps and interactions with
19+
* Toucan Protocol's main contracts:
2020
* 1. Obtain a Toucan pool token such as BCT or NCT (by performing a token
2121
* swap).
2222
* 2. Redeem the pool token for a TCO2 token.
2323
* 3. Retire the TCO2 token.
2424
*
2525
* These steps are combined in each of the following "auto offset" methods
2626
* implemented in `OffsetHelper` to allow a retirement within one transaction:
27-
* - `autoOffsetUsingPoolToken()` if the user has already owns a Toucan pool
27+
* - `autoOffsetUsingPoolToken()` if the user already owns a Toucan pool
2828
* token such as BCT or NCT,
2929
* - `autoOffsetUsingETH()` if the user would like to perform a retirement
3030
* using MATIC,
3131
* - `autoOffsetUsingToken()` if the user would like to perform a retirement
3232
* using an ERC20 token: USDC, WETH or WMATIC.
3333
*
3434
* In these methods, "auto" refers to the fact that these methods use
35-
* `autoRedeem` in order to automatically choose a TCO2 token corresponding
35+
* `autoRedeem()` in order to automatically choose a TCO2 token corresponding
3636
* to the oldest tokenized carbon project in the specfified token pool.
37-
* There are no fees incurred by the user when using `autoRedeem`.
37+
* There are no fees incurred by the user when using `autoRedeem()`, i.e., the
38+
* user receives 1 TCO2 token for each pool token (BCT/NCT) redeemed.
3839
*
39-
* There are two read helper functions `calculateNeededETHAmount()` and
40-
* `calculateNeededTokenAmount()` that can be used before calling
41-
* `autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how MATIC,
42-
* respectively how much of the ERC20 token must be sent to the `OffsetHelper`
43-
* contract in order to retire the specified amount of carbon.
40+
* There are two `view` helper functions `calculateNeededETHAmount()` and
41+
* `calculateNeededTokenAmount()` that should be called before using
42+
* `autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how much
43+
* MATIC, respectively how much of the ERC20 token must be sent to the
44+
* `OffsetHelper` contract in order to retire the specified amount of carbon.
4445
*/
4546
contract OffsetHelper is OffsetHelperStorage {
4647
using SafeERC20 for IERC20;
4748

49+
/**
50+
* @notice Contract constructor. Should specify arrays of ERC20 symbols and
51+
* addresses that can used by the contract.
52+
*
53+
* @dev See `isEligible()` for a list of tokens that can be used in the
54+
* contract. These can be modified after deployment by the contract owner
55+
* using `setEligibleTokenAddress()` and `deleteEligibleTokenAddress()`.
56+
*
57+
* @param _eligibleTokenSymbols A list of token symbols.
58+
* @param _eligibleTokenAddresses A list of token addresses corresponding
59+
* to the provided token symbols.
60+
*/
4861
constructor(
4962
string[] memory _eligibleTokenSymbols,
5063
address[] memory _eligibleTokenAddresses
@@ -265,9 +278,9 @@ contract OffsetHelper is OffsetHelperStorage {
265278
/**
266279
* @notice Swap eligible ERC20 tokens for Toucan pool tokens (BCT/NCT) on SushiSwap
267280
* @dev Needs to be approved on the client side
268-
* @param _fromToken token to deposit and swap
269-
* @param _toToken token to swap for (will be held within contract)
270-
* @param _amount amount of NCT / BCT wanted
281+
* @param _fromToken The ERC20 oken to deposit and swap
282+
* @param _toToken The token to swap for (will be held within contract)
283+
* @param _amount The required amount of the Toucan pool token (NCT/BCT)
271284
*/
272285
function swap(
273286
address _fromToken,
@@ -358,8 +371,8 @@ contract OffsetHelper is OffsetHelperStorage {
358371

359372
/**
360373
* @notice Swap MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap
361-
* @param _toToken token to swap for (will be held within contract)
362-
* @param _amount amount of NCT / BCT wanted
374+
* @param _toToken Token to swap for (will be held within contract)
375+
* @param _amount Amount of NCT / BCT wanted
363376
*/
364377
function swap(address _toToken, uint256 _amount) public payable {
365378
// check tokens
@@ -403,7 +416,7 @@ contract OffsetHelper is OffsetHelperStorage {
403416
}
404417

405418
/**
406-
* @notice allow users to withdraw tokens they have deposited
419+
* @notice Allow users to withdraw tokens they have deposited.
407420
*/
408421
function withdraw(address _erc20Addr, uint256 _amount) public {
409422
require(
@@ -416,8 +429,8 @@ contract OffsetHelper is OffsetHelperStorage {
416429
}
417430

418431
/**
419-
* @notice allow people to deposit BCT / NCT
420-
* @dev needs to be approved
432+
* @notice Allow users to deposit BCT / NCT.
433+
* @dev Needs to be approved
421434
*/
422435
function deposit(address _erc20Addr, uint256 _amount) public {
423436
require(isRedeemable(_erc20Addr), "Token not eligible");
@@ -427,12 +440,12 @@ contract OffsetHelper is OffsetHelperStorage {
427440
}
428441

429442
/**
430-
* @notice Redeems the specified amount of NCT / BCT for TCO2
431-
* @dev needs to be approved on the client side
432-
* @param _fromToken could be the address of NCT or BCT
433-
* @param _amount amount to redeem
434-
* @return tco2s an array of the TCO2 addresses that were redeemed
435-
* @return amounts an array of the amounts of each TCO2 that were redeemed
443+
* @notice Redeems the specified amount of NCT / BCT for TCO2.
444+
* @dev Needs to be approved on the client side
445+
* @param _fromToken Could be the address of NCT or BCT
446+
* @param _amount Amount to redeem
447+
* @return tco2s An array of the TCO2 addresses that were redeemed
448+
* @return amounts An array of the amounts of each TCO2 that were redeemed
436449
*/
437450
function autoRedeem(address _fromToken, uint256 _amount)
438451
public
@@ -463,8 +476,9 @@ contract OffsetHelper is OffsetHelperStorage {
463476

464477
/**
465478
* @notice Retire the specified TCO2 tokens.
466-
* @param _tco2s the addresses of the TCO2s to retire
467-
* @param _amounts the amounts to retire from the matching TCO2
479+
* @param _tco2s The addresses of the TCO2s to retire
480+
* @param _amounts The amounts to retire from each of the corresponding
481+
* TCO2 addresses
468482
*/
469483
function autoRetire(address[] memory _tco2s, uint256[] memory _amounts)
470484
public
@@ -496,9 +510,9 @@ contract OffsetHelper is OffsetHelperStorage {
496510
// ----------------------------------------
497511

498512
/**
499-
* @notice you can use this to change or add eligible tokens and their addresses if needed
500-
* @param _tokenSymbol symbol of the token to add
501-
* @param _address the address of the token to add
513+
* @notice Change or add eligible tokens and their addresses.
514+
* @param _tokenSymbol The symbol of the token to add
515+
* @param _address The address of the token to add
502516
*/
503517
function setEligibleTokenAddress(
504518
string memory _tokenSymbol,
@@ -508,8 +522,8 @@ contract OffsetHelper is OffsetHelperStorage {
508522
}
509523

510524
/**
511-
* @notice you can use this to delete eligible tokens if needed
512-
* @param _tokenSymbol symbol of the token to add
525+
* @notice Delete eligible tokens stored in the contract.
526+
* @param _tokenSymbol The symbol of the token to remove
513527
*/
514528
function deleteEligibleTokenAddress(string memory _tokenSymbol)
515529
public
@@ -520,8 +534,8 @@ contract OffsetHelper is OffsetHelperStorage {
520534
}
521535

522536
/**
523-
* @notice you can use this to change the TCO2 contracts registry if needed
524-
* @param _address the contract registry to use
537+
* @notice Change the TCO2 contracts registry.
538+
* @param _address The address of the Toucan contract registry to use
525539
*/
526540
function setToucanContractRegistry(address _address)
527541
public

‎docs/OffsetHelper.md

Lines changed: 46 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -5,39 +5,52 @@
55
Helper functions that simplify the carbon offsetting (retirement)
66
process.
77

8-
Retiring carbon tokens normally requires multiple steps and interactions
9-
with Toucan Protocol's main contracts:
8+
Retiring carbon tokens requires multiple steps and interactions with
9+
Toucan Protocol's main contracts:
1010
1. Obtain a Toucan pool token such as BCT or NCT (by performing a token
1111
swap).
1212
2. Redeem the pool token for a TCO2 token.
1313
3. Retire the TCO2 token.
1414

1515
These steps are combined in each of the following "auto offset" methods
1616
implemented in `OffsetHelper` to allow a retirement within one transaction:
17-
- `autoOffsetUsingPoolToken()` if the user has already owns a Toucan pool
17+
- `autoOffsetUsingPoolToken()` if the user already owns a Toucan pool
1818
token such as BCT or NCT,
1919
- `autoOffsetUsingETH()` if the user would like to perform a retirement
2020
using MATIC,
2121
- `autoOffsetUsingToken()` if the user would like to perform a retirement
2222
using an ERC20 token: USDC, WETH or WMATIC.
2323

2424
In these methods, "auto" refers to the fact that these methods use
25-
`autoRedeem` in order to automatically choose a TCO2 token corresponding
25+
`autoRedeem()` in order to automatically choose a TCO2 token corresponding
2626
to the oldest tokenized carbon project in the specfified token pool.
27-
There are no fees incurred by the user when using `autoRedeem`.
27+
There are no fees incurred by the user when using `autoRedeem()`, i.e., the
28+
user receives 1 TCO2 token for each pool token (BCT/NCT) redeemed.
2829

29-
There are two read helper functions `calculateNeededETHAmount()` and
30-
`calculateNeededTokenAmount()` that can be used before calling
31-
`autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how MATIC,
32-
respectively how much of the ERC20 token must be sent to the `OffsetHelper`
33-
contract in order to retire the specified amount of carbon.
30+
There are two `view` helper functions `calculateNeededETHAmount()` and
31+
`calculateNeededTokenAmount()` that should be called before using
32+
`autoOffsetUsingETH()` and `autoOffsetUsingToken()`, to determine how much
33+
MATIC, respectively how much of the ERC20 token must be sent to the
34+
`OffsetHelper` contract in order to retire the specified amount of carbon.
3435

3536
### constructor
3637

3738
```solidity
3839
constructor(string[] _eligibleTokenSymbols, address[] _eligibleTokenAddresses) public
3940
```
4041

42+
Contract constructor. Should specify arrays of ERC20 symbols and
43+
addresses that can used by the contract.
44+
45+
_See `isEligible()` for a list of tokens that can be used in the
46+
contract. These can be modified after deployment by the contract owner
47+
using `setEligibleTokenAddress()` and `deleteEligibleTokenAddress()`._
48+
49+
| Name | Type | Description |
50+
| ---- | ---- | ----------- |
51+
| _eligibleTokenSymbols | string[] | A list of token symbols. |
52+
| _eligibleTokenAddresses | address[] | A list of token addresses corresponding to the provided token symbols. |
53+
4154
### Redeemed
4255

4356
```solidity
@@ -222,9 +235,9 @@ _Needs to be approved on the client side_
222235

223236
| Name | Type | Description |
224237
| ---- | ---- | ----------- |
225-
| _fromToken | address | token to deposit and swap |
226-
| _toToken | address | token to swap for (will be held within contract) |
227-
| _amount | uint256 | amount of NCT / BCT wanted |
238+
| _fromToken | address | The ERC20 oken to deposit and swap |
239+
| _toToken | address | The token to swap for (will be held within contract) |
240+
| _amount | uint256 | The required amount of the Toucan pool token (NCT/BCT) |
228241

229242
### fallback
230243

@@ -266,46 +279,46 @@ Swap MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap
266279

267280
| Name | Type | Description |
268281
| ---- | ---- | ----------- |
269-
| _toToken | address | token to swap for (will be held within contract) |
270-
| _amount | uint256 | amount of NCT / BCT wanted |
282+
| _toToken | address | Token to swap for (will be held within contract) |
283+
| _amount | uint256 | Amount of NCT / BCT wanted |
271284

272285
### withdraw
273286

274287
```solidity
275288
function withdraw(address _erc20Addr, uint256 _amount) public
276289
```
277290

278-
allow users to withdraw tokens they have deposited
291+
Allow users to withdraw tokens they have deposited.
279292

280293
### deposit
281294

282295
```solidity
283296
function deposit(address _erc20Addr, uint256 _amount) public
284297
```
285298

286-
allow people to deposit BCT / NCT
299+
Allow users to deposit BCT / NCT.
287300

288-
_needs to be approved_
301+
_Needs to be approved_
289302

290303
### autoRedeem
291304

292305
```solidity
293306
function autoRedeem(address _fromToken, uint256 _amount) public returns (address[] tco2s, uint256[] amounts)
294307
```
295308

296-
Redeems the specified amount of NCT / BCT for TCO2
309+
Redeems the specified amount of NCT / BCT for TCO2.
297310

298-
_needs to be approved on the client side_
311+
_Needs to be approved on the client side_
299312

300313
| Name | Type | Description |
301314
| ---- | ---- | ----------- |
302-
| _fromToken | address | could be the address of NCT or BCT |
303-
| _amount | uint256 | amount to redeem |
315+
| _fromToken | address | Could be the address of NCT or BCT |
316+
| _amount | uint256 | Amount to redeem |
304317

305318
| Name | Type | Description |
306319
| ---- | ---- | ----------- |
307-
| tco2s | address[] | an array of the TCO2 addresses that were redeemed |
308-
| amounts | uint256[] | an array of the amounts of each TCO2 that were redeemed |
320+
| tco2s | address[] | An array of the TCO2 addresses that were redeemed |
321+
| amounts | uint256[] | An array of the amounts of each TCO2 that were redeemed |
309322

310323
### autoRetire
311324

@@ -317,43 +330,43 @@ Retire the specified TCO2 tokens.
317330

318331
| Name | Type | Description |
319332
| ---- | ---- | ----------- |
320-
| _tco2s | address[] | the addresses of the TCO2s to retire |
321-
| _amounts | uint256[] | the amounts to retire from the matching TCO2 |
333+
| _tco2s | address[] | The addresses of the TCO2s to retire |
334+
| _amounts | uint256[] | The amounts to retire from each of the corresponding TCO2 addresses |
322335

323336
### setEligibleTokenAddress
324337

325338
```solidity
326339
function setEligibleTokenAddress(string _tokenSymbol, address _address) public virtual
327340
```
328341

329-
you can use this to change or add eligible tokens and their addresses if needed
342+
Change or add eligible tokens and their addresses.
330343

331344
| Name | Type | Description |
332345
| ---- | ---- | ----------- |
333-
| _tokenSymbol | string | symbol of the token to add |
334-
| _address | address | the address of the token to add |
346+
| _tokenSymbol | string | The symbol of the token to add |
347+
| _address | address | The address of the token to add |
335348

336349
### deleteEligibleTokenAddress
337350

338351
```solidity
339352
function deleteEligibleTokenAddress(string _tokenSymbol) public virtual
340353
```
341354

342-
you can use this to delete eligible tokens if needed
355+
Delete eligible tokens stored in the contract.
343356

344357
| Name | Type | Description |
345358
| ---- | ---- | ----------- |
346-
| _tokenSymbol | string | symbol of the token to add |
359+
| _tokenSymbol | string | The symbol of the token to remove |
347360

348361
### setToucanContractRegistry
349362

350363
```solidity
351364
function setToucanContractRegistry(address _address) public virtual
352365
```
353366

354-
you can use this to change the TCO2 contracts registry if needed
367+
Change the TCO2 contracts registry.
355368

356369
| Name | Type | Description |
357370
| ---- | ---- | ----------- |
358-
| _address | address | the contract registry to use |
371+
| _address | address | The address of the Toucan contract registry to use |
359372

0 commit comments

Comments
 (0)