# @1delta/margin-fetcher 中文文档

规范地址：https://npmcn.com/package/%401delta/margin-fetcher/

版本：5\.0\.152
npm 元数据更新时间：2026-11-06T11:16:03.356Z
中文译文更新时间：2026-11-06T02:13:25.605Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%401delta/margin-fetcher
原文对照：https://npmcn.com/package/%401delta/margin-fetcher/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：16.1 MB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2025-07-08T13:52:52.358Z
- 最新版本发布：2026-11-06T11:16:03.141Z
- 近 30 天下载量：6611（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：471（近 12 个月 369 个）

## 中文简介

多protocol出借数据采集器支持Morpho Blue,Aave V2/V3,化合物V2/V3,Euler,Init,Lista DAO,和Morpho Midnight. 在一个统一的f中提供公共市场数据(率、TVL、配置)和每个用户的位置数据(余额、股份、抵押品)

## 安装

```sh
npm install @1delta/margin-fetcher
```

也可以使用：`pnpm add @1delta/margin-fetcher`、`yarn add @1delta/margin-fetcher`、`bun add @1delta/margin-fetcher`

## README

# @ 1delta/ 边际- fetcher

多protocol出借数据采集器,支持Morpho Blue, Aave V2/V3, 化合物 V2/V3,欧拉,伊尼特,利斯塔·达奥和莫尔福·米德尼特. 提供公共市场数据 (比率、TVL、配置)和每个用户的位置数据(余额、股份、抵押品) 统一格式.

## Morpho Blue 是如何工作的

### 议定书概览

摩福蓝是一个 **孤立市场** 贷款协议。 不同于集合协议 (ave,化合物),所有资产共用一个池,每个Morpho市场是一个 **独立对** 由五个参数定义:

| 参数 | 说明 |
| --- | --- |
| `loanToken` | 可提供和出借的资产 |
| `collateralToken` | 以抵押形式交存的资产 |
| `oracle` | 配对的价格预告 |
| `irm` | 利率示范合同 |
| `lltv` | 贷款与收入之比(18-十进制) |

这五个参数被散成 `uniqueKey` (字节32),表示 市场链.

### 利率模式

Morpho使用一个 **适应曲线 IRM** 根据利用率调整费率 相对于90%的目标:

```
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)
```

曲线使用4x的陡度因子,表示在充分利用时速为: 4x的速率目标。 速率按每秒WAD值和复合值存储 持续.

密钥常数 :

-   **目标利用**: 90% (单位:千美元)
-   **曲线陡峭度**编号: 4x
-   **目标负率**:~0.1% APY
-   **目标最大比率**: ~200 % APY (韩语)
-   **调整速度**: 50x/年(责任)

### 股份制会计

位置通过 **份额** 而不是原始资产。 允许 不按用户更新存储的利息累积 :

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

何处 `VIRTUAL_SHARES = 1e6` 防止股本通膨.

### 市场数据说明

每个莫福市场生产 **两个条目** 在常态输出中:

1.  **贷款入帐** ——可借款资产
    
    -   有过 `borrowingEnabled: true`, (中文(简体) ), `collateralActive: false`
    -   包括存款/借款
    -   奖励(MORPHO标志性奖励)
2.  **担保项** ——抵押资产
    
    -   有过 `borrowingEnabled: false`, (中文(简体) ), `collateralActive: true`
    -   LTV 市场因素 `lltv`
    -   没有利率(担保在莫尔福没有收益)

### 白名单对未上市市场

恶毒的市场可能是 **白名单** (经检验,可见于Morpho UI)或 **未列出** (从治所除名). 这个 `includeUnlistedMorphoMarkets` 旗帜 控制是否从 API 获取未列出的市场。 未上市的市场是 标记为 `isListed: false` 编辑 `MorphoMarket` 参数.

## 建筑

### 数据获取策略

获取器使用 **混合办法** 引导每个贷款人到一个API 或链上路径 :

