# MentoBroker

## MentoBroker

The contract executes token swaps between reserve assets and GoodDollar tokens through exchange providers.

### Contract Specs

The MentoBroker contract is the primary interface for users to buy and sell GoodDollar tokens. It executes swaps between reserve assets (like CUSD, USDC, or native tokens) and GoodDollar (G$) tokens through the exchange provider system. This enables the core economic mechanism of GoodDollar: users can purchase G$ tokens by providing collateral, and sell G$ tokens to receive collateral back. The contract manages trading limits, calculates swap amounts using Bancor-style formulas, and provides both fixed input and fixed output swap types.

### Events

#### Swap

Emitted when a swap occurs between tokens.

| Parameter name     | Annotation                                                   |
| ------------------ | ------------------------------------------------------------ |
| `exchangeProvider` | The address of the exchange provider that executed the swap. |
| `exchangeId`       | The ID of the exchange used for the swap.                    |
| `trader`           | The address of the trader who initiated the swap.            |
| `tokenIn`          | The address of the input token.                              |
| `tokenOut`         | The address of the output token.                             |
| `amountIn`         | The amount of input tokens swapped.                          |
| `amountOut`        | The amount of output tokens received.                        |

```solidity
event Swap(
    address exchangeProvider,
    bytes32 indexed exchangeId,
    address indexed trader,
    address indexed tokenIn,
    address tokenOut,
    uint256 amountIn,
    uint256 amountOut
);
```

#### TradingLimitConfigured

Emitted when a new trading limit is configured for an exchange and token pair.

| Parameter name | Annotation                                                          |
| -------------- | ------------------------------------------------------------------- |
| `exchangeId`   | The ID of the exchange.                                             |
| `token`        | The address of the token for which the trading limit is configured. |
| `config`       | The trading limit configuration struct.                             |

```solidity
event TradingLimitConfigured(bytes32 exchangeId, address token, ITradingLimits.Config config);
```

### Functions

#### getAmountIn

Calculates the amount of tokenIn needed to receive a given amountOut of tokenOut. Uses the exchange provider's pricing formula.

| Parameter name     | Annotation                                   |
| ------------------ | -------------------------------------------- |
| `exchangeProvider` | The address of the exchange provider to use. |
| `exchangeId`       | The ID of the exchange.                      |
| `tokenIn`          | The address of the input token.              |
| `tokenOut`         | The address of the output token.             |
| `amountOut`        | The desired amount of output tokens.         |

**Returns:** The amount of input tokens needed to receive the specified amount of output tokens.

```solidity
function getAmountIn(
    address exchangeProvider,
    bytes32 exchangeId,
    address tokenIn,
    address tokenOut,
    uint256 amountOut
) external view returns (uint256 amountIn);
```

#### getAmountOut

Calculates the amount of tokenOut received for a given amountIn of tokenIn. Uses the exchange provider's pricing formula.

| Parameter name     | Annotation                                   |
| ------------------ | -------------------------------------------- |
| `exchangeProvider` | The address of the exchange provider to use. |
| `exchangeId`       | The ID of the exchange.                      |
| `tokenIn`          | The address of the input token.              |
| `tokenOut`         | The address of the output token.             |
| `amountIn`         | The amount of input tokens.                  |

**Returns:** The amount of output tokens that will be received.

```solidity
function getAmountOut(
    address exchangeProvider,
    bytes32 exchangeId,
    address tokenIn,
    address tokenOut,
    uint256 amountIn
) external view returns (uint256 amountOut);
```

#### swapIn

Executes a token swap with fixed input amount. Transfers tokenIn from msg.sender and returns tokenOut. Enforces amountOutMin to prevent excessive slippage.

| Parameter name     | Annotation                                                            |
| ------------------ | --------------------------------------------------------------------- |
| `exchangeProvider` | The address of the exchange provider to use.                          |
| `exchangeId`       | The ID of the exchange.                                               |
| `tokenIn`          | The address of the input token.                                       |
| `tokenOut`         | The address of the output token.                                      |
| `amountIn`         | The amount of input tokens to swap.                                   |
| `amountOutMin`     | The minimum amount of output tokens to receive (slippage protection). |

**Returns:** The amount of output tokens received.

```solidity
function swapIn(
    address exchangeProvider,
    bytes32 exchangeId,
    address tokenIn,
    address tokenOut,
    uint256 amountIn,
    uint256 amountOutMin
) external returns (uint256 amountOut);
```

#### swapOut

Executes a token swap with fixed output amount. Transfers tokenIn from msg.sender (up to amountInMax) and returns the specified amountOut.

| Parameter name     | Annotation                                                         |
| ------------------ | ------------------------------------------------------------------ |
| `exchangeProvider` | The address of the exchange provider to use.                       |
| `exchangeId`       | The ID of the exchange.                                            |
| `tokenIn`          | The address of the input token.                                    |
| `tokenOut`         | The address of the output token.                                   |
| `amountOut`        | The desired amount of output tokens to receive.                    |
| `amountInMax`      | The maximum amount of input tokens to spend (slippage protection). |

**Returns:** The amount of input tokens actually spent.

```solidity
function swapOut(
    address exchangeProvider,
    bytes32 exchangeId,
    address tokenIn,
    address tokenOut,
    uint256 amountOut,
    uint256 amountInMax
) external returns (uint256 amountIn);
```

#### burnStableTokens

Permissionless function to burn stable tokens directly. Transfers tokens from msg.sender and burns them.

| Parameter name | Annotation                               |
| -------------- | ---------------------------------------- |
| `token`        | The address of the stable token to burn. |
| `amount`       | The amount of tokens to burn.            |

**Returns:** True if the burn was successful.

```solidity
function burnStableTokens(address token, uint256 amount) external returns (bool);
```

#### getExchangeProviders

Returns the list of all registered exchange provider addresses.

**Returns:** Array of all registered exchange provider addresses.

```solidity
function getExchangeProviders() external view returns (address[] memory);
```

#### isExchangeProvider

Checks if an address is a registered exchange provider.

| Parameter name     | Annotation            |
| ------------------ | --------------------- |
| `exchangeProvider` | The address to check. |

**Returns:** True if the address is a registered exchange provider, false otherwise.

```solidity
function isExchangeProvider(address exchangeProvider) external view returns (bool);
```