feat(vault-v2-reallocation): migrate vault v2 reallocation bot

[haydenshively]

Stacked on #165. Migrates the standalone vault-v2-reallocation-bot into the monorepo as bots/vault-v2-reallocation, the sibling of bots/vault-v1-reallocation, on the same flat bots-as-programs shape and @repo/bot-kit runtime.

What's here

• GraphQL dropped for RPC, block-pinned: vault state comes from blue-sdk's fetchAccrualVaultV2 (factory-validated — a free per-tick V2 identity check) plus per-id absoluteCap/relativeCap/allocation reads the SDK fetcher doesn't cover for regular adapters. The old bot's graphql-request + codegen SDK + .gql files and its checked-in 1754-line ABI are gone; zero new external dependencies (blue-sdk 6.5.0 was already pinned for the V1 bot).
• Both strategies ported (equalize-utilizations — the default, what prod ran — and apy-range) as config-injected closures emitting exact-amount deltas; idle is first-class (denominator folding / idle top-up), executed as ONE vault.multicall([deallocate…, allocate…]).
• One shared-package change (first commit): a declarative Policy.multicall { innerSelectors, innerTargetsByOuter } field — evaluatePolicy itself decodes the bundle and requires every inner call to be allocate/deallocate to the adapter registered for the targeted vault. No bot-supplied code runs inside the guard, so the outer-envelope trust boundary is unchanged (hence no TIB; this is the V2 analogue of feat(vault-v1-reallocation): migrate vault v1 reallocation bot #165's target-list widening). Tested incl. smuggled-selector, cross-vault-adapter, empty-bundle, and malformed-bytes denials.
• All three cap levels enforced in sizing (upgrade over the old bot, which ignored adapter/collateral caps): per-market cap headroom plus shared adapter-level and per-collateral pools, all measured against the on-chain allocation(id) the contract enforces — NOT accrued position assets, which drift above it (visible in live data: allocation 120000000000 vs accrued 120001419437 on Hyperithm Apex). A binding aggregate cap shrinks the plan instead of looping sim-reverts.
• Both adapter generations supported: every live VaultV2 uses the MorphoMarketV1AdapterV2 contract, not the original adapter the old bot's code nominally modeled — vault-data.ts normalizes both SDK shapes (identical calldata + cap ids). Fail-loud typed error unless a vault has exactly one Morpho Blue market adapter.
• Same runtime/safety surface as the V1 bot: signer policy pinned to whitelist+multicall, pending queue, per-tick allocator re-check with auto-resume, DRY_RUN ramp-up (compose/Railway default new services to it), balance/heartbeat monitors, wide tick.end counters, operator surface + CI wiring (vault-v2-realloc in deploy-bot/staging/production + CalVer release job).

⚠️ Found during verification: the old bot's prod whitelist is broken

All three whitelisted addresses in the old repo's production config (mainnet 0xBEEF0173…, 0x8eB67A50…; base 0xbeeF010f…) are MetaMorpho V1 vaults, not VaultV2s (verified on-chain: withdrawQueueLength answers, adaptersLength reverts, the V2 factory disowns them) — the old V2 bot cannot ever have reallocated anything in production. Deploy-time whitelists must be chosen fresh; the README documents this and this bot fails loud at startup on any non-V2 entry.

Deliberately dropped from the old repo

GraphQL API layer, checked-in VaultV2 ABI, capsIds.ts (SDK helpers are byte-identical), hand-rolled WAD/IRM math (blue-sdk MathLib/AdaptiveCurveIrmLib/SharesMath), multi-chain single process, setInterval runtime, Promise.all sends, console logging, the dead apy-range override tables (their keys never matched the whitelist), and the anvil fork suites (the old vaultSetup.ts V2 timelock harness is the seed for a future fork suite; noted in README).

Verification

• pnpm lint / pnpm format / pnpm knip / typecheck (bot + bot-kit): clean. Root pnpm test: all pass except the 4 pre-existing fork/e2e suites needing RPC_URL_8453 env files. 63 new bot tests + 7 new bot-kit policy tests; break-one-assertion verified per repo rule; quoter-bot jsdoc:build green.
• Live smoke on mainnet (public RPC, throwaway key, DRY_RUN=true) against Hyperithm USDC Apex (~$8.5M, 20 markets): startup identity/adapter/policy wiring, allocator.missing_role skip path, interval gate, clean tick.end counters and SIGINT. A separate live probe exercised fetchVaultV2Data → strategy → (no move found) with real caps/allocations.
• The fail-loud paths were exercised live: non-V2 address → startup.error factory rejection; V2 vault with an unsupported adapter shape → typed InvalidVaultError.
• docker build not verified locally (daemon not running) — the Dockerfile is the V1 bot's byte-for-byte with paths adjusted; Railway builds server-side.

Follow-ups

Shared with the V1 bot: fork test suite, pure-bigint bips gate cleanup, possible extraction of the shared strategy math into a @repo/* package once both bots merge. Railway provisioning + GitHub Environments (vault-v2-realloc-{staging,production}) are deploy-time operator steps.

🤖 Generated with Claude Code

Update: restacked on #165's review-fix commit (61980bc)

Mirrored the applicable V1 review fixes in fix(vault-v2-reallocation): mirror v1 review fixes: bot-kit's new simulateCall replaces the local simulate helper; snapshots accrue to the pinned block's timestamp instead of wall clock; apy-range hard-excludes non-AdaptiveCurve markets (a zero rateAtTarget degenerates the curve inversion into 'far below range' and would drain the position on simulation-passing calldata — same hazard the V1 review found), surfaced per tick as market.non_adaptive_curve; equalize clamps its target utilization at 100% for bad-debt states. Deliberately NOT mirrored: the V1 allocator|curator|owner role-gate widening — VaultV2.allocate requires isAllocator[msg.sender] strictly (vaults-v2 source, ALLOCATOR FUNCTIONS), so curator/owner keys do not qualify on V2.

Update: dual-model review pass (Opus + GPT 5.6 Sol) — 3 must-fix correctness defects found and fixed

Commit fix(vault-v2-reallocation): apply dual-model review findings:

1. relativeCap == WAD is the contract's no-constraint sentinel (allocateInternal skips the relative check) — the bot treated it as a binding 100% ceiling, zeroing the adapter pool on any fully-deployed vault → silent permanent no-op. Confirmed live: Hyperithm USDC Apex produced no plan pre-fix and an exactly-funded 9-leg plan post-fix. The old test fixtures (allocation: 0 aggregates) masked the production shape; new tests pin it.
2. Cap headroom basis corrected to the accrued position (the adapter trues allocation(id) up to expectedSupplyAssets on every touch, so cap − storedAllocation overstates headroom by the drift), with aggregate pools carrying every market's drift and the plan's own deallocations credited back (they execute first) — a full adapter cap no longer blocks valid rebalances.
3. Equalize now clamps allocations to deallocations + idle (allocate pulls from vault balance; unclamped plans were guaranteed revert-loops on real shapes, e.g. a small adapter position in a big cold market).

Plus should-fixes/nits from the same pass and a peer-session audit: zero-target division guards (dust borrow / sub-curve APY bounds), contribution-gated min-delta triggers, classifyMarket/apyDeltaBips helpers de-duplicating the two passes, throw-safe multicall policy evaluation + dirty-padding test in bot-kit, adapter.changed tick detection for mid-run adapter swaps, market ids on reallocation.found legs, multicall-batched cap reads + parallel getBlock, isAddressEqual conventions, stale V1 wording, and honest README language for the both-sides leg gate (see below).

Known behavior kept for old-bot fidelity (deliberate, flagged for product review): a plan fires only when both sides have ≥1 leg, so pure idle deployment (fresh deposits, every market at/above target) never fires — same gate as the old V2 bot, but in V1 idle was a market so the gate had different reach. Documented in the README as a follow-up decision.

Verification: 303 tests green across vault-v2-reallocation/bot-kit/vault-v1-reallocation/workspace; break-one-assertion on the WAD sentinel, idle clamp, zero-target guards, and pool crediting; live probe on a $8.5M 20-market prod vault validating alloc ≤ dealloc + idle and plan encoding.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

[chatgpt-codex-connector]

💡 Codex Review

morpho-bots/bots/vault-v2-reallocation/scripts/deploy-railway.ts

Lines 49 to 52 in 03a8fa7

	function required(env: Env, name: string): string {
	const value = env[name]
	if (!value || !value.trim()) throw new Error(`Missing required env var: ${name}`)
	return value.trim()

Replace plain deployment errors with typed failures

When required configuration is absent—and throughout the other expected Railway CLI failure paths—this script throws plain Error, preventing callers from distinguishing configuration, CLI, and deployment failures and bypassing the repository’s required sanitization boundary. Define named exported error subclasses in separate kebab-case *.error.ts files and use the appropriate type at each expected failure site.

AGENTS.md reference: AGENTS.md:L43-L50

---

morpho-bots/bots/vault-v2-reallocation/scripts/deploy-railway.ts

Lines 49 to 52 in 03a8fa7

	function required(env: Env, name: string): string {
	const value = env[name]
	if (!value || !value.trim()) throw new Error(`Missing required env var: ${name}`)
	return value.trim()

Convert deployment utilities to arrow constants

This newly added deployment script declares required and the remaining helper utilities with function declarations, contrary to the repository-wide arrow-utility convention. Convert these helpers to const arrow functions so the new operator surface follows the mandated utility pattern.

AGENTS.md reference: AGENTS.md:L51-L52

---

morpho-bots/packages/bot-kit/src/policy.ts

Line 130 in 03a8fa7

const decodeMulticallData = (data: Hex): readonly Hex[] | undefined => {

Move multicall utilities out of the error-class module

The newly added decodeMulticallData and checkMulticall utilities live in policy.ts, which also contains PolicyViolationError; this breaks the repository’s utility-isolation invariant. Move the multicall helpers to a focused utility module and import them into the policy module.

AGENTS.md reference: AGENTS.md:L41-L42

---

morpho-bots/bots/vault-v2-reallocation/src/math.ts

Lines 150 to 152 in 03a8fa7

	const key = getAddress(collateralToken)
	pools.adapter += amount
	pools.byCollateral.set(key, (pools.byCollateral.get(key) ?? 0n) + amount)

Repay aggregate cap deficits before crediting deallocations

When an adapter or collateral allocation is already above its buffered cap—because interest accrued or a curator reduced the cap—createDepositPools starts that pool at zero, but creditPools then treats every deallocated asset as fresh headroom. A subsequent allocation can therefore restore the pre-deallocation over-cap balance, causing the exact multicall to revert repeatedly, or erase the intended 99.99% safety buffer. Track each pool’s existing cap deficit and credit only the portion of a deallocation that moves the effective allocation below the buffered ceiling.

---

morpho-bots/bots/vault-v2-reallocation/src/math.ts

Lines 48 to 50 in 03a8fa7

	MathLib.min(
	getWithdrawalToUtilization(marketData.state, targetUtilization),
	marketData.vaultAssets

Preserve a position in original-generation adapter markets

When a market on the supported original MorphoMarketV1Adapter has zero or sufficiently low utilization, the computed withdrawal can be at least the adapter’s entire position, and this clamp emits a full deallocation. That adapter removes a market from marketParamsList when its allocation reaches zero, while this bot discovers candidates from that list, so later ticks cannot re-enter the market if demand returns without an external allocator first restoring it. Cap the withdrawal below the full position for this adapter generation or discover inactive markets independently.

---

morpho-bots/bots/vault-v2-reallocation/src/index.ts

Lines 220 to 223 in 03a8fa7

	// Config/client never came up, so we cannot honor LOG_LEVEL — emit the failure directly.
	console.error(
	JSON.stringify({ level: 'error', event: 'startup.error', error: ensureError(error).message })
	)

Sanitize startup errors before writing them to logs

When startup fails during an RPC-backed vault check, a viem transport error’s full message can contain the authenticated RPC URL, request payload, and provider response, and this catch writes it verbatim to operator logs. Emit a bounded safe reason such as the viem shortMessage, while retaining the original error only as an internal cause, so provider credentials and untrusted response data cannot leak.

AGENTS.md reference: AGENTS.md:L48-L50

---

morpho-bots/bots/vault-v2-reallocation/scripts/deploy-railway.ts

Lines 272 to 275 in 03a8fa7

	const strategy = suffixed('STRATEGY', chain.chainId) ?? 'equalize-utilizations'
	// New deployments default to dry-run; flip DRY_RUN_<chainId>=false once the plans look right.
	const dryRun = !/^(0|false)$/i.test(suffixed('DRY_RUN', chain.chainId) ?? '')
	const betterstackHeartbeatUrl = suffixed('BETTERSTACK_HEARTBEAT_URL', chain.chainId)

Propagate per-chain reallocation intervals during deployment

When operators follow the documented migration posture and supply REALLOCATION_INTERVAL_MS_1=900000 and REALLOCATION_INTERVAL_MS_8453=300000, this deployment script never reads or writes either value, so both Railway services silently run the bot’s 600000 ms default instead of the stated production cadences. Parse the suffixed interval with the other per-chain settings and set REALLOCATION_INTERVAL_MS on each service.

---

morpho-bots/bots/vault-v2-reallocation/src/strategies/reconcile.ts

Lines 136 to 139 in 03a8fa7

	const toDeallocate = min(move.amount, remainingAmountToDeallocate)
	remainingAmountToDeallocate -= toDeallocate
	creditPools(legPools, move.marketData.params.collateralToken, toDeallocate)
	if (toDeallocate > 0n) deallocations.push(toLeg(move, toDeallocate))

Preserve collateral funding when trimming deallocations

When idle parking is disabled and deallocations from multiple collateral groups exceed the allocation total, this market-order trim can retain a deallocation from collateral A while dropping the collateral B deallocation whose credit made the planned B allocation pass sizing. The emission pass then clamps the B allocation to zero but still returns and submits the retained deallocation, parking assets idle despite allowIdleParking: false. Trim deallocations with awareness of the collateral pools required by emitted allocations, or discard/rebalance the plan when the final sides no longer match.

---

morpho-bots/bots/vault-v2-reallocation/src/strategies/reconcile.ts

Lines 122 to 123 in 03a8fa7

	if (min(totalAmountToDeallocate, totalAmountToAllocate) === 0n || !didClearMinDelta) {
	return undefined

Re-evaluate the delta threshold after trimming legs

When the only move with clearsMinDelta: true is later omitted by the market-order budget or cap-pool trimming, this pre-emission check remains armed and the reconciler submits only below-threshold legs. That defeats the strategy’s firing threshold and can generate repeated low-value transactions; compute the gate from the legs that actually survive into the final reallocation.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cashd]

approved for OSS as a reference

[cashd]

/simplify + review pass on this one. 30-ish threads below, roughly by weight — a few real ones up top (relative-cap rounding, 3 vacuous tests, README flag described backwards), then rule hits, reuse of stuff we already have in blue-sdk / @repo/utils, per-tick RPC waste, and simplifications. Anything tagged "low pri" / "not for this PR" / "fyi" is optional; I'll ticket the cross-bot dedupe and the workflow release-job copy separately.

Suggestions are inline where the drop-in was clean.

[cashd]

The contract rounds this down (firstTotalAssets.mulDivDown(relativeCap, WAD) in VaultV2), so wMulUp can put our ceiling 1 wei above the contract's. The 99.99% buffer hides it in prod, but the tests call this with capBufferWad = WAD where the mismatch is real.

Suggested change

	const bufferedRelative = MathLib.wMulDown(MathLib.wMulUp(totalAssets, cap.relative), capBufferWad)
	const bufferedRelative = MathLib.wMulDown(MathLib.wMulDown(totalAssets, cap.relative), capBufferWad)

[cashd]

This passes vacuously if the strategy ever returns undefined here — every expect is inside the if. Same at L248. Both produce a plan today (I checked), but that's incidental.

Swap to expect(result).toBeDefined() and assert on result!.

[cashd]

Both assertions here are toBeUndefined(), so it passes identically whether idle is folded or not. Worth a hot+cold pair asserting the allocation grows by exactly min(surplus, idle) between idleAssets: 0n and a large idle.

[cashd]

This is backwards vs the code — allowIdleParking gates whether deallocation surplus may park in idle (reconcile.ts:119); allocations always draw on idle. An operator flipping it to stop idle deployment gets nothing.

Suggested change

	AdaptiveCurveIRM curve; allocations top up from idle (`ALLOW_IDLE_REALLOCATION`). Fires only
	past `MIN_APY_DELTA_BIPS`.
	AdaptiveCurveIRM curve; deallocation surplus parks in idle only when `ALLOW_IDLE_REALLOCATION=true`
	(allocations always draw on idle). Fires only
	past `MIN_APY_DELTA_BIPS`.

[cashd]

nested ternary — repo rule is none. Early returns read cleaner:

Suggested change

	const bound =
	utilization > upperBound ? upperBound : utilization < lowerBound ? lowerBound : undefined
	const boundFor = (u: bigint): bigint | undefined => {
	if (u > upperBound) return upperBound
	if (u < lowerBound) return lowerBound
	return undefined
	}
	const bound = boundFor(utilization)

[cashd]

low pri: 4 positional params here, getDepositableAmount, intEnv, resolveMinApyDeltaBips — conventions say >3 → trailing object. Churn for little value rn, up to you.

[cashd]

Zooming out: strategy-config.ts, build.ts, both script *.error.ts, invalid-config.error.ts, tsconfig.json are byte-identical to vault-v1; this file and deploy-railway.ts differ only in strings; the env parsers here are the 5th copy repo-wide. Drift is already visible (v2's zero-target guard isn't in v1).

Not for this PR — I'll file a ticket for env parsers → bot-kit and a shared reallocation core.

[cashd]

6th verbatim copy of this job. Not for this PR, but the tag step belongs in deploy-bot.yml behind stage == 'production' so adding a bot is one case line. Will ticket.

[cashd]

The v1 TIB explicitly defers V2 "as a separate decision", and this PR also changes bot-kit's documented outer-envelope-only signer guarantee (multicall inner-call inspection). I think it needs a TIB-2026-08-17-vault-v2-reallocation-bot.md covering: the multicall policy design, delta legs, both-sides-required firing, 3-level cap pools, one-adapter assumption.

[cashd]

fyi only: vaultV2.accrueInterest(timestamp) at L234 re-runs position/market.accrueInterest for every market via adapter.realAssets (blue-sdk 6.4 adapters), so each market is accrued twice per vault. CPU-only, sub-ms — no change needed, just so it's known.