OffsetHelper
The OffsetHelper contract simplifies the carbon offsetting (retirement) process.
The OffsetHelper is a peripheral contract that simplifies the experience of buying and redeeming carbon reference tokens and retiring TCO2 tokens. The contract lives in this repository.
In more exact terms, the OffsetHelper abstracts the process of retiring TCO2, which normally looks like so:
user exchanges USDC for BCT/NCT tokens at one of the DEXs (Uniswap, Sushiswap, etc. depending on network)
user interacts with the BCT/NCT token contract to redeem the tokens for TCO2
user interacts with the TCO2 token contract to retire the TCO2
With the OffsetHelper contract, the user only needs to interact with the OffsetHelper contract, which will take care of the rest of the contract calls 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 specified token pool. There are no fees incurred by the user when using autoRedeem()
, i.e., the user receives 1 TCO2 token for each carbon reference token e.g., NCT redeemed.
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.
Approvals
The OffsetHelper is a smart contract that calls other smart contracts. As a security measure, users need to approve
the OffsetHelper contract address, so the other smart contracts accept interactions routed through this address.
Note: you must approve the pool contract in the TCO2 token that is to be deposited in order for the pool to be able to transfer the TCO2 on your behalf.
Accepted tokens
Celo
cUSD
, WETH
, USDC
Polygon
USDC
, WETH
, WMATIC
Functions
autoOffsetExactOutToken
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 many native tokens (e.g., MATIC) must be sent to the OffsetHelper
contract in order to retire the specified amount of TCO2 tokens.
This function:
Swaps the ERC20 token sent to the contract for the specified carbon reference token
Redeems the reference tokens received for the lowest quality TCO2 tokens available
Retires the TCO2 tokens
Note: The user must approve the ERC20 token that will be used for the swap.
Parameters
_fromToken
address
The address of the ERC20 token that the user will use to swap (e.g., cUSD
, USDC
, WETH
, WMATIC
)
_poolToken
address
The address of the carbon reference token that the user wants to redeem, e.g., NCT
_amountToOffset
uint256
The amount of TCO2 to retire
Return Values
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
Retire carbon credits using the oldest TCO2 tokens available from the specified Toucan carbon pool by swapping ERC20 tokens (cUSD
, USDC
, WETH
, WMATIC
). All of provided "in
" token is consumed for retirement.
The view
helper function calculateExpectedPoolTokenForToken()
can be used to calculate the expected amount of TCO2s that will be offset using autoOffsetExactInToken()
.
This function:
Swaps the ERC20 token sent to the contract for the specified carbon reference token
Redeems the reference token for the lowest quality TCO2 tokens available
Retires the TCO2 tokens
Note: The client must approve the ERC20 token that is sent to the contract.
Parameters
_fromToken
address
The address of the ERC20 token that the user sends (e.g., cUSD
, USDC
, WETH
, WMATIC
)
_poolToken
address
The address of the carbon reference token to offset
_amountToSwap
uint256
The amount of ERC20 token to swap into carbon reference token. Full amount will be used for retirement.
Return Values
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
Retire carbon credits using the oldest TCO2 tokens available from the specified Toucan token pool by sending native tokens e.g., MATIC.
Note: While this method refers to "ETH", it actually refers to the blockchain's native token, and will use WMATIC on Polygon.
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:
Swaps the native token e.g. MATIC sent to the contract for the specified pool token
Redeems the pool token for the poorest quality TCO2 tokens available
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
_poolToken
address
The address of the pool token to offset, e.g., NCT
_amountToOffset
uint256
The amount of TCO2 to retire
Return Values
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
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:
Swaps the native token e.g. MATIC sent to the contract for the specified pool token
Redeems the pool token for the poorest quality TCO2 tokens available
Retires the TCO2 tokens
This function is only available on Polygon, not on Celo.
Parameters
_poolToken
address
The address of the pool token to offset
Return Values
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
Retire carbon credits using the oldest TCO2 tokens available by sending Toucan carbon reference tokens, e.g., NCT.
This function:
Redeems the reference tokens for the poorest quality TCO2 tokens available
Retires the TCO2 tokens
Note: The user must approve the carbon reference token to be swapped.
Parameters
_poolToken
address
The address of the pool token to offset, e.g., NCT
_amountToOffset
uint256
The amount of TCO2 to retire
Return Values
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
Swap eligible ERC20 tokens for Toucan carbon reference tokens (BCT/NCT) on a DEX.
Note: The user must approve the carbon reference token to be swapped.
Parameters
_fromToken
address
The address of the ERC20 token used for the swap
_poolToken
address
The address of the carbon reference token to swap for, e.g., NCT
_toAmount
uint256
The required amount of the Toucan reference token (NCT/BCT)
swapExactInToken
Swap eligible ERC20 tokens for Toucan carbon reference tokens (BCT/NCT) on a DEX. All provided ERC20 tokens will be swapped.
Note: The user must approve the carbon reference token to be swapped.
Parameters
_fromToken
address
The address of the ERC20 token used for the swap
_poolToken
address
The address of the carbon reference token to swap for, e.g., NCT
_fromAmount
uint256
The amount of ERC20 token to swap
Return Values
amountOut
uint256
Resulting amount of Toucan carbon reference tokens that were acquired for the swapped ERC20 tokens.
swapExactOutETH
Swap native tokens (e.g., MATIC) for Toucan carbon reference tokens (BCT/NCT) on a DEX. Remaining native tokens that were not consumed by the swap are returned.
Parameters
_poolToken
address
The address of the carbon reference token to swap for, e.g., NCT
_toAmount
uint256
The required amount of the Toucan carbon reference token (NCT/BCT)
swapExactInETH
Swap native tokens (e.g., MATIC) for Toucan carbon reference tokens (BCT/NCT) on a DEX. All provided native tokens will be swapped.
Parameters
_poolToken
address
The address of the carbon reference token to swap for, e.g., NCT
Return Values
amountOut
uint256
Resulting amount of Toucan carbon reference token that got acquired for the swapped native tokens
autoRedeem
Auto-redeems the specified amount of NCT / BCT for default TCO2 tokens.
Note: The user must approve the carbon reference token to be redeemed.
Parameters
_fromToken
address
The address of the carbon pool to redeem from
_amount
uint256
Amount to redeem
Return Values
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
Retire the specified TCO2 tokens.
The account sending the transaction needs to hold enough of each of the TCO2 tokens specified for this function to execute.
Parameters
_tco2s
address[]
The addresses of the TCO2s to retire
_amounts
uint256[]
The amounts to retire from each of the corresponding TCO2 addresses
calculateNeededTokenAmount
Returns how much of the specified ERC20 token is required in order to swap for the desired amount of a Toucan carbon reference token such as NCT.
Parameters
_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
amountIn
uint256
The amount of the ERC20 token required in order to swap for the specified amount of the pool token
calculateExpectedPoolTokenForToken
Calculates the expected amount of Toucan carbon reference token that can be acquired by swapping the provided amount of ERC20 token.
Parameters
_fromToken
address
The address of the ERC20 token used for the swap
_poolToken
address
The address of the carbon reference token to swap for, such as NCT
_fromAmount
uint256
The amount of ERC20 token to swap
Return Values
amountOut
uint256
The expected amount of carbon reference token that can be acquired
calculateNeededETHAmount
Return how much native tokens e.g, MATIC is required in order to swap for the desired amount of a Toucan carbon reference token, e.g., NCT.
Parameters
_poolToken
address
The address of the carbon reference token to swap for, e.g., NCT
_toAmount
uint256
The desired amount of carbon reference token to receive
Return Values
amountIn
uint256
The amount of native tokens required in order to swap for the specified amount of the carbon reference token
calculateExpectedPoolTokenForETH
Calculates the expected amount of Toucan carbon reference tokens that can be acquired by swapping the provided amount of native tokens e.g., MATIC.
Parameters
_poolToken
address
The address of the carbon reference token to swap for, e.g., NCT
_fromTokenAmount
uint256
The amount of native tokens to swap
Return Values
amountOut
uint256
The expected amount of carbon reference token that can be acquired
isPoolAddressEligible
Checks if an address identifies a Toucan carbon pool.
Parameters
_poolToken
address
The address of the carbon reference token to test
Return Values
_isEligible
bool
Returns a bool if the address identifies a Toucan carbon pool
isERC20AddressEligible
Checks if ERC20 Token is supported for swapping. Check the accepted tokens.
Parameters
_erc20Address
address
The address of the ERC20 token that the user sends (e.g., cUSD, cUSD, USDC, WETH, WMATIC)
Return Values
_path
address[]
Returns the path of the token to be exchanged
Last updated