Carbon pool contracts

All carbon pools have the same standard functions

Toucan's Carbon Pool smart contracts extend the ERC20 standard — carbon reference tokens are ERC20 tokens. Pool contracts are upgradeable. Contract addresses for deployed carbon pools can be found at app.toucan.earth/contracts.

deposit

Accepts TCO2 deposits into the pool, and mints an equivalent number of the pool's reference tokens

function deposit(address erc20Addr, uint256 amount) external virtual;

Parameters

Name	Type	Description
erc20Addr	address	Address of the TCO2 tokens to deposit in pool
amount	uint256	Number of TCO2 tokens to deposit in pool (multiplied by 1e18)

Note: you have to 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.

checkEligible

Checks if token can be deposited in the pool. Each pool comes with its own eligibility criteria.

function checkEligible(address erc20Addr) public view virtual returns (bool);

Parameters

Name	Type	Description
erc20Address	address	Address of the token to check

Return Values

Name	Type	Description
Eligibility	bool	Boolean representing whether the pool accepts the TCO2 tokens specified

calculateRedeemFees

Calculates the amount of fees paid to selectively redeem TCO2 tokens. Pool fees are levied in the carbon pool's reference token.

function calculateRedeemFees(
        address[] memory tco2s,
        uint256[] memory amounts
) external view virtual returns (uint256);

Parameters

Name	Type	Description
tco2s	address[]	An array of addresses of the TCO2s you want redeemed
amounts	uint256[]	An array of amounts you want redeemed

The tco2s and amounts arrays have to be of equal length, and related to each other by index — i.e. redeem the number of tokens specified in amounts[3] of TCO2 contract address tco2s[3] from the pool.

Return Values

Name	Type	Description
total	uint256	The total amount of pool reference tokens you will pay in fees to redeem the given TCO2s

redeemMany

Selectively redeems carbon reference tokens for underlying TCO2 tokens. This is 1:1, minus fees. The user's pool tokens get burnt in the process.

function redeemMany(address[] memory tco2s, uint256[] memory amounts)
        external virtual;

Parameters

Name	Type	Description
tco2s	address[]	An array of addresses of the TCO2s you want redeemed
amounts	uint256[]	An array of amounts you want redeemed

It's of note that the arrays have to be of equal length — see note above.

redeemAuto

Automatically redeems pool tokens for underlying TCO2 tokens. This is 1:1 and doesn't incur fees. You will receive TCO2 tokens that are considered lower quality based on an index called scoredTCO2s (explained here). The user's reference tokens get burnt within the process. The function returns arrays of the contract addresses and amounts of the TCO2 tokens redeemed.

function redeemAuto(uint256 amount) external virtual
        returns (address[] memory tco2s, uint256[] memory amounts);

Parameters

Name	Type	Description
amount	uint256	Amount of carbon reference tokens to redeem for TCO2s

Return Values

Name	Type	Description
tco2s	address[]	An array of addresses of the TCO2s that were redeemed
amounts	uint256[]	An array of amounts that were redeemed for each given TCO2

redeemAuto2

Automatically redeems pool tokens for underlying TCO2 tokens. This is 1:1 and doesn't incur fees. You will receive TCO2 tokens that are considered lower quality based on an index called scoredTCO2s (explained here). The user's reference tokens get burnt within the process. The function returns arrays of the contract addresses and amounts of the TCO2 tokens redeemed.

function redeemAuto2(uint256 amount) external virtual
        returns (address[] memory tco2s, uint256[] memory amounts);

Parameters

Name	Type	Description
amount	uint256	Amount of carbon reference tokens to redeem for TCO2s

Return Values

Name	Type	Description
tco2s	address[]	An array of addresses of the TCO2s that were redeemed
amounts	uint256[]	An array of amounts that were redeemed for each given TCO2

redeemAndBurn

Redeems a whitelisted TCO2 tokens without paying any fees and immediately burns it. This is not a retirement, but a burn of the TCO2. It is used to clean the pools of subpar TCO2s, and was initially added to burn HFC-23 credits. The user's pool tokens get burnt within the process.

function redeemAndBurn(address tco2, uint256 amount) external;

Parameters

Name	Type	Description
tco2	address	The address of the TCO2s to be burned from the pool
amount	uint256	The amount of the TCO2 to be burned from the pool

Note: you have to approve the pool token from the TCO2 contract that is to be redeemed and burned in order for this to work.

getScoredTCO2s

Returns an array of ranked TCO2 addresses.

scoredTCO2s[0] is the lowest ranked TCO2's contract address — the rank is then ascending

It's important to note that (currently) this is set manually which means sometimes some of the returned addresses may have a balance of 0 within the pool.

function getScoredTCO2s() external view returns (address[] memory);

Return values

Name	Type	Description
scoredTCO2s	address[]	The addresses of TCO2s in the pool ascending by rank

getRemaining

Returns the remaining space in the pool before hitting its cap.

function getRemaining() public view returns (uint256);

Return values

Name	Type	Description
remaining	uint256	supplyCap - totalSupply