[DRAFT] Proposal: On-Chain Circuit Breaker

This is a draft proposal for a change that aims to improve the functionality of Mento. The change will include the creation of new contracts and updates to Exchange.sol.

Simple Summary

Design of an automated on-chain circuit breaker to limit trading via mento when prices shift more than a calculated threshold.


Mento currently relies on centralized oracles, run by cLabs, to provide up to date price data. In the case of large price movements, the oracle clients have a circuit breaker implemented which will trigger if a new price to be reported is greater than a configurable threshold. Once activated, the circuit breaker stops the oracle from sending price reports until it’s manually restarted.

This proposal will move this responsibility from oracle clients to a new on-chain mechanism that will have the ability to recover without manual intervention and is easily extensible. This change will also introduce the concept of ‘trading modes’ for a mento exchange. Trading modes will determine the direction of trading allowed for a particular mento exchange. Initially, the only trading modes will be bi-directional(the current default trading mode) and no trading. The proposed design will allow the addition of new trading modes, such as unidirectional trading, in future.


Oracles are a core component of the Mento protocol. They deliver the necessary price data for our stable assets to maintain their peg. In the case of decentralized oracles, price data is potentially subject to manipulation by the entity running the oracle or other malicious actors. Introducing an on-chain circuit breaker will provide an extra layer of security to protect from any manipulation, attacks or extreme market volatility. This feature will also serve as a base for future functionality to be built on whilst supporting the move to decentralized oracles.


The on-chain circuit breaker will be comprised of the BreakerBox contract & separate breaker contracts that implement the IBreaker interface. The BreakerBox will act as a simple interface to evaluate all breaker criteria and initially will only be called when a buy or sell is made through an exchange. If an exchange meets any breaker criteria, it will be switched to the relevant trading mode. Governance will be able to add and remove exchanges and breakers to the BreakerBox. The BreakerBox will also store the current active trading mode of each exchange. The Exchange contract will use this to determine whether or not an incoming trade should revert. This proposal will only introduce one breaker contract, the MedianDeltaBreaker. This breaker will trip when the current report price is greater than a calculated threshold for the exchange’s stable token relative to the last report price. Values used to calculate the threshold will be configurable by governance. When the breaker trips for an exchange, the BreakerBox will switch the exchange to no trading mode.


The circuit breaker aims to minimize the risk to the reserve in times of extreme price volatility. Extreme volatility can expose the reserve to risk without that risk actually materializing. The reserve risk is only materialized when a mint/burn of mento stables occurs when they are significantly above or below the peg. To mitigate the risk, the point of trade is the latest moment the breaker should be triggered.


Whilst performing the breaker check during mint/burn appears to offer the best protection, it will increase the gas cost of the transactions. The gas cost would also increase with every breaker that is added. It’s possible to minimize the increase by ensuring checks are only made once per block. The cost of this can also be further minimized by using the exchange trigger as a secondary check and another trigger as a primary check.

Other integration options considered include the following:

By hooking into the existing process of oracle reporting, the circuit breaker would be triggered in times of extreme volatility as soon as the on-chain “truth” was deemed questionable. Whilst this option would allow the mechanism to react early, it becomes possible for an attacker to front-run the circuit breaker activation. The risk to the reserve is easily materialized without an additional hook at the point of mint/burn. This option also has a reliance on oracles being alive and reporting.

Another option considered was the introduction of ‘BreakerBox keepers’. The goal would be to trigger the BreakerBox check at a regular interval. This option would require additional infrastructure to be set up and could introduce more centralized dependencies if the mento team takes ownership of maintaining the keepers.

Technical Specification
Trading Modes

A tradingMode will allow an exchange to determine what type of trading is permitted. Trading modes will be stored as uint in the BreakerBox using a mapping that references an exchange and its current trading mode. Initially, there will be two trading modes, bi-directional mode(1) & no trading(0). At the time of trading, an exchange will look up the trading mode it is currently in and will allow or revert the buy/sell transaction based on this lookup.

IBreaker public interface:

Breaker contracts encapsulate the logic required to determine whether or not a breaker should trip and when it can be reset. Each breaker can only trigger the activation of one trading mode. A breaker contract must implement the IBreaker interface. Breakers may have additional parameters that can also be set by governance, this includes cooldown time.

IBreakerBox public interface:

The BreakerBox will primarily facilitate switching between trading modes based on logic defined in the individual breaker contracts. The contract will be responsible for the following:

  • Storing addresses of breaker contracts
  • Storing addresses of known mento exchanges and their current trading modes.
  • Storing the block number of the last trading mode update for an exchange
  • Evaluating trigger conditions for all breakers & updating exchange trading modes when a breakers trigger needs are met

Breakers & exchanges can be added and removed to the BreakerBox through authenticated functions only accessible to governance. When a breaker is removed, any exchanges that are currently in the breakers’ trading mode will be set to the default mode. Governance will also be able to switch an exchange to a specified trading mode manually.

Integration & Existing Contract Modifications

The BreakerBox will hook into the existing process of buying & selling in mento exchanges. A new modifier checkTradingMode(bool isBuy) will be created in the exchange contract and added to Exchange.buy() and Exchange.sell() functions. When called, the modifier will make a call to the BreakerBox.checkBreakers() function. When the function returns, the trading mode of the exchange will be checked against the isBuy parameter to determine whether or not the function call should be reverted.



Summary of Changes:
  • Create IBreakerBox & IBreaker interfaces
  • Create BreakerBox contract
  • Create MedianDeltaBreaker contract
  • Add modifier to Exchange contract
  • Update Exchange.buy()
  • Update Exchange.sell()
Test Cases

Will be included with implementation.

Security Considerations

Implementing this proposal allows new circuit breaker logic to be added and integrated quickly. Whilst this should minimize risk to the reserve, it is possible to introduce new security vulnerabilities if care is not taken during implementation. New breaker logic should be thoroughly tested, reviewed and audited as each breaker has the potential to introduce the occurrence of false-positive triggers and false-negative triggers to the mechanism.


Cool start!

Can a ‘breaker’ be triggered by the balance of assets in the reserve, maybe even segregated: reserve total, Celo-only, and non-Celo?

That thought is trying to establish a practical breaker of last resort triggered before the point where the stable coins could not be redeemed for full value.

Given the draft legislation info that has come out from NY and the USA over the last few days/hours, that threshold appears to be a likely future requirement for any digital currency to remain viable from a regulatory perspective.

As long as the data required by the breaker is available on-chain then it’s possible to create any type of breaker. In the case of a reserve asset balance breaker, getting the total balance of assets in the reserve would require more effort as only $CELO is held on-chain. So without introducing some cross-chain interactions this wouldn’t be possible right now.

1 Like

Is there a third party oracle that could be queried automatically, say on chainlink…

Chainlink does offer a solution, proof of reserve, that does this. However, I’m not sure of the details or if we can use chainlink. This reserve balance breaker won’t be included in the scope of this change, but I think it’s worth investigating at some point. I added this as a feature request here, so it doesn’t get lost.

1 Like

Sounds like what your proposing can accept that input later, one step at a time is great. Going the right way!

1 Like