> For the complete documentation index, see [llms.txt](https://docs.toucan.earth/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toucan.earth/developers/smart-contracts/offset-helper.md).

# OffsetHelper

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](https://github.com/ToucanProtocol/OffsetHelper).

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.

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

## 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. 

{% hint style="success" %}
**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.
{% endhint %}

## Accepted tokens

| Chain   | Tokens                   |
| ------- | ------------------------ |
| Celo    | `cUSD`, `WETH`, `USDC`   |
| Polygon | `USDC`, `WETH`, `WMATIC` |

## Functions

### autoOffsetExactOutToken

```solidity
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()`](#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:

1. Swaps the ERC20 token sent to the contract for the specified carbon reference token
2. Redeems the reference tokens received for the lowest quality TCO2 tokens available
3. Retires the TCO2 tokens

{% hint style="success" %}
**Note:** The user must approve the ERC20 token that will be used for the swap.
{% endhint %}

#### Parameters

| Name              | Type      | Description                                                                                            |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `_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

| 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

```solidity
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 carbon pool by swapping ERC20 tokens (`cUSD`, `USDC`, `WETH`, `WMATIC`). All of provided "`in`" token is consumed for retirement.

The `view` helper function [`calculateExpectedPoolTokenForToken()`](#calculateexpectedpooltokenfortoken) can be used to calculate the expected amount of TCO2s that will be offset using `autoOffsetExactInToken()`.

This function:

1. Swaps the ERC20 token sent to the contract for the specified carbon reference token
2. Redeems the reference token for the lowest quality TCO2 tokens available
3. Retires the TCO2 tokens

{% hint style="success" %}
**Note:** The client must approve the ERC20 token that is sent to the contract.
{% endhint %}

#### Parameters

| Name            | Type      | Description                                                                                             |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `_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

| 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

```solidity
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.

{% hint style="danger" %}
**Note:** While this method refers to "ETH", it actually refers to the blockchain's native token, and will use WMATIC on Polygon.
{% endhint %}

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. Swaps the native token e.g. MATIC sent to the contract for the specified pool token
2. Redeems the pool token for the poorest quality TCO2 tokens available
3. Retires the TCO2 tokens

{% hint style="info" %}
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.
{% endhint %}

#### Parameters

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

#### 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

```solidity
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()`](#calculateexpectedpooltokenforeth) can be used to calculate the expected amount of TCO2s that will be offset using `autoOffsetExactInETH()`.

This function:

1. Swaps the native token e.g. MATIC sent to the contract for the specified pool token
2. Redeems the pool token for the poorest quality TCO2 tokens available
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 |

#### 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

```solidity
function autoOffsetPoolToken(address _poolToken, uint256 _amountToOffset) public returns (address[] tco2s, uint256[] amounts)
```

Retire carbon credits using the oldest TCO2 tokens available by sending Toucan carbon reference tokens, e.g., NCT.

This function:

1. Redeems the reference tokens for the poorest quality TCO2 tokens available
2. Retires the TCO2 tokens

{% hint style="success" %}
**Note:** The user must approve the carbon reference token to be swapped.
{% endhint %}

#### Parameters

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

#### 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

```solidity
function swapExactOutToken(address _fromToken, address _poolToken, uint256 _toAmount) public
```

Swap eligible ERC20 tokens for Toucan carbon reference tokens (BCT/NCT) on a DEX.

{% hint style="success" %}
**Note:** The user must approve the carbon reference token to be swapped.
{% endhint %}

#### Parameters

| Name         | Type      | Description                                                      |
| ------------ | --------- | ---------------------------------------------------------------- |
| `_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

```solidity
function swapExactInToken(address _fromToken, address _poolToken, uint256 _fromAmount) public returns (uint256 amountOut)
```

Swap eligible ERC20 tokens for Toucan carbon reference tokens (BCT/NCT) on a DEX. All provided ERC20 tokens will be swapped.

{% hint style="success" %}
**Note:** The user must approve the carbon reference token to be swapped.
{% endhint %}

#### Parameters

| Name          | Type      | Description                                                      |
| ------------- | --------- | ---------------------------------------------------------------- |
| `_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

| Name        | Type      | Description                                                                                         |
| ----------- | --------- | --------------------------------------------------------------------------------------------------- |
| `amountOut` | `uint256` | Resulting amount of Toucan carbon reference tokens that were acquired for the swapped ERC20 tokens. |

### swapExactOutETH

```solidity
function swapExactOutETH(address _poolToken, uint256 _toAmount) public payable
```

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

| Name         | Type      | Description                                                        |
| ------------ | --------- | ------------------------------------------------------------------ |
| `_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

```solidity
function swapExactInETH(address _poolToken) public payable returns (uint256 amountOut)
```

Swap native tokens (e.g., MATIC) for Toucan carbon reference tokens (BCT/NCT) on a DEX. All provided native tokens will be swapped.

#### Parameters

| Name         | Type      | Description                                                      |
| ------------ | --------- | ---------------------------------------------------------------- |
| `_poolToken` | `address` | The address of the carbon reference token to swap for, e.g., NCT |

#### Return Values

| Name        | Type      | Description                                                                                       |
| ----------- | --------- | ------------------------------------------------------------------------------------------------- |
| `amountOut` | `uint256` | Resulting amount of Toucan carbon reference token that got acquired for the swapped native tokens |

### autoRedeem

```solidity
function autoRedeem(address _fromToken, uint256 _amount) public returns (address[] tco2s, uint256[] amounts)
```

Auto-redeems the specified amount of NCT / BCT for default TCO2 tokens.

{% hint style="success" %}
**Note:** The user must approve the carbon reference token to be redeemed.
{% endhint %}

#### Parameters

| Name         | Type      | Description                                   |
| ------------ | --------- | --------------------------------------------- |
| `_fromToken` | `address` | The address of the carbon pool to redeem from |
| `_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

```solidity
function autoRetire(address[] _tco2s, uint256[] _amounts) public
```

Retire the specified TCO2 tokens.

{% hint style="success" %}
The account sending the transaction needs to hold enough of each of the TCO2 tokens specified for this function to execute.
{% endhint %}

#### 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

```solidity
function calculateNeededTokenAmount(address _fromToken, address _poolToken, uint256 _toAmount) public view returns (uint256 amountIn)
```

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

| 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

```solidity
function calculateExpectedPoolTokenForToken(address _fromToken, address _poolToken, uint256 _fromAmount) public view returns (uint256 amountOut)
```

Calculates the expected amount of Toucan carbon reference 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 carbon reference token to swap for, such as NCT |
| `_fromAmount` | `uint256` | The amount of ERC20 token to swap                                  |

#### Return Values

| Name        | Type      | Description                                                        |
| ----------- | --------- | ------------------------------------------------------------------ |
| `amountOut` | `uint256` | The expected amount of carbon reference token that can be acquired |

### calculateNeededETHAmount

```solidity
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 carbon reference token, e.g., NCT.

#### Parameters

| Name         | Type      | Description                                                      |
| ------------ | --------- | ---------------------------------------------------------------- |
| `_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

| Name       | Type      | Description                                                                                                  |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `amountIn` | `uint256` | The amount of native tokens required in order to swap for the specified amount of the carbon reference token |

### calculateExpectedPoolTokenForETH

```solidity
function calculateExpectedPoolTokenForETH(address _poolToken, uint256 _fromTokenAmount) public view returns (uint256 amountOut)
```

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

| Name               | Type      | Description                                                      |
| ------------------ | --------- | ---------------------------------------------------------------- |
| `_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

| Name        | Type      | Description                                                        |
| ----------- | --------- | ------------------------------------------------------------------ |
| `amountOut` | `uint256` | The expected amount of carbon reference token that can be acquired |

### isPoolAddressEligible

```solidity
function isPoolAddressEligible(address _poolToken) public view returns (bool _isEligible)
```

Checks if an address identifies a Toucan carbon pool.

#### Parameters

| Name         | Type      | Description                                       |
| ------------ | --------- | ------------------------------------------------- |
| `_poolToken` | `address` | The address of the carbon reference token to test |

#### Return Values

| Name          | Type   | Description                                                   |
| ------------- | ------ | ------------------------------------------------------------- |
| `_isEligible` | `bool` | Returns a bool if the address identifies a Toucan carbon pool |

### isERC20AddressEligible

```solidity
function isERC20AddressEligible(address _erc20Address) public view returns (address[] _path)
```

Checks if ERC20 Token is supported for swapping. Check the [accepted tokens](#accepted-tokens).

#### 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 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.toucan.earth/developers/smart-contracts/offset-helper.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.