tapimo 0.15.1 → 0.18.0

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

@@ -18,7 +18,6 @@ import * as Scope from '../../../Scope.js'
 import * as Db from '../../../db/Db.js'
 import * as core_EarnVaults from '../../../db/tables/earnVaults.js'
 import * as RewardCampaignDistributors from '../../../db/tables/rewardCampaignDistributors.js'
-import * as RewardCampaigns from '../../../db/tables/rewardCampaigns.js'
 import * as RewardEligibilityAssociations from '../../../db/tables/rewardEligibilityAssociations.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
@@ -26,6 +25,7 @@ import * as Cursor from '../../../internal/Cursor.js'
 import * as EarnRates from '../../../internal/EarnRates.js'
 import * as EarnSharePrices from '../../../internal/EarnSharePrices.js'
 import * as EarnVaults from '../../../internal/EarnVaults.js'
+import * as EarnWithdrawals from '../../../internal/EarnWithdrawals.js'
 import type * as Log from '../../../internal/Log.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
 import * as RewardRead from '../../../internal/rewards/Read.js'
@@ -663,11 +663,13 @@ export namespace schema {
       z.meta({ examples: ['0'] }),
     ),
     assetBalance: Schema.DecimalString.check(
-      z.describe('Assets held by this account at the observation block, in asset base units.'),
+      z.describe(
+        'Public vault assets held by this account at the observation block, in asset base units.',
+      ),
       z.meta({ examples: ['250000000'] }),
     ),
     assetToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(
-      z.describe('TIP-20 asset token accepted by the vault or its selected Zone route.'),
+      z.describe('TIP-20 asset token accepted by the public parent vault.'),
     ),
     chainId: Schema.ChainId.check(
       z.describe('Chain containing the account position.'),
@@ -677,6 +679,17 @@ export namespace schema {
       z.describe('Stable resource ID for this vault position, equal to the account address.'),
       z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
     ),
+    privateAssetBalance: z
+      .optional(Schema.DecimalString)
+      .check(
+        z.describe(
+          'Private Zone assets held by this account at the observation block, in private asset base units.',
+        ),
+        z.meta({ examples: ['250000000'] }),
+      ),
+    privateAssetToken: z
+      .optional(Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50'))
+      .check(z.describe('TIP-20 private asset used by the validated Zone route.')),
     shareAllowance: Schema.DecimalString.check(
       z.describe(
         'Earn shares the vault may spend from a direct account, in share base units. Always zero for Zone-routed positions, which use Zone withdrawals instead of approvals.',
@@ -730,7 +743,9 @@ export namespace schema {
                     ),
                 })
                 .check(
-                  z.describe('Vault asset amount receiving this annual rate.'),
+                  z.describe(
+                    'Vault asset amount receiving this annual rate. Zero for an eligible boost with no currently qualified amount.',
+                  ),
                   z.meta({
                     examples: [{ baseUnits: '25000000000', decimals: 6, formatted: '25000' }],
                   }),
@@ -742,14 +757,16 @@ export namespace schema {
               type: z
                 .enum(['base', 'boost'])
                 .check(
-                  z.describe('Base vault yield or qualified depositor boost.'),
+                  z.describe('Base vault yield or eligible depositor boost target.'),
                   z.meta({ examples: ['boost'] }),
                 ),
             })
             .check(z.describe('Position component receiving one annual rate.')),
         )
         .check(
-          z.describe('Position amounts grouped by the annual rate they receive.'),
+          z.describe(
+            'Position amounts grouped by annual rate. Eligible active boosts appear even with zero qualified amount and do not increase the balance-weighted net rate.',
+          ),
           z.meta({
             examples: [
               [
@@ -789,7 +806,9 @@ export namespace schema {
         z.describe('Assets deposited with this account as receiver over indexed vault history.'),
       ),
       totalWithdrawn: Schema.DecimalString.check(
-        z.describe('Assets returned by completed withdrawals over indexed vault history.'),
+        z.describe(
+          'Completed withdrawal proceeds plus other outgoing shares valued at their transfer blocks.',
+        ),
       ),
     }),
     z.strictObject({
@@ -863,7 +882,7 @@ export namespace schema {
     ),
     currentValue: Schema.DecimalString.check(
       z.describe(
-        'Asset value of the account’s active earn shares at the latest indexed block, in asset base units.',
+        'Asset value of the account’s active earn shares at the ending indexed block, in asset base units.',
       ),
       z.meta({ examples: ['600000'] }),
     ),
@@ -874,14 +893,39 @@ export namespace schema {
   })
 
   const earningsPeriod = z
-    .enum(['30d', 'active', 'lifetime'])
+    .enum(['7d', '30d', 'active', 'custom', 'lifetime'])
     .check(
       z.describe(
-        'Earnings period to calculate: trailing 30 days, shares still held, or lifetime history.',
+        'Earnings period: trailing 7 or 30 days, shares still held, explicit timestamps, or lifetime history.',
       ),
       z.meta({ examples: ['lifetime'] }),
     )
 
+  const earningsWindow = z.extend(earningsBase, {
+    end: z.iso
+      .datetime()
+      .check(
+        z.describe(
+          'UTC ending boundary. Includes activity through the latest indexed block at or before this timestamp.',
+        ),
+        z.meta({ examples: ['2026-09-18T00:00:00.000Z'] }),
+      ),
+    period: z
+      .enum(['7d', '30d', 'custom'])
+      .check(
+        z.describe('Rolling or explicitly bounded earnings window.'),
+        z.meta({ examples: ['7d'] }),
+      ),
+    start: z.iso
+      .datetime()
+      .check(
+        z.describe(
+          'UTC opening boundary. Excludes activity through the latest indexed block at or before this timestamp.',
+        ),
+        z.meta({ examples: ['2026-09-11T00:00:00.000Z'] }),
+      ),
+  })
+
   const earnings = z.union([
     z.extend(earningsBase, {
       lifetimeEarnings: z
@@ -889,7 +933,7 @@ export namespace schema {
         .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.',
+            'Current share value plus withdrawals, including outgoing shares valued when transferred, minus asset deposits, at the latest indexed block.',
           ),
           z.meta({ examples: ['0'] }),
         ),
@@ -901,7 +945,7 @@ export namespace schema {
       ),
       totalWithdrawn: Schema.DecimalString.check(
         z.describe(
-          'Assets returned by completed redemptions and exact withdrawals initiated by this account over complete indexed vault history.',
+          'Completed vault withdrawal proceeds plus other outgoing shares valued at their transfer blocks, regardless of recipient or spender.',
         ),
         z.meta({ examples: ['1000000'] }),
       ),
@@ -941,13 +985,7 @@ export namespace schema {
           z.meta({ examples: ['complete'] }),
         ),
     }),
-    z.extend(earningsBase, {
-      period: z
-        .literal('30d')
-        .check(
-          z.describe('Returns cash-flow-adjusted earnings over the trailing 30 days.'),
-          z.meta({ examples: ['30d'] }),
-        ),
+    z.extend(earningsWindow, {
       status: z
         .literal('complete')
         .check(
@@ -959,13 +997,18 @@ export namespace schema {
         .check(
           z.regex(/^-?\d+$/),
           z.describe(
-            'Ending share value plus realized assets, minus deposits and opening share value, over the trailing 30 days.',
+            'Ending share value plus withdrawals, including outgoing shares valued when transferred, minus deposits and opening share value, over the requested window.',
           ),
           z.meta({ examples: ['0'] }),
         ),
     }),
     z.extend(earningsBase, {
-      period: earningsPeriod,
+      period: z
+        .enum(['active', 'lifetime'])
+        .check(
+          z.describe('Earnings period with unavailable cost basis.'),
+          z.meta({ examples: ['lifetime'] }),
+        ),
       status: z
         .literal('incomplete_cost_basis')
         .check(
@@ -975,13 +1018,17 @@ export namespace schema {
           z.meta({ examples: ['incomplete_cost_basis'] }),
         ),
     }),
-    z.extend(earningsBase, {
-      period: z
-        .literal('30d')
+    z.extend(earningsWindow, {
+      status: z
+        .literal('incomplete_cost_basis')
         .check(
-          z.describe('Trailing period with an unresolved async redemption.'),
-          z.meta({ examples: ['30d'] }),
+          z.describe(
+            'Indexed activity cannot reconstruct the requested window’s asset cost basis.',
+          ),
+          z.meta({ examples: ['incomplete_cost_basis'] }),
         ),
+    }),
+    z.extend(earningsWindow, {
       status: z
         .literal('pending_redemption')
         .check(
@@ -1422,12 +1469,42 @@ export namespace schema {
       })
       .check(z.describe('Path parameters identifying an earn vault account.'))
 
-    /** Query parameters selecting the chain containing the vault. */
+    /** Query parameters selecting the chain and earnings interval. */
     export const Query = z
       .strictObject({
         chainId: Schema.ChainIdQuery,
+        end: z
+          .optional(z.iso.datetime({ offset: true }))
+          .check(
+            z.describe(
+              'Required with period=custom. Inclusive ISO 8601 ending timestamp; indexed history must cover this time.',
+            ),
+            z.meta({ examples: ['2026-09-18T00:00:00.000Z'] }),
+          ),
         period: z._default(earningsPeriod, 'lifetime'),
+        start: z
+          .optional(z.iso.datetime({ offset: true }))
+          .check(
+            z.describe(
+              'Required with period=custom. Exclusive ISO 8601 opening timestamp, earlier than end.',
+            ),
+            z.meta({ examples: ['2026-09-11T00:00:00.000Z'] }),
+          ),
       })
+      .check(
+        z.refine(
+          (value) =>
+            value.period === 'custom'
+              ? value.start !== undefined &&
+                value.end !== undefined &&
+                Date.parse(value.start) < Date.parse(value.end)
+              : value.start === undefined && value.end === undefined,
+          {
+            message:
+              'Only period=custom accepts start and end; both are required and start must be earlier than end',
+          },
+        ),
+      )
       .check(z.describe('Query parameters selecting an earn vault account.'))
 
     /** Earnings for one account and period in one Earn vault. */
@@ -1447,7 +1524,7 @@ export function earn(options: earn.Options = {}) {
   return new Hono<App.Environment>()
     .post(
       '/v1/earn/rewards/eligibility',
-      Auth.policy({ apiKey: { scopes: [Scope.wildcard] } }),
+      Auth.policy({ apiKey: { scopes: ['rewards:write'] } }),
       OpenApi.validate('json', schema.registerRewardEligibility.Body, {
         code: 'body_invalid',
         message: 'Invalid reward eligibility registration',
@@ -1480,6 +1557,25 @@ export function earn(options: earn.Options = {}) {
         if (!c.get('supportedChainIds').has(body.chainId))
           return Response.unsupportedChainId(c, body.chainId, c.get('supportedChainIds'))
         c.set('chainId', body.chainId)
+        if (c.get('zones').has(body.chainId))
+          return Response.error(c, {
+            code: 'chain_id_unsupported',
+            message: `Zone chain ID ${body.chainId} is not supported for rewards registration.`,
+            status: 400,
+          })
+
+        const principal = Auth.getPrincipal(c)
+        if (
+          principal?.type === 'api_key' &&
+          principal.environment === 'sandbox' &&
+          Viem.isMainnet(body.chainId)
+        )
+          return Response.error(c, {
+            code: 'api_key_forbidden',
+            message: 'Sandbox API keys only support testnet.',
+            status: 403,
+          })
+
         c.header('Cache-Control', Cache.policies.noStore)
         const result = await RewardEligibilityAssociations.upsert(Db.get(c.get('db')), {
           ...body,
@@ -1944,21 +2040,26 @@ export function earn(options: earn.Options = {}) {
           })
         if (c.get('zones').has(chainId)) Cache.setPolicy(c, Cache.policies.noStore)
         try {
-          const position = await getVaultPosition(c, {
-            account: address,
-            asOf: query.asOf,
-            chainId,
-            vault: vaultId,
-          })
-          const apy = query.include.includes('apy')
-            ? await resolvePositionApy(c, {
+          const position_pending = Timing.time(c, 'earn_position', () =>
+            getVaultPosition(c, {
+              account: address,
+              asOf: query.asOf,
+              chainId,
+              vault: vaultId,
+            }),
+          )
+          // Rate and vault reads depend only on the vault, so they overlap the
+          // position's chained RPC hops instead of queueing behind them.
+          const apy_pending = query.include.includes('apy')
+            ? resolvePositionApy(c, {
                 chainId,
+                position: position_pending,
                 recipient: address,
-                shareBalance: position.shareBalance,
-                value: position.value,
                 vault: vaultId,
               })
             : undefined
+          const position = await position_pending
+          const apy = await apy_pending
           const rewards = query.include.some((value) => value.startsWith('rewards'))
             ? await RewardRead.recipient({
                 chainId,
@@ -1979,6 +2080,12 @@ export function earn(options: earn.Options = {}) {
               asOf: query.asOf,
               block: position.block,
               id: address,
+              ...(position.privateAssetBalance === undefined
+                ? {}
+                : { privateAssetBalance: position.privateAssetBalance.toString() }),
+              ...(position.privateAssetToken === undefined
+                ? {}
+                : { privateAssetToken: position.privateAssetToken }),
               ...(rewards
                 ? {
                     rewards: query.include.includes('rewards.proof')
@@ -2080,7 +2187,7 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Gets an account’s indexed asset value and earnings for lifetime history, the trailing 30 days, or shares still held.',
+          'Gets an account’s asset value and earnings for lifetime history, shares still held, or a rolling or custom time window.',
         operationId: 'getEarnVaultEarnings',
         responses: OpenApi.responses({
           errors: {
@@ -2109,7 +2216,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultEarnings.Query),
-        name: 'tempo-api:earn-vault-earnings:v4',
+        name: 'tempo-api:earn-vault-earnings:v5',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -2141,13 +2248,15 @@ export function earn(options: earn.Options = {}) {
         const chainId = query.chainId ?? c.get('chainId')
         try {
           const data = await getVaultEarnings(c, {
+            ...query,
             account: address,
             chainId,
-            period: query.period,
             vault: vaultId,
           })
           return c.json(Response.validated(schema.getEarnVaultEarnings.Response, data), 200)
         } catch (cause) {
+          if (cause instanceof IndexedBlockNotFoundError || cause instanceof IndexedCoverageError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
           try {
             await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId })
           } catch (vaultCause) {
@@ -2271,19 +2380,27 @@ export async function getVaultEarnings(
 ) {
   const client = c.get('getClient')(options.chainId)
   const tidx = c.get('getTidx')(options.chainId)
-  const [block, rewardTransfer] = await Promise.all([
-    getLatestIndexedBlock(tidx),
-    getRewardTransferPredicate(c, options),
+  const [block, earnings] = await Promise.all([
+    options.period === 'custom'
+      ? getIndexedBlockAtOrBefore(tidx, options.end!)
+      : getLatestIndexedBlock(tidx),
+    getEarningsConfiguration(c, options),
   ])
   const blockNumber = block.number
-  if (options.period === '30d')
+  if (options.period === '7d' || options.period === '30d' || options.period === 'custom')
     return getWindowVaultEarnings(c, {
       account: options.account,
       blockNumber,
       chainId: options.chainId,
+      earnings,
+      end: options.period === 'custom' ? new Date(options.end!).toISOString() : block.timestamp,
       period: options.period,
-      rewardTransfer,
-      timestamp: block.timestamp,
+      start:
+        options.period === 'custom'
+          ? new Date(options.start!).toISOString()
+          : new Date(
+              Date.parse(block.timestamp) - Ttl.days(options.period === '7d' ? 7 : 30),
+            ).toISOString(),
       vault: options.vault,
     })
   const position = client.earn.getPosition({
@@ -2303,7 +2420,7 @@ export async function getVaultEarnings(
     const activeCostBasis = await getActiveCostBasis(tidx, {
       account: options.account,
       blockNumber,
-      rewardTransfer,
+      rewardTransfer: getRewardTransferPredicate(current.shareToken, earnings.rewardDistributors),
       shareBalance: current.shareBalance,
       shareToken: current.shareToken,
       vault: options.vault,
@@ -2324,10 +2441,11 @@ export async function getVaultEarnings(
     }),
     position,
   ])
-  const externalShareTransfer = await hasExternalShareTransfer(tidx, {
+  const transfers = await getShareTransferState(tidx, {
     account: options.account,
     blockNumber,
-    rewardTransfer,
+    client,
+    rewardTransfer: getRewardTransferPredicate(current.shareToken, earnings.rewardDistributors),
     shareToken: current.shareToken,
     startBlockNumber: beforeFirstBlockNumber,
     vault: options.vault,
@@ -2339,9 +2457,10 @@ export async function getVaultEarnings(
     id: options.account,
     period: options.period,
   }
-  if (history.incompleteCostBasis || externalShareTransfer)
+  if (history.incompleteCostBasis || transfers.external || transfers.withdrawn === undefined)
     return { ...base, status: 'incomplete_cost_basis' as const }
-  const totalWithdrawn = history.redeemed + history.withdrewExact + history.finalized
+  const totalWithdrawn =
+    history.redeemed + history.withdrewExact + history.finalized + transfers.withdrawn
   const cashFlows = {
     totalDeposited: history.deposited.toString(),
     totalWithdrawn: totalWithdrawn.toString(),
@@ -2357,7 +2476,7 @@ export async function getVaultEarnings(
   }
 }
 
-/** Reads cash-flow-adjusted earnings over a trailing indexed window. */
+/** Reads cash-flow-adjusted earnings over an indexed time window. */
 async function getWindowVaultEarnings(
   c: Context<App.Environment>,
   options: getWindowVaultEarnings.Options,
@@ -2370,13 +2489,19 @@ async function getWindowVaultEarnings(
       blockNumber: BigInt(options.blockNumber),
       vault: options.vault,
     }),
-    getWindowStartBlockNumber(tidx, { days: 30, timestamp: options.timestamp }),
+    options.period === 'custom'
+      ? getIndexedBlockAtOrBefore(tidx, options.start).then((block) => block.number)
+      : getWindowStartBlockNumber(tidx, { timestamp: options.start }),
   ])
-  const [externalShareTransfer, history, opening] = await Promise.all([
-    hasExternalShareTransfer(tidx, {
+  const [transfers, history, opening] = await Promise.all([
+    getShareTransferState(tidx, {
       account: options.account,
       blockNumber: options.blockNumber,
-      rewardTransfer: options.rewardTransfer,
+      client,
+      rewardTransfer: getRewardTransferPredicate(
+        current.shareToken,
+        options.earnings.rewardDistributors,
+      ),
       shareToken: current.shareToken,
       startBlockNumber,
       vault: options.vault,
@@ -2399,12 +2524,15 @@ async function getWindowVaultEarnings(
     account: options.account,
     assetToken: current.assetToken,
     currentValue: current.value.toString(),
+    end: options.end,
     id: options.account,
     period: options.period,
+    start: options.start,
   }
   if (
     opening === undefined ||
-    externalShareTransfer ||
+    transfers.external ||
+    transfers.withdrawn === undefined ||
     history.incompleteCostBasis ||
     opening.crossBoundaryRedemption ||
     opening.endShares !== current.shareBalance
@@ -2425,7 +2553,7 @@ async function getWindowVaultEarnings(
     finalized: history.finalized,
     openingValue,
     redeemed: history.redeemed,
-    withdrewExact: history.withdrewExact,
+    withdrewExact: history.withdrewExact + transfers.withdrawn,
   })
   return { ...base, status: 'complete' as const, windowEarnings: windowEarnings.toString() }
 }
@@ -2439,12 +2567,14 @@ declare namespace getWindowVaultEarnings {
     blockNumber: number
     /** Tempo chain containing the vault. */
     chainId: z.output<typeof Schema.ChainId>
-    /** Trailing earnings period. */
-    period: '30d'
-    /** SQL predicate recognizing paid rewards in the share-transfer history. */
-    rewardTransfer: string
-    /** Latest indexed block timestamp. */
-    timestamp: string
+    /** Counterparties recognized for this vault's earnings. */
+    earnings: z.output<typeof EarnVaults.schema.Earnings>
+    /** Inclusive ending timestamp in UTC. */
+    end: string
+    /** Rolling or custom earnings period. */
+    period: '7d' | '30d' | 'custom'
+    /** Exclusive opening timestamp in UTC. */
+    start: string
     /** Earn vault contract address. */
     vault: z.output<typeof Schema.Address>
   }
@@ -2482,10 +2612,9 @@ export declare namespace calculateWindowEarnings {
 
 export declare namespace getVaultEarnings {
   /** Inputs identifying the account and vault to calculate. */
-  type Options = {
+  type Options = z.output<typeof schema.getEarnVaultEarnings.Query> & {
     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>
   }
 }
@@ -2559,12 +2688,12 @@ export declare namespace parseIndexedBlockAtOrBefore {
   }
 }
 
-/** Resolves the last indexed block at or before a trailing-day boundary. */
+/** Resolves a rolling boundary, allowing windows that start before the chain existed. */
 async function getWindowStartBlockNumber(
   tidx: Tidx.Client,
   options: getWindowStartBlockNumber.Options,
 ) {
-  const cutoff = new Date(Date.parse(options.timestamp) - Ttl.days(options.days)).toISOString()
+  const cutoff = options.timestamp
   const result = await tidx.fetch({
     query:
       `SELECT num FROM blocks WHERE timestamp <= '${cutoff}' ORDER BY num DESC LIMIT 1` as string,
@@ -2577,11 +2706,9 @@ async function getWindowStartBlockNumber(
 }
 
 declare namespace getWindowStartBlockNumber {
-  /** Inputs defining a trailing boundary from an indexed timestamp. */
+  /** Inputs defining a rolling window's opening boundary. */
   type Options = {
-    /** Number of trailing days. */
-    days: number
-    /** Timestamp anchoring the end of the window. */
+    /** Canonical UTC timestamp anchoring the start of the window. */
     timestamp: string
   }
 }
@@ -2824,31 +2951,44 @@ declare namespace getWindowShareState {
   }
 }
 
-/** Builds a share-transfer predicate for the vault's verified reward distributors. */
-async function getRewardTransferPredicate(
+/** Combines recorded campaign distributors with additional per-vault reward distributors. */
+async function getEarningsConfiguration(
   c: Context<App.Environment>,
   options: Pick<getVaultEarnings.Options, 'chainId' | 'vault'>,
-) {
+): Promise<z.output<typeof EarnVaults.schema.Earnings>> {
   const db = Db.get(c.get('db'))
-  const campaign = await RewardCampaigns.get(db, {
+  const record = await core_EarnVaults.get(db, {
     chainId: options.chainId,
     vaultAddress: options.vault,
   })
-  if (!campaign) return '0'
   const distributors = await RewardCampaignDistributors.list(db, {
     chainId: options.chainId,
     vaultAddress: options.vault,
   })
+  return {
+    rewardDistributors: [
+      ...new Set([
+        ...distributors.map(({ distributorAddress }) => distributorAddress),
+        ...(record?.earnings?.rewardDistributors ?? []),
+      ]),
+    ],
+  }
+}
+
+/** Builds a share-transfer predicate scoped to this vault's share token and configured distributors. */
+function getRewardTransferPredicate(
+  shareToken: z.output<typeof Schema.Address>,
+  distributors: readonly z.output<typeof Schema.Address>[],
+) {
   if (distributors.length === 0) return '0'
   const addresses = distributors
-    .map(({ distributorAddress }) => Schema.Address.parse(distributorAddress))
+    .map((address) => Schema.Address.parse(address))
     .map((address) => `'${address}'`)
     .join(', ')
-  const shareToken = Schema.Address.parse(campaign.earnShareAddress)
 
   // Batch rewards have no per-recipient event; exclude treasury returns instead. Qualify the filter so TIDX does not apply it to other event CTEs.
   return `
-    token = '${shareToken}'
+    token = '${shareToken.toLowerCase()}'
     AND "from" IN (${addresses})
     AND tx_hash NOT IN (
       SELECT returned.tx_hash FROM UnspentReturned AS returned
@@ -2857,12 +2997,10 @@ async function getRewardTransferPredicate(
   `
 }
 
-/** 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.
+/** Reads unknown incoming shares and recipient-independent outgoing share values. */
+async function getShareTransferState(tidx: Tidx.Client, options: getShareTransferState.Options) {
+  const withdrawals = await EarnWithdrawals.read(tidx, options)
+  // Incoming rewards and cancelled requests are known; other receipts still lack deposit basis.
   const result = await tidx.fetch({
     engine: 'clickhouse',
     query: `
@@ -2874,56 +3012,11 @@ async function hasExternalShareTransfer(
             AND toUInt256(amount) > 0
             AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
-            AND (
-              ("from" = '${options.account}' AND "to" != '${options.vault}')
-              OR (
-                "to" = '${options.account}'
-                AND "from" != '${zeroAddress}'
-                AND "from" != '${options.vault}'
-                AND NOT (${options.rewardTransfer})
-              )
-            )
-        ) + (
-          SELECT count()
-          FROM (
-            SELECT tx_hash, toUInt256(amount) AS amount, count() AS transfer_count
-            FROM token_transfers
-            WHERE token = '${options.shareToken.toLowerCase()}'
-              AND toUInt256(amount) > 0
-              AND "from" = '${options.account}'
-              AND "to" = '${options.vault}'
-              AND block_num > ${options.startBlockNumber}
-              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.startBlockNumber}
-                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.startBlockNumber}
-                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.startBlockNumber}
-                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)
+            AND "to" = '${options.account}'
+            AND "from" != '${options.account}'
+            AND "from" != '${zeroAddress}'
+            AND "from" != '${options.vault}'
+            AND NOT (${options.rewardTransfer})
         ) + (
           SELECT count()
           FROM (
@@ -2960,13 +3053,20 @@ async function hasExternalShareTransfer(
   })
   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
+  return {
+    external: count > 0,
+    withdrawn:
+      count > 0
+        ? undefined
+        : await EarnWithdrawals.value(options.client, { vault: options.vault, withdrawals }),
+  }
 }
 
-declare namespace hasExternalShareTransfer {
+declare namespace getShareTransferState {
   type Options = {
     account: z.output<typeof Schema.Address>
     blockNumber: number
+    client: Viem.getClient.ReturnType
     rewardTransfer: string
     shareToken: z.output<typeof Schema.Address>
     startBlockNumber: number
@@ -3073,6 +3173,14 @@ export declare namespace calculateActiveCostBasis {
 
 /** Reads the active asset cost basis for shares held at one indexed block. */
 async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis.Options) {
+  const withdrawals = await EarnWithdrawals.read(tidx, {
+    ...options,
+    startBlockNumber: beforeFirstBlockNumber,
+  })
+  const outgoing =
+    withdrawals.length === 0
+      ? '0'
+      : `(tx_hash, log_idx) IN (${withdrawals.map(({ transactionHash, logIndex }) => `('${transactionHash}', ${logIndex})`).join(', ')})`
   const result = await tidx.fetch({
     engine: 'clickhouse',
     query: `
@@ -3168,6 +3276,7 @@ async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis
           AND "to" = '${options.account}'
           AND "from" != '${zeroAddress}'
           AND "from" != '${options.vault}'
+          AND "from" != '${options.account}'
           AND block_num <= ${options.blockNumber}
         UNION ALL
         SELECT
@@ -3181,7 +3290,7 @@ async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis
         WHERE token = '${options.shareToken.toLowerCase()}'
           AND toUInt256(amount) > 0
           AND "from" = '${options.account}'
-          AND "to" != '${options.vault}'
+          AND (${outgoing})
           AND block_num <= ${options.blockNumber}
       ) AS actions
       ORDER BY block_num, log_idx
@@ -3630,21 +3739,63 @@ export async function getVaultPosition(
 ): Promise<getVaultPosition.ReturnType> {
   const zone = c.get('zones').get(options.chainId)
   if (!zone) {
-    const block =
-      options.asOf === undefined
-        ? undefined
-        : await getIndexedBlockAtOrBefore(c.get('getTidx')(options.chainId), options.asOf)
+    if (options.asOf === undefined) return readLivePosition(c, options)
+    const block = await getIndexedBlockAtOrBefore(c.get('getTidx')(options.chainId), options.asOf)
     const position = await c
       .get('getClient')(options.chainId)
       .earn.getPosition({
         account: options.account,
-        ...(block ? { blockNumber: BigInt(block.number) } : {}),
+        blockNumber: BigInt(block.number),
         vault: options.vault,
       })
     return { ...position, block, valueToken: position.assetToken }
   }
 
-  const route = await resolveZonePositionRoute(c, {
+  const { blockNumber, discovery, position, sourceBlock } = await getZoneVaultPositionCore(
+    c,
+    options,
+  )
+  const privateAsset = await resolveZonePositionPrivateAsset(c, {
+    chainId: options.chainId,
+    discovery,
+    vault: options.vault,
+  }).catch((cause) => {
+    recordZonePositionEnrichmentFailure(c, {
+      cause,
+      chainId: discovery.chainId,
+      operation: 'resolvePrivateAsset',
+    })
+    return undefined
+  })
+  const privateAssetBalance =
+    privateAsset && sourceBlock >= privateAsset.deploymentBlock
+      ? await readZoneBalance(c.get('getClient')(options.chainId), {
+          account: options.account,
+          blockNumber,
+          token: privateAsset.token,
+        }).catch((cause) => {
+          recordZonePositionEnrichmentFailure(c, {
+            cause,
+            chainId: options.chainId,
+            operation: 'eth_call',
+          })
+          return undefined
+        })
+      : undefined
+  return {
+    ...position,
+    ...(privateAssetBalance === undefined || privateAsset === undefined
+      ? {}
+      : { privateAssetBalance, privateAssetToken: privateAsset.token }),
+  }
+}
+
+/** Reads the on-chain Zone position without optional private-route enrichment. */
+async function getZoneVaultPositionCore(
+  c: Context<App.Environment>,
+  options: getVaultPosition.Options,
+) {
+  const core = await resolveZonePositionCore(c, {
     chainId: options.chainId,
     vault: options.vault,
   })
@@ -3658,44 +3809,168 @@ export async function getVaultPosition(
     readZoneBalance(zoneClient, {
       account: options.account,
       blockNumber,
-      token: route.privateAsset,
+      token: core.vaultAsset,
+    }).catch(async (cause) => {
+      // The public vault asset may not be deployed on the private Zone.
+      if (
+        cause instanceof ContractFunctionExecutionError &&
+        cause.walk((error) => error instanceof ContractFunctionZeroDataError)
+      )
+        return 0n
+      const code = await zoneClient.getCode({ address: core.vaultAsset, blockNumber })
+      if (!code || code === '0x') return 0n
+      throw cause
     }),
     readZoneBalance(zoneClient, {
       account: options.account,
       blockNumber,
-      token: route.shareToken,
+      token: core.shareToken,
+    }).catch(async (cause) => {
+      if (
+        cause instanceof ContractFunctionExecutionError &&
+        cause.walk((error) => error instanceof ContractFunctionZeroDataError)
+      )
+        throw new EarnVaults.NotFoundError()
+      const code = await zoneClient.getCode({ address: core.shareToken, blockNumber })
+      if (!code || code === '0x') throw new EarnVaults.NotFoundError()
+      throw cause
     }),
     readZoneSourceBlock(c, {
       blockNumber,
       historical: block !== undefined,
-      portal: route.portal,
-      sourceChainId: route.sourceChainId,
+      portal: core.portal,
+      sourceChainId: core.sourceChainId,
       zoneClient,
     }),
   ])
   const sourceBlock = Value.toNumber(importedParentBlockNumber)
-  if (sourceBlock === undefined || sourceBlock < route.deploymentBlock)
-    throw new EarnVaults.NotFoundError()
-  const value = await c
-    .get('getClient')(route.sourceChainId)
-    .earn.getRedeemQuote({
-      blockNumber: BigInt(sourceBlock),
-      shareAmount: shareBalance,
-      vault: options.vault,
-    })
+  if (sourceBlock === undefined) throw new EarnVaults.NotFoundError()
+  const value = await quoteZonePosition(c.get('getClient')(core.sourceChainId), {
+    blockNumber: BigInt(sourceBlock),
+    shareAmount: shareBalance,
+    vault: options.vault,
+  })
+  return {
+    blockNumber,
+    discovery: core.discovery,
+    position: {
+      assetAllowance: 0n,
+      assetBalance,
+      assetToken: core.vaultAsset,
+      block,
+      shareAllowance: 0n,
+      shareBalance,
+      shareToken: core.shareToken,
+      value,
+      valueToken: core.vaultAsset,
+    },
+    sourceBlock,
+  }
+}
+
+/** Quotes Zone shares only after the verified parent block contains the vault. */
+export async function quoteZonePosition(
+  client: ReturnType<App.Environment['Variables']['getClient']>,
+  options: quoteZonePosition.Options,
+) {
+  const code = await client.getCode({ address: options.vault, blockNumber: options.blockNumber })
+  if (!code || code === '0x') throw new EarnVaults.NotFoundError()
+  return client.earn.getRedeemQuote(options)
+}
+
+export declare namespace quoteZonePosition {
+  /** Aligned parent observation used to value Zone shares. */
+  type Options = {
+    /** Verified parent block imported by the Zone. */
+    blockNumber: bigint
+    /** Zone shares to quote. */
+    shareAmount: bigint
+    /** Public parent vault to quote. */
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/**
+ * Reads a live direct-chain position in two RPC hops by caching the vault's
+ * immutable token bindings, which otherwise cost a hop on every request.
+ */
+async function readLivePosition(
+  c: Context<App.Environment>,
+  options: readLivePosition.Options,
+): Promise<getVaultPosition.ReturnType> {
+  const client = c.get('getClient')(options.chainId)
+  const { asset, shareToken } = await resolveVaultBindings(c, options)
+  const [assetAllowance, assetBalance, shareAllowance, shareBalance] = await client.multicall({
+    allowFailure: false,
+    contracts: [
+      {
+        abi: Abis.tip20,
+        address: asset,
+        args: [options.account, options.vault],
+        functionName: 'allowance',
+      },
+      { abi: Abis.tip20, address: asset, args: [options.account], functionName: 'balanceOf' },
+      {
+        abi: Abis.tip20,
+        address: shareToken,
+        args: [options.account, options.vault],
+        functionName: 'allowance',
+      },
+      { abi: Abis.tip20, address: shareToken, args: [options.account], functionName: 'balanceOf' },
+    ],
+  })
+  const value = await client.earn.getRedeemQuote({
+    shareAmount: shareBalance,
+    vault: options.vault,
+  })
   return {
-    assetAllowance: 0n,
+    assetAllowance,
     assetBalance,
-    assetToken: route.privateAsset,
-    block,
-    shareAllowance: 0n,
+    assetToken: asset,
+    shareAllowance,
     shareBalance,
-    shareToken: route.shareToken,
+    shareToken,
     value,
-    valueToken: route.vaultAsset,
+    valueToken: asset,
   }
 }
 
+declare namespace readLivePosition {
+  /** Account and direct-chain vault whose live position is read. */
+  type Options = Pick<getVaultPosition.Options, 'account' | 'chainId' | 'vault'>
+}
+
+/** Resolves a vault's asset and EarnShare addresses, cached because they never change after deployment. */
+async function resolveVaultBindings(
+  c: Context<App.Environment>,
+  options: resolveVaultBindings.Options,
+) {
+  return Store.memoize(
+    async () => {
+      const [asset, shareToken] = await c
+        .get('getClient')(options.chainId)
+        .multicall({
+          allowFailure: false,
+          contracts: [
+            { abi: Abis.earnVault, address: options.vault, functionName: 'asset' },
+            { abi: Abis.earnVault, address: options.vault, functionName: 'earnShare' },
+          ],
+        })
+      return { asset, shareToken }
+    },
+    {
+      key: `earn-vault-bindings:v1:${options.chainId}:${options.vault.toLowerCase()}`,
+      store: c.get('store'),
+      ttl: Ttl.hours(1),
+    },
+  )
+}
+
+declare namespace resolveVaultBindings {
+  /** Vault whose immutable token bindings are resolved. */
+  type Options = Pick<getVaultPosition.Options, 'chainId' | 'vault'>
+}
+
 export declare namespace getVaultPosition {
   /** Inputs selecting one direct or Zone-routed account position. */
   type Options = {
@@ -3708,6 +3983,10 @@ export declare namespace getVaultPosition {
   /** Normalized position state across a direct chain or private Zone. */
   type ReturnType = Actions.earn.getPosition.ReturnValue & {
     block?: { number: number; timestamp: string } | undefined
+    /** Private route token balance, when Zone enrichment succeeds. */
+    privateAssetBalance?: bigint | undefined
+    /** Private route token address, when Zone enrichment succeeds. */
+    privateAssetToken?: z.output<typeof Schema.Address> | undefined
     valueToken: z.output<typeof Schema.Address>
   }
 }
@@ -3797,60 +4076,47 @@ export declare namespace alignZoneSourceBlock {
   }
 }
 
-/** Resolves the verified parent vault and token pair for one Zone route. */
-async function resolveZonePositionRoute(
+/** Resolves the public parent vault and Zone checkpoint boundary. */
+async function resolveZonePositionCore(
   c: Context<App.Environment>,
-  options: resolveZonePositionRoute.Options,
-): Promise<resolveZonePositionRoute.ReturnType> {
+  options: resolveZonePositionCore.Options,
+): Promise<resolveZonePositionCore.ReturnType> {
   const zone = c.get('zones').get(options.chainId)
   if (!zone?.sourceId) throw new EarnVaults.NotFoundError()
-  const db = Db.get(c.get('dbCached'))
-  const record = await core_EarnVaults.get(db, {
-    chainId: zone.sourceId,
-    vaultAddress: options.vault,
-  })
-  const configured = record?.zones.find((route) => route.chainId === options.chainId)
-  if (!record || !configured) throw new EarnVaults.NotFoundError()
   const discovery = await resolveVaultDiscovery(c, {
     chainId: zone.sourceId,
     include: [],
     vaultAddress: options.vault,
+  }).catch((cause) => {
+    if (isIncompatible(cause)) throw new EarnVaults.NotFoundError()
+    throw cause
   })
-  const [route] = await EarnVaults.resolveZoneRoutes({
-    discovery,
-    getClient: c.get('getClient'),
-    routes: [configured],
-    zones: [...c.get('zones').values()],
-  })
-  const privateAsset = route?.inputTokens[0]
   const portalContract = zone.contracts?.['portal']
   const portal = Schema.Address.safeParse(
     portalContract && 'address' in portalContract
       ? portalContract.address
       : portalContract?.[zone.sourceId]?.address,
   )
-  if (!route || !privateAsset || !portal.success) throw new EarnVaults.NotFoundError()
+  if (!portal.success) throw new EarnVaults.NotFoundError()
   return {
-    deploymentBlock: route.deploymentBlock,
+    discovery,
     portal: portal.data,
-    privateAsset,
     shareToken: discovery.shareToken.address,
     sourceChainId: zone.sourceId,
     vaultAsset: discovery.assetToken.address,
   }
 }
 
-declare namespace resolveZonePositionRoute {
-  /** Zone and parent vault selecting one curated route. */
+declare namespace resolveZonePositionCore {
+  /** Zone and public parent vault selecting one position. */
   type Options = {
     chainId: z.output<typeof Schema.ChainId>
     vault: z.output<typeof Schema.Address>
   }
 
-  /** Verified addresses needed to read and value a Zone position. */
+  /** Public addresses and checkpoint boundary needed to read and value a Zone position. */
   type ReturnType = {
-    deploymentBlock: number
-    privateAsset: z.output<typeof Schema.Address>
+    discovery: EarnVaults.Discovery
     portal: z.output<typeof Schema.Address>
     shareToken: z.output<typeof Schema.Address>
     sourceChainId: number
@@ -3858,6 +4124,69 @@ declare namespace resolveZonePositionRoute {
   }
 }
 
+/** Resolves an optional validated private asset from the Admin Zone route. */
+async function resolveZonePositionPrivateAsset(
+  c: Context<App.Environment>,
+  options: resolveZonePositionPrivateAsset.Options,
+) {
+  const record = await core_EarnVaults.get(Db.get(c.get('dbCached')), {
+    chainId: options.discovery.chainId,
+    vaultAddress: options.vault,
+  })
+  const configured = record?.zones.find((route) => route.chainId === options.chainId)
+  if (!configured) return undefined
+  const [route] = await EarnVaults.resolveZoneRoutes({
+    discovery: options.discovery,
+    getClient: c.get('getClient'),
+    routes: [configured],
+    zones: [...c.get('zones').values()],
+  })
+  const token = route?.inputTokens[0]
+  return token ? { deploymentBlock: route.deploymentBlock, token } : undefined
+}
+
+declare namespace resolveZonePositionPrivateAsset {
+  /** Curated route to validate for optional Zone enrichment. */
+  type Options = {
+    /** Private Zone containing the route. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** Public vault bindings used to validate the route. */
+    discovery: EarnVaults.Discovery
+    /** Public parent vault address. */
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+/** Records a bounded dependency signal without failing the core Zone position. */
+function recordZonePositionEnrichmentFailure(
+  c: Context<App.Environment>,
+  options: recordZonePositionEnrichmentFailure.Options,
+) {
+  Cache.setPolicy(c, Cache.policies.noStore)
+  const rpc = Viem.requestFailure(options.cause)
+  const failure: Log.ProviderFailure = rpc
+    ? { ...rpc, chainId: options.chainId, id: 'rpc', operation: options.operation }
+    : {
+        chainId: options.chainId,
+        failure: 'unknown',
+        id: 'earn-zone-position',
+        operation: options.operation,
+      }
+  c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure])
+}
+
+declare namespace recordZonePositionEnrichmentFailure {
+  /** Dependency failure and bounded operation label for request logging. */
+  type Options = {
+    /** Dependency error to classify and redact. */
+    cause: unknown
+    /** Chain associated with the failed dependency. */
+    chainId: number
+    /** Logical operation that failed. */
+    operation: 'eth_call' | 'resolvePrivateAsset'
+  }
+}
+
 /** Lists every vault where an account holds earn shares, ordered by vault address. */
 export async function listPositions(c: Context<App.Environment>, options: listPositions.Options) {
   const denomination = options['valuation.currency']
@@ -3866,15 +4195,7 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
   const sourceChainId = zone ? zone.sourceId : options.chainId
   if (sourceChainId === undefined) throw new EarnVaults.NotFoundError()
   const db = Db.get(c.get('dbCached'))
-  const recordsPromise = core_EarnVaults
-    .list(db, { chainId: sourceChainId })
-    .then((records) =>
-      zone
-        ? records.filter((record) =>
-            record.zones.some((route) => route.chainId === options.chainId),
-          )
-        : records,
-    )
+  const recordsPromise = core_EarnVaults.list(db, { chainId: sourceChainId })
   // The verified page needs no index: the registry is the candidate set.
   const heldPromise =
     options.verified || zone
@@ -3918,11 +4239,14 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
         batch.map(async (vault) => {
           const record = registry.get(vault)
           try {
-            const position = await getVaultPosition(c, {
+            const input = {
               account: options.address,
               chainId: options.chainId,
               vault: Schema.Address.parse(vault),
-            })
+            }
+            const position = zone
+              ? (await getZoneVaultPositionCore(c, input)).position
+              : await getVaultPosition(c, input)
             return { position, record, vaultAddress: vault }
           } catch (cause) {
             if (cause instanceof EarnVaults.NotFoundError) return undefined
@@ -3945,15 +4269,48 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
       : undefined
   const [cashFlows, tokens, valueTokens, snapshot] = await Promise.all([
     indexedBlock
-      ? getVaultLifetimeCashFlows(c.get('getTidx')(options.chainId), {
-          account: options.address,
-          blockNumber: indexedBlock.number,
-          vaults: page.map(({ vaultAddress }) => Schema.Address.parse(vaultAddress)),
-        })
+      ? (async () => {
+          const tidx = c.get('getTidx')(options.chainId)
+          const flows = await getVaultLifetimeCashFlows(tidx, {
+            account: options.address,
+            blockNumber: indexedBlock.number,
+            vaults: page.map(({ vaultAddress }) => Schema.Address.parse(vaultAddress)),
+          })
+          for (const { position, vaultAddress } of page) {
+            const flow = flows.get(vaultAddress)
+            if (flow?.status !== 'complete') continue
+            const vault = Schema.Address.parse(vaultAddress)
+            const withdrawals = await EarnWithdrawals.read(tidx, {
+              account: options.address,
+              blockNumber: indexedBlock.number,
+              shareToken: position.shareToken,
+              startBlockNumber: beforeFirstBlockNumber,
+              vault,
+            })
+            const withdrawn = await EarnWithdrawals.value(c.get('getClient')(options.chainId), {
+              vault,
+              withdrawals,
+            })
+            flows.set(
+              vaultAddress,
+              withdrawn === undefined
+                ? { status: 'incomplete_history' }
+                : {
+                    ...flow,
+                    totalWithdrawn: (BigInt(flow.totalWithdrawn) + withdrawn).toString(),
+                  },
+            )
+          }
+          return flows
+        })()
       : undefined,
     (async () => {
       const addresses = [
-        ...new Set(page.flatMap(({ position }) => [position.assetToken, position.shareToken])),
+        ...new Set(
+          page.flatMap(({ position }) =>
+            zone ? [position.shareToken] : [position.assetToken, position.shareToken],
+          ),
+        ),
       ]
       const groups: Tokens.resolveTokens.ReturnType[] = []
       for (let index = 0; index < addresses.length; index += tokenReadChunkSize)
@@ -4088,7 +4445,7 @@ declare namespace queryHeldVaults {
 /** Serializes one live position into the address-scoped row contract. */
 function serializePosition(options: serializePosition.Options) {
   const { position, tokens } = options
-  const assetToken = getToken(tokens, position.assetToken)
+  const assetToken = getToken(options.valueTokens ?? tokens, position.assetToken)
   const shareToken = getToken(tokens, position.shareToken)
   const valueToken = getToken(options.valueTokens ?? tokens, position.valueToken)
   const vaultAddress = Schema.Address.parse(options.vaultAddress.toLowerCase())
@@ -4437,6 +4794,7 @@ async function readVaultDiscovery(
   return Timing.time(c, 'earn_vault_discovery', () =>
     EarnVaults.resolve({
       getClient: c.get('getClient'),
+      hints: c.get('store'),
       include: options.include,
       input: {
         chainId: options.chainId,
@@ -4523,80 +4881,78 @@ async function resolvePositionApy(
     c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure])
   }
   const rateFailures: Log.ProviderFailure[] = []
-  const [rates, discovery] = await Promise.all([
-    Timing.time(c, 'earn_apy', () =>
-      EarnRates.resolve({
-        chainId: sourceChainId,
-        getClient: c.get('getClient'),
-        getTidx: c.get('getTidx'),
-        onFailure: (failure) => {
-          rateFailures.push({ ...failure, chainId: sourceChainId })
-        },
-        store: c.get('store'),
-        vaults: [options.vault],
-      }),
-    ).catch(() => {
-      rateFailures.push({
-        chainId: sourceChainId,
-        failure: 'unknown',
-        id: 'earn-apy',
-        operation: 'resolve',
-      })
-      return undefined
-    }),
-    resolveVaultDiscovery(c, {
+  const rates_pending = Timing.time(c, 'earn_apy', () =>
+    EarnRates.resolve({
       chainId: sourceChainId,
-      include: [],
-      vaultAddress: options.vault,
-    }).catch((cause) => {
-      const failure = Viem.requestFailure(cause)
-      recordFailure(
-        failure
-          ? { ...failure, chainId: sourceChainId, id: 'rpc', operation: 'eth_call' }
-          : {
-              chainId: sourceChainId,
-              failure: 'unknown',
-              id: 'earn-vaults',
-              operation: 'getVault',
-            },
-      )
-      return undefined
+      getClient: c.get('getClient'),
+      getTidx: c.get('getTidx'),
+      onFailure: (failure) => {
+        rateFailures.push({ ...failure, chainId: sourceChainId })
+      },
+      store: c.get('store'),
+      vaults: [options.vault],
     }),
-  ])
-  const base = rates?.get(options.vault.toLowerCase())
-  const rateFailure = rateFailures[0]
-  if (rateFailure) recordFailure(rateFailure)
-  if (!base || !discovery) return null
-  return await Timing.time(c, 'earn_rewards_apy', async () => {
-    const [earnFees, record] = await Promise.all([
-      c.get('getClient')(sourceChainId).readContract({
-        abi: Abis.earnVault,
-        address: options.vault,
-        functionName: 'earnFees',
-      }),
-      core_EarnVaults.get(Db.get(c.get('db')), {
+  ).catch(() => {
+    rateFailures.push({
+      chainId: sourceChainId,
+      failure: 'unknown',
+      id: 'earn-apy',
+      operation: 'resolve',
+    })
+    return undefined
+  })
+  // Vault facts and the registry row depend only on the vault, so they load
+  // alongside the rate read rather than after it.
+  const vault_pending = Timing.time(c, 'earn_vault_facts', () =>
+    Promise.all([
+      resolveVaultApyFacts(c, { chainId: sourceChainId, vault: options.vault }),
+      core_EarnVaults.get(Db.get(c.get('dbCached')), {
         chainId: options.chainId,
         vaultAddress: options.vault,
       }),
-    ])
+    ]),
+  ).catch((cause: unknown) => {
+    const failure = Viem.requestFailure(cause)
+    recordFailure(
+      failure
+        ? { ...failure, chainId: sourceChainId, id: 'rpc', operation: 'eth_call' }
+        : (sharePriceProviderFailure({ cause, chainId: sourceChainId }) ?? {
+            chainId: options.chainId,
+            failure: 'unknown',
+            id: 'earn-rewards',
+            operation: 'getPositionApy',
+          }),
+    )
+    return undefined
+  })
+  // The handler surfaces a failed position read; here it only ends enrichment.
+  const position = await options.position.catch(() => undefined)
+  const [rates, vault] = await Promise.all([rates_pending, vault_pending])
+  const base = rates?.get(options.vault.toLowerCase())
+  const rateFailure = rateFailures[0]
+  if (rateFailure) recordFailure(rateFailure)
+  if (!base || !vault || !position) return null
+  const [facts, record] = vault
+  return await Timing.time(c, 'earn_rewards_apy', () => {
     // Accounting retains qualified shares for excluded infrastructure, so apply its current exclusions here too.
     const zoneContracts = [...c.get('zones').values()]
       .filter((zone) => zone.sourceId === options.chainId)
       .flatMap((zone) => positionApyContractAddresses(zone.contracts))
+    // Registration must show on the next read, so reward rows stay on the primary.
     return RewardRead.positionApy({
-      assetDecimals: discovery.assetToken.decimals,
+      assetDecimals: facts.assetDecimals,
       baseNet: base.net,
       chainId: options.chainId,
       db: c.get('db'),
       excludedAddresses: [
-        discovery.engine.address,
-        earnFees,
+        facts.engine,
+        facts.earnFees,
         ...(record?.zones.map((zone) => zone.earnRouter) ?? []),
         ...zoneContracts,
       ],
       recipient: options.recipient,
-      shareBalance: options.shareBalance.toString(),
-      value: options.value.toString(),
+      shareBalance: position.shareBalance.toString(),
+      value: position.value.toString(),
       vaultAddress: options.vault,
     })
   }).catch((cause) => {
@@ -4612,17 +4968,51 @@ async function resolvePositionApy(
   })
 }
 
+/**
+ * Resolves the vault facts wallet APY needs (engine, fee sink, asset decimals)
+ * in one cached hop; full discovery costs several and serves no other field.
+ */
+async function resolveVaultApyFacts(
+  c: Context<App.Environment>,
+  options: resolveVaultApyFacts.Options,
+) {
+  return Store.memoize(
+    async () => {
+      const client = c.get('getClient')(options.chainId)
+      const { asset } = await resolveVaultBindings(c, options)
+      const [assetDecimals, earnFees, engine] = await client.multicall({
+        allowFailure: false,
+        contracts: [
+          { abi: Abis.tip20, address: asset, functionName: 'decimals' },
+          { abi: Abis.earnVault, address: options.vault, functionName: 'earnFees' },
+          { abi: Abis.earnVault, address: options.vault, functionName: 'engine' },
+        ],
+      })
+      return { assetDecimals, earnFees, engine }
+    },
+    {
+      key: `earn-vault-apy-facts:v1:${options.chainId}:${options.vault.toLowerCase()}`,
+      store: c.get('store'),
+      // Matches the rate bucket so a migrated engine reappears with the reset rate.
+      ttl: Ttl.minutes(15),
+    },
+  )
+}
+
+declare namespace resolveVaultApyFacts {
+  /** Vault whose engine, fee sink, and asset decimals are resolved. */
+  type Options = Pick<getVaultPosition.Options, 'chainId' | 'vault'>
+}
+
 declare namespace resolvePositionApy {
-  /** Current wallet position used to resolve its effective APY. */
+  /** Wallet and vault whose effective APY is resolved alongside a live position read. */
   type Options = {
     /** Chain containing the vault position. */
     chainId: z.output<typeof Schema.ChainId>
+    /** In-flight live position supplying the EarnShare balance and asset value. */
+    position: Promise<getVaultPosition.ReturnType>
     /** Wallet receiving the position yield. */
     recipient: z.output<typeof Schema.Address>
-    /** Current EarnShare balance. */
-    shareBalance: bigint
-    /** Current asset value of the position. */
-    value: bigint
     /** EarnVault containing the position. */
     vault: z.output<typeof Schema.Address>
   }