Toucan
Ask or search…
K

Contract Interactions

Toucan SDK provides you with several useful tools to quickly redeem and retire carbon credits. In case you can't find the function that you need with the Toucan SDK, you can also directly interact with the contracts.
The OffsetHelper combines these steps in each of the following "auto offset" methods to allow carbon credit retirement (offsetting) within one transaction:
  1. 1.
    Obtain a pool token such as BCT or NCT (by performing a token swap).
  2. 2.
    Redeem the pool token for a TCO2 token.
  3. 3.
    Retire the TCO2 token.

autoOffsetPoolToken

The autoOffsetPoolToken retires carbon credits using the lowest quality (oldest) TCO2 tokens available from the specified token pool by sending ERC20 tokens (cUSD, USDC, WETH, WMATIC). All provided tokens are consumed for offsetting. When automatically redeeming pool tokens for the lowest quality TCO2s there are no fees and you receive exactly 1 TCO2 token for 1 pool token. This method may take up to 1 minute to return a result. It returns the redeem transaction.
function autoOffsetPoolToken(
pool: PoolSymbol,
amount: BigNumber
): Promise<ContractReceipt>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool token to offset, e.g., NCT
amount
BigNumber
amount of TCO2 to offset.

autoOffsetExactInToken

The autoOffsetExactInToken retires carbon credits using the lowest quality (oldest) TCO2 tokens available by sending Toucan pool tokens, e.g., NCT. This method may take up to 1 minute to return a result. It returns the redeem transaction.
function autoOffsetExactInToken(
swapToken: string,
pool: PoolSymbol,
amount: BigNumber
): Promise<ContractReceipt>;

Params

Name
Type
Description
swapToken
string
portal for the token to swap into pool tokens (only accepts WETH, WMATIC and USDC) *
pool
PoolSymbol
symbol of the pool (token) to use *
amount
BigNumber
the amount of ERC20 token to swap into Toucan pool token. Full amount will be used for offsetting. *

autoOffsetExactOutToken

The autoOffsetExactOutToken retires a specified amount of carbon credits using the lowest quality (oldest) TCO2 tokens available from the specified token pool by sending ERC20 tokens (cUSD, USDC, WETH, WMATIC). This method may take up to 1 minute to return a result. It returns the offset transaction.
function autoOffsetExactOutToken(
swapToken: string,
pool: PoolSymbol,
amount: BigNumber
): Promise<ContractReceipt>;

Params

Name
Type
Description
swapToken
string
portal for the token to swap into pool tokens (only accepts WETH, WMATIC and USDC)
pool
PoolSymbol
symbol of the pool (token) to use
amount
BigNumber
amount of CO2 tons to offset

autoOffsetExactInETH

The autoOffsetExactInETH swaps ETH for carbon pool tokens and uses them to retire carbon. This method may take up to 1 minute to return a result.It returns the offset transaction.
function autoOffsetExactInETH(
pool: PoolSymbol,
amount: BigNumber
): Promise<ContractReceipt>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use e.g., "NCT"
amount
BigNumber
the amount of native tokens e.g., MATIC to swap into Toucan pool token. Full amount will be used for offsetting.

autoOffsetExactInETH

The autoOffsetExactInETH swaps ETH for carbon pool tokens and uses them to retire carbon. This method may take up to 1 minute to return a result.It returns the offset transaction.
function autoOffsetExactInETH(
pool: PoolSymbol,
amount: BigNumber
): Promise<ContractReceipt>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use e.g., "NCT"
amount
BigNumber
the amount of native tokens e.g., MATIC to swap into Toucan pool token. Full amount will be used for offsetting.

autoOffsetExactOutETH

The autoOffsetExactOutETH retires a specified amount of carbon credits using the lowest quality (oldest) TCO2 tokens available from the specified token pool by sending a native token e.g. MATIC. This method may take up to 1 minute to return a result. It returns the offset transaction.
function autoOffsetExactOutETH(
pool: PoolSymbol,
amount: BigNumber
): Promise<ContractReceipt>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use
amount
BigNumber
amount of CO2 tons to offset

calculateExpectedPoolTokenForToken

The calculateExpectedPoolTokenForToken calculates the expected amount of Toucan Pool token that can be acquired by swapping the provided amount of ERC20 token. It returns amount (BigNumber) The expected amount of Pool token that can be acquired.
function calculateExpectedPoolTokenForToken(
swapToken: string,
pool: PoolSymbol,
amount: BigNumber
): Promise<BigNumber>;

