leverage

Spiral Stake — mcp 只读数据骨干（第 1a 步）

Spiral Stake 策略数据的组合权威层 + 读取 API。它将应用的客户端数据组合逻辑迁移到服务端，并以 JSON 形式返回，让三类使用方共用一个核心：

1. 应用 — 提供它当前获取的完整读取接口，便于第 2 步进行一对一替换。
2. Agent — 冻结的 /strategies contract。
3. 合作伙伴（后续） — 简洁、版本化、自描述的 REST 接口（OpenAPI）。

只读。不写入 contract，不构建交易，不签名，不处理私钥。它只组合数据并提供 JSON。MCP 工具层、执行/build_* 和合作伙伴身份验证属于后续步骤——接口边界已预留（core + http），但尚未构建。

---

架构

src/
  core/        pure composition — no I/O, unit-testable
    leverage.ts        ← VERBATIM copy of v2-client/src/utils/leverage.ts (byte-diff gated)
    apy.ts             collateral-APY resolution (Pendle/DeFiLlama/Royco/StableWatch/on-chain)
    leverageApy.ts     30/60/90d leveraged-APY windows + lumpy-token smoothing
    compose.ts         Market assembly from warm raw (port of FlashLeverage.createInstance)
    strategy.ts        Market → frozen /strategies contract (ladder, freshness, spiralHints)
    exitLiquidity.ts   exit-liquidity tier (the single verdict) + thresholds
  sources/     one adapter per upstream (fetch + parse). native fetch + viem; no axios/wagmi
  cache/       two-layer cache — RAW store (last-good) + warming policy (CONTRACT cadences)
  warmer/      background scheduler (stale-while-revalidate); reads NEVER fetch
  http/        thin hono REST layer (the only thing that knows about requests)
  data/        static market config (copied from the app) + readMarkets port
  config/      env (validated) + structured logger with correlation ids

数据流：warmer 按照 CONTRACT 规定的频率获取上游数据 → 将原始数据写入缓存（失败时保留最近一次成功数据）→ core 仅基于已预热的原始数据组合策略 → http 提供这些数据。 上游数据过期或获取失败时，会按字段组提供最近一次成功数据，并明确显示其过期时长——绝不丢弃，也绝不强制转换为 0。

---

运行

cp .env.example .env      # fill in RPC + API keys (secrets via env only)
npm install
npm run dev               # tsx watch; serves on :$PORT (default 8787)
npm test                  # golden + parity gates
npm run typecheck         # tsc --noEmit
npm run openapi           # (re)emit openapi.json
node --import tsx scripts/smoke.ts   # live: prime + print one composed strategy

启动后即可访问 /health（存活状态 + 缓存诊断）和 /ready（在 warmer 预热所需数据前返回 503）。

---

端点 — 应用读取清单 → 端点映射

