feat(morpho-sdk): support BluePublicAllocator reallocations

.agents/pr-review-engine/agents/documentation.md

@@ -50,6 +50,7 @@ For each Markdown file affected, flag:
 - **Stale prose.** A statement that no longer matches the code after the diff — e.g. README documents a function that was removed/renamed; AGENTS.md lists a rule the code change just violated; an example that no longer compiles.
 - **Out-of-sync inventories.** A file enumerating personas, packages, slash commands, scripts, supported chains, etc. that no longer matches reality after the diff. E.g. a README that lists "supported chains: mainnet, base" while the diff just added arbitrum.
 - **Cross-doc consistency.** When the diff changes a rule in `AGENTS.md`, every persona that enforces it (per the backlink `> Applied by personas: …`) should reflect the new rule. When the diff renames a section heading in `AGENTS.md`, every doc that references that section by title needs an update.
+- **Implemented TIB rewrites.** Treat a TIB already present on the target branch as a historical record. Flag edits that update its implementation-time names or examples; changed decisions require a superseding TIB, while operational clarifications require a dated addendum. A TIB introduced on the current branch may stay in sync with its implementation before landing.
 - **Code blocks that drift from the code.** A bash snippet in a `.md` that uses a flag the script no longer supports; a TypeScript snippet whose imports no longer resolve.
 
 ## 3. Pointer / link integrity

.changeset/brave-vaults-reallocate.md

@@ -0,0 +1,20 @@
+---
+"@morpho-org/morpho-ts": minor
+"@morpho-org/blue-sdk": minor
+"@morpho-org/blue-sdk-viem": minor
+"@morpho-org/liquidity-sdk-viem": patch
+"@morpho-org/morpho-sdk": minor
+"@morpho-org/wdk-protocol-lending-morpho-evm": minor
+---
+
+Add canonical `vaultV1PublicAllocatorAbi` and `vaultV2BluePublicAllocatorAbi` exports plus per-chain `vaultV1PublicAllocator` and `vaultV2BluePublicAllocator` registry entries to `morpho-ts`, preserving `publicAllocatorAbi` and `publicAllocator` as deprecated V1 aliases. Move the shared `marketParamsAbi` source of truth there while preserving its `blue-sdk` re-export, and raise the `blue-sdk` peer range to the introducing `morpho-ts` minor. Add Vault V2 allocation-cap helpers and the updated `canPullFromIdle`/`canPullFromMarket`/WAD-scaled penalty config types to `blue-sdk`, accept iterable active-adapter, vault-allowlist, and reallocation-plan inputs while materializing them before repeated use, add chain-registry-backed deployless and fallback reads to `blue-sdk-viem`, and expose Vault V2 shared-liquidity discovery, planning, metrics, maximum-penalty filtering, and flat market/idle reallocations through `morpho-sdk` Blue flows.
+
+V2 bundles now reject chains without a registered BluePublicAllocator before exposing requirements, pull the proportional loan-token penalty through GeneralAdapter1, grant the allocator an exact non-skippable allowance from Bundler3, pass the configured `uint64 penalty` in calldata, and keep the nonpayable allocator calls out of `tx.value`. `VaultV2BluePublicAllocatorConfig` is hydrated as a class with exact per-call penalty calculation, `VaultV2BlueMarketPublicAllocatorConfig` computes max-in capacity from its absolute cap, and plan totals stay local to their consumers. The planner mirrors contract execution order for penalties, source deallocation, first vault accrual (including zero-elapsed loss recognition), and target allocation; freezes the resulting relative-cap denominator across later calls for that vault; keeps every adapter coherent with one canonical simulated state per Morpho market; preserves supplied address casing while matching vaults and adapters case-insensitively; rejects incomplete allocator snapshots instead of silently reporting no liquidity; rejects non-positive operation amounts and same-market moves across adapters; and uses the latest timestamp in its complete input snapshot by default.
+
+Use coherent protocol-specific names across the V1 and V2 reallocation APIs, including `VaultV1ReallocationData`, `VaultV2BlueReallocationData`, `computeVaultV1Reallocations`, `VaultV2BluePublicAllocatorOptions`, `VaultV2BluePublicAllocatorConfig`, its fetcher family, and Vault V2-prefixed Bundler actions. Add `MorphoBlue.getVaultV1ReallocationData`, `getVaultV1Reallocations`, `getVaultV2BlueReallocationData`, and `getVaultV2BlueReallocations`; preserve the published unversioned `getReallocationData` and `getReallocations` as deprecated V1 aliases. Both versioned planners reject reallocation snapshots from another chain. Keep V1's `defaultMaxWithdrawalUtilization` configurable, and add V2's scalar `maxWithdrawalUtilization` for its friendly phase while retaining the 100% adversarial fallback.
+
+Compatibility note: this minor intentionally accepts four breaking changes. `VaultV2MorphoMarketV1Adapter.ids()` and `VaultV2MorphoMarketV1AdapterV2.ids()` now return the labeled readonly tuple `readonly [adapterCapId: Hash, collateralCapId: Hash, adapterMarketCapId: Hash]` instead of mutable `Hash[]`, while `VaultV2MorphoVaultV1Adapter.ids()` now returns `readonly [adapterCapId: Hash]`; `MorphoBlue.withdraw`, `borrow`, and `refinance` may now return `Transaction<ERC20ApprovalAction>` from `getRequirements()` for Vault V2 penalty funding; `BlueWithdrawAction`, `BlueBorrowAction`, `BlueSupplyCollateralBorrowAction`, and `BlueRefinanceAction` now require `reallocationPenaltyAssets`; and Vault V2 reallocation discovery now accepts only zero-penalty vaults by default. Runtime ordering for `ids()` is unchanged. Consumers should spread `ids()` when a mutable array is required, handle approval transactions in exhaustive requirement consumers, set `reallocationPenaltyAssets: 0n` in handwritten V1 or no-penalty action descriptors, and explicitly set `maxPenalty` when opting into a nonzero Vault V2 allocator penalty. Explicit and hand-built penalties remain supported up to WAD (100%), preserving the existing maximum.
+
+Name allocation-cap helpers `adapterCapId`, `collateralCapId`, and `adapterMarketCapId`. Preserve the published `adapterId`, `collateralId`, and `marketParamsId` helpers as deprecated aliases.
+
+Add an explicit `MorphoBorrowWithVaultV2ReallocationsOptions` WDK opt-in for Vault V2 reallocations and their possible approval requirement while preserving the legacy Vault V1-only `MorphoBorrowOptions` input and authorization-only requirement result type. Reallocation plans must use exactly one vault version per transaction.

