# @1delta/margin-fetcher

Multi-protocol lending data fetcher supporting Morpho Blue, Aave V2/V3, Compound V2/V3, Euler, Init, Lista DAO, and Morpho Midnight. Provides public market data (rates, TVL, configs) and per-user position data (balances, shares, collateral) in a unified format.

## How Morpho Blue Works

### Protocol overview

Morpho Blue is an **isolated-market** lending protocol. Unlike pooled protocols (Aave, Compound) where all assets share a single pool, each Morpho market is a **standalone pair** defined by five parameters:

| Parameter | Description |
|-----------|-------------|
| `loanToken` | The asset that can be supplied and borrowed |
| `collateralToken` | The asset deposited as collateral |
| `oracle` | Price oracle for the pair |
| `irm` | Interest Rate Model contract |
| `lltv` | Liquidation Loan-To-Value ratio (18-decimal WAD) |

These five parameters are hashed into a `uniqueKey` (bytes32) that identifies the market on-chain.

### Interest rate model

Morpho uses an **adaptive curve IRM** that adjusts rates based on utilization relative to a 90% target:

```
utilization = totalBorrowAssets / totalSupplyAssets

If utilization > 90%: rateAtTarget increases over time (via exponential adjustment)
If utilization < 90%: rateAtTarget decreases over time

borrowRate = curve(rateAtTarget, utilization)
supplyRate = borrowRate * utilization * (1 - fee)
```

The curve uses a steepness factor of 4x, meaning at full utilization the rate is 4x the rate-at-target. Rates are stored as per-second WAD values and compounded continuously.

Key constants:
- **Target utilization**: 90%
- **Curve steepness**: 4x
- **Min rate at target**: ~0.1% APY
- **Max rate at target**: ~200% APY
- **Adjustment speed**: 50x/year (exponential)

### Share-based accounting

Positions are tracked via **shares** rather than raw assets. This allows interest to accrue without storage updates per-user:

```
assets = shares * (totalAssets + 1) / (totalShares + VIRTUAL_SHARES)
```

Where `VIRTUAL_SHARES = 1e6` prevents share inflation attacks.

### Market data representation

Each Morpho market produces **two entries** in the normalized output:

1. **Loan entry** — the borrowable asset
   - Has `borrowingEnabled: true`, `collateralActive: false`
   - Contains deposit/borrow APRs, total supply/debt, liquidity
   - Rewards (MORPHO token incentives) attached here