应用在 v2-client/src/api-services/* 中执行的每项数据读取，都映射到此处的一个端点（持仓仍由仪表盘后端提供，不在此处重新实现）：

应用读取（api-services/*）	mcp 端点
getTokenApy、getAllMorphoMarketsData、fetchMerklSpotIncentives、价格、链上价值 → 组合后的市场	GET /v1/strategies、GET /v1/strategies/:id
FlashLeverage.createInstance → 应用完整的客户端 Market[] 组合	GET /v1/app/markets（原始领域模型；BigNumber→{"$bn":…}，bigint→{"$bigint":…} — 使用前需还原）
morpho.ts getAllBorrowApyHistories / getBorrowApyHistory	GET /v1/markets/borrow-apy-history、GET /v1/markets/:id/borrow-apy-history
apy.ts resolveTokenApyHistory（DeFiLlama/Royco/StableWatch 历史数据）、chart.ts getApyChart	GET /v1/collateral/apy-history、GET /v1/collateral/:id/apy-history
merkl.ts fetchMerklIncentiveData（借款激励 APR 历史数据）	GET /v1/markets/:id/incentive-history
token.ts getAllLoanTokenPrices / getTokenPrice	GET /v1/prices
chart.ts getMarketChart（CoinGecko 价格图表）	GET /v1/prices/chart?coinId=&days=&currency=（按需代理）
chart.ts getDexOhlcv（对于没有 CoinGecko/TradingView 图表的代币，获取 DEX 价格图表，例如 Robinhood 上的 CASHCAT/PONS）	GET /v1/prices/ohlcv?chainId=&token=&timeframe=&aggregate=&limit=（按需代理 GeckoTerminal，缓存 30 秒，失败时保留最近一次成功数据；COINGECKO_PRO_API_KEY 可提高速率限制）
dashboard.ts getApySnapshot（StableWatch 稳定 APY）	GET /v1/stable-apy — 直接从 StableWatch 获取，作为已预热的上游数据；现在 mcp 拥有此数据，不再依赖仪表盘 /apy 端点
—（协议级数据，并非应用读取）	GET /v1/tvl — 所有受支持链上的协议 TVL，每 5 分钟根据链上持仓预热：tvlUsd = 用户净权益（抵押品 − 债务，即 DefiLlama TVL），grossTvlUsd = 循环借贷抵押品总额，borrowedUsd = 债务总额，另含 positions/users；在计算完首条链之前返回 503
swap/meta-dex 聚合器、推荐、持仓	不在范围内（执行 / 后端领域）

跨领域能力：/v1 版本控制、将 CORS 限制为 CORS_ORIGINS、统一的错误封装（{ error: { code, message, correlationId } }）、每个请求都有一个关联 ID（通过 x-correlation-id 回传）、结构化 JSON 日志，以及位于 /openapi.json 的 OpenAPI 3.1 规范（另有已提交的 openapi.json）。

---

对齐门槛

1. leverage.ts 黄金向量测试——test/golden/leverage.golden.test.ts 固定输入 → 精确输出；leverage.parity.test.ts 断言该文件与应用的 leverage.ts 逐字节相同。这会将每个 APY/LTV/阶梯数值锁定为与应用一致。
2. /strategies 组合——test/parity/strategies.compose.test.ts 使用受控夹具填充原始缓存，并逐字段断言组合后的契约（数据来源、LTV 计算、通过原样使用的 leverage.ts 计算的阶梯、新鲜度周期、null 与字段缺失的区别、spiralHints 隔离）。在 CI 中离线运行。
3. 实时黄金集 + 应用表面一致性——scripts/capture-parity.ts 让预热器连接真实上游数据源，并将固定市场集的组合后 /strategies（以及 APY/借款历史）写入 test/fixtures/。与应用的对齐差异通过将相同的固定输入传入应用的客户端组合逻辑并进行比较来生成（应用会记录其组合后的市场）；PR 提交这些夹具以及空差异。这道门槛让我们能安全地卸载 TVL。

---

已冻结的决策（对齐关键项）

• bignumber.js 固定为与应用相同的 9.3.1；不更改全局 BigNumber.config → toFixed(2) / 舍入（ROUND_HALF_UP）保持一致。
• 使用 viem 替代 wagmi 进行链上读取：getCollateralValueInLoanToken（multicall3）、stUSDS str()、spUSDG vsr()（链 4663）。与应用完全一致地保留其对 JSON 数字执行的（有意损失精度的）BigInt(liqLtv)，不做“修正”。
• maxLeverage = calcLeverage(maxLtv)；defaultLeverage = calcLeverage(safeLtv)， safeLtv = maxLtv% − 0.75——与应用推导方式完全一致。阶梯为整数步长 1x … ⌊maxLeverage⌋（LTV =(1 − 1/lev)·100），然后是精确的 max。
• 退出滑点由应用的每周刷新脚本写入 collateralTokens.json；该文件的 mtime 即为 exitLiquidity.asOf。等级（唯一的判定结果）及其阈值位于 spiralHints 中；原始 slippagePct 保留在 exitLiquidity 下，无路线时保留 null。