# Mento

{% hint style="warning" %}
This section describes the state of the contracts as of April 2023.
{% endhint %}

* **Module Name:** Mento Module
* **Contract Sources:**&#x20;
  * [MentoExchange.sol](https://github.com/Kolektivo/kolektivo-monetary-contracts/blob/development/src/mento/MentoExchange.sol)
  * [MentoRegistry.sol](https://github.com/Kolektivo/kolektivo-monetary-contracts/blob/development/src/mento/MentoRegistry.sol)
  * [MentoReserve.sol](https://github.com/Kolektivo/kolektivo-monetary-contracts/blob/development/src/mento/MentoReserve.sol)
  * [KolektivoGuilder.sol](https://github.com/Kolektivo/kolektivo-monetary-contracts/blob/development/src/mento/KolektivoGuilder.sol)
  * Oracles

<figure><img src="https://807599655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIhKhzl8NzsNE6Q8tO6lW%2Fuploads%2Ffo1IcVYq7msfjTTI7CJQ%2FKolektivo%20Monetary%20System%20(4).jpg?alt=media&#x26;token=3cddfc73-440f-426f-a7ac-812afba851b6" alt=""><figcaption><p>Zoom in the Mento Module.</p></figcaption></figure>

<details>

<summary>Table of Contents</summary>

[Summary](#summary)

[Module Details](#module-details)

[Mento](#mento)

* [Exchange](#exchange)
* [Registry](#registry)
* [Reserve](#reserve)
* [Stable Token](#stable-token)

[kCUR Oracle](#kcur-oracle)

[Back-End Services](#back-end-services)

* [Mento Arbitrage Service](#mento-arbitrage-service)
* [Mento SortedOracle Service](#mento-sortedoracle-service)

</details>

## Summary

This module is the deployment of the single collateral [Mento system](https://docs.celo.org/protocol/stability/doto) from Celo, where the reserve token is presumably used as the backing token for a community currency (e.g. kCUR for kGuilder). A good explanation of the behavior of the Mento stability algorithm can be found in [this paper](https://celo.org/papers/Celo_Stability_Analysis.pdf). A good overall intro to the mechanism behind this can be found in this [article](https://medium.com/celohq/diving-into-the-celo-price-stability-protocol-d7afd210609e). The contracts themselves are [on Github](https://github.com/celo-org/celo-monorepo/tree/master/packages/protocol/contracts/stability), which already contains some elements of [Granda Mento](https://docs.celo.org/celo-codebase/protocol/stability/granda-mento).

## Module Details

Our deployment of the Mento module has 4 core components consisting of the original `Exchange.sol`, `Registry.sol,` and `Reserve.sol`contracts from the Celo Mento Protocol, as well as the `KolektivoGuilder.sol` contract, which is our interpretation of the `StableToken.sol` contract from the Celo Mento Protocol. On top of this, oracles update the contracts with crucial data, and a back-end service is being run.

{% embed url="https://github.com/celo-org/celo-monorepo/tree/master/packages/protocol/contracts/stability" %}
You can consult the original Mento contracts on the Celo GitHub
{% endembed %}

## Mento

### Exchange

The `MentoExchange.sol` contract that Kolektivo deployed takes root in the [Exchange.sol](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/stability/Exchange.sol) from Mento. The language has been updated to the latest version of Solidity —  i.e. from Solidity 0.5.13 to 0.8.10. In the context of the Kolektivo MVP, this contract serves as a trading interface between the Kolektivo Guilder (kG) and the Kolektivo Reserve Token (kCUR) using a Constant Product Market Maker Model. In this sense, it is easily comparable to a pool.&#x20;

{% embed url="https://github.com/Kolektivo/kolektivo-monetary-contracts/blob/development/src/mento/MentoExchange.sol" %}

### Registry

The `MentoRegistry.sol` contract that Kolektivo deployed takes root in the original [UsingRegistryV2.sol](https://github.com/celo-org/celo-monorepo/blob/1d48109b00d99d32789b36d55641a5ef298b2740/packages/protocol/contracts/common/UsingRegistryV2.sol) from Mento. The language has been updated to the latest version of Solidity —  i.e. from Solidity 0.5.13 to 0.8.10. This contract is fundamental for the good functioning of the Mento Module as it registers and stores addresses, and associates them with identifiers.

{% embed url="https://github.com/Kolektivo/kolektivo-monetary-contracts/blob/development/src/mento/MentoRegistry.sol" %}

### Mento Reserve

The `MentoReserve.sol` contract that Kolektivo deployed takes root in the original [Reserve.sol ](https://github.com/celo-org/celo-monorepo/blob/1d48109b00d99d32789b36d55641a5ef298b2740/packages/protocol/contracts/stability/Reserve.sol)contract from Mento. The language has been updated to the latest version of Solidity —  i.e. from Solidity 0.5.13 to 0.8.10. This contract stores and manages assets, and ensures the price stability of the stable tokens with respect to their pegs. This contract also introduces parametrizable economic parameters, such as a Tobin Tax (`tobinTax`), or daily spending limits (`spendingRatio`).

{% embed url="https://github.com/Kolektivo/kolektivo-monetary-contracts/blob/development/src/mento/MentoReserve.sol" %}

### Stable Token

The `KolektivoGuilder.sol` contract that Kolektivo deployed takes root in the original [StableToken.sol](https://github.com/celo-org/celo-monorepo/blob/1d48109b00d99d32789b36d55641a5ef298b2740/packages/protocol/contracts/stability/StableToken.sol) contract from Mento. The language has been updated to the latest version of Solidity —  i.e. from Solidity 0.5.13 to 0.8.10. In Celo Mento, `StableToken` implements ERC-20 tokens and Celo-specific features for stable assets. Each stable asset has its own contract, with `StableToken.sol` for the Celo Dollar, `StableTokenEUR.sol` for the Celo Euro, and so forth for new stable assets. The`KolektivoGuilder.sol` is the Kolektivo Guilder (kG): An ERC-20 with a parametrizable notion of inflation and freezing options. The contract is ownable and in the context of the Kolektivo Minimum Viable Product (MVP), managed by the Kolektivo multi-sig.&#x20;

{% embed url="https://github.com/Kolektivo/kolektivo-monetary-contracts/blob/development/src/mento/StableTokenKG.sol" %}

## kCUR Oracle

On top of being extensively used in the Reserve module, the kCUR oracle is also fundamental in the context of the Mento module. A kCUR Data Provider [back-end service](#back-end-services) regularly pushes reports about the state of kCUR's price in the kCUR Symmetric pool to the kCUR oracle. The `MentoExchange.sol` contract  queries the kCUR oracle to be updated about the state of kCUR's price. This protects the Mento Exchange from arbitrage opportunities that could occcur in the case of wrong token price reporting.&#x20;

## Back-End Services

{% hint style="info" %}
As of April 2023, Kolektivo deployed a number of off-chain backend services that will observe specific contracts and APIs, execute transactions and reports asset data on-chain.
{% endhint %}

### Mento Arbitrage Service

<figure><img src="https://807599655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIhKhzl8NzsNE6Q8tO6lW%2Fuploads%2FYU0AUNZ2vzOjRr96uNiN%2FBlank%20diagram%20(13).jpeg?alt=media&#x26;token=df482202-8dbd-4b4b-ba94-7d6be36e1de3" alt=""><figcaption></figcaption></figure>

#### Summary

For the Mento Module, we need a **Mento Exchange Arbitrage Service** as back-end service to make sure that the kCUR-kG ratio remains close to what it has been set at, and that kG remains pegged to ANG. For that, the service queries the price of kCUR, ANG, as well as the kCUR-kG ratio, and is able to conduct buy or sell orders to balance the kCUR-kG ratio so that kG stays pegged to ANG.

#### Functions

* The service queries the price of kCUR from the kCUR oracle periodically.
* The service queries the price of ANG denominated in dollar from a public API periodically.
* The service queries the current kCUR-kG ratio from the `MentoExchange.sol` contract.
* The service is able to evaluate the ratio of kG to kCUR, based on the price of kCUR and ANG.
* The service is able to decide to buy or sell to balance the ratio of kCUR-kG so that kG stays pegged to the Guilder.
* The service is able to buy and sell, to and from, the Symmetric kCUR pool.
* The service is able to buy and sell, to and from, the Symmetric kG pool.

### Mento SortedOracle Service

<figure><img src="https://807599655-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIhKhzl8NzsNE6Q8tO6lW%2Fuploads%2FHRjmenjYONy1TauAoNdc%2FKolektivo%20Monetary%20System%20(8).jpg?alt=media&#x26;token=39b0bc83-8d41-4758-9bb3-eb365282f1cf" alt=""><figcaption></figcaption></figure>

#### Summary

This back-end service is to be differentiated from the Reserve Oracles. It enables to convey the kG to kCUR exchange rate to the Mento system — rather than a token USD price. The kG to kCUR exchange rate conveys how many kGs are needed to buy a single kCUR — e.g. if the exchange rate is expressed as 1.33, that means it costs 1.33 kG to get 1 kCUR.

Assuming that the USD price of kG is $0.5586592178770949, the exchange rate is computed as:

rate = 1 / (0.5586592178770949 / kCurPrice)

Since we only care about buying one kCur, there is nothing to multiply, the amount of required kG **is** the rate. This rate is what is then reported to the Mento Oracle.

#### Functions

* The service is able to get the address of the SortedOracles contract.
* The service is able to compute the exchange rate as given above.
* The service is able to call `report` on the address of the SortedOracles contract.

## Failure Modes

{% hint style="danger" %}
Please note that this experimental MVP software is provided on an "as is" and "as available" basis. As this module is an first attempt, be aware that different failures may occur. We do not give any warranties and will not be liable for any loss incurred through any use of this codebase.

You can find the audits for the Mento Protocol v1.0.0 [here](https://blog.openzeppelin.com/celo-contracts-audit/#phase-3), and the audits for the Mento Protocol v2.0.0 [here](https://www.verilog.solutions/audits/mento/).
{% endhint %}
