================
 Topup
================

`Handler Contract <https://github.com/merofinance/protocol/blob/main/interfaces/actions/topup/ITopUpHandler.sol>`_
====================================================================================================================

Overview
================

- Interface containing required methods for performing collateral top ups on a lending protocol
- This needs to be implemented by each protocol-specific top up handler (e.g. `Aave Handler <https://github.com/merofinance/protocol/blob/main/contracts/actions/topup/handlers/AaveHandler.sol>`_, `Compound Handler <https://github.com/merofinance/protocol/blob/main/contracts/actions/topup/handlers/CompoundHandler.sol>`_)


`Topup Action Contract <https://github.com/merofinance/protocol/blob/main/contracts/actions/topup/TopUpAction.sol>`_
====================================================================================================================

Overview
================

- LP token holders can register a position on a supported protocol for top up
- Positions can get updated or removed at any time
- Keepers can execute collateral top ups
- Top-ups are executed through pre-registered top-up handlers


`Topup Fee Handler Contract <https://github.com/merofinance/protocol/blob/main/contracts/actions/topup/TopUpActionFeeHandler.sol>`_
====================================================================================================================================

Overview
================

- Handles fees charged on top up amount


Integrating Protocols for Top Ups
===================================

There is a number of protocols for which Mero supports collateral top ups.

Currently the following protocols are supported:

    * `Compound <https://compound.finance/>`_
    * `Aave <https://aave.com/>`_

We aim to add support to various other protocols. Please reach out if you are interested in integrating with Mero by emailing ``info@mero.finance``.

This section outlines how protocols can be integrated with Mero. Note that in the future integration will be subject to approval from the Mero DAO.


Getting Started: Top Up Handlers
--------------------------------

Integrating a new protocol can be relatively straightforward. The top up logic is mostly abstracted away and handled by the ``TopUpAction`` contract. This contract handles the registration/deletion/updating of positions, while also containing a list of all supported *Top up handlers*. A top up handler is a contract which contains the top up logic for a specific protocol. Hence, integrating a new protocol requires to create a new top up handler for it.

A top up handler contains the following interface.


.. py:function:: function topUp(bytes32 account, address underlying, uint256 amount, bytes memory extra) external payable

    Tops up the account for the protocol

    * ``account``: Account to be topped up
    * ``underlying``: Underlying currency to be used for top up
    * ``amount``: Amount to be topped up
    * ``extra``: Arbitrary data that can be passed to the handler


.. py:function:: TopUpHandler.getUserFactor(address account, bytes memory extra) external returns (uint256)

    Returns a factor for the user which should always be >= 1 for sufficiently colletaralized positions and should get closer to 1 when collaterization level decreases

    *  ``account``: Account for which to get the factor
    * ``extra``: Arbitrary data that can be passed to the handler

    .. note:
        Note that the ``user factor`` is the current aggregated collateralization factor of the user including any internal liquidation threshold or other security parameters. A user factor of 1 should be the exact limit before a user gets liquidated.

An example implementation of a top up handler is given by the `Top Up Handler for Compound <https://github.com/merofinance/protocol/blob/main/contracts/actions/topup/handlers/CompoundHandler.sol>`_.


Adding A Top Up Handler
-----------------------

Once a new protocol top up handler has been implemented it only needs to be added to the ``TopUpAction`` contract. This can be done via the following method:


.. py:function:: updateTopUpHandler(bytes32 protocol, address handlerAddress) external

    Update an existing or add a new top up handler.

    * ``protocol``: Name of the protocol as ``bytes32``
    * ``handlerAddress``: Address of the handler


.. note:
        In the future adding and removing protocols will only be possible via the Mero DAO.