> For the complete documentation index, see [llms.txt](https://docs.gooddollar.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gooddollar.org/for-developers/core-contracts/mentoexchangeprovider.md).

# MentoExchangeProvider

## MentoExchangeProvider

The contract implements the core exchange mechanism for GoodDollar using a Bancor-style bonding curve.

### Contract Specs

The MentoExchangeProvider contract implements the core exchange mechanism for GoodDollar using a Bancor-style bonding curve. It creates and manages liquidity pools (PoolExchanges) that define the relationship between reserve assets and GoodDollar tokens. This contract is essential for maintaining the price stability and liquidity of GoodDollar tokens, which is crucial for the UBI distribution system. It calculates mint amounts from expansion and reserve interest, updates reserve ratios, and provides continuous pricing through the Bancor formula.

### Events

#### ExchangeCreated

Emitted when a new PoolExchange has been created.

| Parameter name | Annotation                                        |
| -------------- | ------------------------------------------------- |
| `exchangeId`   | The ID of the newly created exchange.             |
| `reserveAsset` | The address of the reserve asset in the exchange. |
| `tokenAddress` | The address of the token in the exchange.         |

```solidity
event ExchangeCreated(
    bytes32 indexed exchangeId,
    address indexed reserveAsset,
    address indexed tokenAddress
);
```

#### ExchangeDestroyed

Emitted when a PoolExchange has been destroyed.

| Parameter name | Annotation                                        |
| -------------- | ------------------------------------------------- |
| `exchangeId`   | The ID of the destroyed exchange.                 |
| `reserveAsset` | The address of the reserve asset in the exchange. |
| `tokenAddress` | The address of the token in the exchange.         |

```solidity
event ExchangeDestroyed(
    bytes32 indexed exchangeId,
    address indexed reserveAsset,
    address indexed tokenAddress
);
```

#### ExitContributionSet

Emitted when the exit contribution for a pool is set.

| Parameter name     | Annotation                                    |
| ------------------ | --------------------------------------------- |
| `exchangeId`       | The ID of the exchange.                       |
| `exitContribution` | The exit contribution value set for the pool. |

```solidity
event ExitContributionSet(
    bytes32 indexed exchangeId,
    uint256 exitContribution
);
```

#### ReserveRatioUpdated

Emitted when reserve ratio for exchange is updated.

| Parameter name | Annotation                   |
| -------------- | ---------------------------- |
| `exchangeId`   | The ID of the exchange.      |
| `reserveRatio` | The new reserve ratio value. |

```solidity
event ReserveRatioUpdated(bytes32 indexed exchangeId, uint32 reserveRatio);
```

### Functions

#### createExchange

Creates a new PoolExchange with the provided parameters. Returns the exchangeId for the created exchange.

| Parameter name | Annotation                                                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exchange`     | The PoolExchange struct containing exchange parameters (reserveAsset, tokenAddress, tokenSupply, reserveBalance, reserveRatio, exitContribution). |

**Returns:** The ID of the newly created exchange.

```solidity
function createExchange(
    IBancorExchangeProvider.PoolExchange calldata exchange
) external returns (bytes32 exchangeId);
```

#### getPoolExchange

Retrieves the PoolExchange struct for a given exchangeId.

| Parameter name | Annotation                          |
| -------------- | ----------------------------------- |
| `exchangeId`   | The ID of the exchange to retrieve. |

**Returns:** The PoolExchange struct containing exchange parameters.

```solidity
function getPoolExchange(
    bytes32 exchangeId
) external view returns (PoolExchange memory exchange);
```

#### getExchangeIds

Returns array of all exchange IDs.

**Returns:** Array of all exchange IDs.

```solidity
function getExchangeIds() external view returns (bytes32[] memory exchangeIds);
```

#### currentPrice

Gets the current price based on the Bancor formula for the specified exchange.

| Parameter name | Annotation                                   |
| -------------- | -------------------------------------------- |
| `exchangeId`   | The ID of the exchange to get the price for. |

**Returns:** The current price based on the Bancor formula.

```solidity
function currentPrice(bytes32 exchangeId) external view returns (uint256 price);
```

#### mintFromExpansion

Calculates and returns the amount of tokens to be minted as a result of expansion. Uses expansion scaler to determine the new reserve ratio.

| Parameter name    | Annotation                                                    |
| ----------------- | ------------------------------------------------------------- |
| `exchangeId`      | The ID of the exchange.                                       |
| `expansionScaler` | The expansion scaler used to determine the new reserve ratio. |

**Returns:** The amount of tokens to be minted as a result of expansion.

```solidity
function mintFromExpansion(
    bytes32 exchangeId,
    uint256 expansionScaler
) external returns (uint256 amountToMint);
```

#### mintFromInterest

Calculates the amount of tokens to be minted as a result of the reserve interest. Interest is added to reserve balance, and tokens are minted to maintain the ratio.

| Parameter name    | Annotation                                |
| ----------------- | ----------------------------------------- |
| `exchangeId`      | The ID of the exchange.                   |
| `reserveInterest` | The amount of reserve interest collected. |

**Returns:** The amount of tokens to be minted as a result of the reserve interest.

```solidity
function mintFromInterest(
    bytes32 exchangeId,
    uint256 reserveInterest
) external returns (uint256);
```

#### updateRatioForReward

Calculates and updates the reserve ratio needed to mint the reward.

| Parameter name | Annotation                           |
| -------------- | ------------------------------------ |
| `exchangeId`   | The ID of the exchange.              |
| `reward`       | The amount of reward tokens to mint. |

```solidity
function updateRatioForReward(bytes32 exchangeId, uint256 reward) external;
```


---

# 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.gooddollar.org/for-developers/core-contracts/mentoexchangeprovider.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.