tapimo 0.15.1 → 0.18.0

package/dist/apps/data/routes/earn.js

@@ -7,7 +7,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';
@@ -15,6 +14,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 * as OpenApi from '../../../internal/OpenApi.js';
 import * as RewardRead from '../../../internal/rewards/Read.js';
 import * as Response from '../../../internal/Response.js';
@@ -377,10 +377,16 @@ export var schema;
     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 a direct account, in asset base units. Always zero for Zone-routed positions, which use Zone withdrawals instead of approvals.'), z.meta({ examples: ['0'] })),
-        assetBalance: Schema.DecimalString.check(z.describe('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.')),
+        assetBalance: Schema.DecimalString.check(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 public parent vault.')),
         chainId: Schema.ChainId.check(z.describe('Chain containing the account position.'), z.meta({ examples: [42431] })),
         id: Schema.Address.check(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.'), z.meta({ examples: ['0'] })),
         shareBalance: Schema.DecimalString.check(z.describe('Earn shares held by this account at the observation block, in share base units.'), z.meta({ examples: ['99500000'] })),
         shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(z.describe('TIP-20 token representing earn shares.')),
@@ -402,16 +408,16 @@ export var schema;
                     .string()
                     .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Position amount rendered in whole vault asset units.'), z.meta({ examples: ['25000'] })),
             })