Params

Name
Type
Description
swapToken
string
The ERC20 token used for the swap
pool
PoolSymbol
symbol of the pool token to swap for, e.g., NCT
amount
BigNumber
The amount of ERC20 token to swap

calculateExpectedPoolTokenForETH

The calculateExpectedPoolTokenForETH calculates the expected amount of Toucan Pool token that can be acquired by swapping the provided amount of native tokens e.g., MATIC. It returns amount (BigNumber) The expected amount of Pool token that can be acquired.
function calculateExpectedPoolTokenForETH(
pool: PoolSymbol,
amount: BigNumber
): Promise<BigNumber>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use
amount
BigNumber
amount of native tokens to swap for, e.g., MATIC

calculateNeededTokenAmount

The calculateNeededTokenAmount calculates 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. It returns amount (BigNumber) of the ERC20 token required in order to swap for the specified amount of the pool token.
function calculateNeededTokenAmount(
swapToken: string,
pool: PoolSymbol,
amount: BigNumber
): Promise<BigNumber>;

Params

Name
Type
Description
swapToken
string
The ERC20 token used for the swap
pool
PoolSymbol
symbol of the pool token to swap for, e.g., NCT
amount
BigNumber
The desired amount of pool token to receive

calculateNeededETHAmount

The calculateNeededETHAmount calculates the amount of native tokens e.g, MATIC is required in order to swap for the desired amount of a Toucan pool token, e.g., NCT. It returns amount (BigNumber) of native tokens, e.g., MATIC required in order to swap for the specified amount of the pool token.
function calculateNeededETHAmount(
pool: PoolSymbol,
amount: BigNumber
): Promise<BigNumber>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool token to swap for, e.g., NCT
amount
BigNumber
The desired amount of pool token to receive

retire

The retire function retires/burns an amount of TCO2s (each represents 1 ton of CO2). If you don't own any TCO2s you need to buy pool tokens, e.g., NCTs on a DEX and redeem these first. It returns the retirement transaction.
function retire(
amount: BigNumber,
tco2Address: string
): Promise<ContractReceipt>;

Params

Name
Type
Description
amount
BigNumber
amount of TCO2 to retire
tco2Address
string
address of the TCO2 token to retire

retireFrom

The retireFrom function retires/burns an amount of TCO2s from a different address/wallet. The function requires approval from the address you're trying to retire from. If you don't own any TCO2s you need to buy pool tokens, e.g., NCTs on a DEX and redeem these first. It returns the retirement transaction.
function retireFrom(
amount: BigNumber,
address: string,
tco2Address: string
): Promise<ContractReceipt>;

Params

Name
Type
Description
amount
BigNumber
amount of TCO2 to retire
address
string
address of the account to retire from
tco2Address
string
address of the TCO2 token to retire

retireAndMintCertificate

The retireAndMintCertificate function retires/burns an amount of TCO2s & mints the NFT certificate for it within the same transaction. If you don't own any TCO2s you need to buy pool tokens, e.g., NCTs on a DEX and redeem these first. It returns the retirement transaction.
function retireAndMintCertificate(
retirementEntityName: string,
beneficiaryAddress: string,
beneficiaryName: string,
retirementMessage: string,
amount: BigNumber,
tco2Address: string
): Promise<ContractReceipt>;

Params

