tapimo 0.19.0 → 0.20.0

package/src/apps/data/routes/earn.ts

@@ -1,4 +1,5 @@
 import { type Context, Hono } from 'hono'
+import { HTTPException } from 'hono/http-exception'
 import { Value as core_Value } from 'ox'
 import { Abis, type Actions } from 'viem/tempo'
 import {
@@ -101,6 +102,8 @@ const scanLimit = 50
 // Concurrent metadata reads in one macrotask collapse into one deployless
 // multicall; an await between small chunks keeps each call under the RPC limit.
 const tokenReadChunkSize = 20
+// Bumped when the public vault shape changes, so no older cached body is served.
+const vaultCacheName = 'tempo-api:earn-vaults:v7'
 const tempoStateAddress = '0x1c00000000000000000000000000000000000000'
 const tempoStateAbi = parseAbi(['function tempoBlockNumber() view returns (uint64)'])
 const zonePortalAbi = parseAbi(['function lastSyncedTempoBlockNumber() view returns (uint64)'])
@@ -168,12 +171,10 @@ export namespace schema {
     export const Association = z
       .strictObject({
         chainId: Schema.ChainId,
-        firstRegisteredAt: z.iso
-          .datetime()
-          .check(
-            z.describe('When the association was first registered.'),
-            z.meta({ examples: ['2026-08-25T20:00:00.000Z'] }),
-          ),
+        firstRegisteredAt: Schema.dateTime().check(
+          z.describe('When the association was first registered.'),
+          z.meta({ examples: ['2026-08-25T20:00:00.000Z'] }),
+        ),
         id: z.string().check(
           z.describe('Stable reward eligibility association identifier.'),
           z.meta({
@@ -182,12 +183,10 @@ export namespace schema {
             ],
           }),
         ),
-        latestRegisteredAt: z.iso
-          .datetime()
-          .check(
-            z.describe('When the association was most recently registered.'),
-            z.meta({ examples: ['2026-08-25T20:00:00.000Z'] }),
-          ),
+        latestRegisteredAt: Schema.dateTime().check(
+          z.describe('When the association was most recently registered.'),
+          z.meta({ examples: ['2026-08-25T20:00:00.000Z'] }),
+        ),
         registrationOrder: z
           .string()
           .check(
@@ -516,16 +515,10 @@ export namespace schema {
     capabilities: z
       .optional(EarnVaults.schema.Discovery.shape.capabilities)
       .check(z.describe('Vault capabilities, when requested.')),
-    description: z
-      .nullable(z.string())
-      .check(
-        z.describe('Curated vault description, or null when the vault is not verified.'),
-        z.meta({ examples: ['deelUSD deposited into the canonical Tempo Earn deployment.'] }),
-      ),
     engine,
     id: Schema.Address.check(
       z.describe('Stable vault id, equal to the lowercase vault address.'),
-      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
+      z.meta({ examples: ['0xb20ba39ccf522d69b7a21e3f369be5de73a2c694'] }),
     ),
     instantLiquidity: EarnVaults.schema.Discovery.shape.instantLiquidity.check(
       z.describe(
@@ -539,9 +532,14 @@ export namespace schema {
           'Instant liquidity valued in USD, when requested via `include=tvl`, or null when liquidity is unavailable or the asset has no priced display currency.',
         ),
       ),
+    // Kept as an empty string for clients that require the field; registry labels name
+    // customers, so only the admin app serves them.
     label: z
       .string()
-      .check(z.describe('Vault display label.'), z.meta({ examples: ['deelUSD Earn'] })),
+      .check(
+        z.describe('Always empty; curated labels are not public.'),
+        z.meta({ examples: [''] }),
+      ),
     sharePrice: z
       .nullable(value)
       .check(
@@ -565,12 +563,6 @@ export namespace schema {
         ],
       }),
     ),
-    slug: z
-      .nullable(z.string())
-      .check(
-        z.describe('Curated URL slug, or null when the vault is not verified.'),
-        z.meta({ examples: ['deelusd-earn'] }),
-      ),
     state: EarnVaults.schema.Discovery.shape.state,
     tvl: z
       .optional(z.nullable(value))
@@ -581,7 +573,7 @@ export namespace schema {
       ),
     vaultAddress: Schema.Address.check(
       z.describe('Earn vault contract address.'),
-      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
+      z.meta({ examples: ['0xb20ba39ccf522d69b7a21e3f369be5de73a2c694'] }),
     ),
     verified: z
       .boolean()
@@ -617,10 +609,35 @@ export namespace schema {
     'EarnVault',
   )
 
+  // Registry labels name customers, so only the admin app serves them.
+  const curatedVault = z.extend(vault, {
+    description: z
+      .nullable(z.string())
+      .check(
+        z.describe('Curated vault description, or null when the vault is not verified.'),
+        z.meta({ examples: ['pathUSD deposited into the canonical Tempo Earn deployment.'] }),
+      ),
+    label: z
+      .string()
+      .check(z.describe('Vault display label.'), z.meta({ examples: ['Sentora pathUSD (Earn)'] })),
+    slug: z
+      .nullable(z.string())
+      .check(
+        z.describe('Curated URL slug, or null when the vault is not verified.'),
+        z.meta({ examples: ['sentora-pathusd-earn'] }),
+      ),
+  })
+
+  /** One Earn vault with its curated registry label, slug, and description. */
+  export const CuratedVault = Schema.describe(
+    curatedVault,
+    'A compatible earn vault with its curated registry fields.',
+  )
+
   /** One registry-curated Earn vault. */
   export const VerifiedVault = OpenApi.component(
     Schema.describe(
-      z.extend(vault, {
+      z.extend(curatedVault, {
         engine: z.extend(engine, { type: engineType }),
         slug: z
           .string()
@@ -825,7 +842,7 @@ export namespace schema {
         ),
         id: Schema.Address.check(
           z.describe('Stable resource ID for this position, equal to the vault address.'),
-          z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
+          z.meta({ examples: ['0xb20ba39ccf522d69b7a21e3f369be5de73a2c694'] }),
         ),
         lifetimeCashFlows: z
           .optional(lifetimeCashFlows)
@@ -847,7 +864,7 @@ export namespace schema {
         ),
         vaultAddress: Schema.Address.check(
           z.describe('Earn vault contract address holding this position.'),
-          z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
+          z.meta({ examples: ['0xb20ba39ccf522d69b7a21e3f369be5de73a2c694'] }),
         ),
         verified: z
           .boolean()
@@ -891,28 +908,24 @@ export namespace schema {
     )
 
   const earningsWindow = z.extend(earningsBase, {
-    end: z.iso
-      .datetime()
-      .check(
-        z.describe(
-          'UTC ending boundary. Includes activity through the latest indexed block at or before this timestamp.',
-        ),
-        z.meta({ examples: ['2026-09-18T00:00:00.000Z'] }),
+    end: Schema.dateTime().check(
+      z.describe(
+        'UTC ending boundary. Includes activity through the latest indexed block at or before this timestamp.',
       ),
+      z.meta({ examples: ['2026-09-18T00:00:00.000Z'] }),
+    ),
     period: z
       .enum(['7d', '30d', 'custom'])
       .check(
         z.describe('Rolling or explicitly bounded earnings window.'),
         z.meta({ examples: ['7d'] }),
       ),
-    start: z.iso
-      .datetime()
-      .check(
-        z.describe(
-          'UTC opening boundary. Excludes activity through the latest indexed block at or before this timestamp.',
-        ),
-        z.meta({ examples: ['2026-09-11T00:00:00.000Z'] }),
+    start: Schema.dateTime().check(
+      z.describe(
+        'UTC opening boundary. Excludes activity through the latest indexed block at or before this timestamp.',
       ),
+      z.meta({ examples: ['2026-09-11T00:00:00.000Z'] }),
+    ),
   })
 
   const earnings = z.union([
@@ -1076,60 +1089,16 @@ export namespace schema {
     limit: Schema.Limit,
   })
 
-  const collectionQuery = z
-    .extend(collectionFilters, { 'apy.window': EarnRates.schema.Window })
-    .check(z.describe('Query parameters for listing earn vaults.'))
-
   const vaultSelector = z.strictObject({
     chainId: Schema.ChainIdQuery,
     include: includeQuery,
   })
 
-  /** Schemas for the getEarnVaults operation. */
-  export namespace getEarnVaults {
-    /** Query parameters for all compatible deployed Earn vaults. */
-    export const Query = collectionQuery
-
-    /** Paginated list of compatible deployed Earn vaults. */
-    export const Response = OpenApi.component(
-      z
-        .strictObject({
-          data: z
-            .array(Vault)
-            .check(z.describe('Compatible deployed earn vaults in deployment order.')),
-          meta: z.optional(meta),
-          nextCursor: Schema.NextCursor,
-        })
-        .check(z.describe('A page of compatible deployed earn vaults.')),
-      'EarnVaultList',
-    )
-  }
-
-  /** Schemas for the getVerifiedEarnVaults operation. */
-  export namespace getVerifiedEarnVaults {
-    /** Collection query without rates or valuation, for surfaces that cannot measure them. */
-    export const BaseQuery = Schema.describe(
-      z.extend(collectionFilters, { include: baseIncludeQuery }),
-      'Query parameters for listing earn vaults.',
-    )
-
-    /** Query parameters for registry-curated Earn vaults. */
-    export const Query = collectionQuery
-
-    /** Paginated list of registry-curated Earn vaults. */
-    export const Response = OpenApi.component(
-      z
-        .strictObject({
-          data: z
-            .array(VerifiedVault)
-            .check(z.describe('Registry-curated earn vaults ordered by vault address.')),
-          meta: z.optional(meta),
-          nextCursor: Schema.NextCursor,
-        })
-        .check(z.describe('A page of registry-curated earn vaults.')),
-      'VerifiedEarnVaultList',
-    )
-  }
+  /** Collection filters without rates or valuation, for surfaces that cannot measure them. */
+  export const VaultCollectionQuery = Schema.describe(
+    z.extend(collectionFilters, { include: baseIncludeQuery }),
+    'Query parameters for listing earn vaults.',
+  )
 
   /** Schemas for the getEarnAddressPositions operation. */
   export namespace getEarnAddressPositions {
@@ -1228,7 +1197,7 @@ export namespace schema {
 
   /** Schemas for the getEarnVaultSharePrices operation. */
   export namespace getEarnVaultSharePrices {
-    const timestamp = z.iso.datetime({ offset: true })
+    const timestamp = Schema.dateTime({ offset: true })
 
     /** Path parameters identifying one Earn vault. */
     export const Params = z
@@ -1280,12 +1249,10 @@ export namespace schema {
         sharePrice: value.check(
           z.describe('Assets returned for one whole Earn share at the observation block.'),
         ),
-        timestamp: z.iso
-          .datetime()
-          .check(
-            z.describe('Requested daily observation timestamp.'),
-            z.meta({ examples: ['2026-07-01T00:00:00.000Z'] }),
-          ),
+        timestamp: Schema.dateTime().check(
+          z.describe('Requested daily observation timestamp.'),
+          z.meta({ examples: ['2026-07-01T00:00:00.000Z'] }),
+        ),
       })
       .check(z.describe('One historical Earn vault share price.'))
 
@@ -1319,13 +1286,13 @@ export namespace schema {
 
   /** Schemas for the getEarnVaultPosition operation. */
   export namespace getEarnVaultPosition {
-    const asOf = z.iso.datetime({ offset: true })
+    const asOf = Schema.dateTime({ offset: true })
 
     /** Path parameters identifying the Earn vault and account. */
     export const Params = z
       .strictObject({
         address: Schema.Address.check(z.describe('Account whose earn position to read.')),
-        vaultId: Schema.address('0x4f94590b636f5878bce585e82379de81e1ec174f').check(
+        vaultId: Schema.address('0xb20ba39ccf522d69b7a21e3f369be5de73a2c694').check(
           z.describe('Earn vault contract address.'),
         ),
       })
@@ -1360,12 +1327,10 @@ export namespace schema {
             z.describe('Indexed observation block.'),
             z.meta({ examples: [31039238] }),
           ),
-        timestamp: z.iso
-          .datetime()
-          .check(
-            z.describe('Timestamp of the indexed observation block.'),
-            z.meta({ examples: ['2026-07-21T09:00:00.000Z'] }),
-          ),
+        timestamp: Schema.dateTime().check(
+          z.describe('Timestamp of the indexed observation block.'),
+          z.meta({ examples: ['2026-07-21T09:00:00.000Z'] }),
+        ),
       })
       .check(z.describe('Indexed block used for a historical Earn position observation.'))
 
@@ -1463,7 +1428,7 @@ export namespace schema {
       .strictObject({
         chainId: Schema.ChainIdQuery,
         end: z
-          .optional(z.iso.datetime({ offset: true }))
+          .optional(Schema.dateTime({ offset: true }))
           .check(
             z.describe(
               'Required with period=custom. Inclusive ISO 8601 ending timestamp; indexed history must cover this time.',
@@ -1472,7 +1437,7 @@ export namespace schema {
           ),
         period: z._default(earningsPeriod, 'lifetime'),
         start: z
-          .optional(z.iso.datetime({ offset: true }))
+          .optional(Schema.dateTime({ offset: true }))
           .check(
             z.describe(
               'Required with period=custom. Exclusive ISO 8601 opening timestamp, earlier than end.',
@@ -1646,134 +1611,6 @@ export function earn(options: earn.Options = {}) {
         )
       },
     )
-    .get(
-      '/v1/earn/vaults',
-      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
-      OpenApi.validate('query', schema.getEarnVaults.Query, {
-        code: 'query_invalid',
-        message: 'Invalid query parameters',
-      }),
-      OpenApi.describeRoute({
-        description:
-          'Lists compatible earn vaults discovered from deployment events and resolved from current chain state.',
-        operationId: 'getEarnVaults',
-        responses: OpenApi.responses({
-          errors: {
-            400: {
-              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
-            },
-            502: 'Could not read earn deployment or vault data.',
-          },
-          success: {
-            description: 'A page of compatible deployed earn vaults.',
-            schema: schema.getEarnVaults.Response,
-          },
-        }),
-        summary: 'List vaults',
-        tags: ['Earn'],
-      }),
-      // Live state and rate enrichment are embedded, so every vault read caches
-      // as current-state rather than slow-changing metadata.
-      Cache.response<App.Environment>({
-        cacheControl: Cache.policies.state,
-        key: (c) => vaultCacheKey(c, schema.getEarnVaults.Query),
-        name: 'tempo-api:earn-vaults:v5',
-      }),
-      async (c) => {
-        if (Auth.narrowAccess) return Auth.paidAccessError(c)
-        if (OpenApi.narrowValidation)
-          return Response.error(c, {
-            code: 'chain_id_invalid',
-            message: 'Invalid chain id',
-            status: 400,
-          })
-        if (OpenApi.narrowValidation)
-          return Response.error(c, {
-            code: 'chain_id_unsupported',
-            message: 'Unsupported chain id',
-            status: 400,
-          })
-        if (OpenApi.narrowValidation)
-          return OpenApi.validationError(c, {
-            code: 'query_invalid',
-            message: 'Invalid query parameters',
-          })
-
-        const query = c.req.valid('query')
-        try {
-          const chainId = query.chainId ?? c.get('chainId')
-          const data = await listVaults(c, { ...query, chainId, oracle })
-          return c.json(Response.validated(schema.getEarnVaults.Response, data), 200)
-        } catch (cause) {
-          return Response.upstream(c, cause)
-        }
-      },
-    )
-    .get(
-      '/v1/earn/vaults/verified',
-      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
-      OpenApi.validate('query', schema.getVerifiedEarnVaults.Query, {
-        code: 'query_invalid',
-        message: 'Invalid query parameters',
-      }),
-      OpenApi.describeRoute({
-        description:
-          'Lists registry-curated earn vaults after resolving their current onchain configuration.',
-        operationId: 'getVerifiedEarnVaults',
-        responses: OpenApi.responses({
-          errors: {
-            400: {
-              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
-            },
-            502: 'Could not read curated earn registry or vault data.',
-          },
-          success: {
-            description: 'A page of registry-curated earn vaults.',
-            schema: schema.getVerifiedEarnVaults.Response,
-          },
-        }),
-        summary: 'List verified vaults',
-        tags: ['Earn'],
-      }),
-      Cache.response<App.Environment>({
-        cacheControl: Cache.policies.state,
-        key: (c) => vaultCacheKey(c, schema.getVerifiedEarnVaults.Query),
-        name: 'tempo-api:earn-vaults:v4',
-      }),
-      async (c) => {
-        if (Auth.narrowAccess) return Auth.paidAccessError(c)
-        if (OpenApi.narrowValidation)
-          return Response.error(c, {
-            code: 'chain_id_invalid',
-            message: 'Invalid chain id',
-            status: 400,
-          })
-        if (OpenApi.narrowValidation)
-          return Response.error(c, {
-            code: 'chain_id_unsupported',
-            message: 'Unsupported chain id',
-            status: 400,
-          })
-        if (OpenApi.narrowValidation)
-          return OpenApi.validationError(c, {
-            code: 'query_invalid',
-            message: 'Invalid query parameters',
-          })
-
-        const query = c.req.valid('query')
-        try {
-          const chainId = query.chainId ?? c.get('chainId')
-          const data = await listVerifiedVaults(c, {
-            ...query,
-            chainId,
-            oracle,
-          })
-          return c.json(Response.validated(schema.getVerifiedEarnVaults.Response, data), 200)
-        } catch (cause) {
-          return Response.upstream(c, cause)
-        }
-      },
-    )
     .get(
       '/v1/earn/addresses/:address/positions',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -2310,8 +2147,13 @@ export function earn(options: earn.Options = {}) {
       }),
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
-        key: (c) => vaultCacheKey(c, schema.getEarnVault.Query),
-        name: 'tempo-api:earn-vaults:v4',
+        key: (c) => {
+          const url = new URL(vaultCacheKey(c, schema.getEarnVault.Query))
+          // The outer edge cache uses this URL, not the inner cache namespace.
+          url.searchParams.set('cache', vaultCacheName)
+          return url.toString()
+        },
+        name: vaultCacheName,
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -2357,6 +2199,8 @@ export function earn(options: earn.Options = {}) {
               message: 'Earn vault not found',
               status: 404,
             })
+          // A Zone access refusal (`ZoneAccess.visible`) is no upstream failure; it keeps its own status and code.
+          if (cause instanceof HTTPException) throw cause
           return Response.upstream(c, cause)
         }
       },
@@ -3367,273 +3211,6 @@ declare namespace getActiveCostBasis {
   }
 }
 
-/** Lists compatible deployed Earn vaults. */
-export async function listVaults(c: Context<App.Environment>, options: listVaults.Options) {
-  const db = Db.get(c.get('dbCached'))
-  const [records, snapshot] = await Promise.all([
-    core_EarnVaults.list(db, { chainId: options.chainId }),
-    VerifiedTokens.snapshot(c, options.chainId),
-  ])
-  const include = vaultInclude(options)
-  const apyByVault = new Map<string, EarnRates.Apy | null>()
-  const registry = new Map(records.map((record) => [record.vaultAddress.toLowerCase(), record]))
-  const decoded = options.cursor ? Cursor.decode(options.cursor, ['int', 'int']) : undefined
-  let position = decoded
-    ? ([Number(decoded[0]), Number(decoded[1])] as listVaults.Position)
-    : undefined
-  let hasMore = false
-  let scanned = 0
-  const matches: listVaults.Match[] = []
-
-  while (matches.length <= options.limit && scanned < maxScannedDeployments) {
-    const page = await queryDeployments(c, {
-      asset: options.asset,
-      chainId: options.chainId,
-      cursor: position,
-      limit: discoveryBatchLimit({
-        filtered: options.capability.length > 0 || options['engine.type'] !== undefined,
-        limit: options.limit,
-        matches: matches.length,
-        remaining: maxScannedDeployments - scanned,
-      }),
-    })
-    hasMore = page.hasMore
-    if (page.items.length === 0) {
-      hasMore = false
-      break
-    }
-    scanned += page.items.length
-
-    const apyVaults =
-      apyByVault.size === 0 &&
-      include.includes('apy') &&
-      options.capability.length === 0 &&
-      options['engine.type'] === undefined
-        ? page.items
-            .slice(0, options.limit - matches.length)
-            .map(({ vaultAddress }) => vaultAddress)
-        : []
-    // Rate boundaries and historical quotes depend only on candidate addresses,
-    // so the unfiltered page can resolve them alongside live vault discovery.
-    const [discovered, prefetchedApy] = await Promise.all([
-      Promise.all(
-        page.items.map(async (item) => {
-          const record = registry.get(item.vaultAddress.toLowerCase())
-          try {
-            const discovered = await resolveVaultDiscovery(c, {
-              chainId: options.chainId,
-              include: discoveryInclude(options),
-              vaultAddress: item.vaultAddress,
-            })
-            const { discovery, zoneRoutes } = await resolveVaultRoutes(c, {
-              capability: options.capability,
-              discovery: discovered,
-              include,
-              record,
-            })
-            return { discovery, position: item.position, record, zoneRoutes }
-          } catch (cause) {
-            if (!record && isIncompatible(cause)) return undefined
-            throw cause
-          }
-        }),
-      ),
-      apyVaults.length > 0
-        ? resolvePageApy(c, {
-            chainId: options.chainId,
-            include,
-            vaults: apyVaults,
-            window: options['apy.window'],
-          })
-        : undefined,
-    ])
-    for (const [vault, apy] of prefetchedApy ?? []) apyByVault.set(vault, apy)
-    for (const match of discovered) {
-      if (!match || !matchesVaultFilters(match.discovery, options)) continue
-      matches.push(match)
-    }
-
-    position = page.items.at(-1)!.position
-    if (!hasMore) break
-  }
-
-  const page = matches.slice(0, options.limit)
-  const discoveries = page.map(({ discovery }) => discovery)
-  const missingApyVaults = include.includes('apy')
-    ? discoveries.flatMap(({ vaultAddress }) =>
-        apyByVault.has(vaultAddress.toLowerCase()) ? [] : [vaultAddress],
-      )
-    : []
-  const [missingApy, rates, rewards, tokens] = await Promise.all([
-    missingApyVaults.length > 0
-      ? resolvePageApy(c, {
-          chainId: options.chainId,
-          include,
-          vaults: missingApyVaults,
-          window: options['apy.window'],
-        })
-      : undefined,
-    resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
-    resolvePageRewards(c, {
-      chainId: options.chainId,
-      include,
-      vaults: discoveries.map(({ vaultAddress }) => vaultAddress),
-    }),
-    resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
-  ])
-  for (const [vault, apy] of missingApy ?? []) apyByVault.set(vault, apy)
-  const apy = include.includes('apy') ? apyByVault : undefined
-  const data = await Promise.all(
-    page.map((match) =>
-      resolveVault(c, {
-        ...match,
-        apy,
-        include,
-        rates,
-        rewards: rewards?.get(match.discovery.vaultAddress),
-        snapshot,
-        tokens,
-      }),
-    ),
-  )
-  const last = matches[options.limit - 1]
-  const nextPosition =
-    matches.length > options.limit ? last?.position : hasMore ? position : undefined
-  return {
-    data,
-    ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
-    nextCursor: nextPosition ? Cursor.encode(nextPosition) : null,
-  }
-}
-
-export declare namespace listVaults {
-  /** One compatible deployment found while scanning TIDX. */
-  type Match = {
-    discovery: EarnVaults.Discovery
-    position: Position
-    record?: RegistryRecord | undefined
-    zoneRoutes: readonly EarnVaults.ResolvedZoneRoute[]
-  }
-
-  /** Options for listing compatible Earn vaults. */
-  type Options = z.output<typeof schema.getEarnVaults.Query> & {
-    chainId: z.output<typeof Schema.ChainId>
-    /** FX rate oracle backing TVL valuation. */
-    oracle: FxOracle.Oracle
-  }
-
-  /** TIDX deployment cursor position. */
-  type Position = [number, number]
-}
-
-/** Lists registry-curated Earn vaults. */
-export async function listVerifiedVaults(
-  c: Context<App.Environment>,
-  options: listVerifiedVaults.Options,
-) {
-  const db = Db.get(c.get('dbCached'))
-  const [records, snapshot] = await Promise.all([
-    core_EarnVaults.list(db, { chainId: options.chainId }),
-    VerifiedTokens.snapshot(c, options.chainId),
-  ])
-  const decoded = options.cursor ? Cursor.decode(options.cursor, ['address']) : undefined
-  const cursor = decoded?.[0]?.toString().toLowerCase()
-  const candidates = records.filter(
-    (record) => !cursor || record.vaultAddress.toLowerCase() > cursor,
-  )
-  const include = vaultInclude(options)
-  const matches: listVerifiedVaults.Match[] = []
-
-  let offset = 0
-  while (offset < candidates.length && matches.length <= options.limit) {
-    const batchSize = discoveryBatchLimit({
-      filtered: options.capability.length > 0 || options['engine.type'] !== undefined,
-      limit: options.limit,
-      matches: matches.length,
-      remaining: candidates.length - offset,
-    })
-    const batch = candidates.slice(offset, offset + batchSize)
-    offset += batch.length
-    const discovered = await Promise.all(
-      batch.map(async (record) => {
-        const discovered = await resolveVaultDiscovery(c, {
-          chainId: options.chainId,
-          include: discoveryInclude(options),
-          vaultAddress: Schema.Address.parse(record.vaultAddress.toLowerCase()),
-        })
-        const { discovery, zoneRoutes } = await resolveVaultRoutes(c, {
-          capability: options.capability,
-          discovery: discovered,
-          include,
-          record,
-        })
-        return { discovery, record, zoneRoutes }
-      }),
-    )
-    for (const match of discovered) {
-      if (!matchesVaultFilters(match.discovery, options)) continue
-      matches.push(match)
-    }
-  }
-
-  const page = matches.slice(0, options.limit)
-  const discoveries = page.map(({ discovery }) => discovery)
-  const [apy, rates, rewards, tokens] = await Promise.all([
-    resolvePageApy(c, {
-      chainId: options.chainId,
-      include,
-      vaults: discoveries.map(({ vaultAddress }) => vaultAddress),
-      window: options['apy.window'],
-    }),
-    resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
-    resolvePageRewards(c, {
-      chainId: options.chainId,
-      include,
-      vaults: discoveries.map(({ vaultAddress }) => vaultAddress),
-    }),
-    resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
-  ])
-  const data = await Promise.all(
-    page.map(async (match) =>
-      Response.validated(
-        schema.VerifiedVault,
-        await resolveVault(c, {
-          ...match,
-          apy,
-          include,
-          rates,
-          rewards: rewards?.get(match.discovery.vaultAddress),
-          snapshot,
-          tokens,
-        }),
-      ),
-    ),
-  )
-  const last = matches[options.limit - 1]
-  return {
-    data,
-    ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
-    nextCursor:
-      matches.length > options.limit && last ? Cursor.encode([last.record.vaultAddress]) : null,
-  }
-}
-
-export declare namespace listVerifiedVaults {
-  /** One verified vault and its current onchain state. */
-  type Match = {
-    discovery: EarnVaults.Discovery
-    record: RegistryRecord
-    zoneRoutes: readonly EarnVaults.ResolvedZoneRoute[]
-  }
-
-  /** Options for listing verified Earn vaults. */
-  type Options = z.output<typeof schema.getVerifiedEarnVaults.Query> & {
-    chainId: z.output<typeof Schema.ChainId>
-    /** FX rate oracle backing TVL valuation. */
-    oracle: FxOracle.Oracle
-  }
-}
-
 /** Reads daily historical share prices for one Earn vault. */
 export async function getVaultSharePrices(
   c: Context<App.Environment>,
@@ -4914,7 +4491,7 @@ export async function getVault(c: Context<App.Environment>, options: getVault.Op
   try {
     const discovered = await resolveVaultDiscovery(c, {
       chainId: options.chainId,
-      include: discoveryInclude({ capability: [], include: options.include }),
+      include: discoveryInclude({ include: options.include }),
       vaultAddress: options.vaultAddress,
     })
     const include = vaultInclude(options)
@@ -5008,9 +4585,7 @@ function discoveryInclude(
   options: discoveryInclude.Options,
 ): readonly EarnVaults.resolve.Include[] {
   const includeCapabilities =
-    options.include.includes('capabilities') ||
-    options.include.includes('zone') ||
-    options.capability.length > 0
+    options.include.includes('capabilities') || options.include.includes('zone')
   return [
     ...(options.include.includes('access') ? (['access'] as const) : []),
     ...(includeCapabilities ? (['capabilities'] as const) : []),
@@ -5018,7 +4593,7 @@ function discoveryInclude(
 }
 
 declare namespace discoveryInclude {
-  type Options = Pick<z.output<typeof schema.getEarnVaults.Query>, 'capability' | 'include'>
+  type Options = Pick<z.output<typeof schema.getEarnVault.Query>, 'include'>
 }
 
 async function resolveVaultDiscovery(
@@ -5076,11 +4651,13 @@ async function resolveVaultRoutes(
     options.include.includes('capabilities') ||
     options.capability.includes('privateRouting') ||
     options.capability.includes('routerSwaps')
-  const visibleRoutes = record.zones.filter(
-    (route) => ZoneAccess.check(c, { chainId: route.chainId, verb: 'read' }).allowed,
-  )
-  // Capabilities describe the vault; API-key scopes limit only the route metadata.
-  const routes = needsCapabilities ? record.zones : includesRoutes ? visibleRoutes : []
+  await ZoneAccess.ensure(c)
+  // Capabilities describe the vault; API-key scopes limit only the route metadata, checked only when requested.
+  const routes = needsCapabilities
+    ? record.zones
+    : includesRoutes
+      ? record.zones.filter((route) => ZoneAccess.visible(c, { chainId: route.chainId }))
+      : []
   if (routes.length === 0) return { discovery, zoneRoutes: [] }
 
   const resolved = await EarnVaults.resolveZoneRoutes({
@@ -5097,16 +4674,14 @@ async function resolveVaultRoutes(
       ? { ...discovery, capabilities: EarnVaults.addZoneRouteCapabilities(capabilities) }
       : discovery,
     zoneRoutes: includesRoutes
-      ? resolved.filter(
-          (route) => ZoneAccess.check(c, { chainId: route.chainId, verb: 'read' }).allowed,
-        )
+      ? resolved.filter((route) => ZoneAccess.visible(c, { chainId: route.chainId }))
       : [],
   }
 }
 
 declare namespace resolveVaultRoutes {
   type Options = {
-    capability: z.output<typeof schema.getEarnVaults.Query>['capability']
+    capability: z.output<typeof schema.VaultCollectionQuery>['capability']
     discovery: EarnVaults.Discovery
     include: z.output<typeof schema.getEarnVault.Query>['include']
     record?: RegistryRecord | undefined
@@ -5289,27 +4864,6 @@ function resolvePageApy(c: Context<App.Environment>, options: resolvePageApy.Opt
   )
 }
 
-function resolvePageRewards(c: Context<App.Environment>, options: resolvePageRewards.Options) {
-  if (!options.include.includes('apy')) return undefined
-  return Timing.time(c, 'earn_rewards_apy', () =>
-    RewardRead.resolveCollection({
-      chainId: options.chainId,
-      db: c.get('dbCached'),
-      vaults: options.vaults,
-    }).catch(() => {
-      Cache.setPolicy(c, Cache.policies.noStore)
-      const failure = {
-        chainId: options.chainId,
-        failure: 'unknown',
-        id: 'earn-rewards',
-        operation: 'listVaultRewards',
-      } satisfies Log.ProviderFailure
-      c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure])
-      return new Map<string, readonly RewardRead.Reward[]>()
-    }),
-  )
-}
-
 function resolveVaultRewards(c: Context<App.Environment>, options: resolveVaultRewards.Options) {
   if (!options.include.includes('apy')) return undefined
   return Timing.time(c, 'earn_rewards_apy', () =>
@@ -5339,14 +4893,6 @@ declare namespace resolveVaultRewards {
   }
 }
 
-declare namespace resolvePageRewards {
-  type Options = {
-    chainId: z.output<typeof Schema.ChainId>
-    include: z.output<typeof schema.getEarnVault.Query>['include']
-    vaults: readonly z.output<typeof Schema.Address>[]
-  }
-}
-
 declare namespace resolvePageApy {
   type Options = {
     chainId: z.output<typeof Schema.ChainId>
@@ -5413,9 +4959,11 @@ declare namespace resolvePageTokens {
 
 async function resolveVault(c: Context<App.Environment>, options: resolveVault.Options) {
   const { discovery, record } = options
-  const zones = [...c.get('zones').values()].filter(
-    (zone) => ZoneAccess.check(c, { chainId: zone.id, verb: 'read' }).allowed,
-  )
+  await ZoneAccess.ensure(c)
+  // Only `include=zone` reads Zones, so other reads never fail on an unreadable delegation.
+  const zones = options.include.includes('zone')
+    ? [...c.get('zones').values()].filter((zone) => ZoneAccess.visible(c, { chainId: zone.id }))
+    : []
   const valued = options.include.includes('tvl')
     ? Valuation.valuationFor({
         amount: BigInt(discovery.state.totalAssets),
@@ -5521,7 +5069,6 @@ export function serializeVault(options: serializeVault.Options): z.output<typeof
     ...(options.include.includes('apy') ? { apy } : {}),
     assetToken: options.assetToken,
     ...(options.include.includes('capabilities') ? { capabilities: discovery.capabilities } : {}),
-    description: record?.description ?? null,
     engine: {
       address: discovery.engine.address.toLowerCase(),
       type: discovery.engine.type,
@@ -5532,7 +5079,7 @@ export function serializeVault(options: serializeVault.Options): z.output<typeof
     ...(options.include.includes('tvl')
       ? { instantLiquidityValue: options.instantLiquidityValue }
       : {}),
-    label: record?.label ?? options.shareToken.name,
+    label: '',
     sharePrice:
       discovery.sharePrice === null
         ? null
@@ -5543,7 +5090,6 @@ export function serializeVault(options: serializeVault.Options): z.output<typeof
             formatted: core_Value.format(BigInt(discovery.sharePrice), options.assetToken.decimals),
           },
     shareToken: options.shareToken,
-    slug: record?.slug ?? null,
     state: discovery.state,
     ...(options.include.includes('tvl') ? { tvl: options.tvl } : {}),
     vaultAddress,
@@ -5645,101 +5191,6 @@ function getToken(
   return Response.validated(Tokens.schema.Token, token)
 }
 
-async function queryDeployments(
-  c: Context<App.Environment>,
-  options: queryDeployments.Options,
-): Promise<queryDeployments.Result> {
-  const factories = deploymentFactories[options.chainId] ?? []
-  if (factories.length === 0) return { hasMore: false, items: [] }
-  const filters: string[] = []
-  if (options.asset) filters.push(`lower(asset) = '${options.asset.toLowerCase()}'`)
-  if (options.cursor)
-    filters.push(
-      Cursor.keyset([
-        {
-          literal: Cursor.literal(options.cursor[0], 'int'),
-          name: 'block_num',
-          order: 'desc',
-        },
-        {
-          literal: Cursor.literal(options.cursor[1], 'int'),
-          name: 'log_idx',
-          order: 'desc',
-        },
-      ]),
-    )
-
-  // Authenticate emitters before deduplication so a forged newer event cannot
-  // replace a factory deployment or suppress it through outer filters.
-  const result = await c
-    .get('getTidx')(options.chainId)
-    .fetch({
-      chainId: options.chainId,
-      engine: 'clickhouse',
-      query: `
-      SELECT "earnVault", asset, block_num, log_idx
-      FROM (
-        SELECT
-          "earnVault",
-          asset,
-          block_num,
-          log_idx
-        FROM EarnStackDeployed
-        WHERE address IN (${factories.map((address) => `'${address}'`).join(', ')})
-        ORDER BY block_num DESC, log_idx DESC
-        LIMIT 1 BY lower("earnVault")
-      )
-      ${filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : ''}
-      ORDER BY block_num DESC, log_idx DESC
-      LIMIT ${options.limit + 1}
-    ` as string,
-      signatures: [deployedSignature],
-    })
-
-  const rows: readonly Record<string, unknown>[] = result.rows
-  const items = rows.slice(0, options.limit).map((row) => {
-    const vaultAddress = Schema.Address.safeParse(Value.toText(row['earnVault']))
-    const asset = Schema.Address.safeParse(Value.toText(row['asset']))
-    const blockNumber = Value.toNumber(row['block_num'])
-    const logIndex = Value.toNumber(row['log_idx'])
-    if (
-      !vaultAddress.success ||
-      !asset.success ||
-      blockNumber === undefined ||
-      logIndex === undefined
-    )
-      throw new Error('TIDX returned an invalid Earn deployment row.')
-    return {
-      asset: asset.data,
-      position: [blockNumber, logIndex] as queryDeployments.Position,
-      vaultAddress: vaultAddress.data,
-    }
-  })
-  return { hasMore: rows.length > options.limit, items }
-}
-
-declare namespace queryDeployments {
-  type Item = {
-    asset: z.output<typeof Schema.Address>
-    position: Position
-    vaultAddress: z.output<typeof Schema.Address>
-  }
-
-  type Options = {
-    asset?: z.output<typeof Schema.Address> | undefined
-    chainId: z.output<typeof Schema.ChainId>
-    cursor?: Position | undefined
-    limit: number
-  }
-
-  type Position = [number, number]
-
-  type Result = {
-    hasMore: boolean
-    items: readonly Item[]
-  }
-}
-
 /** Tests live vault state against the shared collection filters. */
 export function matchesVaultFilters(
   discovery: EarnVaults.Discovery,
@@ -5758,7 +5209,7 @@ export function matchesVaultFilters(
 export declare namespace matchesVaultFilters {
   /** Filters shared by the all-vault and verified-vault collections. */
   type Options = Pick<
-    z.output<typeof schema.getEarnVaults.Query>,
+    z.output<typeof schema.VaultCollectionQuery>,
     'asset' | 'capability' | 'engine.type'
   >
 }