# Moonwell Core

Moonwell Core is a Compound V2-compatible lending protocol deployed on Base and OP Mainnet. Developers interact with two main contracts: **mTokens** (market-level supply, borrow, repay, liquidate) and the **Comptroller** (collateral management, account health, risk parameters).

## Architecture

```
┌──────────────────────────────────────────────────────┐
│                    Comptroller                        │
│  Policy layer - collateral, health checks, rewards   │
└──────────┬────────────────────────────┬──────────────┘
           │                            │
     ┌─────▼──────┐             ┌──────▼───────┐
     │  mToken A  │             │  mToken B    │
     │  (e.g.     │             │  (e.g.       │
     │   mUSDC)   │             │   mWETH)     │
     └────────────┘             └──────────────┘
      mint / redeem              borrow / repay
      supply / withdraw          liquidateBorrow
```

All user-facing operations (supply, borrow, repay, withdraw, liquidate) go through mToken contracts. The Comptroller enforces collateral requirements and risk limits behind the scenes.

## Components

| Component                                                                        | Purpose                                                            |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [mTokens](https://docs.moonwell.fi/moonwell/developers/protocol/mtokens)         | Market contracts - supply, borrow, repay, withdraw, liquidate      |
| [Comptroller](https://docs.moonwell.fi/moonwell/developers/protocol/comptroller) | Policy layer - collateral, health checks, risk parameters, rewards |
| [OEV](https://docs.moonwell.fi/moonwell/developers/protocol/oev)                 | Oracle wrappers - early price access for liquidations              |
| [4626 Vaults](https://docs.moonwell.fi/moonwell/developers/protocol/4626-vaults) | ERC-4626 wrappers around mToken markets                            |

## Where to Start

| Goal                                     | Start here                                                                                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Integrate Moonwell lending markets       | [Guide: Core Market Integration](https://docs.moonwell.fi/moonwell/developers/guides/core-market-integration)                                 |
| Build a yield product on top of Moonwell | [Guide: Vault Integration](https://docs.moonwell.fi/moonwell/developers/guides/vault-integration)                                             |
| Build an OEV liquidation bot             | [Guide: OEV Liquidator Bot](https://docs.moonwell.fi/moonwell/developers/guides/oev-liquidator)                                               |
| Full mToken function reference           | [mTokens](https://docs.moonwell.fi/moonwell/developers/protocol/mtokens) - `mint()`, `redeem()`, `borrow()`, `liquidateBorrow()`              |
| Full Comptroller function reference      | [Comptroller](https://docs.moonwell.fi/moonwell/developers/protocol/comptroller) - `enterMarkets()`, `getAccountLiquidity()`, `claimReward()` |
| Understand risk controls                 | [Comptroller - Risk Parameters](https://docs.moonwell.fi/moonwell/developers/protocol/comptroller/risk-parameters)                            |
| OEV mechanism details                    | [OEV](https://docs.moonwell.fi/moonwell/developers/protocol/oev) - `updatePriceEarlyAndLiquidate()`                                           |

## Key Patterns

**Error handling** - mToken and Comptroller functions use two failure modes:

* **Error codes** - Business logic failures return a non-zero `uint` without reverting. Always check the return value.
* **Reverts** - Transfer failures, math overflows, and pause/cap enforcement revert the transaction.

**Interest accrual** - Interest accrues per-second (not per-block). The exchange rate between mTokens and underlying grows automatically as interest accrues.

**Collateral flow** - Supply → `enterMarkets()` → Borrow. You must explicitly enable an asset as collateral before borrowing against it.

For step-by-step integration walkthroughs, see the [Guides](https://docs.moonwell.fi/moonwell/developers/guides).