leverage

Spiral Stake — mcp 読み取りデータ基盤（Step 1a）

Spiral Stake の戦略データに対する構成権限と読み取り APIです。アプリのクライアント側データ構成をサーバー側に移植し、JSON として返すことで、3 つの利用者が 1 つのコアを使えるようにします。

1. アプリ — 現在取得している完全な読み取りサーフェスです。Step 2 で同等の置き換えを行います。
2. エージェント — 凍結された /strategies コントラクトです。
3. パートナー（後日） — 明確で、バージョン管理され、自己記述的な REST サーフェス（OpenAPI）です。

読み取り専用です。 コントラクトへの書き込み、トランザクションの構築、署名、秘密鍵の取り扱いはありません。数値を構成して 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 を返します
スワップ／メタ DEX アグリゲーター、紹介、ポジション	対象外（実行／バックエンドのドメイン）

共通機能：/v1 によるバージョン管理、CORS_ORIGINS に限定した CORS、一貫したエラー形式（{ 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）は同一です。
• オンチェーンの読み取りには wagmi ではなく viem を使用します：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 に書き込まれます。このファイルの更新日時が exitLiquidity.asOf になります。唯一の判定であるティアは閾値とともに spiralHints に格納し、未加工の slippagePct は exitLiquidity に保持します。ルートがない場合の null も維持します。