Contract interactions

Interact with Toucan smart contracts using our JavaScript SDK

The Toucan SDK provides you with several useful tools to quickly redeem and retire carbon credits programmatically. In case you can't find the function that you need with the Toucan SDK, you can also directly interact with the contracts.

OffsetHelper related methods

The OffsetHelper combines these steps in each of the following "auto offset" methods to allow carbon credit retirement (offsetting) within one transaction:

1. Obtain a pool token such as NCT (by performing a token swap)

2. Redeem the pool token for a TCO2 token

3. Retire the TCO2 token

autoOffsetPoolToken

The autoOffsetPoolToken retires carbon credits using the lowest quality (oldest) TCO2 tokens available from the specified carbon pool. This method does not include a token swap — the user must already hold reference tokens. All provided reference tokens are consumed for offsetting.

This method may take up to 1 minute to return a result. It returns the redeem transaction.

When automatically redeeming pool tokens for the lowest quality TCO2s there are no fees — you receive exactly 1 TCO2 token for 1 reference token.

Also, note that "Pool Token" in the method name refers to "carbon reference token".

function autoOffsetPoolToken(
  pool: PoolSymbol,
  amount: BigNumber
): Promise<ContractReceipt>;

Params

Name	Type	Description
pool	PoolSymbol	symbol of the carbon reference token to offset with, e.g. NCT
amount	BigNumber	amount of TCO2 tokens to redeem and retire

autoOffsetExactInToken

The autoOffsetExactInToken extends the functionality described in autoOffsetPoolToken by including a step to swap another token, like USDC, WETH or WMATIC, for the carbon reference tokens.

This method allows you to specify exactly how many tokens you want to use to swap and retire — i.e. how many USDC, WETH or WMATIC tokens you want to spend.

The autoOffsetExactOutToken allows you to specify exactly how many carbon reference tokens you want to swap for, redeem and retire. The amount of swapTokens needed will be found using calculation methods described below.

• With autoOffsetExactInToken, you know how much you'll spend, but not how many TCO2 tokens will be retired

• With autoOffsetExactOutToken, you know how many TCO2 tokens will be retired, but not how much you'll spend

After the swap is completed, subsequent steps are the same as above. 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 — WETH, WMATIC or USDC	The ticker for the token to swap into carbon reference tokens
pool	PoolSymbol e.g. NCT	symbol of the carbon reference token to use
amount	BigNumber	the amount of ERC20 token to swap into carbon reference 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 — WETH, WMATIC or USDC	The ticker for the token to swap into pool tokens (only accepts WETH, WMATIC and USDC)
pool	PoolSymbol e.g. NCT	Symbol of the carbon reference token to use
amount	BigNumber	Amount of TCO2 tokens to retire

autoOffsetExactInETH

Same as autoOffsetExactInToken, but the autoOffsetExactInETH swaps the blockchain's native token for carbon reference tokens, instead of allowing you to specify the swapToken.

Note: While this method refers to "ETH", it actually will use WMATIC on Polygon. The function is not currently available on Celo.

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 e.g. NCT	Ticker symbol of the carbon reference token to acquire and redeem
amount	BigNumber	The amount of native tokens e.g., MATIC to swap into Toucan carbon reference tokens. The full amount of redeemed TCO2 tokens will be used for offsetting.

autoOffsetExactOutETH

Same as autoOffsetExactOutToken, but the autoOffsetExactOutETH swaps the blockchain's native token for carbon reference tokens, instead of allowing you to specify the swapToken.

Note that while this method refers to "ETH", it actually will use WMATIC on Polygon. The function is not currently available on Celo.

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 e.g. NCT	Ticker symbol of the carbon reference token to acquire and redeem
amount	BigNumber	The amount of TCO2 tokens to retire

calculateExpectedPoolTokenForToken

Calculates and returns the expected amount of carbon references tokens that can be acquired by swapping the provided amount of ERC20 token.

function calculateExpectedPoolTokenForToken(
  swapToken: string,
  pool: PoolSymbol,
  amount: BigNumber
): Promise<BigNumber>;

Params

Name	Type	Description
swapToken	string — WETH, WMATIC or USDC	The ERC20 token used for the swap
pool	PoolSymbol e.g. NCT	Symbol of the carbon reference token to swap for
amount	BigNumber	The amount of ERC20 token to swap

calculateExpectedPoolTokenForETH

Calculates and returns the expected amount of carbon references tokens that can be acquired by swapping the provided amount of native token.

Note that while this method refers to "ETH", it actually will use WMATIC on Polygon. The function is not currently available on Celo.

function calculateExpectedPoolTokenForETH(
  pool: PoolSymbol,
  amount: BigNumber
): Promise<BigNumber>;

Params

Name	Type	Description
pool	PoolSymbol e.g. NCT	Symbol of the carbon reference token to swap for
amount	BigNumber	Amount of native tokens to swap for, e.g., WMATIC

calculateNeededTokenAmount

Calculates how much of the specified ERC20 token is required in order to swap for the desired amount of a specified carbon reference token.

function calculateNeededTokenAmount(
  swapToken: string,
  pool: PoolSymbol,
  amount: BigNumber
): Promise<BigNumber>;

Params

Name	Type	Description
swapToken	string — WETH, WMATIC or USDC	The ERC20 token used for the swap
pool	PoolSymbol e.g. NCT	Symbol of the pool token to swap for
amount	BigNumber	The desired amount of carbon reference token to receive

