Toucan
Ask or search…
K

OffsetHelper

The OffsetHelper contract implements helper functions that simplify the carbon offsetting (retirement) process.
This contract lives in this repository. Its purpose is to simplify the carbon offsetting process.
What it does in more exact terms is it abstracts the process of retiring TCO2, which normally looks like the following steps:
  • user exchanges ERC20 tokens e.g., cUSD or USDC for pool tokens (e.g., NCT) at a DEX (Uniswap Ubeswap on Celo and SushiSwap on Polygon, etc. depending on the network)
  • user interacts with the pool token contract to redeem the tokens for TCO2
  • user interacts with the TCO2 token contract to retire the TCO2
The user can use ERC20 tokens listed below to interact with the OffsetHelper contract which takes care of executing all the above steps in a single transaction.
In these methods, "auto" refers to the fact that these methods use 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(), i.e., t e user receives 1 TCO2 token for each pool token e.g., NCT redeemed.
When automatically redeeming pool tokens for the oldest TCO2s there are no fees and you receive exactly 1 TCO2 token for 1 pool token.
Testing the OffsetHelper on testnet may lead to an Error: execution reverted as the OffsetHelper depends on available liquidity in some DEX pools, which can not always be guaranteed.

Accepted tokens

Chain
Tokens
Celo
cUSD, WETH, USDC
Polygon
USDC, WETH, WMATIC

Functions

autoOffsetExactOutToken

function autoOffsetExactOutToken(address _fromToken, address _poolToken, uint256 _amountToOffset) public returns (address[] tco2s, uint256[] amounts)
Retire carbon credits using the oldest TCO2 tokens available from the specified Toucan token pool by sending ERC20 tokens (cUSD, USDC, WETH, WMATIC). The view helper function calculateNeededTokenAmount() should be called before using autoOffsetExactOutToken(), to determine how much native tokens e.g., MATIC must be sent to the OffsetHelper contract in order to retire the specified amount of carbon.
This function:
  1. 1.
    Swaps the ERC20 token sent to the contract for the specified pool token.
  2. 2.
    Redeems the pool token for the poorest quality TCO2 tokens available.
  3. 3.
    Retires the TCO2 tokens.
Note: The client must approve the ERC20 token that is sent to the contract.
When automatically redeeming pool tokens for the oldest TCO2s there are no fees and you receive exactly 1 TCO2 token for 1 pool token.

Parameters

Name
Type
Description
_fromToken
address
The address of the ERC20 token that the user sends (e.g., cUSD, cUSD, USDC, WETH, WMATIC)
_poolToken
address
The address of the Toucan pool token that the user wants to offset, e.g., NCT
_amountToOffset
uint256
The amount of TCO2 to offset

Return Values

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

autoOffsetExactInToken

function autoOffsetExactInToken(address _fromToken, address _poolToken, uint256 _amountToSwap) public returns (address[] tco2s, uint256[] amounts)
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.
The view helper function calculateExpectedPoolTokenForToken() can be used to calculate the expected amount of TCO2s that will be offset using autoOffsetExactInToken().
This function:
  1. 1.
    Swaps the ERC20 token sent to the contract for the specified pool token.
  2. 2.
    Redeems the pool token for the poorest quality TCO2 tokens available.
  3. 3.
    Retires the TCO2 tokens.
Note: The client must approve the ERC20 token that is sent to the contract.
When automatically redeeming pool tokens for the oldest TCO2s there are no fees and you receive exactly 1 TCO2 token for 1 pool token.

Parameters

Name
Type
Description
_fromToken
address
The address of the ERC20 token that the user sends (e.g., cUSD, cUSD, USDC, WETH, WMATIC)
_poolToken
address
The address of the pool token to offset, e.g., NCT
_amountToSwap
uint256
The amount of ERC20 token to swap into Toucan pool token. Full amount will be used for offsetting.

Return Values

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

autoOffsetExactOutETH

