refactor: vault v2 indexer

AGENTS.md

@@ -165,6 +165,12 @@ When touching transaction and position flows, validation MUST include all releva
 29. **Preview prop integrity**: any position/risk preview component that separates current and projected props must receive quote- or input-derived projected balances through dedicated `projected*` props while preserving live balances in `current*` props, so amount rows, LTV deltas, and liquidation metrics stay synchronized instead of mixing current and projected states.
 30. **Fee preview consistency**: transaction previews that show protocol/app fees must derive token/USD display from shared fee-display helpers, use compact token amounts with explicit full-value hover content, threshold tiny USD values as `< $0.01` while preserving exact USD on hover, and avoid ad hoc per-modal formatting drift.
 31. **Market list first-paint integrity**: shared multi-chain market list queries must not let a single slow chain or slow fallback path block first paint indefinitely; network fetches should use bounded request timeouts that account for fallback coverage, and any fallback path used for first paint must preserve market completeness (no truncated `first: 1000` fallback). Once page 1 reveals total count, remaining pagination should be fetched in parallel or bounded parallel batches instead of strict sequential loops.
+32. **Canonical vault-metadata source integrity**: when Monarch API exposes chain-scoped V2 vault metadata (owner, curator, asset, allocators, sentinels, adapters, caps), use it as the primary read chokepoint. Do not rebuild the same view through per-chain subgraphs, slow Morpho API fanout, local key caches, or event parsing except for narrow RPC fallback while a fresh write has not been indexed yet.
+33. **Adapter-factory write integrity**: new market-adapter deployment must use the configured chain-scoped `MorphoMarketV1AdapterV2` factory directly, and post-tx adapter discovery should come from the V2 creation receipt/log rather than an extra factory read. Existing vault adapter type labels may come from Monarch API, but do not reintroduce V1 deployment assumptions or version-branching into the write path.
+34. **Vault post-tx refresh integrity**: do not invalidate/refetch Monarch-backed vault queries before transaction confirmation. After confirmed vault writes that change Monarch-indexed fields (metadata, adapters, allocators, caps), trigger the shared vault-query refetch chokepoint with bounded follow-up retries so indexer lag does not leave the UI stale.
+35. **Monarch proxy boundary integrity**: server-side Monarch proxy routes must use server-only API key env vars and bounded `AbortController` timeouts on upstream fetches. Do not let Monarch GraphQL or metrics calls hang indefinitely, and do not reference `NEXT_PUBLIC_*` secrets in server authorization headers.
+36. **Vault fallback and adapter-sentinel integrity**: treat `zeroAddress` as “no adapter” in all vault routing and transaction-critical paths, canonicalize vault query/cache identity by lowercase address plus chain, and when Monarch metadata is unavailable fail closed or return explicit unknown state instead of synthesizing empty vault data or assuming missing allocators/caps from absent indexed fields.
+37. **Vault setup-state derivation integrity**: only infer “adapter missing”, “needs initialization”, or auto-advance setup states from resolved adapter/vault queries, never from undefined/loading/error values. When Monarch returns both active adapter addresses and adapter detail rows, merge the union by canonical address instead of letting one source replace the other.
 
 
 ### REQUIRED: Regression Rule Capture

app/api/monarch/metrics/route.ts

@@ -1,25 +1,30 @@
 import { type NextRequest, NextResponse } from 'next/server';