calculateNeededETHAmount

Calculates the amount of native tokens (e.g, MATIC) required to swap for the desired amount of a carbon reference token, e.g., NCT.

function calculateNeededETHAmount(
  pool: PoolSymbol,
  amount: BigNumber
): Promise<BigNumber>;

Params

Name	Type	Description
pool	PoolSymbol e.g. NCT	Symbol of the pool token to swap for
amount	BigNumber	The desired amount of carbon reference tokens to receive

TCO2 related methods

retire

The retire function retires an amount of TCO2 tokens and returns the retirement transaction.

function retire(
  amount: BigNumber,
  tco2Address: string
): Promise<ContractReceipt>;

Params

Name	Type	Description
amount	BigNumber	Amount of TCO2 tokens to retire
tco2Address	string	Address of the TCO2 token to retire

retireFrom

The retireFrom function retires an amount of TCO2 tokens 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 tokens to retire
address	string	Address of the account to retire from
tco2Address	string	Contract address of the TCO2 token to retire

retireAndMintCertificate

The retireAndMintCertificate function retires an amount of TCO2s & mints the NFT RetirementCertificate 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 (i.e. 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 tokens to retire
tco2Address	string	Contract 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	Contract 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	Contract address of the TCO2 token

Return values are described in the smart contract docs for the getAttributes function ->

getTCO2Remaining

The getTCO2Remaining function gets the remaining space in TCO2 contract before hitting the deposit cap. It returns a BigNumber representing the remaining space.

function getTCO2Remaining(tco2Address: string): Promise<BigNumber>;

Params

Name	Type	Description
tco2Address	string	Contract address of the TCO2 token

Pool related methods

depositTCO2

The depositTCO2 function deposits TCO2 tokens from a user's account into a carbon pool and mints and deposits an equivalent number of the pool's reference tokens back into the user's account. It returns returns the deposit transaction.

function depositTCO2(
  pool: PoolSymbol,
  amount: BigNumber,
  tco2Address: string
): Promise<ContractReceipt>;

Params

Name	Type	Description
pool	PoolSymbol e.g. NCT	Symbol of the pool (token) to use
amount	BigNumber	Amount of TCO2 tokens to deposit
tco2Address	string	Contract 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 e.g. NCT	Symbol of the pool to check against
tco2Address	string	Contract address of the TCO2 token to check

redeemAuto

The redeemAuto function automatically redeems TCO2 tokens from the pool up to the deposit cap. It returns the redemption transaction, which returns an array containing TCO2 contract addresses (string) and amounts (BigNumber).

function redeemAuto(
  pool: PoolSymbol,
  amount: BigNumber
): Promise<ContractReceipt>;

Params

Name	Type	Description
pool	PoolSymbol e.g. NCT	Symbol of the pool redeem from
amount	BigNumber	Amount of carbon reference tokens to redeem

redeemAuto2 [deprecated]

function redeemAuto2(
  pool: PoolSymbol,
  amount: BigNumber
): Promise<ContractReceipt>;

This function is deprecated. Use redeemAuto instead.

Params

Name	Type	Description
pool	PoolSymbol e.g. NCT	Symbol of the pool to redeem from
amount	BigNumber	Amount of carbon reference tokens to redeem

redeemMany

The redeemMany function redeems carbon reference tokens for specified TCO2 tokens in specified amounts 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 e.g. NCT	Symbol of the pool to redeem from
tco2Addresses	string[]	Array of TCO2 contract addresses
amounts	BigNumber[]	Array of amounts of TCO2 tokens to redeem for each

The tco2Addresses and amounts arrays must be of equal length, and align based on index, i.e. "Redeem amounts[4] tokens from TCO2 contract address tco2Addresses[4]."

calculateRedeemFees

The calculateRedeemFees function calculates the fees to selectively redeem carbon reference tokens for TCO2s. It returns amount (BigNumber) of fees it will cost to redeem. Fees are levied in the pool's reference token.

function calculateRedeemFees(
  pool: PoolSymbol,
  tco2Addresses: string[],
  amounts: BigNumber[]
): Promise<FeeCalculationResult>;

Params

Name	Type	Description
pool	PoolSymbol e.g. NCT	Symbol of the pool (token) to use
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, i.e. supplyCap - totalSupply. It returns BigNumber representing the remaining space in the pool.

function getPoolRemaining(pool: PoolSymbol): Promise<BigNumber>;

Params

Name	Type	Description
pool	PoolSymbol e.g. NCT	Symbol of the pool (token) to check

getScoredTCO2s

The getScoredTCO2s function gets an array of TCO2s ordered by score for a specific pool; 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 e.g. NCT	Symbol of the pool (token) to use

Contract registry related methods

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	Contract 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 connect directly to the contract and call the specific function. Learn more about smart contract functions in Carbon pool contracts, TCO2 Contracts and the OffsetHelper docs.

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 e.g. NCT	Symbol of the pool

getPoolContract

The getPoolContract function retrieves an ethers.Contract object based on the pool symbol.

function getPoolContract(pool: PoolSymbol): IToucanPoolToken;

Params

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

getTCO2Contract

The getTCO2Contract function retrieves an ethers.Contract object based on the TCO2 contract address.

function getTCO2Contract(tco2Address: string): IToucanCarbonOffsets;

Params

Name	Type	Description
tco2Address	string	Address of TCO2 contract to instantiate an ethers.Contract object for

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 pool 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);