```
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 使用 API 软件** 在大多数铁链上。 链回落用于 没有API支持的链(OP Mainnet, Soneium, Hemi, Berachain, Sei).

### API 路径 (GraphQL)

获取从 `https://blue-api.morpho.org/graphql`数字 :

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

API提供预先计算的APY、USD值和奖励数据。 业余活动 在正常化期间实行转换.

### 链上路径( Morpho Lens)

使用自定义的镜头合同,该合同将返回紧凑的二进制编码市场数据:

```
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 }
```

#### 二进制编码(每个市场256字节)

```
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)
```

### 用户数据路径

```
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
```

## 文件结构

```
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 扩展名

Lista是一款有额外的每个市场田地的Morpho Blue分叉. 使用357字节 二进制记录而不是256:

| 额外字段 | 类型 | 说明 |
| --- | --- | --- |
| `minLoan` | 宾特128 | 最低贷款额 |
| `hasWhitelist` | 嘘 | 市场是否有准入控制 |
| `loanProvider` | 地址 | 贷款代号的 Yield 来源 |
| `collateralProvider` | 地址 | 抵押品的 Yield 来源 |
| `broker` | 地址 | 核准的经纪人合同 |

用户数据还包括在余额之前准备的每个市场白名单旗 记录.

### 定期经纪人`LendingBroker`(中文(简体) )

一些Lista市场注册a **`LendingBroker`** 强制性债务方 摩诃叉市场之门户. 抵押品供应/抽水仍无进展 通过正常的摩拉道,但 **借钱还钱,通过经纪人**, (中文(简体) ), 在原始的Moolah位置之上,它覆盖了一个更丰富的债务模式。 这个 链上经纪人是 ERC-1967 代理(例如 BNB) `0x1Fa2…8b54` - 冲动 `0xb680…58bb`),经核实的来源 `LendingBroker.sol` 编号 : `BrokerMath.sol`获取器 生活补助 [`lending/public-data/lista/listaBroker.ts`](https://npmcn.com/package/%401delta/margin-fetcher/src/lending/public-data/lista/listaBroker.ts)· ; 编曲编码器 `contracts-delegation` (单位:千美元)`ListaBrokerLending.sol`, (中文(简体) ), `CalldataLib.encodeListaBroker*`) (中文(简体) ).

**每个用户有两个债务桶.** 一个中介市场 **无弹性/可变 借款** 在Moolah层

-   **N 定期职位** ——每个 `{posId, principal, apr, start, end, …}` 带有 a 的分档 _锁定_ APR和一个成熟。 已确认 `posId`。 。 。 .
-   **一个动态位置** ——可变速率位置,"接通"桶. 目标在于哨兵的还款 `posId == type(uint128).max` (单位:千美元)`LISTA_BROKER_DYNAMIC_POS`) (中文(简体) ).

`broker.getUserTotalDebt(user)` 是权威总计(固定+动态+) (所有利息).

#### 借款

作曲家打电话 `borrow(amount, termId, user, receiver)`。 。 。 . `user` (单位:千美元) 职位拥有者)是 **总是认证的呼叫者** 并且必须获得授权 莫奥拉的作曲家`setAuthorization`——债务永远无法针对 别人 经纪人从Moolah那里借了钱,把贷款抵押给 `receiver`。 。 。 .

> **原生 :** 经纪人 _能够_ 取消WBNB BNB,但只保留其EOA直接 `borrow(amount)` 编号 : `borrow(amount, termId)` 负担过重 `msg.sender`。 。 。 . 这个 `receiver`\- 作曲家必须使用的变种(Moolah需要 `receiver == broker` 当经纪人注册时) **总是发送ERC20 WBNB, 永远不是本地人**提供本地BNB, 连锁在借款后的未包装步骤.

#### 偿还

`encodeListaBrokerRepay(loanToken, assets, native, broker, posId, onBehalf)` → `repay(amount, posId, onBehalf)` (固定)或 `repay(amount, onBehalf)` (动力学, 发送器 `posId`) (中文(简体) ).

-   **先是利息,然后是校长.**
-   **`onBehalf`** 直接取自调用数据( 恰好像 Morpho 的回报) `onBehalfOf`() ——只偿还债务并退还超额 作曲家,这样 **二分之一的回报是无权限的**。必须是非零(经纪人) 返回数 `ZeroAddress`)),没有呼叫者退后.
-   **`assets == 0`** 偿还作曲家的完整余额( e)`balanceOf` 编号 : `selfbalance`);经纪人退还任何超额. 干净的"关闭它" 模式:略微多出资金,用 `assets == 0`,取出尘.
-   **原生 :** 两者的偿还超载都是 `payable` 并包装 `msg.value` 内部 (关于 `LOAN_TOKEN == WBNB`,则 `NativeNotSupported`) (中文(简体) ). 那个作曲家 本地路径向上转发值并跳过 ERC20 批准 。 超额退款作为 原生 BNB 给作曲家(未按明确数量进行洗刷).

#### 提前还款处罚

偿还固定职位 **校长之前 `end`** 罚款 (单位:千美元)`BrokerMath.getPenaltyForFixedPosition`:

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

≈ **其余的本金仍为利息的一半 任期**它从本金上省了下来 供应到Moolah金库 作为收入,所以它是 **添加剂** - 在顶部 `outstanding + accruedInterest`。 。 。 . 惩罚是 **0 已成熟** (单位:千美元)`block.timestamp > end`) (中文(简体) ). 拾取者把它浮出水面 每笔贷款 `earlyRepayPenalty` (对 _全额未付本金_· ; 部分的线性缩放)。 用经纪人的 `previewRepayFixedLoanPosition(user, amount, posId)` 准确的 `(interest, penalty, principal)` 分页.

#### 成熟度和再融资

一个固定位置 **利息冻结时间 `end`** (单位:千美元)`getAccruedInterestForFixedPosition` 上限为 `position.end`; 成熟后它会 累积的利息不再有固定利息,不处罚.

`refinanceMaturedFixedPositions(user, posIds)` 是一个 **只有机器人** 函数 (单位:千美元)`onlyRole(BOT)`)——用户和作曲家 **无法** 调用它,所以它是 **没有** 被曝光为SDK/组合对手. 它将成熟的固定位置迁移到 活性桶:净本金+已冻结利息在当下正常化 动态速率并加入动态位置,固定位置是 **删除**。成熟和机器人呼叫之间的窗口是无息的 (协议吸收它).

#### 迟付

| 何时 | 目标 | 费用 |
| --- | --- | --- |
| 在此之前 `end` | 已固定 `posId` | 本金+应计利息+ **提前处罚** |
| 之后 `end`在机器人再融资之前 | 已固定 `posId` | 特等+ **冻结** 利息, **无处罚** - 最便宜的 |
| 机器人再融资后 | **动态** 发送器 | 本金+再融资所得利息+ **动态利率利息** |

> **再融资是一种种族.** 以成熟者为目标的回报 `posId` **返回数** (单位:千美元)`position not found`如果机器人首先重新融资; 回到动态 报答。 成熟但尚未筹资的窗口(`isMatured: true`, (中文(简体) ), `earlyRepayPenalty: '0'`)是最便宜的报答时间.

#### 数据形状

中间商市场喷出 **无可变债务** - 这个职位是 `debt` 实值 `0`,则 权威总数 `debtStable`,每笔固定贷款按项目分列 `terms[]` 数组( r)`ListaTermLoan`:

| 外地 | 说明 |
| --- | --- |
| `loanId` | `posId` - 偿还目标 `LISTA_BROKER_REPAY` 编曲操作 |
| `debt` | 未偿(主要+应计利息)贷款单位 |
| `aprFraction` | 锁定固定的 APR 分数 |
| `maturity` 编号 : `termDays` | unix 到期时间戳/ 任期长度 |
| `accruedInterest` | 未清应计利息 |
| `earlyRepayPenalty` | 立即关闭贷款; `0` 已到期 |
| `isMatured` | `now >= end` |

> **说明:** `terms[]` 目前只逐项列出固定贷款。 动态位置 (后再融资)列入 `debtStable` 总计但尚未浮出 其可偿还期限.

## 午夜延长时间

Morpho Midnight 只是一个基地, **固定比率/固定成熟度** 借贷协议 建于一个 **链外签名报价单** (零息信贷/债务) (单位) **不是莫福蓝叉**因此它被模拟为自己的 `'midnight'` 提供者(`Lender.MORPHO_MIDNIGHT`, (中文(简体) ), `isMidnight`(没有) `isMorphoType`。没有池和利用率曲线: 从每个报价 `tick` 价格及其时间与成熟度,只能通过 API (英语). 每个成熟度都是自己孤立的市场,按键 `MORPHO_MIDNIGHT_<marketId>`。 。 。 .

### API 第一次获取

与Morpho Blue的GraphQL-then-on-chain杂交不同,午夜公共数据是 **仅限 API** ——无链上公众退缩 `fetchLenderAll`编辑 捡取者住在 [`lending/public-data/midnight/`](https://npmcn.com/package/%401delta/margin-fetcher/src/lending/public-data/midnight/)数字 :

-   **`apiClient` 编号 : `fetchPublic`** - 一个 `ApiBookSource` 读取顺序书 市场`GET /books/{id}`从午夜API。 基础 URL 解析 覆盖 ~ 配置 ~ 主机默认( )`https://api.morpho.org/v0/midnight`; 计 数 工人们可以把它指向dev API通过 `MIDNIGHT_API_BASE` (见 `data-sdk` `setMidnightApiBase`) (中文(简体) ).
-   **`math.ts`** - 移植 `TickLib` (单位:千美元)`tickToApr` )等),比特校验对 `@morpho-org/midnight-sdk`。 。 。 .
-   **`convertPublic`** ——将本作规范化为 `MorphoGeneralPublicResponse` 键 `MORPHO_MIDNIGHT_<id>`,排放固定借款/供应APR和a 单身 `params.market.terms[]` (单位:千美元)`{termId, durationSecs, durationDays, apr}`具有成熟度的——所以 成熟度流经相同的通用 `terms[]` 路径作为 Lista 的固定贷款. 单位在 **贷款代号的小数** (不是18个): `assets = units × price / WAD`这样 `units ≈ assets`。 。 。 .