function autoOffsetExactOutETH(address _poolToken, uint256 _amountToOffset) public payable returns (address[] tco2s, uint256[] amounts)
Retire carbon credits using the oldest TCO2 tokens available from the specified Toucan token pool by sending native tokens e.g., MATIC.
The view helper function calculateNeededETHAmount() should be called before using autoOffsetExactOutETH(), to determine how much native tokens e.g., MATIC must be sent to the OffsetHelper contract in order to retire the specified amount of carbon.
This function:
  1. 1.
    Swaps the native token e.g. MATIC sent to the contract for the specified pool token.
  2. 2.
    Redeems the pool token for the poorest quality TCO2 tokens available.
  3. 3.
    Retires the TCO2 tokens.
If the user sends too much native tokens , the leftover amount will be sent back to the user. This function is only available on Polygon, not on Celo.

Parameters

Name
Type
Description
_poolToken
address
The address of the pool token to offset, e.g., NCT
_amountToOffset
uint256
The amount of TCO2 to offset.

Return Values

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

autoOffsetExactInETH

function autoOffsetExactInETH(address _poolToken) public payable returns (address[] tco2s, uint256[] amounts)
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.
The view helper function calculateExpectedPoolTokenForETH() can be used to calculate the expected amount of TCO2s that will be offset using autoOffsetExactInETH().
This function:
  1. 1.
    Swaps the native token e.g. MATIC sent to the contract for the specified pool token.
  2. 2.
    Redeems the pool token for the poorest quality TCO2 tokens available.
  3. 3.
    Retires the TCO2 tokens.
This function is only available on Polygon, not on Celo.

Parameters

Name
Type
Description
_poolToken
address
The address of the pool token to offset, e.g., NCT

Return Values

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

autoOffsetPoolToken

function autoOffsetPoolToken(address _poolToken, uint256 _amountToOffset) public returns (address[] tco2s, uint256[] amounts)
Retire carbon credits using the oldest TCO2 tokens available by sending Toucan pool tokens, e.g., NCT.
This function:
  1. 1.
    Redeems the pool token for the poorest quality TCO2 tokens available.
  2. 2.
    Retires the TCO2 tokens.
Note: The client must approve the pool token that is sent.

Parameters

Name
Type
Description
_poolToken
address
The address of the pool token to offset, e.g., NCT
_amountToOffset
uint256
The amount of TCO2 to offset.

Return Values

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

swapExactOutToken

function swapExactOutToken(address _fromToken, address _poolToken, uint256 _toAmount) public
Swap eligible ERC20 tokens for Toucan pool tokens (BCT/NCT) on SushiSwap
Needs to be approved on the client side

Parameters

Name
Type
Description
_fromToken
address
The address of the ERC20 token used for the swap
_poolToken
address
The address of the pool token to swap for, e.g., NCT
_toAmount
uint256
The required amount of the Toucan pool token (NCT/BCT)

swapExactInToken

function swapExactInToken(address _fromToken, address _poolToken, uint256 _fromAmount) public returns (uint256 amountOut)
Swap eligible ERC20 tokens for Toucan pool tokens (BCT/NCT) on SushiSwap. All provided ERC20 tokens will be swapped.
Needs to be approved on the client side.

Parameters

Name
Type
Description
_fromToken
address
The address of the ERC20 token used for the swap
_poolToken
address
The address of the pool token to swap for, e.g., NCT
_fromAmount
uint256
The amount of ERC20 token to swap

Return Values

Name
Type
Description
amountOut
uint256
Resulting amount of Toucan pool token that got acquired for the swapped ERC20 tokens.

swapExactOutETH

function swapExactOutETH(address _poolToken, uint256 _toAmount) public payable
Swap native tokens e.g., MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap. Remaining native tokens that was not consumed by the swap is returned.

Parameters

Name
Type
Description
_poolToken
address
The address of the pool token to swap for, e.g., NCT
_toAmount
uint256
The required amount of the Toucan pool token (NCT/BCT)

swapExactInETH

function swapExactInETH(address _poolToken) public payable returns (uint256 amountOut)
Swap native tokens e.g., MATIC for Toucan pool tokens (BCT/NCT) on SushiSwap. All provided native tokens will be swapped.