Name
Type
Description
retirementEntityName
string
name of the entity that does the retirement (you)
beneficiaryAddress
string
address of the beneficiary (in case you're retiring for someone else)
beneficiaryName
string
name of the beneficiary
retirementMessage
string
retirement message
amount
BigNumber
amount of TCO2 to retire
tco2Address
string
address of the TCO2 token to retire

getDepositCap

The getDepositCap function gets the cap for TCO2s based on totalVintageQuantity.
function getDepositCap(tco2Address: string): Promise<BigNumber>;

Params

Name
Type
Description
tco2Address
string
address of the TCO2 token

getAttributes

The getAttributes function retrieves the attributes of the TCO2 token. It returns an array of attributes including vintage and project details.
function getAttributes(tco2Address: string): Promise<Attributes>;

Params

Name
Type
Description
tco2Address
string
address of the TCO2 token

getTCO2Remaining

The getTCO2Remaining function gets the remaining space in TCO2 contract before hitting the cap. It returns a BigNumber representing the remaining space.
function getTCO2Remaining(tco2Address: string): Promise<BigNumber>;

Params

Name
Type
Description
tco2Address
string
address of the TCO2 token

depositTCO2

The depositTCO2 function deposits TCO2 tokens from a user's address into a Toucan pool and mints a pool token for the user. It returns returns the deposit transaction.
function depositTCO2(
pool: PoolSymbol,
amount: BigNumber,
tco2Address: string
): Promise<ContractReceipt>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"
amount
BigNumber
amount of TCO2s to deposit
tco2Address
string
address of the TCO2 token

checkEligible

The checkEligible function checks if a TCO2 is eligible for pool. It returns a boolean.
function checkEligible(pool: PoolSymbol, tco2Address: string): Promise<boolean>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"
tco2Address
string
address of the TCO2 token

redeemAuto

The redeemAuto function automatically redeems TCO2 tokens from the pool up to the deposit cap. It returns the redemption transaction. It returns an array containing tco2 addresses (string) and amounts (BigNumber).
function redeemAuto(
pool: PoolSymbol,
amount: BigNumber
): Promise<ContractReceipt>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"
amount
BigNumber
amount of pool tokens to redeem

redeemAuto2

function redeemAuto2(
pool: PoolSymbol,
amount: BigNumber
): Promise<ContractReceipt>;
This function is deprecated. Use redeemAuto instead.

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"
amount
BigNumber
amount of pool tokens to redeem

redeemMany

The redeemMany function selectively redeems pool tokens for TCO2s in a single transaction. It returns the redeem transaction.
function redeemMany(
pool: PoolSymbol,
tco2Addresses: string[],
amounts: BigNumber[]
): Promise<ContractReceipt>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"
tco2Addresses
string[]
array of TCO2 contract addresses
amounts
BigNumber[]
array of amounts of TCO2 tokens to redeem for each tco2s

calculateRedeemFees

The calculateRedeemFees function calculates the fees to selectively redeem pool tokens for TCO2s. It returns amount (BigNumber) of fees it will cost to redeem.
function calculateRedeemFees(
pool: PoolSymbol,
tco2Addresses: string[],
amounts: BigNumber[]
): Promise<FeeCalculationResult>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"
tco2Addresses
string[]
array of TCO2 contract addresses
amounts
BigNumber[]
array of amounts of TCO2 tokens to redeem

getPoolRemaining

The getPoolRemaining function gets the remaining space in pool contract before hitting the cap. It returns BigNumber representing the remaining space.
function getPoolRemaining(pool: PoolSymbol): Promise<BigNumber>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"

getScoredTCO2s

The getScoredTCO2s function ets an array of scored TCO2s; scoredTCO2s[0] is lowest ranked. It returns an array of TCO2 addresses by rank.
function getScoredTCO2s(pool: PoolSymbol): Promise<string[]>;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"

checkIfTCO2

The checkIfTCO2 function checks if an address represents a TCO2. It returns a boolean.
function checkIfTCO2(address: string): Promise<boolean>;

Params

Name
Type
Description
address
string
address of the token to check

Interact directly with Toucan's contracts

If you need to interact with a method of our contracts that hasn't been implemented in the SDK yet, you can also get the contract and call the specific function. Learn more about Pool and TCO2 Contracts and the OffsetHelper
It's important to note that, if you want to use write methods you need to have a signer set in the Toucan Client!

getPoolAddress

The getPoolAddress function returns the address of a Toucan pool.
function getPoolAddress(pool: PoolSymbol): string;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"

getPoolContract

The getPoolContract function retrieves an ethers.Contract based on the symbol, to interact with the pool token.
function getPoolContract(pool: PoolSymbol): IToucanPoolToken;

Params

Name
Type
Description
pool
PoolSymbol
symbol of the pool (token) to use, e.g. "NCT"

getTCO2Contract

The getTCO2Contract function retrieves an ethers.Contract based on the address, to interact with the the Toucan TCO2.
function getTCO2Contract(tco2Address: string): IToucanCarbonOffsets;

Params

Name
Type
Description
tco2Address
string
address of TCO2 ethers.Contract to instantiate

getRegistryContract

The getRegistryContract function retrieves an ethers.Contract to interact with the contract registry.
function getRegistryContract(): IToucanContractRegistry;

Examples

You can always access any method or property of the BCT, NCT and TCO2 contracts by first getting and storing them in a variable, like this:
toucan.setSigner(signer);
const nct = await toucan.getPoolContract("NCT");
const tco2 = await toucan.getTCO2Contract(tco2Address);
const registry = await toucan.getRegistryContract();
const remainingTCO2 = await nct.tokenBalances(tco2Address);