These preliminary docs are intended to give auditors an introduction and overview over the Mento Core Contracts Upgrade #1 - Multi Collateral Mint.

Why core contract upgrade?

Several areas of improvement have been identified since operating the Mento core contracts in their current state since Spring 2020. The first area has been the operational complexity of adding new stablecoins, where each time a new set of contracts has to be deployed. Another area has been users, who only have been able to mint and burn stables against the native CELO seignorage token, not the remaining reserve assets. This comes with a downward spiral risk, which would traditionally be called a bank run. An algorithmic issue has been that by the constant product market maker setup alone, slippage and trading limits could only be set together, not independently. Another economic area of improvement has been the missing possibility to mint and burn larger amounts of stables without high slippage, which was necessary to protect the reserve against market price manipulation and oracle attacks.

Intent and goals of the upgrade

The goals of the contract upgrade are

1. Reduce operational complexity of adding new stabletokens
2. Multi collateral minting: Set the path for stabletoken minting and burning against multiple reserve assets, including larger mints and burns at lower slippage
3. Separate pricing from attack protection: Slippage and trading limits
4. Introduce helpful abstractions to become more flexible for future protocol changes, like changing pricing algorithms without core contract, only config changes.

Problem solution

MultiCollateral-Mento or “McMint” is a generalization of the current Mento system with the aim of allowing virtual pools between any mento stable asset and mento collateral asset to be traded under different pricing regimes. New exchange pairs can be deployed through configuration only. Responsibility of reserve asset management and the pricing logic for virtual pools is split into separate contracts. The core contract upgrade moves oracle circuit breakers from the oracle clients to on-chain, automating and modularizing the circuit breaker logic. Slippage and trading limits are separated in pricing contracts and configurable exchange trading limits.

Architecture & Code

Broker.sol is the entry point for traders. It is responsible for requesting and executing swaps. It is the only contract with spender rights over the reserve and minting & burning rights over stable assets. When executing swaps, it enforces trading limits. The broker orchestrates swaps by calling BiPoolManager.sol. The Broker also exposes a burn function for burning stable tokens without subject to trading limits or regular exchange operations.

BiPoolManager.sol is responsible for storing and managing the state of configured asset pools, which can consist of two assets. With its state information on assets and bucket sizes it prices trades using a pricing module. It also checks if trading is allowed or suspended as decided by the on-chain circuit breaker BreakerBox.sol. Currently, it can price trades with constant-product or constant-sum as specified in the respective pricing modules.

TradingLimits.sol stores and keeps track of trading limits for all exchange pairs. Limits are configurable for 5-minute and 1-day intervals, as well as a total global limit. It is called by Broker.sol when requesting swaps. The limits exist to protect the protocol against possible economic exploits or smart contract hacks.

BreakerBox.sol is an on-chain circuit breaker for oracle reports. It maintains a state for each price feed, whether trading is allowed or suspended. It is modular by design and allows for flexible addition and deletion of price feeds and individual breaking logic. It’s conditions are checked and breakers triggered if necessary by newly added rates in SortedOracles.sol. When a breaker is triggered for a rate feed it will halt the trading of that token. For each requested swap, BiPoolManager.sol checks against this contract whether trading a specific pair is currently allowed or suspended.

MedianDeltaBreaker.sol implements a median delta breaker check for the on-chain circuit breaker managed by BreakerBox.sol. This breaker triggers when an updated oracle median rate changes more than a configured relative threshold from the previous one.