-                .check(z.describe('Vault asset amount receiving this annual rate.'), z.meta({
+                .check(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' }],
             })),
             net: EarnRates.schema.Apy.shape.net.check(z.describe('Annual rate applied to this position amount.'), z.meta({ examples: ['0.07'] })),
             type: z
                 .enum(['base', 'boost'])
-                .check(z.describe('Base vault yield or qualified depositor boost.'), z.meta({ examples: ['boost'] })),
+                .check(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.meta({
+            .check(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: [
                 [
                     {
@@ -435,7 +441,7 @@ export var schema;
                 .literal('complete')
                 .check(z.describe('Cash flows are complete through the indexed boundary.'), z.meta({ examples: ['complete'] })),
             totalDeposited: Schema.DecimalString.check(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.')),
+            totalWithdrawn: Schema.DecimalString.check(z.describe('Completed withdrawal proceeds plus other outgoing shares valued at their transfer blocks.')),
         }),
         z.strictObject({
             status: z
@@ -468,19 +474,30 @@ export var schema;
     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'] })),
+        currentValue: Schema.DecimalString.check(z.describe('Asset value of the account’s active earn shares at the ending 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(['30d', 'active', 'lifetime'])
-        .check(z.describe('Earnings period to calculate: trailing 30 days, shares still held, or lifetime history.'), z.meta({ examples: ['lifetime'] }));
+        .enum(['7d', '30d', 'active', 'custom', 'lifetime'])
+        .check(z.describe('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
                 .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'] })),
+                .check(z.regex(/^-?\d+$/), z.describe('Current share value plus withdrawals, including outgoing shares valued when transferred, minus asset deposits, at the latest indexed block.'), z.meta({ examples: ['0'] })),
             totalDeposited: Schema.DecimalString.check(z.describe('Assets deposited with this account as receiver over complete indexed vault history.'), z.meta({ examples: ['1000000'] })),
-            totalWithdrawn: Schema.DecimalString.check(z.describe('Assets returned by completed redemptions and exact withdrawals initiated by this account over complete indexed vault history.'), z.meta({ examples: ['1000000'] })),
+            totalWithdrawn: Schema.DecimalString.check(z.describe('Completed vault withdrawal proceeds plus other outgoing shares valued at their transfer blocks, regardless of recipient or spender.'), z.meta({ examples: ['1000000'] })),
             period: z
                 .literal('lifetime')
                 .check(z.describe('Returns lifetime net asset earnings.'), z.meta({ examples: ['lifetime'] })),
@@ -499,27 +516,28 @@ export var schema;
                 .literal('complete')
                 .check(z.describe('Earnings include a complete asset-denominated cost basis.'), 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(z.describe('Earnings include a complete asset-denominated cost basis.'), z.meta({ examples: ['complete'] })),
             windowEarnings: z
                 .string()
-                .check(z.regex(/^-?\d+$/), z.describe('Ending share value plus realized assets, minus deposits and opening share value, over the trailing 30 days.'), z.meta({ examples: ['0'] })),
+                .check(z.regex(/^-?\d+$/), z.describe('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(z.describe('Earnings are unavailable when indexed activity cannot reconstruct the asset cost basis for the requested period.'), z.meta({ examples: ['incomplete_cost_basis'] })),
         }),
-        z.extend(earningsBase, {
-            period: z
-                .literal('30d')
-                .check(z.describe('Trailing period with an unresolved async redemption.'), z.meta({ examples: ['30d'] })),
+        z.extend(earningsWindow, {
+            status: z
+                .literal('incomplete_cost_basis')
+                .check(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(z.describe('Earnings are unavailable while an async redemption remains open.'), z.meta({ examples: ['pending_redemption'] })),
@@ -805,12 +823,25 @@ export var schema;
             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. */
+        /** Query parameters selecting the chain and earnings interval. */
         getEarnVaultEarnings.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. */
         getEarnVaultEarnings.Response = OpenApi.component(Schema.describe(earnings, 'Indexed asset value and cost-basis-aware earnings for an account in one earn vault.'), 'EarnVaultEarnings');
@@ -820,7 +851,7 @@ export var schema;
 export function earn(options = {}) {
     const oracle = options.fx?.oracle ?? FxOracle.ecb();
     return new Hono()
-        .post('/v1/earn/rewards/eligibility', Auth.policy({ apiKey: { scopes: [Scope.wildcard] } }), OpenApi.validate('json', schema.registerRewardEligibility.Body, {
+        .post('/v1/earn/rewards/eligibility', Auth.policy({ apiKey: { scopes: ['rewards:write'] } }), OpenApi.validate('json', schema.registerRewardEligibility.Body, {
         code: 'body_invalid',
         message: 'Invalid reward eligibility registration',
     }), OpenApi.describeRoute({
@@ -850,6 +881,21 @@ export function 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,
@@ -1263,21 +1309,24 @@ export function earn(options = {}) {
         if (c.get('zones').has(chainId))
             Cache.setPolicy(c, Cache.policies.noStore);
         try {
-            const position = await getVaultPosition(c, {
+            const position_pending = Timing.time(c, 'earn_position', () => getVaultPosition(c, {
                 account: address,
                 asOf: query.asOf,
                 chainId,
                 vault: vaultId,
-            });
-            const apy = query.include.includes('apy')
-                ? await resolvePositionApy(c, {
+            }));
+            // 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,
@@ -1297,6 +1346,12 @@ export function 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')
@@ -1391,7 +1446,7 @@ export function earn(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), OpenApi.describeRoute({
-        description: 'Gets an account’s indexed asset value and earnings for lifetime history, the trailing 30 days, or shares still held.',
+        description: '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: {
@@ -1419,7 +1474,7 @@ export function earn(options = {}) {
     }), Cache.response({
         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);
@@ -1450,14 +1505,16 @@ export function 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 });
             }
@@ -1561,19 +1618,24 @@ export function earn(options = {}) {
 export async function getVaultEarnings(c, options) {
     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({
@@ -1593,7 +1655,7 @@ export async function getVaultEarnings(c, options) {
         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,
@@ -1615,10 +1677,11 @@ export async function getVaultEarnings(c, options) {
         }),
         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,
@@ -1630,9 +1693,9 @@ export async function getVaultEarnings(c, options) {
         id: options.account,
         period: options.period,
     };
-    if (history.incompleteCostBasis || externalShareTransfer)
+    if (history.incompleteCostBasis || transfers.external || transfers.withdrawn === undefined)
         return { ...base, status: 'incomplete_cost_basis' };
-    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(),
@@ -1647,7 +1710,7 @@ export async function getVaultEarnings(c, options) {
         status: 'complete',
     };
 }
-/** Reads cash-flow-adjusted earnings over a trailing indexed window. */
+/** Reads cash-flow-adjusted earnings over an indexed time window. */
 async function getWindowVaultEarnings(c, options) {
     const client = c.get('getClient')(options.chainId);
     const tidx = c.get('getTidx')(options.chainId);
@@ -1657,13 +1720,16 @@ async function getWindowVaultEarnings(c, options) {
             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,
@@ -1686,11 +1752,14 @@ async function getWindowVaultEarnings(c, options) {
         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)
@@ -1710,7 +1779,7 @@ async function getWindowVaultEarnings(c, options) {
         finalized: history.finalized,
         openingValue,
         redeemed: history.redeemed,
-        withdrewExact: history.withdrewExact,
+        withdrewExact: history.withdrewExact + transfers.withdrawn,
     });
     return { ...base, status: 'complete', windowEarnings: windowEarnings.toString() };
 }
@@ -1782,9 +1851,9 @@ export function parseIndexedBlockAtOrBefore(options) {
         throw new IndexedCoverageError(options.asOf);
     return { number, timestamp: indexedAt };
 }
-/** 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, 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`,
     });
@@ -2001,29 +2070,37 @@ async function getWindowShareState(tidx, options) {
         startShares: receivedStartValue - sentStartValue,
     };
 }
-/** Builds a share-transfer predicate for the vault's verified reward distributors. */
-async function getRewardTransferPredicate(c, options) {
+/** Combines recorded campaign distributors with additional per-vault reward distributors. */
+async function getEarningsConfiguration(c, options) {
     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, distributors) {
     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
@@ -2031,9 +2108,10 @@ async function getRewardTransferPredicate(c, options) {
     )
   `;
 }
-/** Returns whether an account sent or received Earn shares outside known vault flows. */
-async function hasExternalShareTransfer(tidx, 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, 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: `
@@ -2045,56 +2123,11 @@ async function hasExternalShareTransfer(tidx, options) {
             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 (
@@ -2132,7 +2165,12 @@ async function hasExternalShareTransfer(tidx, options) {
     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 }),
+    };
 }
 /** Calculates the asset cost basis attached to an account's remaining Earn shares. */
 export function calculateActiveCostBasis(options) {
@@ -2190,6 +2228,13 @@ export function calculateActiveCostBasis(options) {
 }
 /** Reads the active asset cost basis for shares held at one indexed block. */
 async function getActiveCostBasis(tidx, 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: `
@@ -2285,6 +2330,7 @@ async function getActiveCostBasis(tidx, options) {
           AND "to" = '${options.account}'
           AND "from" != '${zeroAddress}'
           AND "from" != '${options.vault}'
+          AND "from" != '${options.account}'
           AND block_num <= ${options.blockNumber}
         UNION ALL
         SELECT
@@ -2298,7 +2344,7 @@ async function getActiveCostBasis(tidx, options) {
         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
@@ -2630,19 +2676,55 @@ async function resolveSharePriceVaultDiscovery(c, options) {
 export async function getVaultPosition(c, options) {
     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, options) {
+    const core = await resolveZonePositionCore(c, {
         chainId: options.chainId,
         vault: options.vault,
     });
@@ -2655,43 +2737,130 @@ export async function getVaultPosition(c, options) {
         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)
+    if (sourceBlock === undefined)
         throw new EarnVaults.NotFoundError();
-    const value = await c
-        .get('getClient')(route.sourceChainId)
-        .earn.getRedeemQuote({
+    const value = await quoteZonePosition(c.get('getClient')(core.sourceChainId), {
         blockNumber: BigInt(sourceBlock),
         shareAmount: shareBalance,
         vault: options.vault,
     });
     return {
-        assetAllowance: 0n,
+        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, 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);
+}
+/**
+ * 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, options) {
+    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,
         assetBalance,
-        assetToken: route.privateAsset,
-        block,
-        shareAllowance: 0n,
+        assetToken: asset,
+        shareAllowance,
         shareBalance,
-        shareToken: route.shareToken,
+        shareToken,
         value,
-        valueToken: route.vaultAsset,
+        valueToken: asset,
     };
 }
+/** Resolves a vault's asset and EarnShare addresses, cached because they never change after deployment. */
+async function resolveVaultBindings(c, 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),
+    });
+}
 /** Reads a private Zone token balance with the holder as the authorized RPC caller. */
 async function readZoneBalance(client, options) {
     return client.readContract({
@@ -2739,46 +2908,66 @@ export function alignZoneSourceBlock(options) {
         return options.verified;
     return options.reported;
 }
-/** Resolves the verified parent vault and token pair for one Zone route. */
-async function resolveZonePositionRoute(c, options) {
+/** Resolves the public parent vault and Zone checkpoint boundary. */
+async function resolveZonePositionCore(c, options) {
     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)
+    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,
     };
 }
+/** Resolves an optional validated private asset from the Admin Zone route. */
+async function resolveZonePositionPrivateAsset(c, 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;
+}
+/** Records a bounded dependency signal without failing the core Zone position. */
+function recordZonePositionEnrichmentFailure(c, options) {
+    Cache.setPolicy(c, Cache.policies.noStore);
+    const rpc = Viem.requestFailure(options.cause);
+    const failure = 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]);
+}
 /** Lists every vault where an account holds earn shares, ordered by vault address. */
 export async function listPositions(c, options) {
     const denomination = options['valuation.currency'];
@@ -2789,11 +2978,7 @@ export async function listPositions(c, options) {
     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
         ? undefined
@@ -2831,11 +3016,14 @@ export async function listPositions(c, options) {
         const read = await Timing.time(c, 'earn_positions', () => Promise.all(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) {
@@ -2858,15 +3046,42 @@ export async function listPositions(c, options) {
         : 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 = [];
             for (let index = 0; index < addresses.length; index += tokenReadChunkSize)
@@ -2963,7 +3178,7 @@ async function queryHeldVaults(c, options) {
 /** Serializes one live position into the address-scoped row contract. */
 function 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());
@@ -3226,6 +3441,7 @@ async function resolveVaultDiscovery(c, options) {
 async function readVaultDiscovery(c, options) {
     return Timing.time(c, 'earn_vault_discovery', () => EarnVaults.resolve({
         getClient: c.get('getClient'),
+        hints: c.get('store'),
         include: options.include,
         input: {
             chainId: options.chainId,
@@ -3274,78 +3490,74 @@ async function resolvePositionApy(c, options) {
         c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure]);
     };
     const rateFailures = [];
-    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,
+        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,
-            include: [],
+            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) => {
-            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;
         }),
-    ]);
+    ])).catch((cause) => {
+        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 || !discovery)
+    if (!base || !vault || !position)
         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')), {
-                chainId: options.chainId,
-                vaultAddress: options.vault,
-            }),
-        ]);
+    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) => {
@@ -3358,6 +3570,30 @@ async function resolvePositionApy(c, options) {
         return null;
     });
 }
+/**
+ * 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, 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),
+    });
+}
 function positionApyContractAddresses(contract) {
     if (!contract || typeof contract !== 'object')
         return [];