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