-import { MONARCH_API_KEY, getMonarchUrl } from '../utils';
+import {
+  MONARCH_METRICS_API_KEY,
+  MONARCH_METRICS_TIMEOUT_MS,
+  fetchMonarchUpstream,
+  getMonarchMetricsUrl,
+  getMonarchRouteFailure,
+} from '../utils';
 import { reportApiRouteError } from '@/utils/sentry-server';
 
 export async function GET(req: NextRequest) {
-  if (!MONARCH_API_KEY) {
-    console.error('[Monarch Metrics API] Missing MONARCH_API_KEY');
+  if (!MONARCH_METRICS_API_KEY) {
+    console.error('[Monarch Metrics API] Missing MONARCH_METRICS_API_KEY');
     return NextResponse.json({ error: 'Server configuration error' }, { status: 500 });
   }
 
   const searchParams = req.nextUrl.searchParams;
 
   try {
-    const url = getMonarchUrl('/v1/markets/metrics');
+    const url = getMonarchMetricsUrl('/v1/markets/metrics');
     for (const key of ['chain_id', 'sort_by', 'sort_order', 'limit', 'offset']) {
       const value = searchParams.get(key);
       if (value) url.searchParams.set(key, value);
     }
 
-    const response = await fetch(url, {
-      headers: { 'X-API-Key': MONARCH_API_KEY },
-      cache: 'no-store',
+    const response = await fetchMonarchUpstream(url, MONARCH_METRICS_TIMEOUT_MS, {
+      headers: { 'X-API-Key': MONARCH_METRICS_API_KEY },
     });
 
     if (!response.ok) {
@@ -30,12 +35,14 @@ export async function GET(req: NextRequest) {
 
     return NextResponse.json(await response.json());
   } catch (error) {
+    const failure = getMonarchRouteFailure(error, 'Failed to fetch market metrics', 'Monarch metrics request timed out');
+
     reportApiRouteError(error, {
       route: '/api/monarch/metrics',
       method: 'GET',
-      status: 500,
+      status: failure.status,
     });
     console.error('[Monarch Metrics API] Failed to fetch:', error);
-    return NextResponse.json({ error: 'Failed to fetch market metrics' }, { status: 500 });
+    return NextResponse.json({ error: failure.message }, { status: failure.status });
   }
 }

app/api/monarch/utils.ts

@@ -1,7 +1,38 @@
-export const MONARCH_API_ENDPOINT = process.env.MONARCH_API_ENDPOINT;
-export const MONARCH_API_KEY = process.env.MONARCH_API_KEY;
+export const MONARCH_METRICS_API_ENDPOINT = process.env.MONARCH_METRICS_API_ENDPOINT;
+export const MONARCH_METRICS_API_KEY = process.env.MONARCH_METRICS_API_KEY;
+export const MONARCH_METRICS_TIMEOUT_MS = 5_000;
 
-export const getMonarchUrl = (path: string): URL => {
-  if (!MONARCH_API_ENDPOINT) throw new Error('MONARCH_API_ENDPOINT not configured');
-  return new URL(path, MONARCH_API_ENDPOINT.replace(/\/$/, ''));
+const isAbortError = (error: unknown): error is Error => error instanceof Error && error.name === 'AbortError';
+
+export const getMonarchRouteFailure = (
+  error: unknown,
+  fallbackMessage: string,
+  timeoutMessage: string,
+): {
+  message: string;
+  status: number;
+} => {
+  return isAbortError(error) ? { message: timeoutMessage, status: 504 } : { message: fallbackMessage, status: 500 };
+};
+
+export const fetchMonarchUpstream = async (input: URL | string, timeoutMs: number, init: RequestInit): Promise<Response> => {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, timeoutMs);
+
+  try {
+    return await fetch(input, {
+      ...init,
+      cache: 'no-store',
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+export const getMonarchMetricsUrl = (path: string): URL => {
+  if (!MONARCH_METRICS_API_ENDPOINT) throw new Error('MONARCH_METRICS_API_ENDPOINT not configured');
+  return new URL(path, MONARCH_METRICS_API_ENDPOINT.replace(/\/$/, ''));
 };

docs/TECHNICAL_OVERVIEW.md

@@ -6,7 +6,7 @@ Monarch is a client-side DeFi dashboard for the Morpho Blue lending protocol. It
 
 **Key Architectural Decisions:**
 - Next.js 15 App Router with React 18
-- Dual data source strategy: Morpho API (primary) → Subgraph (fallback)
+- Multi-source strategy: Morpho API + Monarch API + selective subgraph fallback
 - Zustand for client state, React Query for server state
 - All user data in localStorage (no backend DB)
 - Multi-chain support with custom RPC override capability
@@ -148,12 +148,18 @@ MorphoChainlinkOracleData {
 
 ## Data Sources
 
-### Dual-Source Strategy
+### Multi-Source Strategy
 
 ```
-Primary: Morpho API (https://blue-api.morpho.org/graphql)
-         ↓ (if unavailable or unsupported chain)
-Fallback: Subgraph (The Graph / Goldsky)
+Markets / positions: Morpho API (https://blue-api.morpho.org/graphql)
+                    ↓ (if unavailable or unsupported chain)
+                    Subgraph (The Graph / Goldsky)
+
+Autovault metadata: Monarch GraphQL (https://api.monarchlend.xyz/graphql)
+                   ↓ (if indexer lag / API failure)
+                   Narrow on-chain RPC fallback
+
+Market metrics: Monarch metrics API via `/api/monarch/metrics`
 ```
 
 **Morpho API Supported Chains:** Mainnet, Base, Unichain, Polygon, Arbitrum, HyperEVM, Monad
@@ -175,7 +181,9 @@ Fallback: Subgraph (The Graph / Goldsky)
 | Market state (APY, utilization) | Morpho API | 30s stale | `useMarketData` |
 | User positions | Morpho API + on-chain | 5 min | `useUserPositions` |
 | Vaults list | Morpho API | 5 min | `useAllMorphoVaultsQuery` |
-| Vault allocations | On-chain (Wagmi) | On demand | `useAllocations` |
+| User autovault metadata | Monarch GraphQL + on-chain enrichment | 60s | `useUserVaultsV2Query` |
+| Vault detail/settings metadata | Monarch GraphQL + narrow RPC fallback | 30s | `useVaultV2Data` |
+| Vault allocations | On-chain multicall | 30s | `useAllocationsQuery` |
 | Token balances | On-chain multicall | 5 min | `useUserBalancesQuery` |
 | Oracle prices | Morpho API | 5 min | `useOracleDataQuery` |
 | Merkl rewards | Merkl API | On demand | `useMerklCampaignsQuery` |
@@ -200,9 +208,11 @@ Split: allMarkets vs whitelistedMarkets
 
 **Vault Data Flow:**
 ```
-1. Fetch vault list from API
-2. Wagmi contract reads for owner, curator, caps
-3. Historical allocations via subgraph
+1. Fetch chain-scoped vault metadata from Monarch GraphQL
+2. Enrich user-specific balances / totalAssets via multicall where needed
+3. Use narrow RPC fallback only when Monarch vault metadata is unavailable
+4. Fetch live allocations from on-chain `allocation(capId)` reads
+5. After vault writes, use shared bounded retry refreshes so Monarch indexing can catch up
 ```
 
 ---
@@ -256,6 +266,7 @@ All hooks in `/src/hooks/queries/` follow React Query patterns:
 | `useOracleDataQuery` | `['oracle-data']` | 5 min | 5 min | Yes |
 | `useUserBalancesQuery` | `['user-balances', addr, networks]` | 30s | - | Yes |
 | `useUserVaultsV2Query` | `['user-vaults-v2', addr]` | 60s | - | Yes |
+| `useVaultV2Data` | `['vault-v2-data', addr, chainId]` | 30s | - | No |
 | `useMarketLiquidations` | `['marketLiquidations', id, net]` | 5 min | - | Yes |
 | `useUserTransactionsQuery` | `['user-transactions', ...]` | 60s | - | No |
 | `useAllocationsQuery` | `['vault-allocations', ...]` | 30s | - | No |
@@ -281,6 +292,11 @@ Fallback Strategy:
 - `cache: 'no-store'` (disable browser cache)
 - Throws on GraphQL errors (strict)
 
+**Monarch GraphQL** (`/src/data-sources/monarch-api/fetchers.ts`):
+- Endpoint: `NEXT_PUBLIC_MONARCH_API_NEW`
+- Browser fetch with `NEXT_PUBLIC_MONARCH_API_KEY`
+- Used as the primary read path for autovault V2 metadata
+
 **Subgraph** (`/src/data-sources/subgraph/fetchers.ts`):
 - Configurable URL per network
 - Logs GraphQL errors but continues (lenient)
@@ -322,6 +338,8 @@ Fallback Strategy:
 | Service | Endpoint | Purpose |
 |---------|----------|---------|
 | Morpho API | `https://blue-api.morpho.org/graphql` | Markets, vaults, positions |
+| Monarch GraphQL | `https://api.monarchlend.xyz/graphql` | Autovault metadata, adapters, caps |
+| Monarch Metrics | `/api/monarch/metrics` → external Monarch metrics API | Market metrics and admin stats |
 | The Graph | Per-chain subgraph URLs | Fallback data, suppliers, borrowers |
 | Merkl API | `https://api.merkl.xyz` | Reward campaigns |
 | Velora API | `https://api.paraswap.io` | Swap quotes and executable tx payloads |

src/abis/morpho-market-v1-adapter-v2-factory.ts

@@ -0,0 +1,11 @@
+import type { Abi } from 'viem';
+
+export const adapterV2FactoryAbi = [
+  {
+    inputs: [{ internalType: 'address', name: 'parentVault', type: 'address' }],
+    name: 'createMorphoMarketV1AdapterV2',
+    outputs: [],
+    stateMutability: 'nonpayable',
+    type: 'function',
+  },
+] as const satisfies Abi;

src/components/common/settings-modal/SettingsHeader.tsx

@@ -3,13 +3,14 @@
 import { ArrowLeftIcon, Cross2Icon } from '@radix-ui/react-icons';
 
 type SettingsHeaderProps = {
+  actions?: React.ReactNode;
   title: string;
   showBack?: boolean;
   onBack?: () => void;
   onClose: () => void;
 };
 
-export function SettingsHeader({ title, showBack, onBack, onClose }: SettingsHeaderProps) {
+export function SettingsHeader({ actions, title, showBack, onBack, onClose }: SettingsHeaderProps) {
   return (
     <div className="flex h-14 items-center justify-between border-b border-border px-6">
       <div className="flex items-center gap-3">
@@ -25,14 +26,17 @@ export function SettingsHeader({ title, showBack, onBack, onClose }: SettingsHea
         )}
         <h2 className="font-zen text-lg text-primary">{title}</h2>
       </div>
-      <button
-        type="button"
-        onClick={onClose}
-        className="flex h-8 w-8 items-center justify-center rounded-full text-secondary transition-colors hover:bg-surface hover:text-primary"
-        aria-label="Close settings"
-      >
-        <Cross2Icon className="h-4 w-4" />
-      </button>
+      <div className="flex items-center gap-1">
+        {actions}
+        <button
+          type="button"
+          onClick={onClose}
+          className="flex h-8 w-8 items-center justify-center rounded-full text-secondary transition-colors hover:bg-surface hover:text-primary"
+          aria-label="Close settings"
+        >
+          <Cross2Icon className="h-4 w-4" />
+        </button>
+      </div>
     </div>
   );
 }

src/components/providers/QueryProvider.tsx

@@ -21,7 +21,6 @@ const ACTIONABLE_QUERY_ROOT_KEYS = new Set<string>([
   'markets',
   'monarch-transactions',
   'merkl-campaigns',
-  'morpho-market-v1-adapters',
   'oracle-data',
   'oracle-metadata',
   'morpho-vaults',

src/data-sources/monarch-api/fetchers.ts

@@ -0,0 +1,53 @@
+type GraphQLVariables = Record<string, unknown>;
+
+type GraphQLError = {
+  message?: string;
+};
+
+type MonarchGraphqlFetcherOptions = {
+  signal?: AbortSignal;
+};
+
+const MONARCH_GRAPHQL_API_ENDPOINT = process.env.NEXT_PUBLIC_MONARCH_API_NEW;
+const MONARCH_GRAPHQL_API_KEY = process.env.NEXT_PUBLIC_MONARCH_API_KEY;
+
+export const monarchGraphqlFetcher = async <T extends Record<string, unknown>>(
+  query: string,
+  variables: GraphQLVariables = {},
+  options: MonarchGraphqlFetcherOptions = {},
+): Promise<T> => {
+  if (!MONARCH_GRAPHQL_API_ENDPOINT || !MONARCH_GRAPHQL_API_KEY) {
+    throw new Error('Monarch GraphQL client not configured');
+  }
+
+  const response = await fetch(MONARCH_GRAPHQL_API_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${MONARCH_GRAPHQL_API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      query,
+      variables,
+    }),
+    cache: 'no-store',
+    signal: options.signal,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Monarch API request failed: ${response.status} ${response.statusText}`);
+  }
+
+  const result = (await response.json()) as T & { errors?: GraphQLError[] };
+
+  if (result.errors && result.errors.length > 0) {
+    const message =
+      result.errors
+        .map((error) => error.message)
+        .filter(Boolean)
+        .join('; ') || 'Unknown Monarch GraphQL error';
+    throw new Error(message);
+  }
+
+  return result;
+};

src/data-sources/monarch-api/index.ts

@@ -0,0 +1,9 @@
+export { monarchGraphqlFetcher } from './fetchers';
+export {
+  fetchMonarchVaultDetails,
+  fetchUserVaultV2DetailsAllNetworks,
+  type VaultAdapterDetails,
+  type UserVaultV2,
+  type VaultV2Cap,
+  type VaultV2Details,
+} from './vaults';