2. **Collateral entry** — the collateral asset
   - Has `borrowingEnabled: false`, `collateralActive: true`
   - LTV factors derived from the market's `lltv`
   - No interest rates (collateral doesn't earn yield in Morpho)

### Whitelisted vs unlisted markets

Morpho markets can be **whitelisted** (curated, visible in the Morpho UI) or **unlisted** (removed from curation). The `includeUnlistedMorphoMarkets` flag controls whether unlisted markets are fetched from the API. Unlisted markets are tagged with `isListed: false` on the `MorphoMarket` params.

## Architecture

### Data fetching strategy

The fetcher uses a **hybrid approach** that routes each lender to either an API or on-chain path:

```
getLenderPublicDataAll(chainId, lenders, ...)
├── lenderCanUseApi(lender, chainId)?
│   ├── YES → getLenderPublicDataViaApi()  →  Morpho GraphQL API
│   └── NO  → getLenderPublicData()        →  On-chain multicall via Morpho Lens
└── Promise.all([onChain, api]) → merged result
```

**Morpho Blue uses the API** on most chains. On-chain fallback is used for chains without API support (OP Mainnet, Soneium, Hemi, Berachain, Sei).

### API path (GraphQL)

Fetches from `https://blue-api.morpho.org/graphql`:

```
fetchMorphoMarkets(chainId, includeUnlisted)
  → GraphQL query (paginated: 200/page, 2 pages for Ethereum mainnet)
  → GetMarketsResponse
  → convertMarketsToMorphoResponse()
  → { [marketId]: MorphoGeneralPublicResponse }
```

The API provides pre-computed APYs, USD values, and reward data. APY→APR conversion is applied during normalization.

### On-chain path (Morpho Lens)

Uses a custom lens contract that returns compact binary-encoded market data:

```
buildMorphoCall(chainId)
  → multicall to MORPHO_LENS.getMarketDataCompact(morpho, marketHashes[])
  → chunks of 50 markets per call (calldata size limit)
  → raw bytes response

getMorphoMarketDataConverter()
  → decodeMarkets(bytes)           // 256-byte records → Market[]
  → MathLib.getBorrowApy(...)      // compute rates from rateAtTarget + utilization
  → MathLib.getSupplyApy(...)
  → { [marketId]: MorphoGeneralPublicResponse }
```

#### Binary encoding (256 bytes per market)

```
Offset  Size   Field
0       20     loanToken (address)
20      20     collateralToken (address)
40      20     oracle (address)
60      20     irm (address)
80      16     lltv (uint128)
96      32     price (uint256) — collateral/loan exchange rate in WAD
128     32     rateAtTarget (uint256) — per-second interest rate
160     16     totalSupplyAssets (uint128)
176     16     totalSupplyShares (uint128)
192     16     totalBorrowAssets (uint128)
208     16     totalBorrowShares (uint128)
224     16     lastUpdate (uint128) — timestamp
240     16     fee (uint128)
```

### User data path

```
buildMorphoUserCallWithLens(chainId, account, lender, marketIds)
  → MORPHO_LENS.getUserDataCompact(marketHashes[], account, morpho)
  → chunks of 100 markets per call

decodePackedMorphoUserDataset(hex)
  → [uint16 count] + [130-byte records × count]
  → BalanceInfo[] { index, supplyShares, borrowShares, supplyAssets, borrowAssets, collateral }

getMorphoUserDataConverterWithLens()
  → map balances to market IDs via index
  → separate loan positions (supply/borrow) from collateral positions
  → format to UserData with USD values
```

## File structure

```
src/lending/
├── public-data/
│   ├── fetchLenderAll.ts          # Hybrid router (API vs on-chain)
│   ├── fetchLender.ts             # On-chain multicall dispatcher
│   ├── fetchLenderExt.ts          # API dispatcher
│   └── morpho/
│       ├── fetchPublic.ts         # GraphQL query + fetch logic
│       ├── convertPublic.ts       # API response → normalized format
│       ├── publicCallBuild.ts     # Morpho Lens call builder
│       ├── getMarketsFromChain.ts # On-chain response → normalized format
│       └── utils/
│           ├── evmParser.ts       # Binary decoder (256-byte records)
│           ├── mathLib.ts         # WAD math, rate calculations
│           └── parsers.ts         # LTV parsing, number formatting
├── user-data/
│   └── morpho/
│       ├── userCallBuild.ts       # User position call builder
│       ├── decoder.ts             # User data binary decoder
│       ├── userCallParse.ts       # Balance → UserData conversion
│       ├── morphoLib.ts           # Share ↔ asset conversion
│       └── types.ts               # Parameter position enums
└── ...

src/types/lender/
└── morpho-types.ts                # GetMarketsResponse, MorphoMarket, MorphoGeneralPublicResponse
```

## Lista DAO extension

Lista is a Morpho Blue fork with additional per-market fields. Uses a 357-byte binary record instead of 256:

| Extra field | Type | Description |
|-------------|------|-------------|
| `minLoan` | uint128 | Minimum loan amount |
| `hasWhitelist` | bool | Whether the market has access control |
| `loanProvider` | address | Yield source for loan token |
| `collateralProvider` | address | Yield source for collateral |
| `broker` | address | Authorized broker contract |

User data also includes per-market whitelist flags prepended before the balance records.

### Fixed-term broker (`LendingBroker`)

Some Lista markets register a **`LendingBroker`** — the mandatory debt-side gateway of a Moolah
(Morpho-fork) market. Collateral supply/withdraw still go through the normal Moolah path, but
**borrow and repay run through the broker**, which overlays a richer debt model on top of the raw
Moolah position. The on-chain broker is an ERC1967 proxy (e.g. BNB `0x1Fa2…8b54` → impl `0xb680…58bb`),
verified source `LendingBroker.sol` / `BrokerMath.sol`. Fetcher support lives in
[`lending/public-data/lista/listaBroker.ts`](src/lending/public-data/lista/listaBroker.ts); the composer
encoders live in `contracts-delegation` (`ListaBrokerLending.sol`, `CalldataLib.encodeListaBroker*`).

**Two debt buckets per user.** A brokered market has **no flexible/variable borrowing** at the
Moolah layer — instead each user holds:

- **N fixed-term positions** — each a `{posId, principal, apr, start, end, …}` tranche with a *locked*
  APR and a maturity. Identified by `posId`.
- **One dynamic position** — a variable-rate position, the catch-all bucket. Targeted on repay by the
  sentinel `posId == type(uint128).max` (`LISTA_BROKER_DYNAMIC_POS`).

`broker.getUserTotalDebt(user)` is the authoritative total (fixed + dynamic + all interest).

#### Borrow

The composer calls `borrow(amount, termId, user, receiver)`. `user` (the position owner) is **always
the authenticated caller** and must have authorized the composer in Moolah (`setAuthorization`) — debt
can never be opened against someone else. The broker borrows from Moolah and forwards the loan token to
`receiver`.

> **Native:** the broker *can* unwrap WBNB→BNB, but only on its EOA-direct `borrow(amount)` /
> `borrow(amount, termId)` overloads that pay `msg.sender`. The `receiver`-variant the composer must use
> (Moolah requires `receiver == broker` when a broker is registered) **always sends ERC20 WBNB, never
> native**. To deliver native BNB, chain an unwrap step after the borrow.

#### Repay

`encodeListaBrokerRepay(loanToken, assets, native, broker, posId, onBehalf)` →
`repay(amount, posId, onBehalf)` (fixed) or `repay(amount, onBehalf)` (dynamic, sentinel `posId`).

- **Interest-first, then principal.**
- **`onBehalf`** is taken straight from calldata (exactly like Morpho's repay `onBehalfOf`) — repaying
  only ever pays debt down and refunds excess to the composer, so **repay-on-behalf is permissionless**.
  Must be non-zero (broker reverts `ZeroAddress`); there is no caller fallback.
- **`assets == 0`** repays the composer's full balance (`balanceOf` / `selfbalance`); the broker refunds
  any excess. The clean "close it out" pattern: over-fund slightly, repay with `assets == 0`, take the dust.
- **Native:** both repay overloads are `payable` and wrap `msg.value` internally (gated on
  `LOAN_TOKEN == WBNB`, else `NativeNotSupported`). The composer's native path forwards the value and
  skips the ERC20 approve. Excess refunds as native BNB to the composer (un-swept on explicit amounts).

#### Early-repayment penalty

Repaying a fixed position's **principal before `end`** incurs a penalty
(`BrokerMath.getPenaltyForFixedPosition`):

```
penalty = ceil( ceil(repayPrincipal × aprPerSecond / RATE_SCALE) × timeLeft / 2 )
```

≈ **half the interest that principal would still accrue over the remaining term**. It's skimmed off the
principal payment and supplied to the Moolah vault as revenue, so it is **additive** — on top of
`outstanding + accruedInterest`. Penalty is **0 once matured** (`block.timestamp > end`). The fetcher
surfaces it per loan as `earlyRepayPenalty` (computed for the *full outstanding principal*; scale linearly
for partials). Use the broker's `previewRepayFixedLoanPosition(user, amount, posId)` for the exact
`(interest, penalty, principal)` split.

#### Maturity & refinancing

A fixed position's **interest freezes at `end`** (`getAccruedInterestForFixedPosition` caps at
`position.end`); after maturity it accrues no further fixed interest and carries no penalty.

`refinanceMaturedFixedPositions(user, posIds)` is a **bot-only** function (`onlyRole(BOT)`) — users and
the composer **cannot** call it, so it is **not** exposed as an SDK/composer op. It migrates matured fixed
positions into the dynamic bucket: net principal + frozen interest are normalized at the current dynamic
rate and added to the dynamic position, and the fixed position is **deleted**. The window between maturity
and the bot's call is interest-free (the protocol absorbs it).

#### Repaying late

| When | Target | Cost |
|------|--------|------|
| Before `end` | fixed `posId` | principal + accrued interest + **early penalty** |
| After `end`, before bot refinances | fixed `posId` | principal + **frozen** interest, **no penalty** — cheapest |
| After bot refinances | **dynamic** sentinel | principal + interest captured at refinance + **dynamic-rate interest since** |

> **Refinance is a race.** A repay targeting a matured `posId` **reverts** (`position not found`) if the
> bot refinances first; fall back to the dynamic repay. The matured-but-not-yet-refinanced window
> (`isMatured: true`, `earlyRepayPenalty: '0'`) is the cheapest time to repay.

#### Data shape

Brokered markets emit **no variable debt** — the position's `debt` is `0`, the authoritative total sits in
`debtStable`, and each fixed loan is itemized in a `terms[]` array (`ListaTermLoan`):

| Field | Description |
|-------|-------------|
| `loanId` | `posId` — the repay target for the `LISTA_BROKER_REPAY` composer op |
| `debt` | outstanding (principal + accrued interest), loan-token units |
| `aprFraction` | locked fixed APR as a fraction |
| `maturity` / `termDays` | unix maturity timestamp / term length |
| `accruedInterest` | outstanding accrued interest |
| `earlyRepayPenalty` | penalty to close the loan now; `0` once matured |
| `isMatured` | `now >= end` |

> **Note:** `terms[]` currently itemizes only fixed loans. The dynamic position (post-refinance) is
> included in the `debtStable` total but not yet surfaced as its own repayable term.

## Morpho Midnight extension

Morpho Midnight is a Base-only, **fixed-rate / fixed-maturity** lending protocol built on an
**order book of off-chain signed offers** (zero-coupon credit/debt units) — it is **NOT a Morpho
Blue fork**, so it is modeled as its own `'midnight'` provider (`Lender.MORPHO_MIDNIGHT`,
`isMidnight`), not `isMorphoType`. There is no pool and no utilization curve: rates are derived
from each offer's `tick` → price and its time-to-maturity, knowable only via the API. Each
maturity is its own isolated market, keyed `MORPHO_MIDNIGHT_<marketId>`.

### API-first fetching

Unlike Morpho Blue's GraphQL-then-on-chain hybrid, Midnight public data is **API-only** — there
is no on-chain public fallback in `fetchLenderAll`. The fetcher lives in
[`lending/public-data/midnight/`](src/lending/public-data/midnight/):

- **`apiClient` / `fetchPublic`** — an `ApiBookSource` reads the order book per market
  (`GET /books/{id}`) from the Midnight API. The base URL resolves override → config → hosted
  default (`https://api.morpho.org/v0/midnight`); the worker can point it at a dev API via
  `MIDNIGHT_API_BASE` (see `data-sdk` `setMidnightApiBase`).
- **`math.ts`** — ported `TickLib` (`tickToApr` etc.), bit-verified against `@morpho-org/midnight-sdk`.
- **`convertPublic`** — normalizes the book into a `MorphoGeneralPublicResponse` keyed by
  `MORPHO_MIDNIGHT_<id>`, emitting the fixed borrow/supply APR and a single-term
  `params.market.terms[]` (`{termId, durationSecs, durationDays, apr}`) carrying the maturity — so
  the maturity flows through the same generic `terms[]` path as Lista's fixed loans. Units are in
  the **loan token's decimals** (not 18): `assets = units × price / WAD`, so `units ≈ assets`.

User positions (`{credit, debt, collateral[128], collateralBitmap}`) are read via multicall in
[`lending/user-data/midnight/`](src/lending/user-data/midnight/), one `UserData` per market.

> **Scope:** the fetcher and direct spot actions (supply collateral / borrow-via-`take` / repay /
> withdraw) are wired. Composer-routed leverage and native ETH are deferred — see
> [`calldata-sdk/src/evm/generic/midnight/COMPOSER_PLAN.md`](../calldata-sdk/src/evm/generic/midnight/COMPOSER_PLAN.md).
