> For the complete documentation index, see [llms.txt](https://docs.moonwell.fi/moonwell/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.moonwell.fi/moonwell/developers/protocol.md).

# 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](/moonwell/developers/protocol/mtokens.md)         | Market contracts - supply, borrow, repay, withdraw, liquidate      |
| [Comptroller](/moonwell/developers/protocol/comptroller.md) | Policy layer - collateral, health checks, risk parameters, rewards |
| [OEV](/moonwell/developers/protocol/oev.md)                 | Oracle wrappers - early price access for liquidations              |
| [4626 Vaults](/moonwell/developers/protocol/4626-vaults.md) | ERC-4626 wrappers around mToken markets                            |

## Where to Start

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