Merge pull request #51 from NyxFoundation/feat/lst-venue

Liquid staking (LST) venue: wstETH-style vault, LST/WETH market, and leverage

Author: adachi-440

.gitignore

@@ -9,6 +9,7 @@ config/*.yaml
 !config/all18-mixed.yaml
 !config/claude-llm.yaml
 !config/vuln-test.yaml
+!config/lst.yaml
 runs/
 cache/
 out/

CLAUDE.md

@@ -44,6 +44,9 @@ validate 失敗はエラー内容を会話に追記して再試行（上限超
 
 run の設定値とエージェントロスターは **`config/local.yaml` 一本**で管理する（env からの設定読取は廃止）。
 解決順は `--config <path>` > `ERIS_CONFIG` > `config/local.yaml` > `config/example.yaml`（committed 雛形 = zero-config 既定）。
+**雛形は `run.localDeploy: true` 既定**（README Quick Start と config/regimes/* に揃えた。fork 用フラグは不要になり
+`npm run sim:realtime` だけで走る）。fork に戻すには `localDeploy: false` + `run.protocols` から `lst` を外す
+（LST の vault は自作で Arbitrum に対応物が無い）+ `ARB_RPC_URL` + 別端末で `npm run anvil`。
 キーは**ネスト lowercase**（`run` / `funding` / `limits` / `flow` / `stress` / `vuln` + `agents`）で
 `sdk/src/runConfig.ts` の `SCHEMA` が内部キーへ写す。ロスターは規約解決（ADR 0015 §6）:
 
@@ -89,6 +92,59 @@ OU の base price はそのまま進め、その上に **SEED 由来でランダ
 - stress run（events かつ `ERIS_RUN_BLOCKS>0`）は**時間制限を自動無効化**しブロック数で終了する（`ERIS_RUN_SECONDS` が先に切れて crash 窓へ到達しない事故を回避。override は `stress_run_time_limit_disabled` で記録）
 - coordinator は `stress_schedule` / `stress_victim_hf` / `stress_liquidation` を events.jsonl へ emit する。liquidator agent には victim アドレスを `ERIS_LIQUIDATION_VICTIMS` で配布する。清算の帰属は agent ログの `liquidationCall`(rawTx) を一次情報にする（events.jsonl を直接読んで解析する。旧 stress-report ツールは撤去済み）
 
+### LST venue（wstETH 風 vault + LST/WETH 二次市場。issue #38 Phase 1。既定 off・**ローカルデプロイ専用**）
+
+利回りで償還レートが上がる非 rebasing の LST（`deployer/contracts/MockLSTVault.sol`）と、その二次市場
+（既存 stableswap-ng factory 上の LST/WETH plain pool）。**同じ資産に価格が 2 つある**のが本質:
+`redemptionRateWeth`（vault が負う par。ただし出金キュー `withdrawalDelayBlocks` 待ち）と
+`marketPriceWeth`（プールが今払う額。discount 付き）。observation は両方 + `discountBps` /
+`yieldPerBlockBps` / キュー長 / 自分サイズでの `instantExitWethWei` / pending を別々に出す。
+
+- **Arbitrum に対応物が無い**（vault は自作）ので fork では使えない。`run.protocols` に `lst` を入れて
+  ローカルデプロイでないと起動時 fail-fast。**`config/example.yaml` の既定ロスターに入っている**
+  （`cd deployer && npm run deploy -- --keep-fresh` → `npm run gen:local-constants` → `npm run sim:realtime`）。
+  LST 単独で見たいときは競合参加者と較正ノブを明示した `config/lst.yaml`
+- **利回りは EVM 時間でなく経済クロック**（`lst.simulatedSecondsPerBlock` / `lst.apyBps`。既定 1 block=1h・3%/yr
+  = Aave WETH supply と同オーダー。速すぎると他 venue が無意味になる）。原資は事前投入 reward reserve に上限され、
+  `accrueRewards()` は permissionless（額はブロック数の純関数なので誰が叩いても同じ）。coordinator は毎ブロック
+  oracle tx と**同じ admin nonce の直列**で叩く（並列にすると nonce 衝突でレートが凍る）
+- **プールの rate oracle 配線が要**（`stEthPerToken()` を asset_type=1 で登録）。未配線だとレート上昇が全員に開かれた
+  無リスク裁定になる（ADR 0007 を毀損）。deploy 時 assert + 起動時 `lst_setup` で乖離 200bps 超は fail-fast
+- **採点は realizable**（`sdk/src/protocols/lst.ts` `realizableWethWei`）: shares は「今プールで売った額」と
+  「run 終了までに finalize するキューの par」の**良い方**。run 終了後にしか claim できない pending は価値から外し
+  `reason:"unrealizable"` で `scoring_unpriced_holdings` に報告する（黙って 0 にしない）。#41 の staged-read
+  インターフェース（`valueAtBlock` / `liquidatableValueUsdc` / `ValuationContext.horizonBlock`）の最初の消費者
+- **Phase 2（選択を非自明にする）実装済み**。`config/lst.yaml` の `lst:` / `stress:` に較正例:
+  - **APY 変動** — `lst.apyRangeBps` + `apyStepBlocks` で seed 由来 Rng（独立 salt）から N ブロックごとに再サンプル
+    → coordinator が `setRewardRate`。固定利回りだと「block 0 で全ステーク」が恒久最適になるため
+  - **キュー混雑 + サイズ依存** — vault の finalize をスループット律速に（`queueThroughputWeiPerBlock`）。
+    `claimableAt = max(floor, queueDrainBlock) + ceil(assets/throughput)` = 大口ほど待ち、先客がいるほど待つ。
+    観測は実効待ちを `estimatedQueueDelayBlocks`（自分の全保有）と `queueDelayPerWethBlocks`（限界 1 WETH）で分けて出す。
+    **採点も実効待ちを使う**（floor で判定すると完了不能な exit を par 評価してしまう）
+  - **`lstSlash`** — ADR 0009 と同じレンジ config で `stress.events` に書ける点イベント。1 ブロックで rate を恒久的に下げる。
+    **discount は開かない**（プールが rate oracle 追随でリプライスする＝oracle が正しく効いている証拠）。
+    slash は「保有者が損をする」リスクであって裁定機会ではない。よって magnitude は利回りスケールで較正する
+    （70 ブロック run の利回り ~3-8bps に対し 10-30bps。最初に試した 100-300bps は利回りの 15 倍でステーク自体が常に負けになった）
+- **Phase 3（レバレッジ）実装済み**。`run.protocols` に `aave` を足すと有効:
+  - deployer が LST を **Aave の担保専用 reserve** として登録（`registerLstReserve`。LTV 70% / LT 75% /
+    bonus 7.5%。**borrow は無効**＝現実の LST 上場と同じで、狙いは「LST を担保に ETH を借りる」レバステーキング）。
+    Aave 自身の同名 reserve から clone できないため **LTV/LT は明示指定**（issue #38 が指摘した通り）。
+    rate strategy のみ WETH から借用
+  - **価格は WETH × 償還レート**。専用 MockAggregator を持ち、`sdk/src/protocols/oracles.ts` が
+    他の全オラクルと同じ 3 経路（mined / mempool / storage）で毎ブロック書く。よって **1 ブロック遅れ**を継承し、
+    slash はまず vault に効き、次ブロックで HF に届く = liquidation cascade の起点
+  - `aaveSupply`/`aaveWithdraw` の asset に `"LST"` を指定可能（`TokenKind` に `"lst"` を追加し、
+    scorer の spot 掃引から外して二重計上を防いでいる。評価は Aave の totalCollateralBase 経由）
+  - `lst-carry` は **`ERIS_LST_LEVERAGE_TARGET_HF` で opt-in**（既定 0=off）。ループは
+    stake→collateralize→borrow→stake で、目標 HF に**着地する**サイズだけ借りる（headroom 基準で借りると
+    目標も下限も突き抜けて borrow/repay が振動する: 実測 24/22 → 2/0）。HF が下限を割ったら他の何より先に返済。
+    prompt 版は spot に専念（LLM に env の opt-in は効かないため、手を出さないよう明記）
+  - 市場側の検証は `test/lstLeverage.test.ts`（要 `ERIS_LOCAL_DEPLOY=1` + ローカルデプロイ。実チェーンで
+    listing → ETH 借入 → slash 後も HF 不変(=oracle lag) → oracle 更新で HF 低下 を検査。CI では skip）
+- **USDC 建て採点では LST 保有戦略は構造的に β で不利**（実測: noop 0 > lst-carry −203 > lst-carry-wide −233、
+  一方で WETH を持たない venue-arb は +115）。alphaUsdc は free inventory の β しか除去せず、
+  LST ポジションは live mark のため。ETH 建て採点（DAT 型）が issue #38 の motivation で follow-on
+
 実時間化（ADR 0005）の前提: **SEED(=regime) は市場条件のラベル**で価格パスは再現可能だが、tx タイミング/着順は非決定 → 同一 regime でも結果はぶれる。run 長は `ERIS_RUN_BLOCKS` 固定で揃える。run の比較が要るときは同一 config を複数回回してサンプルを貯め、`runs/<id>/summary.json` を集計する（旧 evaluate/gate は撤去済み）。
 
 ## アーキテクチャ（環境とエージェント実行の分離。ADR 0006 / ADR 0015）

README.md

@@ -41,7 +41,7 @@ flowchart LR
 
 ## What is this
 
-- **Multi-protocol DeFi environment** — Uniswap V3 / Balancer v2 / Curve / Aave v3 / GMX v2 are all provisioned on a single Anvil, and enabled pluggably through the protocol adapter registry (`sdk/src/protocols/`).
+- **Multi-protocol DeFi environment** — Uniswap V3 / Balancer v2 / Curve / Aave v3 / GMX v2, plus a liquid-staking venue (a wstETH-style vault and its LST/WETH market), are all provisioned on a single Anvil and enabled pluggably through the protocol adapter registry (`sdk/src/protocols/`).
 - **Multi-agent competition** — agents run as fully independent processes, subscribe to blocks at their own pace, and sign and send directly themselves. In-block ordering is determined by anvil `--order fees` (descending priority fee).
 - **Controllable fair price** — the coordinator generates a SEED-derived deterministic fair price every block and writes it to the on-chain `PriceFeed` and mock oracles. Aave health factors and GMX mark prices follow it.
 - **Market stress & liquidation** — price spikes/crashes can be injected to trigger the Aave liquidation path.
@@ -93,15 +93,17 @@ To skip LLMs entirely and run the same strategies rule-based (`agent.ts`), remov
 # Separate terminal: start anvil + deploy all venues via deployer (do not pass --exit)
 cd deployer && npm run deploy -- --keep-fresh
 
-# poc side (repository root): import the deploy addresses and run in local deploy mode
+# poc side (repository root): import the deploy addresses and run
 npm run gen:local-constants
-npm run sim:realtime -- --local-deploy \
-  --seed 1 --blocks 100 --seconds 300 --protocols uniswap,balancer,curve
-# The roster is the inline agents in config/local.yaml (edit the YAML to swap it out.
-# backtest supports swapping via --agents <roster.yaml>)
+npm run sim:realtime
+# The roster and every run knob come from config/local.yaml (edit the YAML to swap them out;
+# backtest supports swapping the roster via --agents <roster.yaml>). One-off overrides are CLI
+# flags: npm run sim:realtime -- --seed 2 --blocks 40
 ```
 
-> The `--local-deploy` flag (or config `run.localDeploy: true`) switches to local deploy mode. The CLI entry point detects this at startup, sets `ERIS_LOCAL_DEPLOY=1` internally, and `sdk/src/constants.ts` overlays the locally-deployed addresses (WETH/USDC/WBTC, etc.) — no need to pass the env by hand.
+> `config/example.yaml` ships with `run.localDeploy: true`, so no flag is needed. The CLI entry point detects it at startup, sets `ERIS_LOCAL_DEPLOY=1` internally, and `sdk/src/constants.ts` overlays the locally-deployed addresses (WETH/USDC/WBTC, etc.) — no need to pass the env by hand. `--local-deploy` still works as a one-off override for a config that does not set it.
+
+> To run against an Arbitrum fork instead, set `run.localDeploy: false` in `config/local.yaml`, remove `lst` from `run.protocols` (its vault is deployed by us and has no Arbitrum counterpart), put `ARB_RPC_URL` in `.env.local`, and start `npm run anvil` in another terminal.
 
 > LLM decisions take ~10s each, hence the 100-block / 300s run above (rule-based runs are fine with 24 blocks / 70s). If the trading agents only emit `noop`, you probably skipped [Choose an LLM backend](#choose-an-llm-backend) — check `runs/<run_id>/agents/<id>.jsonl` for `llm cycle skipped`.
 

config/example.yaml

@@ -12,6 +12,13 @@
 # `.env.local` (ARB_RPC_URL / *_PRIVATE_KEY / ANTHROPIC_API_KEY / OLLAMA_API_KEY).
 # The local Anvil dev keys are used by default even when unspecified.
 #
+# Local deploy by default (run.localDeploy: true), matching the README Quick Start and the official
+# backtest regimes: every venue is deployed onto a bare anvil by the bundled deployer/, so no fork
+# RPC is involved. Start it with `cd deployer && npm run deploy -- --keep-fresh`, then
+# `npm run gen:local-constants` to import the addresses. To run against an Arbitrum fork instead,
+# set localDeploy: false, drop `lst` from run.protocols (its vault has no Arbitrum counterpart) and
+# start `npm run anvil` in another terminal with ARB_RPC_URL set.
+#
 # LLM-driven by default: the trading agents below run in prompt mode (prompt.md, one LLM call per
 # decision; ERIS_AGENT_MODE: "prompt") and need an LLM backend. Pick one:
 #   - Ollama Cloud (default; model gpt-oss:120b): set OLLAMA_API_KEY in `.env.local`
@@ -29,13 +36,20 @@ run:
   blocks: 100
   seconds: 300
   blockTimeSec: 2
-  protocols: [uniswap, balancer, curve]
+  # gmx and aave are left out because they are the slow half of the deploy; add them once
+  # `deployer` has run with them. `lst` is local-only (issue #38) and fails fast on a fork.
+  protocols: [uniswap, balancer, curve, lst]
   economicGas: false
-  localDeploy: false
+  localDeploy: true
   reportDir: ./runs
 
 funding:
-  wethWei: "0" # USDC-only distribution (removes initial directional exposure)
+  # WETH is handed out because the LST venue is WETH-denominated and cannot be traded without it.
+  # That reintroduces price drift (beta) into netPnlUsdc, which is fine for a template you run to
+  # see the thing work — read alphaUsdc for skill. The official regimes under config/regimes/ stay
+  # USDC-only (wethWei: "0") so evaluation runs keep their clean alpha; drop this to "0" too if you
+  # are measuring rather than exploring, and take `lst` out of run.protocols with it.
+  wethWei: "20000000000000000000" # 20 WETH
   usdcUnits: "25000000000"
   # base: { WBTC: "0" }   # initial inventory of additional bases (default 0)
 
@@ -103,3 +117,10 @@ agents:
     description: base-agnostic cross-venue arbitrage (all active bases x all venues; LLM-driven via prompt.md)
     env: { ERIS_AGENT_MODE: "prompt", ERIS_PROMPT_LOG_CALLS: "1" }
     # env: { ERIS_AGENT_MODE: "prompt", ERIS_PROMPT_LOG_CALLS: "1", ERIS_LLM_MODEL: "claude-cli:haiku" }
+  - id: lst-carry
+    wallet: AGENT4_PRIVATE_KEY
+    description: liquid staking — stake for yield, or trade the LST redemption/market gap (LLM-driven via prompt.md)
+    env: { ERIS_AGENT_MODE: "prompt", ERIS_PROMPT_LOG_CALLS: "1" }
+    # env: { ERIS_AGENT_MODE: "prompt", ERIS_PROMPT_LOG_CALLS: "1", ERIS_LLM_MODEL: "claude-cli:haiku" }
+  # config/lst.yaml is the same venue with a second competing participant and the calibration knobs
+  # spelled out, if you want to look at the LST market on its own.