tapimo 0.7.1 → 0.8.0

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

@@ -0,0 +1,2188 @@
+import { type Context, Hono } from 'hono'
+import { Value as core_Value } from 'ox'
+import {
+  type Chain,
+  ContractFunctionExecutionError,
+  ContractFunctionRevertedError,
+  ContractFunctionZeroDataError,
+  zeroAddress,
+} 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 Tidx from '../../../internal/Tidx.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 depositedSignature =
+  'event Deposited(address indexed caller,address indexed receiver,uint256 assets,uint256 earnShares)'
+
+const redeemedSignature =
+  'event Redeemed(address indexed caller,address indexed receiver,uint256 earnShares,uint256 assets)'
+
+const withdrewExactSignature =
+  'event WithdrewExact(address indexed caller,address indexed receiver,uint256 assets,uint256 earnSharesBurned)'
+
+const redeemFinalizedSignature =
+  'event RedeemFinalized(bytes32 indexed requestId,address indexed receiver,uint256 earnShares,address asset,uint256 assets)'
+
+const redeemCancelledSignature =
+  'event RedeemCancelled(bytes32 indexed requestId,address indexed receiver,uint256 earnShares)'
+
+const redeemRequestedSignature =
+  'event RedeemRequested(bytes32 indexed requestId,address indexed requester,address indexed receiver,uint256 earnShares)'
+
+const venueSharesDepositedSignature =
+  'event VenueSharesDeposited(address indexed caller,address indexed receiver,uint256 requestedVenueShares,uint256 receivedVenueShares,uint256 earnShares)'
+
+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 earningsBase = z.strictObject({
+    account: Schema.Address.check(
+      z.describe('Account whose vault earnings were calculated.'),
+      z.meta({ examples: ['0x68f94cfca22e5969c0553bbeab00a2acde88939b'] }),
+    ),
+    assetToken: Schema.TokenAddress.check(
+      z.describe('TIP-20 asset token accepted by the vault.'),
+      z.meta({ examples: ['0x20c000000000000000000000ff04042ee92fd449'] }),
+    ),
+    currentValue: Schema.DecimalString.check(
+      z.describe(
+        'Asset value of the account’s active Earn shares at the latest indexed block, in asset base units.',
+      ),
+      z.meta({ examples: ['600000'] }),
+    ),
+    id: Schema.Address.check(
+      z.describe('Stable resource ID for these vault earnings, equal to the account address.'),
+      z.meta({ examples: ['0x68f94cfca22e5969c0553bbeab00a2acde88939b'] }),
+    ),
+  })
+
+  const earningsPeriod = z
+    .enum(['active', 'lifetime'])
+    .check(z.describe('Earnings period to calculate.'), z.meta({ examples: ['lifetime'] }))
+
+  const earnings = z.union([
+    z.extend(earningsBase, {
+      lifetimeEarnings: z
+        .string()
+        .check(
+          z.regex(/^-?\d+$/),
+          z.describe(
+            'Current share value plus completed redemptions, exact withdrawals, and finalized async assets, minus asset deposits, at the latest indexed block.',
+          ),
+          z.meta({ examples: ['0'] }),
+        ),
+      period: z
+        .literal('lifetime')
+        .check(
+          z.describe('Returns lifetime net asset earnings.'),
+          z.meta({ examples: ['lifetime'] }),
+        ),
+      status: z
+        .literal('complete')
+        .check(
+          z.describe('Earnings include a complete asset-denominated cost basis.'),
+          z.meta({ examples: ['complete'] }),
+        ),
+    }),
+    z.extend(earningsBase, {
+      activeEarnings: z
+        .string()
+        .check(
+          z.regex(/^-?\d+$/),
+          z.describe(
+            'Current share value minus the weighted-average asset cost basis of shares still held, at the latest indexed block.',
+          ),
+          z.meta({ examples: ['0'] }),
+        ),
+      period: z
+        .literal('active')
+        .check(
+          z.describe('Returns earnings on shares still held.'),
+          z.meta({ examples: ['active'] }),
+        ),
+      status: z
+        .literal('complete')
+        .check(
+          z.describe('Earnings include a complete asset-denominated cost basis.'),
+          z.meta({ examples: ['complete'] }),
+        ),
+    }),
+    z.extend(earningsBase, {
+      period: earningsPeriod,
+      status: z
+        .literal('incomplete_cost_basis')
+        .check(
+          z.describe(
+            'Earnings are unavailable when indexed activity cannot reconstruct the remaining asset cost basis.',
+          ),
+          z.meta({ examples: ['incomplete_cost_basis'] }),
+        ),
+    }),
+    z.extend(earningsBase, {
+      period: z
+        .literal('lifetime')
+        .check(
+          z.describe('Returns lifetime net asset earnings.'),
+          z.meta({ examples: ['lifetime'] }),
+        ),
+      status: z
+        .literal('pending_redemption')
+        .check(
+          z.describe('Earnings are unavailable while an async redemption remains open.'),
+          z.meta({ examples: ['pending_redemption'] }),
+        ),
+    }),
+  ])
+
+  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.',
+    )
+  }
+
+  /** Schemas for the getEarnVaultEarnings operation. */
+  export namespace getEarnVaultEarnings {
+    /** Path parameters identifying the Earn vault and account. */
+    export const Params = z
+      .strictObject({
+        address: Schema.Address.check(z.describe('Account whose vault earnings to read.')),
+        vaultId: Schema.address('0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a').check(
+          z.describe('Earn vault contract address.'),
+        ),
+      })
+      .check(z.describe('Path parameters identifying an Earn vault account.'))
+
+    /** Query parameters selecting the chain containing the vault. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        period: z._default(earningsPeriod, 'lifetime'),
+      })
+      .check(z.describe('Query parameters selecting an Earn vault account.'))
+
+    /** Earnings for one account and period in one Earn vault. */
+    export const Response = Schema.describe(
+      earnings,
+      'Indexed asset value and cost-basis-aware earnings 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 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 account 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/earnings/:address',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getEarnVaultEarnings.Params, {
+        code: 'earnings_invalid',
+        message: 'Invalid vault earnings',
+      }),
+      OpenApi.validate('query', schema.getEarnVaultEarnings.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Gets an account’s indexed asset value and earnings for lifetime history or shares still held.',
+        operationId: 'getEarnVaultEarnings',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'earnings_invalid',
+                'query_invalid',
+              ],
+            },
+            404: {
+              codes: ['earn_vault_not_found'],
+              description: 'No compatible Earn vault was found at this address.',
+            },
+            502: 'Could not read the Earn vault earnings.',
+          },
+          success: {
+            description: 'Cost-basis-aware earnings for one account in one vault.',
+            schema: schema.getEarnVaultEarnings.Response,
+          },
+        }),
+        summary: 'Get vault earnings',
+        tags: ['Earn'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVaultEarnings.Query),
+        name: 'tempo-api:earn-vault-earnings:v2',
+      }),
+      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: 'earnings_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 data = await getVaultEarnings(c, {
+            account: address,
+            chainId,
+            period: query.period,
+            vault: vaultId,
+          })
+          return c.json(Response.validated(schema.getEarnVaultEarnings.Response, data), 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 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
+  }
+}
+
+/** Reads one account's indexed value and returns earnings when the history is complete. */
+export async function getVaultEarnings(
+  c: Context<App.Environment>,
+  options: getVaultEarnings.Options,
+) {
+  const client = c.get('getClient')(options.chainId)
+  const tidx = c.get('getTidx')(options.chainId)
+  const blockNumber = await getLatestIndexedBlockNumber(tidx)
+  const position = client.earn.getPosition({
+    account: options.account,
+    blockNumber: BigInt(blockNumber),
+    vault: options.vault,
+  })
+  if (options.period === 'active') {
+    const current = await position
+    const base = {
+      account: options.account,
+      assetToken: current.assetToken,
+      currentValue: current.value.toString(),
+      id: options.account,
+      period: options.period,
+    }
+    const activeCostBasis = await getActiveCostBasis(tidx, {
+      account: options.account,
+      blockNumber,
+      shareBalance: current.shareBalance,
+      shareToken: current.shareToken,
+      vault: options.vault,
+    })
+    if (activeCostBasis === undefined) return { ...base, status: 'incomplete_cost_basis' as const }
+    return {
+      ...base,
+      activeEarnings: (current.value - activeCostBasis).toString(),
+      status: 'complete' as const,
+    }
+  }
+  const [history, current] = await Promise.all([
+    getVaultEarningsHistory(tidx, {
+      account: options.account,
+      blockNumber,
+      vault: options.vault,
+    }),
+    position,
+  ])
+  const externalShareTransfer = await hasExternalShareTransfer(tidx, {
+    account: options.account,
+    blockNumber,
+    shareToken: current.shareToken,
+    vault: options.vault,
+  })
+  const base = {
+    account: options.account,
+    assetToken: current.assetToken,
+    currentValue: current.value.toString(),
+    id: options.account,
+    period: options.period,
+  }
+  if (history.incompleteCostBasis || externalShareTransfer)
+    return { ...base, status: 'incomplete_cost_basis' as const }
+  if (history.pendingRedemption) return { ...base, status: 'pending_redemption' as const }
+  const lifetimeEarnings =
+    current.value + history.redeemed + history.withdrewExact + history.finalized - history.deposited
+  return { ...base, lifetimeEarnings: lifetimeEarnings.toString(), status: 'complete' as const }
+}
+
+export declare namespace getVaultEarnings {
+  /** Inputs identifying the account and vault to calculate. */
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    chainId: z.output<typeof Schema.ChainId>
+    period: z.output<typeof schema.getEarnVaultEarnings.Query>['period']
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Reads the latest block whose indexed logs back the earnings calculation. */
+async function getLatestIndexedBlockNumber(tidx: Tidx.Client) {
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: 'SELECT num FROM blocks ORDER BY num DESC LIMIT 1' as string,
+  })
+  const blockNumber = Value.toNumber(result.rows[0]?.['num'])
+  if (blockNumber === undefined) throw new Error('TIDX returned no indexed block.')
+  return blockNumber
+}
+
+/** Reads the indexed cash flows and exceptional states behind one earnings calculation. */
+async function getVaultEarningsHistory(
+  tidx: Tidx.Client,
+  options: getVaultEarningsHistory.Options,
+) {
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT
+        (
+          SELECT toString(sum(toUInt256(assets)))
+          FROM Deposited
+          WHERE address = '${options.vault}'
+            AND receiver = '${options.account}'
+            AND block_num <= ${options.blockNumber}
+        ) AS deposited_assets,
+        (
+          SELECT toString(sum(toUInt256(finalized.assets)))
+          FROM RedeemFinalized AS finalized
+          INNER JOIN RedeemRequested AS requested
+            ON requested.address = finalized.address
+            AND requested."requestId" = finalized."requestId"
+          WHERE finalized.address = '${options.vault}'
+            AND requested.requester = '${options.account}'
+            AND finalized.block_num <= ${options.blockNumber}
+            AND requested.block_num <= ${options.blockNumber}
+        ) AS finalized_assets,
+        (
+          SELECT count()
+          FROM RedeemRequested AS requested
+          LEFT ANTI JOIN RedeemFinalized AS finalized
+            ON finalized.address = requested.address
+            AND finalized."requestId" = requested."requestId"
+            AND finalized.block_num <= ${options.blockNumber}
+          LEFT ANTI JOIN RedeemCancelled AS cancelled
+            ON cancelled.address = requested.address
+            AND cancelled."requestId" = requested."requestId"
+            AND cancelled.block_num <= ${options.blockNumber}
+          WHERE requested.address = '${options.vault}'
+            AND requested.requester = '${options.account}'
+            AND requested.block_num <= ${options.blockNumber}
+        ) AS pending_redemptions,
+        (
+          SELECT toString(sum(toUInt256(assets)))
+          FROM Redeemed
+          WHERE address = '${options.vault}'
+            AND caller = '${options.account}'
+            AND block_num <= ${options.blockNumber}
+        ) AS redeemed_assets,
+        (
+          SELECT count()
+          FROM RedeemCancelled AS cancelled
+          INNER JOIN RedeemRequested AS requested
+            ON requested.address = cancelled.address
+            AND requested."requestId" = cancelled."requestId"
+          WHERE cancelled.address = '${options.vault}'
+            AND cancelled.block_num <= ${options.blockNumber}
+            AND requested.block_num <= ${options.blockNumber}
+            AND requested.requester != cancelled.receiver
+            AND (
+              requested.requester = '${options.account}'
+              OR cancelled.receiver = '${options.account}'
+            )
+        ) AS transferred_cancellations,
+        (
+          SELECT count()
+          FROM VenueSharesDeposited
+          WHERE address = '${options.vault}'
+            AND receiver = '${options.account}'
+            AND block_num <= ${options.blockNumber}
+        ) AS venue_deposits,
+        (
+          SELECT toString(sum(toUInt256(assets)))
+          FROM WithdrewExact
+          WHERE address = '${options.vault}'
+            AND caller = '${options.account}'
+            AND block_num <= ${options.blockNumber}
+        ) AS withdrew_exact
+    ` as string,
+    signatures: [
+      depositedSignature,
+      redeemCancelledSignature,
+      redeemFinalizedSignature,
+      redeemRequestedSignature,
+      redeemedSignature,
+      venueSharesDepositedSignature,
+      withdrewExactSignature,
+    ],
+  })
+  const row = result.rows[0]
+  const deposited = Value.toIntegerString(row?.['deposited_assets'])
+  const finalized = Value.toIntegerString(row?.['finalized_assets'])
+  const pendingRedemptions = Value.toNumber(row?.['pending_redemptions'])
+  const redeemed = Value.toIntegerString(row?.['redeemed_assets'])
+  const transferredCancellations = Value.toNumber(row?.['transferred_cancellations'])
+  const venueDeposits = Value.toNumber(row?.['venue_deposits'])
+  const withdrewExact = Value.toIntegerString(row?.['withdrew_exact'])
+  if (
+    deposited === undefined ||
+    finalized === undefined ||
+    pendingRedemptions === undefined ||
+    redeemed === undefined ||
+    transferredCancellations === undefined ||
+    venueDeposits === undefined ||
+    withdrewExact === undefined
+  )
+    throw new Error('TIDX returned invalid Earn earnings history.')
+  return {
+    deposited: BigInt(deposited),
+    finalized: BigInt(finalized),
+    incompleteCostBasis: transferredCancellations > 0 || venueDeposits > 0,
+    pendingRedemption: pendingRedemptions > 0,
+    redeemed: BigInt(redeemed),
+    withdrewExact: BigInt(withdrewExact),
+  }
+}
+
+declare namespace getVaultEarningsHistory {
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber: number
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Returns whether an account sent or received Earn shares outside known vault flows. */
+async function hasExternalShareTransfer(
+  tidx: Tidx.Client,
+  options: hasExternalShareTransfer.Options,
+) {
+  // Vault exits pull shares into the vault before burning. Reconcile counts by transaction and amount so unmatched direct sends remain external.
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT
+        (
+          SELECT count()
+          FROM token_transfers
+          WHERE token = '${options.shareToken.toLowerCase()}'
+            AND block_num <= ${options.blockNumber}
+            AND (
+              ("from" = '${options.account}' AND "to" != '${options.vault}')
+              OR ("to" = '${options.account}' AND "from" != '${zeroAddress}')
+            )
+        ) + (
+          SELECT count()
+          FROM (
+            SELECT tx_hash, toUInt256(amount) AS amount, count() AS transfer_count
+            FROM token_transfers
+            WHERE token = '${options.shareToken.toLowerCase()}'
+              AND "from" = '${options.account}'
+              AND "to" = '${options.vault}'
+              AND block_num <= ${options.blockNumber}
+            GROUP BY tx_hash, amount
+          ) AS candidate
+          LEFT JOIN (
+            SELECT tx_hash, amount, count() AS exit_count
+            FROM (
+              SELECT tx_hash, toUInt256(earnShares) AS amount
+              FROM Redeemed
+              WHERE address = '${options.vault}'
+                AND caller = '${options.account}'
+                AND block_num <= ${options.blockNumber}
+              UNION ALL
+              SELECT tx_hash, toUInt256(earnShares) AS amount
+              FROM RedeemRequested
+              WHERE address = '${options.vault}'
+                AND requester = '${options.account}'
+                AND block_num <= ${options.blockNumber}
+              UNION ALL
+              SELECT tx_hash, toUInt256(earnSharesBurned) AS amount
+              FROM WithdrewExact
+              WHERE address = '${options.vault}'
+                AND caller = '${options.account}'
+                AND block_num <= ${options.blockNumber}
+            ) AS protocol_exit
+            GROUP BY tx_hash, amount
+          ) AS matched
+            ON matched.tx_hash = candidate.tx_hash AND matched.amount = candidate.amount
+          WHERE candidate.transfer_count > coalesce(matched.exit_count, 0)
+        ) AS count
+    ` as string,
+    signatures: [redeemedSignature, redeemRequestedSignature, withdrewExactSignature],
+  })
+  const count = Value.toNumber(result.rows[0]?.['count'])
+  if (count === undefined) throw new Error('TIDX returned an invalid Earn-share transfer count.')
+  return count > 0
+}
+
+declare namespace hasExternalShareTransfer {
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber: number
+    shareToken: z.output<typeof Schema.Address>
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Calculates the asset cost basis attached to an account's remaining Earn shares. */
+export function calculateActiveCostBasis(options: calculateActiveCostBasis.Options) {
+  const requests = new Map<string, { costBasis: bigint | undefined; shares: bigint }>()
+  let costBasis: bigint | undefined = 0n
+  let shares = 0n
+
+  const remove = (burned: bigint) => {
+    if (burned > shares || shares === 0n) return undefined
+    const removed = (() => {
+      if (costBasis === undefined) return undefined
+      return burned === shares ? costBasis : (costBasis * burned) / shares
+    })()
+    if (burned === shares) costBasis = 0n
+    else if (costBasis !== undefined && removed !== undefined) costBasis -= removed
+    shares -= burned
+    return { costBasis: removed }
+  }
+
+  for (const action of options.actions) {
+    if (action.kind === 'deposit') {
+      if (costBasis !== undefined) costBasis += action.assets
+      shares += action.shares
+      continue
+    }
+    if (action.kind === 'unknown') {
+      costBasis = undefined
+      shares += action.shares
+      continue
+    }
+    if (action.kind === 'cancel') {
+      const restored = requests.get(action.requestId)
+      if (restored === undefined || restored.shares !== action.shares) return undefined
+      if (costBasis === undefined || restored.costBasis === undefined) costBasis = undefined
+      else costBasis += restored.costBasis
+      shares += restored.shares
+      requests.delete(action.requestId)
+      continue
+    }
+    const removed = remove(action.shares)
+    if (removed === undefined) return undefined
+    if (action.kind === 'request')
+      requests.set(action.requestId, { costBasis: removed.costBasis, shares: action.shares })
+  }
+
+  return shares === options.shareBalance && costBasis !== undefined ? costBasis : undefined
+}
+
+export declare namespace calculateActiveCostBasis {
+  /** One indexed share or cost-basis mutation. */
+  export type Action =
+    | {
+        /** Action discriminator. */
+        kind: 'cancel'
+        /** Async redemption request being cancelled. */
+        requestId: string
+        /** Shares restored to the account. */
+        shares: bigint
+      }
+    | {
+        /** Assets added to the account's cost basis. */
+        assets: bigint
+        /** Action discriminator. */
+        kind: 'deposit'
+        /** Shares issued for the deposit. */
+        shares: bigint
+      }
+    | {
+        /** Action discriminator. */
+        kind: 'redeem'
+        /** Shares removed from the account. */
+        shares: bigint
+      }
+    | {
+        /** Action discriminator. */
+        kind: 'request'
+        /** Async redemption request holding the removed basis. */
+        requestId: string
+        /** Shares removed from the account. */
+        shares: bigint
+      }
+    | {
+        /** Action discriminator. */
+        kind: 'unknown'
+        /** Shares received without an asset-denominated cost basis. */
+        shares: bigint
+      }
+
+  /** Inputs for calculating the remaining cost basis. */
+  export type Options = {
+    /** Indexed mutations in chain order. */
+    actions: readonly Action[]
+    /** Share balance read at the same indexed block. */
+    shareBalance: bigint
+  }
+}
+
+/** Reads the active asset cost basis for shares held at one indexed block. */
+async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis.Options) {
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT kind, request_id, shares, assets
+      FROM (
+        SELECT
+          'deposit' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(earnShares)) AS shares,
+          toString(toUInt256(assets)) AS assets
+        FROM Deposited
+        WHERE address = '${options.vault}'
+          AND receiver = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'redeem' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(earnShares)) AS shares,
+          '0' AS assets
+        FROM Redeemed
+        WHERE address = '${options.vault}'
+          AND caller = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'redeem' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(earnSharesBurned)) AS shares,
+          '0' AS assets
+        FROM WithdrewExact
+        WHERE address = '${options.vault}'
+          AND caller = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'request' AS kind,
+          block_num,
+          log_idx,
+          "requestId" AS request_id,
+          toString(toUInt256(earnShares)) AS shares,
+          '0' AS assets
+        FROM RedeemRequested
+        WHERE address = '${options.vault}'
+          AND requester = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'cancel' AS kind,
+          cancelled.block_num AS block_num,
+          cancelled.log_idx AS log_idx,
+          cancelled."requestId" AS request_id,
+          toString(toUInt256(cancelled.earnShares)) AS shares,
+          '0' AS assets
+        FROM RedeemCancelled AS cancelled
+        INNER JOIN RedeemRequested AS requested
+          ON requested.address = cancelled.address
+          AND requested."requestId" = cancelled."requestId"
+        WHERE cancelled.address = '${options.vault}'
+          AND requested.requester = '${options.account}'
+          AND cancelled.receiver = '${options.account}'
+          AND cancelled.block_num <= ${options.blockNumber}
+          AND requested.block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'unknown' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(earnShares)) AS shares,
+          '0' AS assets
+        FROM VenueSharesDeposited
+        WHERE address = '${options.vault}'
+          AND receiver = '${options.account}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'unknown' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(amount)) AS shares,
+          '0' AS assets
+        FROM token_transfers
+        WHERE token = '${options.shareToken.toLowerCase()}'
+          AND "to" = '${options.account}'
+          AND "from" != '${zeroAddress}'
+          AND "from" != '${options.vault}'
+          AND block_num <= ${options.blockNumber}
+        UNION ALL
+        SELECT
+          'redeem' AS kind,
+          block_num,
+          log_idx,
+          '' AS request_id,
+          toString(toUInt256(amount)) AS shares,
+          '0' AS assets
+        FROM token_transfers
+        WHERE token = '${options.shareToken.toLowerCase()}'
+          AND "from" = '${options.account}'
+          AND "to" != '${options.vault}'
+          AND block_num <= ${options.blockNumber}
+      ) AS actions
+      ORDER BY block_num, log_idx
+    ` as string,
+    signatures: [
+      depositedSignature,
+      redeemCancelledSignature,
+      redeemRequestedSignature,
+      redeemedSignature,
+      venueSharesDepositedSignature,
+      withdrewExactSignature,
+    ],
+  })
+  const actions: calculateActiveCostBasis.Action[] = []
+  for (const row of result.rows) {
+    const kind = Value.toText(row['kind'])
+    if (kind === 'deposit') {
+      const assets = Value.toIntegerString(row['assets'])
+      const shares = Value.toIntegerString(row['shares'])
+      if (assets === undefined || shares === undefined) return undefined
+      actions.push({ assets: BigInt(assets), kind, shares: BigInt(shares) })
+      continue
+    }
+    if (kind === 'redeem') {
+      const shares = Value.toIntegerString(row['shares'])
+      if (shares === undefined) return undefined
+      actions.push({ kind, shares: BigInt(shares) })
+      continue
+    }
+    if (kind === 'cancel') {
+      const requestId = Value.toText(row['request_id'])
+      const shares = Value.toIntegerString(row['shares'])
+      if (requestId === undefined || shares === undefined) return undefined
+      actions.push({ kind, requestId, shares: BigInt(shares) })
+      continue
+    }
+    if (kind === 'request') {
+      const requestId = Value.toText(row['request_id'])
+      const shares = Value.toIntegerString(row['shares'])
+      if (requestId === undefined || shares === undefined) return undefined
+      actions.push({ kind, requestId, shares: BigInt(shares) })
+      continue
+    }
+    if (kind === 'unknown') {
+      const shares = Value.toIntegerString(row['shares'])
+      if (shares === undefined) return undefined
+      actions.push({ kind, shares: BigInt(shares) })
+      continue
+    }
+    return undefined
+  }
+  return calculateActiveCostBasis({ actions, shareBalance: options.shareBalance })
+}
+
+declare namespace getActiveCostBasis {
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber: number
+    shareBalance: bigint
+    shareToken: z.output<typeof Schema.Address>
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** 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'
+}