@1delta/margin-fetcher 5.0.17 → 5.0.19

package/README.md

@@ -1,26 +1,33 @@
 # @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.
+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:
+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) |
+| 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.
+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:
+Morpho uses an **adaptive curve IRM** that adjusts rates based on utilization
+relative to a 90% target:
 
 ```
 utilization = totalBorrowAssets / totalSupplyAssets
@@ -32,9 +39,12 @@ 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.
+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
@@ -43,7 +53,8 @@ Key constants:
 
 ### Share-based accounting
 
-Positions are tracked via **shares** rather than raw assets. This allows interest to accrue without storage updates per-user:
+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)
@@ -67,13 +78,17 @@ Each Morpho market produces **two entries** in the normalized output:
 
 ### 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.
+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:
+The fetcher uses a **hybrid approach** that routes each lender to either an API
+or on-chain path:
 
 ```
 getLenderPublicDataAll(chainId, lenders, ...)
@@ -83,7 +98,8 @@ getLenderPublicDataAll(chainId, lenders, ...)
 └── 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).
+**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)
 
@@ -97,7 +113,8 @@ fetchMorphoMarkets(chainId, includeUnlisted)
   → { [marketId]: MorphoGeneralPublicResponse }
 ```
 
-The API provides pre-computed APYs, USD values, and reward data. APY→APR conversion is applied during normalization.
+The API provides pre-computed APYs, USD values, and reward data. APY→APR
+conversion is applied during normalization.
 
 ### On-chain path (Morpho Lens)
 
@@ -184,64 +201,77 @@ src/types/lender/
 
 ## Lista DAO extension
 
-Lista is a Morpho Blue fork with additional per-market fields. Uses a 357-byte binary record instead of 256:
+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 |
+| 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.
+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).
+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
+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.
+> **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`).
+`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).
+- **`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
 
@@ -252,83 +282,101 @@ Repaying a fixed position's **principal before `end`** incurs a penalty
 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
+≈ **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.
+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).
+`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** |
+| 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.
+> **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`):
+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` |
+| 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.
+> **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>`.
+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
+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
+- **`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.md`](../calldata-sdk/src/evm/generic/midnight/COMPOSER.md).