用户职位(`{credit, debt, collateral[128], collateralBitmap}`改为: 通过多点呼叫 [`lending/user-data/midnight/`](https://npmcn.com/package/%401delta/margin-fetcher/src/lending/user-data/midnight/),一个 `UserData` 每个市场.

> **范围:** 获取者和直接现场行动(供应担保/ 借过`take` /还/取)有线. 由作曲者引导的杠杆和 推迟原生乙型六氯环己烷——见 [`calldata-sdk/src/generic/midnight/COMPOSER.md`](https://npmcn.com/package/%401delta/calldata-sdk/src/generic/midnight/COMPOSER.md)。 。 。 .

## 常见问题

### @1delta/margin-fetcher 是什么？

多protocol出借数据采集器支持Morpho Blue,Aave V2/V3,化合物V2/V3,Euler,Init,Lista DAO,和Morpho Midnight\. 在一个统一的f中提供公共市场数据\(率、TVL、配置\)和每个用户的位置数据\(余额、股份、抵押品\)

### 如何安装 @1delta/margin-fetcher？

在项目目录运行 npm install @1delta/margin-fetcher，或使用 pnpm add / yarn add / bun add。

### @1delta/margin-fetcher 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @1delta/margin-fetcher 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @1delta/margin-fetcher 可以商用吗？

@1delta/margin-fetcher 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @1delta/margin-fetcher 的下载量有多少？

根据 npm 官方下载统计，@1delta/margin-fetcher 在 2026/10/05 – 2026/11/03 这 30 天内被下载 6,611 次，日均约 220 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @1delta/margin-fetcher 还在维护吗？

最新版本 5\.0\.152 发布于 2026/11/06（今天）；至今共发布 471 个版本，其中过去 12 个月发布了 369 个；首次发布于 2025/07/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。