# MentoExpansionController

## MentoExpansionController

The contract controls how new GoodDollar tokens are minted and distributed for UBI.

### Contract Specs

The MentoExpansionController is the heart of GoodDollar's UBI (Universal Basic Income) distribution mechanism. It controls how new GoodDollar tokens are minted and distributed to users. The contract generates UBI tokens through two primary mechanisms: (1) interest earned on reserve collateral, and (2) expansion based on configured rates. These newly minted tokens are then distributed to verified users through the distribution helper, fulfilling GoodDollar's mission of providing universal basic income.

### Events

#### ExpansionConfigSet

Emitted when the expansion config is set for an exchange.

| Parameter name       | Annotation                                                |
| -------------------- | --------------------------------------------------------- |
| `exchangeId`         | The ID of the exchange.                                   |
| `expansionRate`      | The rate of expansion in percentage with 1e18 being 100%. |
| `expansionfrequency` | The frequency of expansion in seconds.                    |

```solidity
event ExpansionConfigSet(
    bytes32 indexed exchangeId,
    uint64 expansionRate,
    uint32 expansionfrequency
);
```

#### RewardMinted

Emitted when a reward is minted.

| Parameter name | Annotation                                  |
| -------------- | ------------------------------------------- |
| `exchangeId`   | The ID of the exchange.                     |
| `to`           | The address of the recipient of the reward. |
| `amount`       | The amount of G$ tokens minted as reward.   |

```solidity
event RewardMinted(
    bytes32 indexed exchangeId,
    address indexed to,
    uint256 amount
);
```

#### InterestUBIMinted

Emitted when UBI is minted through collecting reserve interest.

| Parameter name | Annotation                                           |
| -------------- | ---------------------------------------------------- |
| `exchangeId`   | The ID of the exchange.                              |
| `amount`       | The amount of G$ tokens minted as UBI from interest. |

```solidity
event InterestUBIMinted(bytes32 indexed exchangeId, uint256 amount);
```

#### ExpansionUBIMinted

Emitted when UBI is minted through expansion.

| Parameter name | Annotation                                            |
| -------------- | ----------------------------------------------------- |
| `exchangeId`   | The ID of the exchange.                               |
| `amount`       | The amount of G$ tokens minted as UBI from expansion. |

```solidity
event ExpansionUBIMinted(bytes32 indexed exchangeId, uint256 amount);
```

### Functions

#### setExpansionConfig

Sets the expansion configuration for the given exchange. The expansion rate is in percentage with 1e18 being 100%, and expansion frequency is in seconds.

| Parameter name       | Annotation                                                |
| -------------------- | --------------------------------------------------------- |
| `exchangeId`         | The ID of the exchange to set the expansion config for.   |
| `expansionRate`      | The rate of expansion in percentage with 1e18 being 100%. |
| `expansionFrequency` | The frequency of expansion in seconds.                    |

```solidity
function setExpansionConfig(
    bytes32 exchangeId,
    uint64 expansionRate,
    uint32 expansionFrequency
) external;
```

#### mintUBIFromInterest

Mints UBI for the given exchange from collecting reserve interest. Calls the exchange provider's mintFromInterest and distributes minted tokens through the distribution helper.

| Parameter name    | Annotation                                            |
| ----------------- | ----------------------------------------------------- |
| `exchangeId`      | The ID of the exchange to mint UBI for.               |
| `reserveInterest` | The amount of reserve tokens collected from interest. |

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

#### mintUBIFromReserveBalance

Mints UBI for the given exchange by comparing the actual reserve balance of the contract to the virtual balance. Calculates the difference and mints tokens accordingly.

| Parameter name | Annotation                              |
| -------------- | --------------------------------------- |
| `exchangeId`   | The ID of the exchange to mint UBI for. |

**Returns:** The amount of G$ tokens minted.

```solidity
function mintUBIFromReserveBalance(
    bytes32 exchangeId
) external returns (uint256 amountMinted);
```

#### mintUBIFromExpansion

Mints UBI for the given exchange by calculating the expansion rate. Checks if expansionFrequency time has passed since lastExpansion, calculates expansion scaler, and mints tokens accordingly.

| Parameter name | Annotation                              |
| -------------- | --------------------------------------- |
| `exchangeId`   | The ID of the exchange to mint UBI for. |

**Returns:** The amount of G$ tokens minted.

```solidity
function mintUBIFromExpansion(
    bytes32 exchangeId
) external returns (uint256 amountMinted);
```

#### mintRewardFromRR

Mints a reward amount of tokens for a specific recipient. Updates the reserve ratio through the exchange provider and mints tokens directly to the recipient address.

| Parameter name | Annotation                                  |
| -------------- | ------------------------------------------- |
| `exchangeId`   | The ID of the exchange.                     |
| `to`           | The address of the recipient of the reward. |
| `amount`       | The amount of G$ tokens to mint as reward.  |

```solidity
function mintRewardFromRR(
    bytes32 exchangeId,
    address to,
    uint256 amount
) external;
```