Parameters

Name
Type
Description
_poolToken
address
The address of the pool token to swap for, e.g., NCT

Return Values

Name
Type
Description
amountOut
uint256
Resulting amount of Toucan pool token that got acquired for the swapped native tokens .

autoRedeem

function autoRedeem(address _fromToken, uint256 _amount) public returns (address[] tco2s, uint256[] amounts)
Redeems the specified amount of NCT / BCT for TCO2.
Needs to be approved on the client side

Parameters

Name
Type
Description
_fromToken
address
Could be the address of NCT
_amount
uint256
Amount to redeem

Return Values

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

autoRetire

function autoRetire(address[] _tco2s, uint256[] _amounts) public
Retire the specified TCO2 tokens.

Parameters

Name
Type
Description
_tco2s
address[]
The addresses of the TCO2s to retire
_amounts
uint256[]
The amounts to retire from each of the corresponding TCO2 addresses

calculateNeededTokenAmount

function calculateNeededTokenAmount(address _fromToken, address _poolToken, uint256 _toAmount) public view returns (uint256 amountIn)
Return how much of the specified ERC20 token is required in order to swap for the desired amount of a Toucan pool token, for example, e.g., NCT.

Parameters

Name
Type
Description
_fromToken
address
The address of the ERC20 token used for the swap
_poolToken
address
The address of the pool token to swap for, e.g., NCT
_toAmount
uint256
The desired amount of pool token to receive

Return Values

Name
Type
Description
amountIn
uint256
The amount of the ERC20 token required in order to swap for the specified amount of the pool token

calculateExpectedPoolTokenForToken

function calculateExpectedPoolTokenForToken(address _fromToken, address _poolToken, uint256 _fromAmount) public view returns (uint256 amountOut)
Calculates the expected amount of Toucan Pool token that can be acquired by swapping the provided amount of ERC20 token.

Parameters

Name
Type
Description
_fromToken
address
The address of the ERC20 token used for the swap
_poolToken
address
The address of the pool token to swap for, e.g., NCT
_fromAmount
uint256
The amount of ERC20 token to swap

Return Values

Name
Type
Description
amountOut
uint256
The expected amount of Pool token that can be acquired

calculateNeededETHAmount

function calculateNeededETHAmount(address _poolToken, uint256 _toAmount) public view returns (uint256 amountIn)
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.

Parameters

Name
Type
Description
_poolToken
address
The address of the pool token to swap for, e.g., NCT
_toAmount
uint256
The desired amount of pool token to receive

Return Values

Name
Type
Description
amountIn
uint256
The amount of native tokens required in order to swap for the specified amount of the pool token

calculateExpectedPoolTokenForETH

function calculateExpectedPoolTokenForETH(address _poolToken, uint256 _fromTokenAmount) public view returns (uint256 amountOut)
Calculates the expected amount of Toucan Pool token that can be acquired by swapping the provided amount of native tokens e.g., MATIC.

Parameters

Name
Type
Description
_poolToken
address
The address of the pool token to swap for, e.g., NCT
_fromTokenAmount
uint256
The amount of native tokens to swap

Return Values

Name
Type
Description
amountOut
uint256
The expected amount of Pool token that can be acquired

isPoolAddressEligible

function isPoolAddressEligible(address _poolToken) public view returns (bool _isEligible)
Checks if Pool Address is eligible for offsetting.

Parameters

Name
Type
Description
_poolToken
address
The address of the pool token to offset, e.g., NCT

Return Values

Name
Type
Description
_isEligible
bool
Returns a bool if the Pool token is eligible for offsetting

isERC20AddressEligible

function isERC20AddressEligible(address _erc20Address) public view returns (address[] _path)
Checks if ERC20 Token is eligible for swapping.

Parameters

Name
Type
Description
_erc20Address
address
The address of the ERC20 token that the user sends (e.g., cUSD, cUSD, USDC, WETH, WMATIC)

Return Values

Name
Type
Description
_path
address[]
Returns the path of the token to be exchanged