AGENTS.md

@@ -155,7 +155,8 @@ A scannable list of patterns reviewers reject. Most are review-only today (per t
   - `@returns` describing the return shape.
   - `@throws` for each typed error class an integrator may pattern-match on.
   - One `@example` block with realistic working code: imports, client setup, the call, expected return.
-- **AI-legibility is first-class.** Identical signatures across V1/V2 where protocols overlap. Discriminated unions with obvious `type` tags. Deterministic outputs verifiable byte-for-byte. Error messages read like instructions an agent can act on without guessing. Protocol-specific terms (`LLTV buffer`, `wNative`, `GeneralAdapter1`, `bundler3`, `PublicAllocator`, `MetaMorpho`, `Permit2`, `WAD`) live in the [`packages/morpho-sdk/AGENTS.md`](./packages/morpho-sdk/AGENTS.md) glossary.
+- **AI-legibility is first-class.** Identical signatures across V1/V2 where protocols overlap. Discriminated unions with obvious `type` tags. Deterministic outputs verifiable byte-for-byte. Error messages read like instructions an agent can act on without guessing. Protocol-specific terms (`LLTV buffer`, `wNative`, `GeneralAdapter1`, `bundler3`, `PublicAllocator V1`, `BluePublicAllocator`, `MetaMorpho`, `Permit2`, `WAD`) live in the [`packages/morpho-sdk/AGENTS.md`](./packages/morpho-sdk/AGENTS.md) glossary.
+- **Implemented TIBs are historical records.** Do not rewrite a TIB already present on the target branch to follow later code, symbol, or path changes. Keep the TIB's implementation-time names and examples intact. A changed decision gets a new superseding TIB; an operational clarification gets a dated addendum. Only a TIB introduced for the current implementation may be kept in sync with that implementation before it lands.
 - **TypeDoc-generated reference** published per release.
 - **Feedback loop:** if the same question is asked twice, the answer goes into the relevant `AGENTS.md` or JSDoc on the export it concerns.
 

packages/blue-sdk-viem/AGENTS.md

@@ -12,6 +12,7 @@
 - Normalize unsafe user addresses with `safeGetAddress`, not lowercasing alone.
 - Typed-data helpers return `TypedDataDefinition`, e.g. `getPermitTypedData(...)`.
 - Re-export ABI literals from `@morpho-org/morpho-ts` when they exist there; keep local ABI declarations only for Blue-specific viem surfaces absent from `morpho-ts`.
+- Vault V2 BluePublicAllocator fetchers resolve the chain's single allocator from `vaultV2BluePublicAllocator` in the address registry, using `parameters.chainId` or the client chain id. The hydrated-vault batch fetch derives supported adapter/market/allocation ids, returns active adapters as a set separate from market configs, defaults to one deployless read, and falls back to direct reads.
 
 ## Continuous Improvement
 

packages/blue-sdk-viem/contracts/vault-v2/GetVaultV2BluePublicAllocatorConfig.sol

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.0;
+
+import {IBluePublicAllocator} from "./interfaces/IBluePublicAllocator.sol";
+import {IVaultV2} from "./interfaces/IVaultV2.sol";
+
+struct VaultV2BlueMarketPublicAllocatorRequest {
+    address adapter;
+    bytes32 adapterMarketCapId;
+}
+
+struct VaultV2BlueMarketPublicAllocatorResponse {
+    address adapter;
+    bytes32 adapterMarketCapId;
+    uint256 absoluteCap;
+    bool canPullFromMarket;
+}
+
+struct VaultV2AllocationResponse {
+    bytes32 id;
+    uint256 absoluteCap;
+    uint256 relativeCap;
+    uint256 allocation;
+}
+
+struct VaultV2BluePublicAllocatorResponse {
+    bool isAllocator;
+    bool canPullFromIdle;
+    uint64 penalty;
+    bool[] isActiveAdapters;
+    VaultV2BlueMarketPublicAllocatorResponse[] marketConfigs;
+    VaultV2AllocationResponse[] allocations;
+}
+
+contract GetVaultV2BluePublicAllocatorConfig {
+    function query(
+        IBluePublicAllocator allocator,
+        IVaultV2 vault,
+        address[] calldata adapters,
+        VaultV2BlueMarketPublicAllocatorRequest[] calldata marketRequests,
+        bytes32[] calldata allocationIds
+    ) external view returns (VaultV2BluePublicAllocatorResponse memory res) {
+        res.isAllocator = vault.isAllocator(address(allocator));
+        (res.canPullFromIdle, res.penalty) = allocator.vaultData(address(vault));
+
+        uint256 adaptersLength = adapters.length;
+        res.isActiveAdapters = new bool[](adaptersLength);
+        for (uint256 i; i < adaptersLength; ++i) {
+            res.isActiveAdapters[i] = allocator.isActiveAdapter(address(vault), adapters[i]);
+        }
+
+        uint256 marketRequestsLength = marketRequests.length;
+        res.marketConfigs = new VaultV2BlueMarketPublicAllocatorResponse[](marketRequestsLength);
+        for (uint256 i; i < marketRequestsLength; ++i) {
+            VaultV2BlueMarketPublicAllocatorRequest calldata request = marketRequests[i];
+            res.marketConfigs[i] = VaultV2BlueMarketPublicAllocatorResponse({
+                adapter: request.adapter,
+                adapterMarketCapId: request.adapterMarketCapId,
+                absoluteCap: allocator.absoluteCap(address(vault), request.adapterMarketCapId),
+                canPullFromMarket: allocator.canPullFromMarket(address(vault), request.adapterMarketCapId)
+            });
+        }
+
+        uint256 allocationIdsLength = allocationIds.length;
+        res.allocations = new VaultV2AllocationResponse[](allocationIdsLength);
+        for (uint256 i; i < allocationIdsLength; ++i) {
+            bytes32 id = allocationIds[i];
+            res.allocations[i] = VaultV2AllocationResponse({
+                id: id,
+                absoluteCap: vault.absoluteCap(id),
+                relativeCap: vault.relativeCap(id),
+                allocation: vault.allocation(id)
+            });
+        }
+    }
+}

packages/blue-sdk-viem/contracts/vault-v2/interfaces/IBluePublicAllocator.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (c) 2026 Morpho Association
+pragma solidity ^0.8.0;
+
+interface IBluePublicAllocator {
+    function absoluteCap(address vault, bytes32 id) external view returns (uint256);
+    function canPullFromMarket(address vault, bytes32 id) external view returns (bool);
+    function isActiveAdapter(address vault, address adapter) external view returns (bool);
+    function vaultData(address vault) external view returns (bool canPullFromIdle, uint64 penalty);
+}

packages/blue-sdk-viem/package.json

@@ -30,8 +30,8 @@
     "build:esm": "tsc --build tsconfig.build.esm.json && echo '{\"type\":\"module\"}' > lib/esm/package.json"
   },
   "peerDependencies": {
-    "@morpho-org/blue-sdk": "^6.4.0",
-    "@morpho-org/morpho-ts": "^2.7.0",
+    "@morpho-org/blue-sdk": "^6.6.0",
+    "@morpho-org/morpho-ts": "^2.10.0",
     "viem": "^2.0.0"
   },
   "devDependencies": {

packages/blue-sdk-viem/src/abis.ts

@@ -14,7 +14,9 @@ export {
   publicAllocatorAbi,
   vaultV1AdapterAbi,
   vaultV1AdapterFactoryAbi,
+  vaultV1PublicAllocatorAbi,
   vaultV2Abi,
+  vaultV2BluePublicAllocatorAbi,
   vaultV2FactoryAbi,
   whitelistControllerAggregatorV2Abi,
   wrappedBackedTokenAbi,

packages/blue-sdk-viem/src/fetch/Vault.ts

@@ -15,7 +15,7 @@ import { getChainId, readContract } from "viem/actions";
 import {
   metaMorphoAbi,
   metaMorphoFactoryAbi,
-  publicAllocatorAbi,
+  vaultV1PublicAllocatorAbi,
 } from "../abis.js";
 import { abi, code } from "../queries/GetVault.js";
 import type { DeploylessFetchParameters } from "../types.js";
@@ -60,7 +60,7 @@ export async function fetchVault(
 ) {
   parameters.chainId ??= await getChainId(client);
 
-  const { publicAllocator, metaMorphoFactory } = getChainAddresses(
+  const { vaultV1PublicAllocator, metaMorphoFactory } = getChainAddresses(
     parameters.chainId,
   );
 
@@ -95,7 +95,11 @@ export async function fetchVault(
         abi,
         code,
         functionName: "query",
-        args: [address, publicAllocator ?? zeroAddress, metaMorphoFactory],
+        args: [
+          address,
+          vaultV1PublicAllocator ?? zeroAddress,
+          metaMorphoFactory,
+        ],
       });
 
       return new Vault({
@@ -115,7 +119,7 @@ export async function fetchVault(
         pendingGuardian,
         pendingTimelock,
         publicAllocatorConfig:
-          publicAllocator != null ? publicAllocatorConfig : undefined,
+          vaultV1PublicAllocator != null ? publicAllocatorConfig : undefined,
         supplyQueue: supplyQueue as MarketId[],
         withdrawQueue: withdrawQueue as MarketId[],
         totalSupply,
@@ -247,13 +251,13 @@ export async function fetchVault(
       abi: metaMorphoAbi,
       functionName: "withdrawQueueLength",
     }),
-    publicAllocator != null &&
+    vaultV1PublicAllocator != null &&
       readContract(client, {
         ...parameters,
         address,
         abi: metaMorphoAbi,
         functionName: "isAllocator",
-        args: [publicAllocator],
+        args: [vaultV1PublicAllocator],
       }),
     readContract(client, {
       ...parameters,
@@ -284,22 +288,22 @@ export async function fetchVault(
     publicAllocatorConfigPromise = Promise.all([
       readContract(client, {
         ...parameters,
-        address: publicAllocator!,
-        abi: publicAllocatorAbi,
+        address: vaultV1PublicAllocator!,
+        abi: vaultV1PublicAllocatorAbi,
         functionName: "admin",
         args: [address],
       }),
       readContract(client, {
         ...parameters,
-        address: publicAllocator!,
-        abi: publicAllocatorAbi,
+        address: vaultV1PublicAllocator!,
+        abi: vaultV1PublicAllocatorAbi,
         functionName: "fee",
         args: [address],
       }),
       readContract(client, {
         ...parameters,
-        address: publicAllocator!,
-        abi: publicAllocatorAbi,
+        address: vaultV1PublicAllocator!,
+        abi: vaultV1PublicAllocatorAbi,
         functionName: "accruedFee",
         args: [address],
       }),

packages/blue-sdk-viem/src/fetch/VaultMarketPublicAllocatorConfig.ts

@@ -5,7 +5,7 @@ import {
 } from "@morpho-org/blue-sdk";
 import type { Address, Client } from "viem";
 import { getChainId, readContract } from "viem/actions";
-import { publicAllocatorAbi } from "../abis.js";
+import { vaultV1PublicAllocatorAbi } from "../abis.js";
 import type { FetchParameters } from "../types.js";
 
 /**
@@ -49,14 +49,14 @@ export async function fetchVaultMarketPublicAllocatorConfig(
 ) {
   parameters.chainId ??= await getChainId(client);
 
-  const { publicAllocator } = getChainAddresses(parameters.chainId);
+  const { vaultV1PublicAllocator } = getChainAddresses(parameters.chainId);
   /* v8 ignore next: V8 does not credit this guard's empty false branch; both paths are tested. */
-  if (publicAllocator == null) return;
+  if (vaultV1PublicAllocator == null) return;
 
   const [maxIn, maxOut] = await readContract(client, {
     ...parameters,
-    address: publicAllocator,
-    abi: publicAllocatorAbi,
+    address: vaultV1PublicAllocator,
+    abi: vaultV1PublicAllocatorAbi,
     functionName: "flowCaps",
     args: [vault, marketId],
   });

packages/blue-sdk-viem/src/fetch/fetch.test.ts

@@ -52,7 +52,7 @@ import {
   permissionedErc20WrapperAbi,
   permit2Abi,
   preLiquidationAbi,
-  publicAllocatorAbi,
+  vaultV1PublicAllocatorAbi,
   whitelistControllerAggregatorV2Abi,
   wrappedBackedTokenAbi,
   wstEthAbi,
@@ -223,7 +223,7 @@ function mockVaultMarketConfigReads(
   });
   mockRead(handle, {
     address: ADDRESSES.publicAllocator,
-    abi: publicAllocatorAbi,
+    abi: vaultV1PublicAllocatorAbi,
     functionName: "flowCaps",
     result: [33n, 34n],
   });
@@ -1171,7 +1171,7 @@ describe("vault fetchers", () => {
     const handle = createMockClient(mainnet);
     mockRead(handle, {
       address: ADDRESSES.publicAllocator,
-      abi: publicAllocatorAbi,
+      abi: vaultV1PublicAllocatorAbi,
       functionName: "flowCaps",
       result: [27n, 28n],
     });
@@ -1527,19 +1527,19 @@ describe("vault fetchers", () => {
     });
     mockRead(handle, {
       address: ADDRESSES.publicAllocator,
-      abi: publicAllocatorAbi,
+      abi: vaultV1PublicAllocatorAbi,
       functionName: "admin",
       result: USER,
     });
     mockRead(handle, {
       address: ADDRESSES.publicAllocator,
-      abi: publicAllocatorAbi,
+      abi: vaultV1PublicAllocatorAbi,
       functionName: "fee",
       result: 56n,
     });
     mockRead(handle, {
       address: ADDRESSES.publicAllocator,
-      abi: publicAllocatorAbi,
+      abi: vaultV1PublicAllocatorAbi,
       functionName: "accruedFee",
       result: 57n,
     });

packages/blue-sdk-viem/src/fetch/vault-v2/VaultV2.ts

@@ -325,14 +325,16 @@ export async function fetchVaultV2(
   let liquidityAdapterIds: Hash[] | undefined;
   if (hasMorphoVaultV1LiquidityAdapter)
     liquidityAdapterIds = [
-      VaultV2MorphoVaultV1Adapter.adapterId(liquidityAdapter),
+      VaultV2MorphoVaultV1Adapter.adapterCapId(liquidityAdapter),
     ];
   if (hasMorphoMarketV1AdapterV2LiquidityAdapter) {
     const marketParams = MarketParams.fromHex(liquidityData);
     liquidityAdapterIds = [
-      VaultV2MorphoMarketV1AdapterV2.adapterId(liquidityAdapter),
-      VaultV2MorphoMarketV1AdapterV2.collateralId(marketParams.collateralToken),
-      VaultV2MorphoMarketV1AdapterV2.marketParamsId(
+      VaultV2MorphoMarketV1AdapterV2.adapterCapId(liquidityAdapter),
+      VaultV2MorphoMarketV1AdapterV2.collateralCapId(
+        marketParams.collateralToken,
+      ),
+      VaultV2MorphoMarketV1AdapterV2.adapterMarketCapId(
         liquidityAdapter,
         marketParams,
       ),