tapimo 0.7.1 → 0.7.2

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

@@ -0,0 +1,1391 @@
+import { type Context, Hono } from 'hono'
+import { Value as core_Value } from 'ox'
+import {
+  type Chain,
+  ContractFunctionExecutionError,
+  ContractFunctionRevertedError,
+  ContractFunctionZeroDataError,
+} from 'viem'
+import * as z from 'zod/mini'
+
+import type * as App from '../../../App.js'
+import * as Db from '../../../db/Db.js'
+import * as core_EarnVaults from '../../../db/tables/earnVaults.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as Cache from '../../../internal/Cache.js'
+import * as Cursor from '../../../internal/Cursor.js'
+import * as EarnRates from '../../../internal/EarnRates.js'
+import * as EarnVaults from '../../../internal/EarnVaults.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as Store from '../../../internal/Store.js'
+import * as Timing from '../../../internal/Timing.js'
+import * as Ttl from '../../../internal/Ttl.js'
+import * as Value from '../../../internal/Value.js'
+import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
+import * as FxOracle from '../FxOracle.js'
+import * as Tokens from './tokens.js'
+import * as Valuation from './valuation.js'
+
+const deployedSignature =
+  'event EarnStackDeployed(address indexed earnVault,address indexed earnShare,address indexed earnFees,address engine,address asset,address owner,bytes32 deploymentId,address emergencyGuardian,address asyncJanitor,uint8 migrationMode,bytes32 earnShareSalt,bytes32 controlConfigHash,bytes32 feeConfigHash,bytes32 earnFeesSalt)'
+
+const maxScannedDeployments = 250
+const scanLimit = 50
+
+/** Vault TVL is reported in USD only; the API exposes no denomination parameter. */
+const tvlDenomination = 'USD'
+
+/** `Valuation.valuationFor` floors to 6 dp, so 6 is the precision a valued amount carries. */
+const tvlDecimals = 6
+
+/** Returns the smallest useful live-discovery batch. */
+export function discoveryBatchLimit(options: discoveryBatchLimit.Options): number {
+  const needed = options.limit + 1 - options.matches
+  return Math.min(options.filtered ? needed * 2 : needed, options.remaining, scanLimit)
+}
+
+export declare namespace discoveryBatchLimit {
+  /** Inputs controlling one discovery batch. */
+  type Options = {
+    /** Whether filters can reject resolved candidates. */
+    filtered: boolean
+    /** Requested response page size. */
+    limit: number
+    /** Compatible matches already collected. */
+    matches: number
+    /** Candidates remaining within the scan bound. */
+    remaining: number
+  }
+}
+
+/** Zod schemas owned by the public Earn-vault resource. */
+export namespace schema {
+  const capability = z
+    .enum([
+      'asyncRedeem',
+      'boundedRedeem',
+      'deposit',
+      'exactWithdraw',
+      'inKindDeposit',
+      'privateRouting',
+      'redeem',
+      'routerSwaps',
+    ])
+    .check(z.describe('Vault capability required by the request.'))
+
+  const engineType = z
+    .enum(['erc4626', 'veda'])
+    .check(z.describe('Inferred vault engine type.'), z.meta({ examples: ['erc4626'] }))
+
+  const engine = Schema.describe(
+    z.strictObject({
+      address: Schema.Address.check(
+        z.describe('Current vault engine contract address.'),
+        z.meta({ examples: ['0xd85fc943333a6cd7c0e3391acd54fc4e572f0baf'] }),
+      ),
+      type: z
+        .nullable(engineType)
+        .check(z.describe('Inferred engine type, or null when it is unknown.')),
+      venue: z
+        .nullable(
+          Schema.Address.check(
+            z.describe('Yield venue contract bound to the engine.'),
+            z.meta({ examples: ['0xa8b4f0e69cd4b0e56b676343f02acd8c3b355322'] }),
+          ),
+        )
+        .check(z.describe('Yield venue, or null when the engine does not expose one.')),
+    }),
+    'Current vault engine.',
+  )
+
+  const include = z
+    .enum(['access', 'apy', 'capabilities', 'token.logoUri', 'tvl', 'zone'])
+    .check(z.describe('Optional vault fields to embed via `include`.'))
+
+  const includeQuery = Schema.includeQuery(
+    include,
+    'Comma-separated vault fields to include, such as `apy,tvl`.',
+  )
+
+  // `apy` and `tvl` need indexer and FX access, so surfaces lacking either
+  // select from this reduced set instead.
+  const baseInclude = z
+    .enum(['access', 'capabilities', 'token.logoUri', 'zone'])
+    .check(z.describe('Optional vault fields to embed via `include`.'))
+
+  const baseIncludeQuery = Schema.includeQuery(
+    baseInclude,
+    'Comma-separated vault fields to include, such as `access,zone`.',
+  )
+
+  const zone = z
+    .strictObject({
+      chainId: Schema.ChainId.check(
+        z.describe('Private Zone chain id.'),
+        z.meta({ examples: [421700001] }),
+      ),
+      inputTokens: z
+        .array(Schema.Address)
+        .check(
+          z.describe('Tokens accepted by private deposits.'),
+          z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] }),
+        ),
+      name: z.string().check(z.describe('Private Zone name.'), z.meta({ examples: ['zone-e'] })),
+      outputTokens: z
+        .array(Schema.Address)
+        .check(
+          z.describe('Tokens supported by private redemptions.'),
+          z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] }),
+        ),
+    })
+    .check(z.describe('Private Zone route configured for a verified vault.'))
+
+  const value = z.strictObject({
+    amount: Schema.DecimalString.check(
+      z.describe('Value in base units at `decimals` precision.'),
+      z.meta({ examples: ['125288750000'] }),
+    ),
+    currency: z
+      .string()
+      .check(z.describe('Display currency of this value.'), z.meta({ examples: ['USD'] })),
+    decimals: z
+      .number()
+      .check(
+        z.int(),
+        z.nonnegative(),
+        z.describe('Decimal places used to convert `amount` into `formatted`.'),
+        z.meta({ examples: [6] }),
+      ),
+    formatted: z
+      .string()
+      .check(
+        z.regex(/^\d+(\.\d+)?$/),
+        z.describe('Value rendered in whole units.'),
+        z.meta({ examples: ['125288.75'] }),
+      ),
+  })
+
+  const vault = z.strictObject({
+    access: z
+      .optional(EarnVaults.schema.Discovery.shape.access)
+      .check(z.describe('Vault share-token access, when requested.')),
+    apy: z
+      .optional(z.nullable(EarnRates.schema.Apy))
+      .check(
+        z.describe(
+          'Annualized share-price growth over the selected window, when requested via `include=apy` or by selecting `apy.window`. Null when the rate could not be measured: the vault predates the window, a boundary or historical quote is unavailable, the engine changed inside the window, or the growth is too extreme to annualize as a ratio.',
+        ),
+      ),
+    assetToken: Tokens.schema.Token.check(z.describe('Asset accepted by the vault.')),
+    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: ['Bridge test PATHUSD deposited into Tempo Earn.'] }),
+      ),
+    engine,
+    id: Schema.Address.check(
+      z.describe('Stable vault id, equal to the lowercase vault address.'),
+      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+    ),
+    instantLiquidity: EarnVaults.schema.Discovery.shape.instantLiquidity.check(
+      z.describe(
+        'Assets the venue would release right now, capped at the vault backing, in asset base units. Null when the engine interface cannot report a reliable number.',
+      ),
+    ),
+    label: z
+      .string()
+      .check(z.describe('Vault display label.'), z.meta({ examples: ['btPATHUSD Earn'] })),
+    sharePrice: z
+      .nullable(value)
+      .check(
+        z.describe(
+          'Assets returned for one whole Earn share, in the asset display currency, or null when the engine cannot quote an exit.',
+        ),
+      ),
+    shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
+    slug: z
+      .nullable(z.string())
+      .check(
+        z.describe('Curated URL slug, or null when the vault is not verified.'),
+        z.meta({ examples: ['btpathusd-earn-h8k2m4n6'] }),
+      ),
+    state: EarnVaults.schema.Discovery.shape.state,
+    tvl: z
+      .optional(z.nullable(value))
+      .check(
+        z.describe(
+          'Total assets valued in USD, when requested via `include=tvl`, or null when the asset has no priced display currency.',
+        ),
+      ),
+    vaultAddress: Schema.Address.check(
+      z.describe('Earn vault contract address.'),
+      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+    ),
+    verified: z
+      .boolean()
+      .check(
+        z.describe('Whether this vault is in the curated Earn registry.'),
+        z.meta({ examples: [true] }),
+      ),
+    zone: z
+      .optional(z.nullable(zone))
+      .check(z.describe('Curated private Zone route, when requested, or null when absent.')),
+  })
+
+  /** One compatible Earn vault resolved from current chain state. */
+  export const Vault = Schema.describe(vault, 'A compatible Earn vault resolved from chain state.')
+
+  /** One registry-curated Earn vault. */
+  export const VerifiedVault = Schema.describe(
+    z.extend(vault, {
+      engine: z.extend(engine, { type: engineType }),
+      slug: z
+        .string()
+        .check(
+          z.describe('Stable curated vault slug.'),
+          z.meta({ examples: ['btpathusd-earn-h8k2m4n6'] }),
+        ),
+      verified: z
+        .literal(true)
+        .check(
+          z.describe('This vault is in the curated Earn registry.'),
+          z.meta({ examples: [true] }),
+        ),
+    }),
+    'A registry-curated Earn vault resolved from chain state.',
+  )
+
+  const position = z.strictObject({
+    account: Schema.Address.check(
+      z.describe('Account whose Earn position was read.'),
+      z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
+    ),
+    assetAllowance: Schema.DecimalString.check(
+      z.describe('Assets the vault may spend from this account, in asset base units.'),
+      z.meta({ examples: ['0'] }),
+    ),
+    assetBalance: Schema.DecimalString.check(
+      z.describe('Assets this account currently holds, in asset base units.'),
+      z.meta({ examples: ['250000000'] }),
+    ),
+    assetToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(
+      z.describe('TIP-20 asset token accepted by the vault.'),
+    ),
+    id: Schema.Address.check(
+      z.describe('Stable resource ID for this vault position, equal to the account address.'),
+      z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
+    ),
+    shareAllowance: Schema.DecimalString.check(
+      z.describe('Earn shares the vault may spend from this account, in share base units.'),
+      z.meta({ examples: ['0'] }),
+    ),
+    shareBalance: Schema.DecimalString.check(
+      z.describe('Earn shares this account currently holds, in share base units.'),
+      z.meta({ examples: ['99500000'] }),
+    ),
+    shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(
+      z.describe('TIP-20 token representing Earn shares.'),
+    ),
+    value: Schema.DecimalString.check(
+      z.describe(
+        'Current asset value of this account’s Earn shares, including fees, in asset base units.',
+      ),
+      z.meta({ examples: ['100000000'] }),
+    ),
+  })
+
+  const meta = z
+    .object({
+      valuation: z
+        .optional(Valuation.schema.Pricing)
+        .check(
+          z.describe(
+            'Rate provenance for valued fields. Present when `include=tvl` consulted conversion rates; absent when TVL was not requested, every value was identity-valued, or rates were unavailable.',
+          ),
+        ),
+    })
+    .check(z.describe('Rate provenance for valued fields.'))
+
+  const collectionFilters = z.strictObject({
+    asset: z
+      .optional(Schema.Address)
+      .check(z.describe('Only include vaults accepting this asset address.')),
+    capability: Schema.includeQuery(
+      capability,
+      'Comma-separated capabilities that every returned vault must support.',
+    ),
+    chainId: Schema.ChainIdQuery,
+    cursor: Schema.Cursor,
+    'engine.type': z
+      .optional(engineType)
+      .check(z.describe('Only include vaults with this inferred engine type.')),
+    include: includeQuery,
+    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 = 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.'))
+  }
+
+  /** 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 = 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.'))
+  }
+
+  /** Schemas for the getEarnVault operation. */
+  export namespace getEarnVault {
+    /** Path parameters identifying one Earn vault. */
+    export const Params = z
+      .strictObject({
+        vaultId: Schema.Address.check(z.describe('Earn vault contract address.')),
+      })
+      .check(z.describe('Path parameters identifying one Earn vault.'))
+
+    /** Detail query without rates or valuation, for surfaces that cannot measure them. */
+    export const BaseQuery = Schema.describe(
+      z.extend(vaultSelector, { include: baseIncludeQuery }),
+      'Query parameters selecting one Earn vault.',
+    )
+
+    /** Query parameters selecting the chain containing the vault. */
+    export const Query = z
+      .extend(vaultSelector, { 'apy.window': EarnRates.schema.Window })
+      .check(z.describe('Query parameters selecting one Earn vault.'))
+
+    /** One compatible Earn vault resolved directly from current chain state. */
+    export const Response = Schema.describe(
+      z.extend(vault, { meta: z.optional(meta) }),
+      'A compatible Earn vault resolved from chain state, with rate provenance for its valued fields.',
+    )
+  }
+
+  /** Schemas for the getEarnVaultPosition operation. */
+  export namespace getEarnVaultPosition {
+    /** 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('0xdb48b00fb28d9a8db881fcd671c3fb1bf8c486b6').check(
+          z.describe('Earn vault contract address.'),
+        ),
+      })
+      .check(z.describe('Path parameters identifying an Earn vault position.'))
+
+    /** Query parameters selecting the chain containing the vault. */
+    export const Query = z
+      .strictObject({ chainId: Schema.ChainIdQuery })
+      .check(z.describe('Query parameters selecting an Earn vault position.'))
+
+    /** Current asset and Earn-share state for one account in one vault. */
+    export const Response = Schema.describe(
+      position,
+      'Current asset and Earn-share balances, allowances, and asset value for an account in one Earn vault.',
+    )
+  }
+}
+
+/** Creates the public Earn-vault handlers. */
+export function earn(options: earn.Options = {}) {
+  const oracle = options.fx?.oracle ?? FxOracle.ecb()
+  return new Hono<App.Environment>()
+    .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: { 502: 'Could not read Earn deployment or vault data.' },
+          success: {
+            description: 'A page of compatible deployed Earn vaults.',
+            schema: schema.getEarnVaults.Response,
+          },
+        }),
+        summary: 'List Earn 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) => Cache.urlKey(c, schema.getEarnVaults.Query),
+        name: 'tempo-api:earn-vaults:v2',
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        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: { 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) => Cache.urlKey(c, schema.getVerifiedEarnVaults.Query),
+        name: 'tempo-api:earn-vaults:v2',
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        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/vaults/:vaultId/positions/:address',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getEarnVaultPosition.Params, {
+        code: 'position_invalid',
+        message: 'Invalid vault position',
+      }),
+      OpenApi.validate('query', schema.getEarnVaultPosition.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Gets an account’s asset and Earn-share balances, allowances, and current asset value for one Earn vault.',
+        operationId: 'getEarnVaultPosition',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'position_invalid',
+                'query_invalid',
+              ],
+            },
+            404: {
+              codes: ['earn_vault_not_found'],
+              description: 'No compatible Earn vault was found at the supplied vault address.',
+            },
+            502: 'Could not read the Earn vault position.',
+          },
+          success: {
+            description: 'Current Earn position for one account in one vault.',
+            schema: schema.getEarnVaultPosition.Response,
+          },
+        }),
+        summary: 'Get vault position',
+        tags: ['Earn'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVaultPosition.Query),
+        name: 'tempo-api:earn-vault-positions:v1',
+      }),
+      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: 'position_invalid',
+            message: 'Invalid request parameters',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const { address, vaultId } = c.req.valid('param')
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+        try {
+          const position = await c
+            .get('getClient')(chainId)
+            .earn.getPosition({ account: address, vault: vaultId })
+          return c.json(
+            Response.validated(schema.getEarnVaultPosition.Response, {
+              account: address,
+              assetAllowance: position.assetAllowance.toString(),
+              assetBalance: position.assetBalance.toString(),
+              assetToken: position.assetToken,
+              id: address,
+              shareAllowance: position.shareAllowance.toString(),
+              shareBalance: position.shareBalance.toString(),
+              shareToken: position.shareToken,
+              value: position.value.toString(),
+            }),
+            200,
+          )
+        } catch (cause) {
+          try {
+            await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId })
+          } catch (vaultCause) {
+            if (isIncompatible(vaultCause))
+              return Response.error(c, {
+                code: 'earn_vault_not_found',
+                message: 'Earn vault not found',
+                status: 404,
+              })
+          }
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/earn/vaults/:vaultId',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getEarnVault.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
+      }),
+      OpenApi.validate('query', schema.getEarnVault.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Resolves any compatible Earn vault directly from current chain state and enriches it when curated.',
+        operationId: 'getEarnVault',
+        responses: OpenApi.responses({
+          errors: {
+            404: {
+              codes: ['earn_vault_not_found'],
+              description: 'No compatible Earn vault was found at this address.',
+            },
+            502: 'Could not read Earn vault data.',
+          },
+          success: {
+            description: 'One compatible Earn vault.',
+            schema: schema.getEarnVault.Response,
+          },
+        }),
+        summary: 'Get Earn vault',
+        tags: ['Earn'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVault.Query),
+        name: 'tempo-api:earn-vaults:v2',
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'vault_id_invalid',
+            message: 'Invalid request parameters',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid request parameters',
+          })
+
+        const { vaultId } = c.req.valid('param')
+        const query = c.req.valid('query')
+        try {
+          const chainId = query.chainId ?? c.get('chainId')
+          const data = await getVault(c, {
+            'apy.window': query['apy.window'],
+            chainId,
+            include: query.include,
+            oracle,
+            vaultAddress: vaultId,
+          })
+          return c.json(Response.validated(schema.getEarnVault.Response, data), 200)
+        } catch (cause) {
+          if (cause instanceof NotFoundError)
+            return Response.error(c, {
+              code: 'earn_vault_not_found',
+              message: 'Earn vault not found',
+              status: 404,
+            })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+export declare namespace earn {
+  /** Options for the public Earn-vault handlers. */
+  type Options = {
+    /** FX configuration backing TVL valuation. */
+    fx?: Valuation.addresses.Fx | undefined
+  }
+}
+
+/** 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 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 discovered = await Promise.all(
+      page.items.map(async (item) => {
+        const record = registry.get(item.vaultAddress.toLowerCase())
+        try {
+          const discovery = await resolveVaultDiscovery(c, {
+            chainId: options.chainId,
+            include: discoveryInclude(options),
+            vaultAddress: item.vaultAddress,
+          })
+          return { discovery, position: item.position, record }
+        } catch (cause) {
+          if (!record && isIncompatible(cause)) return undefined
+          throw cause
+        }
+      }),
+    )
+    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 include = vaultInclude(options)
+  const [apy, rates, tokens] = await Promise.all([
+    resolvePageApy(c, {
+      chainId: options.chainId,
+      discoveries,
+      include,
+      window: options['apy.window'],
+    }),
+    resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+    resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
+  ])
+  const data = page.map((match) =>
+    resolveVault(c, { ...match, apy, include, rates, 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
+  }
+
+  /** 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 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) => ({
+        discovery: await resolveVaultDiscovery(c, {
+          chainId: options.chainId,
+          include: discoveryInclude(options),
+          vaultAddress: Schema.Address.parse(record.vaultAddress.toLowerCase()),
+        }),
+        record,
+      })),
+    )
+    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 include = vaultInclude(options)
+  const [apy, rates, tokens] = await Promise.all([
+    resolvePageApy(c, {
+      chainId: options.chainId,
+      discoveries,
+      include,
+      window: options['apy.window'],
+    }),
+    resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+    resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
+  ])
+  const data = page.map((match) =>
+    Response.validated(
+      schema.VerifiedVault,
+      resolveVault(c, { ...match, apy, include, rates, 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
+  }
+
+  /** 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
+  }
+}
+
+/** Gets one compatible Earn vault. */
+export async function getVault(c: Context<App.Environment>, options: getVault.Options) {
+  const db = Db.get(c.get('dbCached'))
+  const [record, snapshot] = await Promise.all([
+    core_EarnVaults.get(db, {
+      chainId: options.chainId,
+      vaultAddress: options.vaultAddress,
+    }),
+    VerifiedTokens.snapshot(c, options.chainId),
+  ])
+  try {
+    const discovery = await resolveVaultDiscovery(c, {
+      chainId: options.chainId,
+      include: discoveryInclude({ capability: [], include: options.include }),
+      vaultAddress: options.vaultAddress,
+    })
+    const discoveries = [discovery]
+    const include = vaultInclude(options)
+    const [apy, rates, tokens] = await Promise.all([
+      resolvePageApy(c, {
+        chainId: options.chainId,
+        discoveries,
+        include,
+        window: options['apy.window'],
+      }),
+      resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+      resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
+    ])
+    return {
+      ...resolveVault(c, {
+        apy,
+        discovery,
+        include,
+        rates,
+        record,
+        snapshot,
+        tokens,
+      }),
+      ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
+    }
+  } catch (cause) {
+    if (cause instanceof EarnVaults.NotFoundError || (!record && isIncompatible(cause)))
+      throw new NotFoundError()
+    throw cause
+  }
+}
+
+export declare namespace getVault {
+  /** Options for getting one Earn vault. */
+  type Options = {
+    /** Canonical rate window the vault's APY covers. */
+    'apy.window': z.output<typeof schema.getEarnVault.Query>['apy.window']
+    chainId: z.output<typeof Schema.ChainId>
+    include: z.output<typeof schema.getEarnVault.Query>['include']
+    /** FX rate oracle backing TVL valuation. */
+    oracle: FxOracle.Oracle
+    vaultAddress: z.output<typeof Schema.Address>
+  }
+}
+
+// Selecting a rate window is a request for the rate it measures, mirroring how
+// a capability filter promotes `capabilities`.
+function vaultInclude(options: vaultInclude.Options) {
+  const { include } = options
+  if (options['apy.window'] === undefined || include.includes('apy')) return include
+  return [...include, 'apy' as const]
+}
+
+declare namespace vaultInclude {
+  type Options = Pick<z.output<typeof schema.getEarnVault.Query>, 'apy.window' | 'include'>
+}
+
+function discoveryInclude(
+  options: discoveryInclude.Options,
+): readonly EarnVaults.resolve.Include[] {
+  const includeCapabilities =
+    options.include.includes('capabilities') ||
+    options.include.includes('zone') ||
+    options.capability.length > 0
+  return [
+    ...(options.include.includes('access') ? (['access'] as const) : []),
+    ...(includeCapabilities ? (['capabilities'] as const) : []),
+  ]
+}
+
+declare namespace discoveryInclude {
+  type Options = Pick<z.output<typeof schema.getEarnVaults.Query>, 'capability' | 'include'>
+}
+
+async function resolveVaultDiscovery(
+  c: Context<App.Environment>,
+  options: resolveVaultDiscovery.Options,
+) {
+  return Store.memoize(
+    () =>
+      Timing.time(c, 'earn_vault_discovery', () =>
+        EarnVaults.resolve({
+          getClient: c.get('getClient'),
+          include: options.include,
+          input: {
+            chainId: options.chainId,
+            vaultAddress: options.vaultAddress,
+          },
+          zones: [...c.get('zones').values()],
+        }),
+      ),
+    {
+      key: `earn-vault:v3:${options.chainId}:${options.vaultAddress.toLowerCase()}:include:${options.include.join(',') || 'base'}`,
+      store: c.get('store'),
+      // Matches the routes' `state` policy `max-age` so the two cache layers do
+      // not compound staleness on live vault state.
+      ttl: Ttl.seconds(30),
+    },
+  )
+}
+
+declare namespace resolveVaultDiscovery {
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    include: readonly EarnVaults.resolve.Include[]
+    vaultAddress: z.output<typeof Schema.Address>
+  }
+}
+
+// Measuring a rate costs indexer boundary queries plus historical quotes against
+// an archive node, so an unrequested rate reaches neither.
+function resolvePageApy(c: Context<App.Environment>, options: resolvePageApy.Options) {
+  if (!options.include.includes('apy')) return undefined
+  return Timing.time(c, 'earn_apy', () =>
+    EarnRates.resolve({
+      chainId: options.chainId,
+      getClient: c.get('getClient'),
+      getTidx: c.get('getTidx'),
+      store: c.get('store'),
+      vaults: options.discoveries.map(({ vaultAddress }) => vaultAddress),
+      window: options.window,
+    }),
+  )
+}
+
+declare namespace resolvePageApy {
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    discoveries: readonly EarnVaults.Discovery[]
+    include: z.output<typeof schema.getEarnVault.Query>['include']
+    window: z.output<typeof schema.getEarnVault.Query>['apy.window']
+  }
+}
+
+// The TVL denomination is a fixed constant, not caller input, so a rate set
+// lacking it leaves `tvl` unpriced instead of failing the whole vault read.
+function resolvePageRates(c: Context<App.Environment>, options: resolvePageRates.Options) {
+  // Valuing total assets is the only reason this read consults the oracle.
+  if (!options.include.includes('tvl')) return undefined
+  return Valuation.ratesFor(c, {
+    currencies: options.discoveries.flatMap((discovery) => {
+      const currency = options.snapshot.byAddress.get(discovery.assetToken.address)?.currency
+      return currency === undefined ? [] : [currency]
+    }),
+    denomination: tvlDenomination,
+    oracle: options.oracle,
+  }).catch((cause) => {
+    if (cause instanceof Valuation.UnsupportedDenominationError) return undefined
+    throw cause
+  })
+}
+
+declare namespace resolvePageRates {
+  type Options = {
+    discoveries: readonly EarnVaults.Discovery[]
+    include: z.output<typeof schema.getEarnVault.Query>['include']
+    oracle: FxOracle.Oracle
+    snapshot: VerifiedTokens.Snapshot
+  }
+}
+
+async function resolvePageTokens(c: Context<App.Environment>, options: resolvePageTokens.Options) {
+  const metadata = new Map(
+    options.discoveries.flatMap(({ assetToken, shareToken }) => [
+      [Schema.Address.parse(assetToken.address.toLowerCase()), assetToken] as const,
+      [Schema.Address.parse(shareToken.address.toLowerCase()), shareToken] as const,
+    ]),
+  )
+  return Tokens.resolveTokens(c, {
+    addresses: [...metadata.keys()],
+    chainId: options.chainId,
+    include: [
+      'token.verified',
+      ...(options.include.includes('token.logoUri') ? (['token.logoUri'] as const) : []),
+    ],
+    metadata,
+    snapshot: options.snapshot,
+  })
+}
+
+declare namespace resolvePageTokens {
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    discoveries: readonly EarnVaults.Discovery[]
+    include: z.output<typeof schema.getEarnVault.Query>['include']
+    snapshot: VerifiedTokens.Snapshot
+  }
+}
+
+function resolveVault(c: Context<App.Environment>, options: resolveVault.Options) {
+  const { discovery, record } = options
+  const valued = options.include.includes('tvl')
+    ? Valuation.valuationFor({
+        amount: BigInt(discovery.state.totalAssets),
+        denomination: tvlDenomination,
+        rates: options.rates,
+        token: options.snapshot.byAddress.get(discovery.assetToken.address),
+      })
+    : undefined
+  return serializeVault({
+    apy: options.apy?.get(discovery.vaultAddress) ?? null,
+    assetToken: getToken(options.tokens, discovery.assetToken.address),
+    discovery,
+    include: options.include,
+    record,
+    shareToken: getToken(options.tokens, discovery.shareToken.address),
+    tvl: valued
+      ? {
+          amount: core_Value.from(valued.amount, tvlDecimals).toString(),
+          currency: valued.currency,
+          decimals: tvlDecimals,
+          formatted: valued.amount,
+        }
+      : null,
+    zones: [...c.get('zones').values()],
+  })
+}
+
+declare namespace resolveVault {
+  type Options = {
+    apy: ReadonlyMap<string, EarnRates.Apy | null> | undefined
+    discovery: EarnVaults.Discovery
+    include: z.output<typeof schema.getEarnVault.Query>['include']
+    rates: Awaited<ReturnType<typeof Valuation.ratesFor>>
+    record?: RegistryRecord | undefined
+    snapshot: VerifiedTokens.Snapshot
+    tokens: Tokens.resolveTokens.ReturnType
+  }
+}
+
+/** Serializes resolved onchain and curated fields into the shared vault contract. */
+export function serializeVault(options: serializeVault.Options): z.output<typeof schema.Vault> {
+  const { discovery, record } = options
+  if (options.include.includes('access') && !discovery.access)
+    throw new Error('Earn vault access was not resolved.')
+  if (options.include.includes('capabilities') && !discovery.capabilities)
+    throw new Error('Earn vault capabilities were not resolved.')
+  const vaultAddress = Schema.Address.parse(discovery.vaultAddress.toLowerCase())
+  return Response.validated(schema.Vault, {
+    ...(options.include.includes('access') ? { access: discovery.access } : {}),
+    ...(options.include.includes('apy') ? { apy: options.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,
+      venue: discovery.engine.venue?.toLowerCase() ?? null,
+    },
+    id: vaultAddress,
+    instantLiquidity: discovery.instantLiquidity,
+    label: record?.label ?? options.shareToken.name,
+    sharePrice:
+      discovery.sharePrice === null
+        ? null
+        : {
+            amount: discovery.sharePrice,
+            currency: options.assetToken.currency,
+            decimals: options.assetToken.decimals,
+            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,
+    verified: record !== undefined,
+    ...(options.include.includes('zone')
+      ? { zone: record ? resolveZone({ discovery, record, zones: options.zones }) : null }
+      : {}),
+  })
+}
+
+export declare namespace serializeVault {
+  /** Values used to serialize one resolved Earn vault. */
+  type Options = {
+    /** Measured rate, or null when unavailable; omitted unless `include` carries `apy`. */
+    apy: EarnRates.Apy | null
+    /** Resolved asset token. */
+    assetToken: z.output<typeof Tokens.schema.Token>
+    /** Live onchain vault state. */
+    discovery: EarnVaults.Discovery
+    /** Optional vault fields selected by the request. */
+    include: z.output<typeof schema.getEarnVault.Query>['include']
+    /** Curated registry row, when verified. */
+    record?: core_EarnVaults.Record | undefined
+    /** Resolved share token. */
+    shareToken: z.output<typeof Tokens.schema.Token>
+    /** USD value of the assets, or null when unpriced; omitted unless `include` carries `tvl`. */
+    tvl: z.output<typeof schema.Vault>['tvl']
+    /** Private Zones available to the vault. */
+    zones: readonly Chain[]
+  }
+}
+
+function resolveZone(options: resolveZone.Options): z.output<typeof schema.Vault.shape.zone> {
+  if (!options.discovery.capabilities?.privateRouting) return null
+  const hasInputs = options.record.privateInputTokens.length > 0
+  const hasOutputs = options.record.privateOutputTokens.length > 0
+  if (!hasInputs && !hasOutputs) return null
+  if (hasInputs !== hasOutputs)
+    throw new Error('Private input and output tokens must both be configured.')
+
+  const configured = options.zones.filter((zone) => zone.sourceId === options.record.chainId)
+  if (configured.length !== 1)
+    throw new Error(`Expected one Earn Zone for chain ${options.record.chainId}.`)
+  const zone = configured[0]!
+  return {
+    chainId: zone.id,
+    inputTokens: options.record.privateInputTokens.map((token) =>
+      Schema.Address.parse(token.toLowerCase()),
+    ),
+    name: zone.name,
+    outputTokens: options.record.privateOutputTokens.map((token) =>
+      Schema.Address.parse(token.toLowerCase()),
+    ),
+  }
+}
+
+declare namespace resolveZone {
+  type Options = {
+    discovery: EarnVaults.Discovery
+    record: RegistryRecord
+    zones: readonly Chain[]
+  }
+}
+
+function getToken(
+  tokens: Tokens.resolveTokens.ReturnType,
+  address: z.output<typeof Schema.Address>,
+): z.output<typeof Tokens.schema.Token> {
+  const token = tokens.get(Schema.Address.parse(address.toLowerCase()))
+  if (!token) throw new Error(`Token metadata was not resolved for ${address}.`)
+  return Response.validated(Tokens.schema.Token, token)
+}
+
+async function queryDeployments(
+  c: Context<App.Environment>,
+  options: queryDeployments.Options,
+): Promise<queryDeployments.Result> {
+  const filters = ['deployment_rank = 1']
+  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',
+        },
+      ]),
+    )
+
+  // ClickHouse supports ordering and windowing over decoded event CTEs.
+  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,
+          row_number() OVER (
+            PARTITION BY lower("earnVault")
+            ORDER BY block_num DESC, log_idx DESC
+          ) AS deployment_rank
+        FROM EarnStackDeployed
+      )
+      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,
+  options: matchesVaultFilters.Options,
+): boolean {
+  if (options.asset && discovery.assetToken.address.toLowerCase() !== options.asset.toLowerCase())
+    return false
+  const capabilities = discovery.capabilities
+  if (options.capability.length > 0 && !capabilities)
+    throw new Error('Earn vault capabilities were not resolved.')
+  if (capabilities && !options.capability.every((name) => capabilities[name])) return false
+  if (options['engine.type'] && discovery.engine.type !== options['engine.type']) return false
+  return true
+}
+
+export declare namespace matchesVaultFilters {
+  /** Filters shared by the all-vault and verified-vault collections. */
+  type Options = Pick<
+    z.output<typeof schema.getEarnVaults.Query>,
+    'asset' | 'capability' | 'engine.type'
+  >
+}
+
+/** Returns whether a failed read proves the address is not a compatible Earn vault. */
+export function isIncompatible(cause: unknown) {
+  if (cause instanceof EarnVaults.NotFoundError) return true
+  if (cause instanceof EarnVaults.VerificationError) return cause.result.status === 'mismatch'
+  if (!(cause instanceof ContractFunctionExecutionError)) return false
+  return Boolean(
+    cause.walk(
+      (error) =>
+        error instanceof ContractFunctionRevertedError ||
+        error instanceof ContractFunctionZeroDataError,
+    ),
+  )
+}
+
+type RegistryRecord = Awaited<ReturnType<typeof core_EarnVaults.list>>[number]
+
+/** Thrown when no compatible Earn vault exists at the requested address. */
+export class NotFoundError extends Error {
+  override name = 'Earn.NotFoundError'
+}