tapimo 0.14.0 → 0.15.0

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

@@ -6,6 +6,9 @@ import {
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
   ContractFunctionZeroDataError,
+  isAddress,
+  parseAbi,
+  parseUnits,
   zeroAddress,
 } from 'viem'
 import * as z from 'zod/mini'
@@ -14,12 +17,18 @@ import type * as App from '../../../App.js'
 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'
 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 type * as Log from '../../../internal/Log.js'
 import * as OpenApi from '../../../internal/OpenApi.js'
+import * as RewardRead from '../../../internal/rewards/Read.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Store from '../../../internal/Store.js'
@@ -28,6 +37,7 @@ import * as Timing from '../../../internal/Timing.js'
 import * as Ttl from '../../../internal/Ttl.js'
 import * as Value from '../../../internal/Value.js'
 import * as VerifiedTokens from '../../../internal/VerifiedTokens.js'
+import * as Viem from '../../../internal/Viem.js'
 import * as FxOracle from '../FxOracle.js'
 import * as Tokens from './tokens.js'
 import * as Valuation from './valuation.js'
@@ -35,6 +45,27 @@ import * as Valuation from './valuation.js'
 const deployedSignature =
   'event EarnStackDeployed(address indexed earnVault,address indexed earnShare,address indexed earnFees,address engine,address asset,address owner,bytes32 deploymentId,address emergencyGuardian,address asyncJanitor,uint8 migrationMode,bytes32 earnShareSalt,bytes32 controlConfigHash,bytes32 feeConfigHash,bytes32 earnFeesSalt)'
 
+// Historical factories for this signature, verified against upstream deployments
+// and compiled EarnFactory releases. See docs/earn-discovery.md before updating.
+const deploymentFactories: Record<number, readonly string[]> = {
+  4217: [
+    '0x5b972d2490d06e436982fab77612fd9987f097d0',
+    '0x75b20eafdbd3dd974d00b573fd72852ab0237afd',
+  ],
+  42431: [
+    '0x0f9ccbc97563a179f5f0886f89ee51c9185f6ec4',
+    '0x2aa26b7e24e6f1fb2d539d527b8f1bb5cacfa288',
+    '0x4990c74ae874f2b0fd4938662e2cdb8ca4c27887',
+    '0x518d4fbd5334bb7ff67c6ebcb67a7d60e1ef8d5d',
+    '0x6742345070be5a20ce05f53b6d08d071162c0ef8',
+    '0x846b8479d64691ff61c05137dc580a1ecdc188c5',
+    '0xb4944264260a6412351d64653f65d2c27d9cb038',
+    '0xb4ecb65a57e3585c3699c1617c2abb5de35a697d',
+    '0xb5e53c6b17c6f3a380ad94f5417c5e541dfeefac',
+    '0xe8fd5b183021ba3f6d3197c5b4238c93561b1b7a',
+  ],
+}
+
 const depositedSignature =
   'event Deposited(address indexed caller,address indexed receiver,uint256 assets,uint256 earnShares)'
 
@@ -56,12 +87,19 @@ const redeemRequestedSignature =
 const venueSharesDepositedSignature =
   'event VenueSharesDeposited(address indexed caller,address indexed receiver,uint256 requestedVenueShares,uint256 receivedVenueShares,uint256 earnShares)'
 
+const unspentReturnedSignature =
+  'event UnspentReturned(address indexed treasury,uint256 earnShares)'
+
 const maxScannedDeployments = 250
 const scanLimit = 50
 
 // Concurrent metadata reads in one macrotask collapse into one deployless
 // multicall; an await between small chunks keeps each call under the RPC limit.
 const tokenReadChunkSize = 20
+const tempoStateAddress = '0x1c00000000000000000000000000000000000000'
+const tempoStateAbi = parseAbi(['function tempoBlockNumber() view returns (uint64)'])
+const zonePortalAbi = parseAbi(['function lastSyncedTempoBlockNumber() view returns (uint64)'])
+const tokenPositionAbi = parseAbi(['function balanceOf(address account) view returns (uint256)'])
 /** Block boundary that includes all indexed history. */
 const beforeFirstBlockNumber = -1
 
@@ -71,6 +109,13 @@ const tvlDenomination = 'USD'
 /** `Valuation.valuationFor` floors to 6 dp, so 6 is the precision a valued amount carries. */
 const tvlDecimals = 6
 
+function toRewardEligibilityAssociation(record: RewardEligibilityAssociations.Record) {
+  return {
+    ...record,
+    id: `${record.vaultAddress}-${record.walletAddress}`,
+  }
+}
+
 /** Returns the smallest useful live-discovery batch. */
 export function discoveryBatchLimit(options: discoveryBatchLimit.Options): number {
   const needed = options.limit + 1 - options.matches
@@ -109,6 +154,118 @@ export declare namespace hasZoneAccess {
 
 /** Zod schemas owned by the public Earn-vault resource. */
 export namespace schema {
+  /** Schemas for the registerRewardEligibility operation. */
+  export namespace registerRewardEligibility {
+    /** Wallet and vault association to register for reward eligibility. */
+    export const Body = z
+      .strictObject({
+        chainId: Schema.ChainId.check(
+          z.describe('Chain containing the Earn vault.'),
+          z.meta({ examples: [4217] }),
+        ),
+        transactionHash: z.optional(Schema.hash(`0x${'33'.repeat(32)}`)),
+        vaultAddress: Schema.Address.check(
+          z.describe('Earn vault contract address.'),
+          z.meta({ examples: ['0x59d27987bc7cc1521bba5f688a170c65840cbf43'] }),
+        ),
+        walletAddress: Schema.Address.check(
+          z.describe('Wallet to register for rewards.'),
+          z.meta({ examples: ['0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6'] }),
+        ),
+      })
+      .check(z.describe('Reward eligibility registration.'))
+
+    /** Persisted reward eligibility association. */
+    export const Association = z
+      .strictObject({
+        chainId: Schema.ChainId,
+        firstRegisteredAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the association was first registered.'),
+            z.meta({ examples: ['2026-08-25T20:00:00.000Z'] }),
+          ),
+        id: z.string().check(
+          z.describe('Stable reward eligibility association identifier.'),
+          z.meta({
+            examples: [
+              '0x59d27987bc7cc1521bba5f688a170c65840cbf43-0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6',
+            ],
+          }),
+        ),
+        latestRegisteredAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the association was most recently registered.'),
+            z.meta({ examples: ['2026-08-25T20:00:00.000Z'] }),
+          ),
+        registrationOrder: z
+          .string()
+          .check(
+            z.regex(/^\d+$/),
+            z.describe('Monotonic registration order.'),
+            z.meta({ examples: ['42'] }),
+          ),
+        transactionHash: z.optional(Schema.hash(`0x${'33'.repeat(32)}`)),
+        vaultAddress: Schema.Address,
+        walletAddress: Schema.Address,
+      })
+      .check(z.describe('Persisted reward eligibility association.'))
+
+    /** Persisted reward eligibility registration result. */
+    export const Response = z
+      .strictObject({
+        association: Association,
+        created: z
+          .boolean()
+          .check(
+            z.describe('Whether this request created the association.'),
+            z.meta({ examples: [true] }),
+          ),
+      })
+      .check(z.describe('Persisted reward eligibility registration result.'))
+  }
+
+  /** Schemas for the getRewardEligibility operation. */
+  export namespace getRewardEligibility {
+    const Limit = z
+      ._default(
+        z.pipe(
+          z.coerce.number().check(z.int(), z.gte(Schema.minLimit)),
+          z.transform((value) => Math.min(value, 100)),
+        ),
+        10,
+      )
+      .check(
+        z.describe(
+          'How many items to return per page (5 to 100, default 10). Use `nextCursor` to fetch more.',
+        ),
+        z.meta({ examples: [10] }),
+      )
+
+    /** Selects one chain and vault eligibility snapshot page. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainId.check(z.describe('Chain containing the Earn vault.')),
+        cursor: Schema.Cursor,
+        limit: Limit,
+        vaultAddress: Schema.Address.check(z.describe('Earn vault contract address.')),
+      })
+      .check(z.describe('Reward eligibility page selector.'))
+
+    /** One page of eligible wallets at the cursor's fixed checkpoint. */
+    export const Response = z
+      .strictObject({
+        chainId: Schema.ChainId,
+        data: z
+          .array(Schema.Address)
+          .check(z.describe('Eligible wallet addresses in registration order.')),
+        nextCursor: Schema.NextCursor,
+        vaultAddress: Schema.Address,
+      })
+      .check(z.describe('A fixed-snapshot page of eligible wallet addresses.'))
+  }
+
   const capability = z
     .enum([
       'asyncRedeem',
@@ -126,25 +283,28 @@ export namespace schema {
     .enum(['erc4626', 'veda'])
     .check(z.describe('Inferred vault engine type.'), z.meta({ examples: ['erc4626'] }))
 
-  const engine = Schema.describe(
-    z.strictObject({
-      address: Schema.Address.check(
-        z.describe('Current vault engine contract address.'),
-        z.meta({ examples: ['0x59d27987bc7cc1521bba5f688a170c65840cbf43'] }),
-      ),
-      type: z
-        .nullable(engineType)
-        .check(z.describe('Inferred engine type, or null when it is unknown.')),
-      venue: z
-        .nullable(
-          Schema.Address.check(
-            z.describe('Yield venue contract bound to the engine.'),
-            z.meta({ examples: ['0x9a044ae05e5e6290dcf56afd69548565e957a626'] }),
-          ),
-        )
-        .check(z.describe('Yield venue, or null when the engine does not expose one.')),
-    }),
-    'Current vault engine.',
+  const engine = OpenApi.component(
+    Schema.describe(
+      z.strictObject({
+        address: Schema.Address.check(
+          z.describe('Current vault engine contract address.'),
+          z.meta({ examples: ['0x59d27987bc7cc1521bba5f688a170c65840cbf43'] }),
+        ),
+        type: z
+          .nullable(engineType)
+          .check(z.describe('Inferred engine type, or null when it is unknown.')),
+        venue: z
+          .nullable(
+            Schema.Address.check(
+              z.describe('Yield venue contract bound to the engine.'),
+              z.meta({ examples: ['0x9a044ae05e5e6290dcf56afd69548565e957a626'] }),
+            ),
+          )
+          .check(z.describe('Yield venue, or null when the engine does not expose one.')),
+      }),
+      'Current vault engine.',
+    ),
+    'EarnVaultEngine',
   )
 
   const include = z
@@ -156,6 +316,85 @@ export namespace schema {
     'Comma-separated vault fields to include, such as `apy,tvl`.',
   )
 
+  const aprRatio = z
+    .string()
+    .check(
+      z.regex(/^\d+(\.\d+)?$/),
+      z.describe('Annual percentage rate as a non-negative decimal ratio.'),
+      z.meta({ examples: ['0.0195'] }),
+    )
+
+  const reward = z.strictObject({
+    apr: z
+      .nullable(aprRatio)
+      .check(z.describe('Current reward APR, or null before its first calculation.')),
+    asset: z
+      .strictObject({
+        address: Schema.Address,
+        chainId: Schema.ChainId,
+        decimals: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Reward asset decimal places.'),
+            z.meta({ examples: [18] }),
+          ),
+      })
+      .check(z.describe('EarnShare token distributed by the reward campaign.')),
+    calculatedThrough: z
+      .optional(z.number().check(z.int(), z.nonnegative()))
+      .check(
+        z.describe('Unix timestamp through which a calculated reward APR applies.'),
+        z.meta({ examples: [1788134700] }),
+      ),
+    campaignId: z
+      .string()
+      .check(
+        z.describe('EarnVault address that identifies the reward campaign.'),
+        z.meta({ examples: ['0x1000000000000000000000000000000000000001'] }),
+      ),
+    endsAt: z
+      .number()
+      .check(
+        z.int(),
+        z.nonnegative(),
+        z.describe('Exclusive campaign end as a Unix timestamp.'),
+        z.meta({ examples: [1790812800] }),
+      ),
+    startsAt: z
+      .number()
+      .check(
+        z.int(),
+        z.nonnegative(),
+        z.describe('Inclusive campaign start as a Unix timestamp.'),
+        z.meta({ examples: [1788134400] }),
+      ),
+    targetTotalApr: aprRatio.check(
+      z.describe('Configured target for combined observed vault yield and Merkle rewards.'),
+      z.meta({ examples: ['0.0700'] }),
+    ),
+  })
+
+  const apy = z.strictObject({
+    asOf: EarnRates.schema.Apy.shape.asOf,
+    methodology: EarnRates.schema.Apy.shape.methodology,
+    net: EarnRates.schema.Apy.shape.net.check(
+      z.describe('Higher of observed vault APY and configured reward campaign targets.'),
+    ),
+    rewards: z
+      .optional(z.array(reward))
+      .check(
+        z.describe(
+          'Enabled, registered Merkle rewards. Omitted when reward enrichment is unavailable.',
+        ),
+      ),
+    vault: EarnRates.schema.Apy.shape.net.check(
+      z.describe('Observed fee-aware vault APY before reward APR.'),
+    ),
+    window: EarnRates.schema.Apy.shape.window,
+  })
+
   // `apy` and `tvl` need indexer and FX access, so surfaces lacking either
   // select from this reduced set instead.
   const baseInclude = z
@@ -167,65 +406,71 @@ export namespace schema {
     'Comma-separated vault fields to include, such as `access,zone`.',
   )
 
-  const zone = z
-    .strictObject({
-      chainId: Schema.ChainId.check(
-        z.describe('Private Zone chain id.'),
-        z.meta({ examples: [421700001] }),
-      ),
-      inputTokens: z
-        .array(Schema.Address)
-        .check(
-          z.describe('Tokens accepted by private deposits.'),
-          z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Private Zone name.'), z.meta({ examples: ['zone-mainnet-internal'] })),
-      outputTokens: z
-        .array(Schema.Address)
-        .check(
-          z.describe('Tokens supported by private redemptions.'),
-          z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
+  const zone = OpenApi.component(
+    z
+      .strictObject({
+        chainId: Schema.ChainId.check(
+          z.describe('Private Zone chain id.'),
+          z.meta({ examples: [421700001] }),
         ),
-    })
-    .check(z.describe('Private Zone route configured for a verified vault.'))
+        inputTokens: z
+          .array(Schema.Address)
+          .check(
+            z.describe('Tokens accepted by private deposits.'),
+            z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
+          ),
+        name: z
+          .string()
+          .check(z.describe('Private Zone name.'), z.meta({ examples: ['zone-mainnet-internal'] })),
+        outputTokens: z
+          .array(Schema.Address)
+          .check(
+            z.describe('Tokens supported by private redemptions.'),
+            z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
+          ),
+      })
+      .check(z.describe('Private Zone route configured for a verified vault.')),
+    'EarnVaultZone',
+  )
 
-  const zoneRoute = z
-    .strictObject({
-      chainId: Schema.ChainId.check(
-        z.describe('Private Zone chain id.'),
-        z.meta({ examples: [421700001] }),
-      ),
-      deploymentBlock: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Parent-chain block that deployed the Earn router.'),
-          z.meta({ examples: [35816964] }),
-        ),
-      earnRouter: Schema.Address.check(
-        z.describe('Parent-chain router for this Zone and Earn vault.'),
-        z.meta({ examples: ['0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6'] }),
-      ),
-      inputTokens: z
-        .array(Schema.Address)
-        .check(
-          z.describe('Tokens accepted by private deposits.'),
-          z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
+  const zoneRoute = OpenApi.component(
+    z
+      .strictObject({
+        chainId: Schema.ChainId.check(
+          z.describe('Private Zone chain id.'),
+          z.meta({ examples: [421700001] }),
         ),
-      name: z
-        .string()
-        .check(z.describe('Private Zone name.'), z.meta({ examples: ['zone-mainnet-internal'] })),
-      outputTokens: z
-        .array(Schema.Address)
-        .check(
-          z.describe('Tokens returned by private redemptions.'),
-          z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
+        deploymentBlock: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Parent-chain block that deployed the Earn router.'),
+            z.meta({ examples: [35822949] }),
+          ),
+        earnRouter: Schema.Address.check(
+          z.describe('Parent-chain router for this Zone and Earn vault.'),
+          z.meta({ examples: ['0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6'] }),
         ),
-    })
-    .check(z.describe('Verified Earn route through one private Zone.'))
+        inputTokens: z
+          .array(Schema.Address)
+          .check(
+            z.describe('Tokens accepted by private deposits.'),
+            z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
+          ),
+        name: z
+          .string()
+          .check(z.describe('Private Zone name.'), z.meta({ examples: ['zone-mainnet-internal'] })),
+        outputTokens: z
+          .array(Schema.Address)
+          .check(
+            z.describe('Tokens returned by private redemptions.'),
+            z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
+          ),
+      })
+      .check(z.describe('Verified Earn route through one private Zone.')),
+    'EarnVaultZoneRoute',
+  )
 
   const value = z.strictObject({
     amount: Schema.DecimalString.check(
@@ -257,10 +502,10 @@ export namespace schema {
       .optional(EarnVaults.schema.Discovery.shape.access)
       .check(z.describe('Vault share-token access, when requested.')),
     apy: z
-      .optional(z.nullable(EarnRates.schema.Apy))
+      .optional(z.nullable(apy))
       .check(
         z.describe(
-          'Annualized share-price growth over the selected window, when requested via `include=apy` or by selecting `apy.window`. Null when the rate could not be measured: the vault predates the window, a boundary or historical quote is unavailable, the engine changed inside the window, or the growth is too extreme to annualize as a ratio.',
+          'Annualized vault yield over the selected window, plus every available current Merkle reward APR. Null when no component is measurable.',
         ),
       ),
     assetToken: Tokens.schema.Token.check(
@@ -365,7 +610,7 @@ export namespace schema {
           [
             {
               chainId: 421700001,
-              deploymentBlock: 35816964,
+              deploymentBlock: 35822949,
               earnRouter: '0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6',
               inputTokens: ['0x20c0000000000000000000006fd9a167923ba194'],
               name: 'zone-mainnet-internal',
@@ -378,26 +623,32 @@ export namespace schema {
   })
 
   /** One compatible Earn vault resolved from current chain state. */
-  export const Vault = Schema.describe(vault, 'A compatible earn vault resolved from chain state.')
+  export const Vault = OpenApi.component(
+    Schema.describe(vault, 'A compatible earn vault resolved from chain state.'),
+    'EarnVault',
+  )
 
   /** One registry-curated Earn vault. */
-  export const VerifiedVault = Schema.describe(
-    z.extend(vault, {
-      engine: z.extend(engine, { type: engineType }),
-      slug: z
-        .string()
-        .check(
-          z.describe('Stable curated vault slug.'),
-          z.meta({ examples: ['btpathusd-earn-h8k2m4n6'] }),
-        ),
-      verified: z
-        .literal(true)
-        .check(
-          z.describe('This vault is in the curated earn registry.'),
-          z.meta({ examples: [true] }),
-        ),
-    }),
-    'A registry-curated earn vault resolved from chain state.',
+  export const VerifiedVault = OpenApi.component(
+    Schema.describe(
+      z.extend(vault, {
+        engine: z.extend(engine, { type: engineType }),
+        slug: z
+          .string()
+          .check(
+            z.describe('Stable curated vault slug.'),
+            z.meta({ examples: ['btpathusd-earn-h8k2m4n6'] }),
+          ),
+        verified: z
+          .literal(true)
+          .check(
+            z.describe('This vault is in the curated earn registry.'),
+            z.meta({ examples: [true] }),
+          ),
+      }),
+      'A registry-curated earn vault resolved from chain state.',
+    ),
+    'VerifiedEarnVault',
   )
 
   const position = z.strictObject({
@@ -406,7 +657,9 @@ export namespace schema {
       z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] }),
     ),
     assetAllowance: Schema.DecimalString.check(
-      z.describe('Assets the vault may spend from this account, in asset base units.'),
+      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(
@@ -414,14 +667,20 @@ export namespace schema {
       z.meta({ examples: ['250000000'] }),
     ),
     assetToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(
-      z.describe('TIP-20 asset token accepted by the vault.'),
+      z.describe('TIP-20 asset token accepted by the vault or its selected Zone route.'),
+    ),
+    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'] }),
     ),
     shareAllowance: Schema.DecimalString.check(
-      z.describe('Earn shares the vault may spend from this account, in share base units.'),
+      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(
@@ -433,12 +692,91 @@ export namespace schema {
     ),
     value: Schema.DecimalString.check(
       z.describe(
-        'Asset value of this account’s earn shares at the observation block, including fees, in asset base units.',
+        'Asset value of this account’s earn shares at the observation block, including fees, in `valueToken` base units.',
       ),
       z.meta({ examples: ['100000000'] }),
     ),
+    valueToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(
+      z.describe('TIP-20 asset denominating `value` on the vault’s parent chain.'),
+    ),
   })
 
+  const positionApy = z
+    .strictObject({
+      breakdown: z
+        .array(
+          z
+            .strictObject({
+              assetAmount: z
+                .strictObject({
+                  baseUnits: Schema.DecimalString.check(
+                    z.describe('Position amount in vault asset base units.'),
+                    z.meta({ examples: ['25000000000'] }),
+                  ),
+                  decimals: z
+                    .number()
+                    .check(
+                      z.int(),
+                      z.nonnegative(),
+                      z.describe('Vault asset decimal places.'),
+                      z.meta({ examples: [6] }),
+                    ),
+                  formatted: z
+                    .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({
+                    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('Position component receiving one annual rate.')),
+        )
+        .check(
+          z.describe('Position amounts grouped by the annual rate they receive.'),
+          z.meta({
+            examples: [
+              [
+                {
+                  assetAmount: {
+                    baseUnits: '25000000000',
+                    decimals: 6,
+                    formatted: '25000',
+                  },
+                  net: '0.07',
+                  type: 'boost',
+                },
+              ],
+            ],
+          }),
+        ),
+      net: EarnRates.schema.Apy.shape.net.check(
+        z.describe('Balance-weighted annual rate for this wallet position.'),
+        z.meta({ examples: ['0.0616666666666667'] }),
+      ),
+    })
+    .check(
+      z.describe(
+        'Wallet-specific effective APY combining live position amounts with qualification from the latest delivered reward snapshot.',
+      ),
+    )
+
   const lifetimeCashFlows = z.union([
     z.strictObject({
       status: z
@@ -464,41 +802,55 @@ export namespace schema {
     }),
   ])
 
-  const addressPosition = z.strictObject({
-    assetAmount: value.check(
-      z.describe('Current asset value of the held shares, including fees, in `assetToken` units.'),
-    ),
-    assetToken: Tokens.schema.Token.check(z.describe('Asset accepted by the vault.')),
-    id: Schema.Address.check(
-      z.describe('Stable resource ID for this position, equal to the vault address.'),
-      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
-    ),
-    lifetimeCashFlows: z
-      .optional(lifetimeCashFlows)
-      .check(z.describe('Lifetime deposits and completed withdrawals, when requested.')),
-    shareAmount: value.check(
-      z.describe('Earn share balance this account holds, in `shareToken` units.'),
-    ),
-    shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
-    valuation: z
-      .optional(z.nullable(Valuation.schema.Value))
-      .check(
-        z.describe(
-          'The position’s nominal value when `valuation.currency` is requested, or `null` when ' +
-            'the asset token is unverified, its display currency has no rate, or rates were unavailable.',
+  const addressPosition = OpenApi.component(
+    z
+      .strictObject({
+        assetAmount: value.check(
+          z.describe(
+            'Current asset value of the held shares, including fees, in `valueToken` units.',
+          ),
         ),
-      ),
-    vaultAddress: Schema.Address.check(
-      z.describe('Earn vault contract address holding this position.'),
-      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
-    ),
-    verified: z
-      .boolean()
-      .check(
-        z.describe('Whether the vault is in the curated earn registry.'),
-        z.meta({ examples: [true] }),
-      ),
-  })
+        assetToken: Tokens.schema.Token.check(z.describe('Asset accepted by the vault.')),
+        chainId: Schema.ChainId.check(
+          z.describe('Chain containing the held shares.'),
+          z.meta({ examples: [42431] }),
+        ),
+        id: Schema.Address.check(
+          z.describe('Stable resource ID for this position, equal to the vault address.'),
+          z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
+        ),
+        lifetimeCashFlows: z
+          .optional(lifetimeCashFlows)
+          .check(z.describe('Lifetime deposits and completed withdrawals, when requested.')),
+        shareAmount: value.check(
+          z.describe('Earn share balance this account holds, in `shareToken` units.'),
+        ),
+        shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
+        valuation: z
+          .optional(z.nullable(Valuation.schema.Value))
+          .check(
+            z.describe(
+              'The position’s nominal value when `valuation.currency` is requested, or `null` when ' +
+                'the asset token is unverified, its display currency has no rate, or rates were unavailable.',
+            ),
+          ),
+        valueToken: Tokens.schema.Token.check(
+          z.describe('Parent-chain asset denominating `assetAmount`.'),
+        ),
+        vaultAddress: Schema.Address.check(
+          z.describe('Earn vault contract address holding this position.'),
+          z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
+        ),
+        verified: z
+          .boolean()
+          .check(
+            z.describe('Whether the vault is in the curated earn registry.'),
+            z.meta({ examples: [true] }),
+          ),
+      })
+      .check(z.describe('An account’s position in one earn vault.')),
+    'EarnAddressPosition',
+  )
 
   const earningsBase = z.strictObject({
     account: Schema.Address.check(
@@ -703,15 +1055,18 @@ export namespace schema {
     export const Query = collectionQuery
 
     /** Paginated list of compatible deployed Earn vaults. */
-    export const Response = z
-      .strictObject({
-        data: z
-          .array(Vault)
-          .check(z.describe('Compatible deployed earn vaults in deployment order.')),
-        meta: z.optional(meta),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of compatible deployed earn vaults.'))
+    export const Response = OpenApi.component(
+      z
+        .strictObject({
+          data: z
+            .array(Vault)
+            .check(z.describe('Compatible deployed earn vaults in deployment order.')),
+          meta: z.optional(meta),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of compatible deployed earn vaults.')),
+      'EarnVaultList',
+    )
   }
 
   /** Schemas for the getVerifiedEarnVaults operation. */
@@ -726,15 +1081,18 @@ export namespace schema {
     export const Query = collectionQuery
 
     /** Paginated list of registry-curated Earn vaults. */
-    export const Response = z
-      .strictObject({
-        data: z
-          .array(VerifiedVault)
-          .check(z.describe('Registry-curated earn vaults ordered by vault address.')),
-        meta: z.optional(meta),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of registry-curated earn vaults.'))
+    export const Response = OpenApi.component(
+      z
+        .strictObject({
+          data: z
+            .array(VerifiedVault)
+            .check(z.describe('Registry-curated earn vaults ordered by vault address.')),
+          meta: z.optional(meta),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of registry-curated earn vaults.')),
+      'VerifiedEarnVaultList',
+    )
   }
 
   /** Schemas for the getEarnAddressPositions operation. */
@@ -753,7 +1111,7 @@ export namespace schema {
         cursor: Schema.Cursor,
         include: Schema.includeQuery(
           z.enum(['earnings']),
-          'Comma-separated position fields to include, such as `earnings`.',
+          'Comma-separated position fields to include, such as `earnings`. Earnings are unavailable when selecting a private Zone.',
         ),
         limit: Schema.Limit,
         'valuation.currency': Schema.Denomination.check(
@@ -788,15 +1146,18 @@ export namespace schema {
       .check(z.describe('Page-level valuation rate provenance.'))
 
     /** Paginated list of the account's earn vault positions. */
-    export const Response = z
-      .strictObject({
-        data: z
-          .array(addressPosition)
-          .check(z.describe('Vaults where the account holds earn shares.')),
-        meta: z.optional(Meta),
-        nextCursor: Schema.NextCursor,
-      })
-      .check(z.describe('A page of the account’s earn vault positions.'))
+    export const Response = OpenApi.component(
+      z
+        .strictObject({
+          data: z
+            .array(addressPosition)
+            .check(z.describe('Vaults where the account holds earn shares.')),
+          meta: z.optional(Meta),
+          nextCursor: Schema.NextCursor,
+        })
+        .check(z.describe('A page of the account’s earn vault positions.')),
+      'EarnAddressPositionList',
+    )
   }
 
   /** Schemas for the getEarnVault operation. */
@@ -820,9 +1181,103 @@ export namespace schema {
       .check(z.describe('Query parameters selecting one earn vault.'))
 
     /** One compatible Earn vault resolved directly from current chain state. */
-    export const Response = Schema.describe(
-      z.extend(vault, { meta: z.optional(meta) }),
-      'A compatible earn vault resolved from chain state, with rate provenance for its valued fields.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.extend(vault, { meta: z.optional(meta) }),
+        'A compatible earn vault resolved from chain state, with rate provenance for its valued fields.',
+      ),
+      'EarnVaultDetail',
+    )
+  }
+
+  /** Schemas for the getEarnVaultSharePrices operation. */
+  export namespace getEarnVaultSharePrices {
+    const timestamp = z.iso.datetime({ offset: true })
+
+    /** Path parameters identifying one Earn vault. */
+    export const Params = z
+      .strictObject({
+        vaultId: Schema.address('0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a').check(
+          z.describe('Earn vault contract address.'),
+        ),
+      })
+      .check(z.describe('Path parameters identifying one Earn vault share-price series.'))
+
+    /** Query parameters selecting a daily historical share-price range. */
+    export const Query = z
+      .strictObject({
+        chainId: Schema.ChainIdQuery,
+        from: timestamp.check(
+          z.describe('First daily share-price observation, as an ISO 8601 timestamp.'),
+          z.meta({ examples: ['2026-07-01T00:00:00.000Z'] }),
+        ),
+        interval: z
+          ._default(z.literal(EarnSharePrices.interval), EarnSharePrices.interval)
+          .check(
+            z.describe('Time between share-price observations.'),
+            z.meta({ examples: [EarnSharePrices.interval] }),
+          ),
+        to: timestamp.check(
+          z.describe('Last possible daily share-price observation, as an ISO 8601 timestamp.'),
+          z.meta({ examples: ['2026-07-31T00:00:00.000Z'] }),
+        ),
+      })
+      .check(
+        z.refine((query) => Date.parse(query.from) <= Date.parse(query.to), {
+          error: '`from` must be before or equal to `to`.',
+          path: ['from'],
+        }),
+        z.refine(
+          (query) =>
+            Math.floor((Date.parse(query.to) - Date.parse(query.from)) / Ttl.days(1)) + 1 <=
+            EarnSharePrices.maxPoints,
+          {
+            error: `Share-price series are limited to ${EarnSharePrices.maxPoints} daily observations.`,
+            path: ['to'],
+          },
+        ),
+        z.describe('Query parameters selecting an Earn vault share-price series.'),
+      )
+
+    const Point = z
+      .strictObject({
+        sharePrice: value.check(
+          z.describe('Assets returned for one whole Earn share at the observation block.'),
+        ),
+        timestamp: z.iso
+          .datetime()
+          .check(
+            z.describe('Requested daily observation timestamp.'),
+            z.meta({ examples: ['2026-07-01T00:00:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('One historical Earn vault share price.'))
+
+    /** Daily share prices for one Earn vault. */
+    export const Response = OpenApi.component(
+      z
+        .strictObject({
+          data: z.array(Point).check(
+            z.describe('Daily Earn vault share prices.'),
+            z.meta({
+              examples: [
+                [
+                  {
+                    sharePrice: {
+                      amount: '1000000',
+                      currency: 'USD',
+                      decimals: 6,
+                      formatted: '1',
+                    },
+                    timestamp: '2026-07-01T00:00:00.000Z',
+                  },
+                ],
+              ],
+            }),
+          ),
+        })
+        .check(z.describe('Daily historical share prices for one Earn vault.')),
+      'EarnVaultSharePriceList',
     )
   }
 
@@ -852,6 +1307,10 @@ export namespace schema {
             z.meta({ examples: ['2026-07-21T09:00:00.000Z'] }),
           ),
         chainId: Schema.ChainIdQuery,
+        include: Schema.includeQuery(
+          z.enum(['apy', 'rewards', 'rewards.proof']),
+          'Include wallet-specific APY or current reward state, optionally with the latest recovery proof.',
+        ),
       })
       .check(z.describe('Query parameters selecting an earn vault position.'))
 
@@ -875,23 +1334,79 @@ export namespace schema {
       .check(z.describe('Indexed block used for a historical Earn position observation.'))
 
     /** Current or historical asset and Earn-share state for one account in one vault. */
-    export const Response = Schema.describe(
-      z.extend(position, {
-        asOf: z
-          .optional(asOf)
+    const Rewards = z
+      .strictObject({
+        cumulativeEntitlement: Schema.DecimalString.check(
+          z.describe('Cumulative EarnShare entitlement.'),
+        ),
+        cumulativePaid: Schema.DecimalString.check(z.describe('Cumulative EarnShare paid.')),
+        deferral: z
+          .optional(z.string())
           .check(
-            z.describe('Requested historical observation time, when supplied.'),
-            z.meta({ examples: ['2026-07-21T09:00:00.000Z'] }),
+            z.describe('Current payout delivery exception.'),
+            z.meta({ examples: ['transfer_unavailable'] }),
           ),
-        block: z
-          .optional(Block)
-          .check(
+        pending: Schema.DecimalString.check(z.describe('EarnShare still owed.')),
+        proof: z
+          .optional(
+            z.strictObject({
+              cumulativeAmount: Schema.DecimalString,
+              distributorAddress: Schema.Address,
+              proof: z.array(Schema.Hash),
+              rootVersion: Schema.DecimalString,
+              statementHash: Schema.Hash,
+            }),
+          )
+          .check(z.describe('Permissionless recovery proof against the confirmed root.')),
+      })
+      .check(z.describe('Current Earn reward state.'))
+
+    export const Response = OpenApi.component(
+      Schema.describe(
+        z.extend(position, {
+          apy: z.optional(z.nullable(positionApy)).check(
             z.describe(
-              'Indexed block used for a historical Earn position observation, when requested.',
+              'Wallet-specific effective APY when requested, or null when unavailable. Qualification comes from the latest delivered reward snapshot and may lag recent deposits or transfers.',
             ),
+            z.meta({
+              examples: [
+                {
+                  breakdown: [
+                    {
+                      assetAmount: {
+                        baseUnits: '25000000000',
+                        decimals: 6,
+                        formatted: '25000',
+                      },
+                      net: '0.07',
+                      type: 'boost',
+                    },
+                  ],
+                  net: '0.07',
+                },
+              ],
+            }),
           ),
-      }),
-      'Current or historical asset and earn-share balances, allowances, and asset value for an account in one earn vault.',
+          asOf: z
+            .optional(asOf)
+            .check(
+              z.describe('Requested historical observation time, when supplied.'),
+              z.meta({ examples: ['2026-07-21T09:00:00.000Z'] }),
+            ),
+          block: z
+            .optional(Block)
+            .check(
+              z.describe(
+                'Indexed block used for a historical Earn position observation, when requested.',
+              ),
+            ),
+          rewards: z
+            .optional(Rewards)
+            .check(z.describe('Current reward state when requested through `include`.')),
+        }),
+        'Current or historical asset and earn-share balances, allowances, and asset value for an account in one earn vault.',
+      ),
+      'EarnVaultPosition',
     )
   }
 
@@ -916,9 +1431,12 @@ export namespace schema {
       .check(z.describe('Query parameters selecting an earn vault account.'))
 
     /** Earnings for one account and period in one Earn vault. */
-    export const Response = Schema.describe(
-      earnings,
-      'Indexed asset value and cost-basis-aware earnings for an account in one earn vault.',
+    export const Response = OpenApi.component(
+      Schema.describe(
+        earnings,
+        'Indexed asset value and cost-basis-aware earnings for an account in one earn vault.',
+      ),
+      'EarnVaultEarnings',
     )
   }
 }
@@ -927,6 +1445,113 @@ export namespace schema {
 export function earn(options: earn.Options = {}) {
   const oracle = options.fx?.oracle ?? FxOracle.ecb()
   return new Hono<App.Environment>()
+    .post(
+      '/v1/earn/rewards/eligibility',
+      Auth.policy({ apiKey: { scopes: [Scope.wildcard] } }),
+      OpenApi.validate('json', schema.registerRewardEligibility.Body, {
+        code: 'body_invalid',
+        message: 'Invalid reward eligibility registration',
+      }),
+      OpenApi.describeRoute({
+        description: 'Registers a wallet and Earn vault association for reward eligibility.',
+        hide: true,
+        operationId: 'registerRewardEligibility',
+        responses: OpenApi.responses({
+          errors: {
+            400: { codes: ['body_invalid', 'chain_id_unsupported'] },
+          },
+          success: {
+            description: 'The persisted reward eligibility association.',
+            schema: schema.registerRewardEligibility.Response,
+          },
+        }),
+        summary: 'Register reward eligibility',
+        tags: ['Earn'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Invalid reward eligibility registration',
+          })
+
+        const body = c.req.valid('json')
+        if (!c.get('supportedChainIds').has(body.chainId))
+          return Response.unsupportedChainId(c, body.chainId, c.get('supportedChainIds'))
+        c.set('chainId', body.chainId)
+        c.header('Cache-Control', Cache.policies.noStore)
+        const result = await RewardEligibilityAssociations.upsert(Db.get(c.get('db')), {
+          ...body,
+        })
+        return c.json(
+          Response.validated(schema.registerRewardEligibility.Response, {
+            association: toRewardEligibilityAssociation(result.record),
+            created: result.created,
+          }),
+          200,
+        )
+      },
+    )
+    .get(
+      '/v1/earn/rewards/eligibility',
+      Auth.policy({ apiKey: { scopes: ['rewards:read'] } }),
+      OpenApi.validate('query', schema.getRewardEligibility.Query, {
+        code: 'query_invalid',
+        message: 'Invalid reward eligibility selector',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Lists reward eligibility associations for one Earn vault at a fixed high-water checkpoint.',
+        hide: true,
+        operationId: 'getRewardEligibility',
+        responses: OpenApi.responses({
+          success: {
+            description: 'A checkpointed page of reward eligibility associations.',
+            schema: schema.getRewardEligibility.Response,
+          },
+        }),
+        summary: 'List reward eligibility',
+        tags: ['Earn'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid reward eligibility selector',
+          })
+
+        const query = c.req.valid('query')
+        const zone = c.get('zones').get(query.chainId)
+        const sourceChainId = zone ? zone.sourceId : query.chainId
+        const principal = Auth.getPrincipal(c)
+        if (
+          principal?.type === 'api_key' &&
+          principal.environment === 'sandbox' &&
+          (sourceChainId === undefined || Viem.isMainnet(sourceChainId))
+        )
+          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 page = await RewardEligibilityAssociations.list(Db.get(c.get('db')), {
+          ...query,
+        })
+        return c.json(
+          Response.validated(schema.getRewardEligibility.Response, {
+            chainId: query.chainId,
+            data: page.data.map((association) => association.walletAddress),
+            nextCursor: page.nextCursor,
+            vaultAddress: query.vaultAddress,
+          }),
+          200,
+        )
+      },
+    )
     .get(
       '/v1/earn/vaults',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
@@ -939,7 +1564,12 @@ export function earn(options: earn.Options = {}) {
           'Lists compatible earn vaults discovered from deployment events and resolved from current chain state.',
         operationId: 'getEarnVaults',
         responses: OpenApi.responses({
-          errors: { 502: 'Could not read earn deployment or vault data.' },
+          errors: {
+            400: {
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+            },
+            502: 'Could not read earn deployment or vault data.',
+          },
           success: {
             description: 'A page of compatible deployed earn vaults.',
             schema: schema.getEarnVaults.Response,
@@ -953,10 +1583,22 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => vaultCacheKey(c, schema.getEarnVaults.Query),
-        name: 'tempo-api:earn-vaults:v4',
+        name: 'tempo-api:earn-vaults:v5',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_invalid',
+            message: 'Invalid chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_unsupported',
+            message: 'Unsupported chain id',
+            status: 400,
+          })
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'query_invalid',
@@ -985,7 +1627,12 @@ export function earn(options: earn.Options = {}) {
           'Lists registry-curated earn vaults after resolving their current onchain configuration.',
         operationId: 'getVerifiedEarnVaults',
         responses: OpenApi.responses({
-          errors: { 502: 'Could not read curated earn registry or vault data.' },
+          errors: {
+            400: {
+              codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'],
+            },
+            502: 'Could not read curated earn registry or vault data.',
+          },
           success: {
             description: 'A page of registry-curated earn vaults.',
             schema: schema.getVerifiedEarnVaults.Response,
@@ -1001,6 +1648,18 @@ export function earn(options: earn.Options = {}) {
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_invalid',
+            message: 'Invalid chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_unsupported',
+            message: 'Unsupported chain id',
+            status: 400,
+          })
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'query_invalid',
@@ -1010,7 +1669,11 @@ export function earn(options: earn.Options = {}) {
         const query = c.req.valid('query')
         try {
           const chainId = query.chainId ?? c.get('chainId')
-          const data = await listVerifiedVaults(c, { ...query, chainId, oracle })
+          const data = await listVerifiedVaults(c, {
+            ...query,
+            chainId,
+            oracle,
+          })
           return c.json(Response.validated(schema.getVerifiedEarnVaults.Response, data), 200)
         } catch (cause) {
           return Response.upstream(c, cause)
@@ -1030,7 +1693,7 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Lists every earn vault where an account currently holds shares, with current balances and optional lifetime cash flows.',
+          'Lists every earn vault where an account currently holds shares on the selected Tempo chain or private Zone. Lifetime cash flows are available on Tempo chains.',
         operationId: 'getEarnAddressPositions',
         responses: OpenApi.responses({
           errors: {
@@ -1093,6 +1756,109 @@ export function earn(options: earn.Options = {}) {
         } catch (cause) {
           if (cause instanceof Valuation.UnsupportedDenominationError)
             return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          if (cause instanceof ZoneEarningsUnsupportedError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/earn/vaults/:vaultId/share-prices',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getEarnVaultSharePrices.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
+      }),
+      OpenApi.validate('query', schema.getEarnVaultSharePrices.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description: 'Lists daily historical share prices for one earn vault.',
+        operationId: 'getEarnVaultSharePrices',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'query_invalid',
+                'vault_id_invalid',
+              ],
+            },
+            404: {
+              codes: ['earn_vault_not_found'],
+              description: 'No compatible earn vault was found at the supplied vault address.',
+            },
+            502: 'Could not read historical earn vault share prices.',
+          },
+          success: {
+            description: 'Daily historical share prices for one earn vault.',
+            schema: schema.getEarnVaultSharePrices.Response,
+          },
+        }),
+        summary: 'List share prices',
+        tags: ['Earn'],
+      }),
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVaultSharePrices.Query),
+        name: 'tempo-api:earn-vault-share-prices:v1',
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_invalid',
+            message: 'Invalid chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_unsupported',
+            message: 'Unsupported chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'vault_id_invalid',
+            message: 'Invalid vault id',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Invalid query parameters',
+          })
+
+        const { vaultId } = c.req.valid('param')
+        const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
+        try {
+          const discovery = await resolveSharePriceVaultDiscovery(c, {
+            chainId,
+            vaultAddress: vaultId,
+          })
+          if (!discovery)
+            return Response.error(c, {
+              code: 'earn_vault_not_found',
+              message: 'Earn vault not found',
+              status: 404,
+            })
+          const data = await getVaultSharePrices(c, {
+            ...query,
+            chainId,
+            discovery,
+            vault: vaultId,
+          })
+          return c.json(Response.validated(schema.getEarnVaultSharePrices.Response, { data }), 200)
+        } catch (cause) {
+          if (
+            cause instanceof EarnSharePrices.IndexedBlockNotFoundError ||
+            cause instanceof EarnSharePrices.IndexedCoverageError
+          )
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          const failure = sharePriceProviderFailure({ cause, chainId })
+          if (failure) c.set('providerFailure', failure)
           return Response.upstream(c, cause)
         }
       },
@@ -1110,7 +1876,7 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Gets an account’s asset and earn-share balances, allowances, and asset value for one earn vault, optionally at an ISO 8601 timestamp.',
+          'Gets an account’s direct or Zone-routed balances and asset value for one earn vault, optionally at an ISO 8601 timestamp.',
         operationId: 'getEarnVaultPosition',
         responses: OpenApi.responses({
           errors: {
@@ -1140,7 +1906,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.noStore,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultPosition.Query),
-        name: 'tempo-api:earn-vault-positions:v2',
+        name: 'tempo-api:earn-vault-positions:v3',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -1170,85 +1936,133 @@ export function earn(options: earn.Options = {}) {
         const { address, vaultId } = c.req.valid('param')
         const query = c.req.valid('query')
         const chainId = query.chainId ?? c.get('chainId')
-        const client = c.get('getClient')(chainId)
+        if (query.asOf && query.include.length > 0)
+          return Response.error(c, {
+            code: 'query_invalid',
+            message: 'Historical position enrichments are not available.',
+            status: 400,
+          })
+        if (c.get('zones').has(chainId)) Cache.setPolicy(c, Cache.policies.noStore)
         try {
-          const block =
-            query.asOf === undefined
-              ? undefined
-              : await getIndexedBlockAtOrBefore(c.get('getTidx')(chainId), query.asOf)
-          try {
-            const position = await client.earn.getPosition({
+          const position = await getVaultPosition(c, {
+            account: address,
+            asOf: query.asOf,
+            chainId,
+            vault: vaultId,
+          })
+          const apy = query.include.includes('apy')
+            ? await resolvePositionApy(c, {
+                chainId,
+                recipient: address,
+                shareBalance: position.shareBalance,
+                value: position.value,
+                vault: vaultId,
+              })
+            : undefined
+          const rewards = query.include.some((value) => value.startsWith('rewards'))
+            ? await RewardRead.recipient({
+                chainId,
+                db: c.get('db'),
+                getClient: c.get('getClient'),
+                recipient: address,
+                vaultAddress: vaultId,
+              })
+            : undefined
+          return c.json(
+            Response.validated(schema.getEarnVaultPosition.Response, {
               account: address,
-              ...(block ? { blockNumber: BigInt(block.number) } : {}),
-              vault: vaultId,
+              ...(query.include.includes('apy') ? { apy } : {}),
+              assetAllowance: position.assetAllowance.toString(),
+              assetBalance: position.assetBalance.toString(),
+              assetToken: position.assetToken,
+              chainId,
+              asOf: query.asOf,
+              block: position.block,
+              id: address,
+              ...(rewards
+                ? {
+                    rewards: query.include.includes('rewards.proof')
+                      ? rewards
+                      : { ...rewards, proof: undefined },
+                  }
+                : {}),
+              shareAllowance: position.shareAllowance.toString(),
+              shareBalance: position.shareBalance.toString(),
+              shareToken: position.shareToken,
+              value: position.value.toString(),
+              valueToken: position.valueToken,
+            }),
+            200,
+          )
+        } catch (cause) {
+          if (cause instanceof IndexedBlockNotFoundError || cause instanceof IndexedCoverageError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          if (cause instanceof ZoneHistoricalAlignmentError)
+            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          if (cause instanceof EarnVaults.NotFoundError)
+            return Response.error(c, {
+              code: 'earn_vault_not_found',
+              message: 'Earn vault not found',
+              status: 404,
             })
-            return c.json(
-              Response.validated(schema.getEarnVaultPosition.Response, {
-                account: address,
-                assetAllowance: position.assetAllowance.toString(),
-                assetBalance: position.assetBalance.toString(),
-                assetToken: position.assetToken,
-                asOf: query.asOf,
-                block,
-                id: address,
-                shareAllowance: position.shareAllowance.toString(),
-                shareBalance: position.shareBalance.toString(),
-                shareToken: position.shareToken,
-                value: position.value.toString(),
-              }),
-              200,
-            )
-          } catch (cause) {
-            if (block) {
-              try {
-                // These immutable bindings establish historical vault identity
-                // without repeating fallible token or redemption subreads.
-                const [asset, shareToken] = await Promise.all([
-                  client.readContract({
-                    abi: Abis.earnVault,
-                    address: vaultId,
-                    blockNumber: BigInt(block.number),
-                    functionName: 'asset',
-                  }),
-                  client.readContract({
-                    abi: Abis.earnVault,
-                    address: vaultId,
-                    blockNumber: BigInt(block.number),
-                    functionName: 'earnShare',
-                  }),
-                ])
-                if (asset === zeroAddress || shareToken === zeroAddress)
-                  return Response.error(c, {
-                    code: 'earn_vault_not_found',
-                    message: 'Earn vault not found',
-                    status: 404,
-                  })
-              } catch (identityCause) {
-                if (isIncompatible(identityCause))
-                  return Response.error(c, {
-                    code: 'earn_vault_not_found',
-                    message: 'Earn vault not found',
-                    status: 404,
-                  })
-                return Response.upstream(c, identityCause)
-              }
-              return Response.upstream(c, cause)
-            }
+          const zone = c.get('zones').get(chainId)
+          if (query.asOf && !zone) {
             try {
-              await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId })
-            } catch (vaultCause) {
-              if (isIncompatible(vaultCause))
+              const block = await getIndexedBlockAtOrBefore(c.get('getTidx')(chainId), query.asOf)
+              const client = c.get('getClient')(chainId)
+              // These immutable bindings establish historical vault identity
+              // without repeating fallible token or redemption subreads.
+              const [asset, shareToken] = await Promise.all([
+                client.readContract({
+                  abi: Abis.earnVault,
+                  address: vaultId,
+                  blockNumber: BigInt(block.number),
+                  functionName: 'asset',
+                }),
+                client.readContract({
+                  abi: Abis.earnVault,
+                  address: vaultId,
+                  blockNumber: BigInt(block.number),
+                  functionName: 'earnShare',
+                }),
+              ])
+              if (asset === zeroAddress || shareToken === zeroAddress)
+                return Response.error(c, {
+                  code: 'earn_vault_not_found',
+                  message: 'Earn vault not found',
+                  status: 404,
+                })
+            } catch (identityCause) {
+              if (
+                identityCause instanceof IndexedBlockNotFoundError ||
+                identityCause instanceof IndexedCoverageError
+              )
+                return Response.error(c, {
+                  code: 'query_invalid',
+                  message: identityCause.message,
+                  status: 400,
+                })
+              if (isIncompatible(identityCause))
                 return Response.error(c, {
                   code: 'earn_vault_not_found',
                   message: 'Earn vault not found',
                   status: 404,
                 })
+              return Response.upstream(c, identityCause)
             }
             return Response.upstream(c, cause)
           }
-        } catch (cause) {
-          if (cause instanceof IndexedBlockNotFoundError || cause instanceof IndexedCoverageError)
-            return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 })
+          if (zone) return Response.upstream(c, cause)
+          try {
+            await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId })
+          } catch (vaultCause) {
+            if (isIncompatible(vaultCause))
+              return Response.error(c, {
+                code: 'earn_vault_not_found',
+                message: 'Earn vault not found',
+                status: 404,
+              })
+          }
           return Response.upstream(c, cause)
         }
       },
@@ -1365,6 +2179,14 @@ export function earn(options: earn.Options = {}) {
         operationId: 'getEarnVault',
         responses: OpenApi.responses({
           errors: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'query_invalid',
+                'vault_id_invalid',
+              ],
+            },
             404: {
               codes: ['earn_vault_not_found'],
               description: 'No compatible earn vault was found at this address.',
@@ -1386,6 +2208,18 @@ export function earn(options: earn.Options = {}) {
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_invalid',
+            message: 'Invalid chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_unsupported',
+            message: 'Unsupported chain id',
+            status: 400,
+          })
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'vault_id_invalid',
@@ -1437,7 +2271,10 @@ export async function getVaultEarnings(
 ) {
   const client = c.get('getClient')(options.chainId)
   const tidx = c.get('getTidx')(options.chainId)
-  const block = await getLatestIndexedBlock(tidx)
+  const [block, rewardTransfer] = await Promise.all([
+    getLatestIndexedBlock(tidx),
+    getRewardTransferPredicate(c, options),
+  ])
   const blockNumber = block.number
   if (options.period === '30d')
     return getWindowVaultEarnings(c, {
@@ -1445,6 +2282,7 @@ export async function getVaultEarnings(
       blockNumber,
       chainId: options.chainId,
       period: options.period,
+      rewardTransfer,
       timestamp: block.timestamp,
       vault: options.vault,
     })
@@ -1465,6 +2303,7 @@ export async function getVaultEarnings(
     const activeCostBasis = await getActiveCostBasis(tidx, {
       account: options.account,
       blockNumber,
+      rewardTransfer,
       shareBalance: current.shareBalance,
       shareToken: current.shareToken,
       vault: options.vault,
@@ -1488,6 +2327,7 @@ export async function getVaultEarnings(
   const externalShareTransfer = await hasExternalShareTransfer(tidx, {
     account: options.account,
     blockNumber,
+    rewardTransfer,
     shareToken: current.shareToken,
     startBlockNumber: beforeFirstBlockNumber,
     vault: options.vault,
@@ -1536,6 +2376,7 @@ async function getWindowVaultEarnings(
     hasExternalShareTransfer(tidx, {
       account: options.account,
       blockNumber: options.blockNumber,
+      rewardTransfer: options.rewardTransfer,
       shareToken: current.shareToken,
       startBlockNumber,
       vault: options.vault,
@@ -1600,6 +2441,8 @@ declare namespace getWindowVaultEarnings {
     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
     /** Earn vault contract address. */
@@ -1981,6 +2824,39 @@ declare namespace getWindowShareState {
   }
 }
 
+/** Builds a share-transfer predicate for the vault's verified reward distributors. */
+async function getRewardTransferPredicate(
+  c: Context<App.Environment>,
+  options: Pick<getVaultEarnings.Options, 'chainId' | 'vault'>,
+) {
+  const db = Db.get(c.get('db'))
+  const campaign = await RewardCampaigns.get(db, {
+    chainId: options.chainId,
+    vaultAddress: options.vault,
+  })
+  if (!campaign) return '0'
+  const distributors = await RewardCampaignDistributors.list(db, {
+    chainId: options.chainId,
+    vaultAddress: options.vault,
+  })
+  if (distributors.length === 0) return '0'
+  const addresses = distributors
+    .map(({ distributorAddress }) => Schema.Address.parse(distributorAddress))
+    .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}'
+    AND "from" IN (${addresses})
+    AND tx_hash NOT IN (
+      SELECT returned.tx_hash FROM UnspentReturned AS returned
+      WHERE returned.address IN (${addresses})
+    )
+  `
+}
+
 /** Returns whether an account sent or received Earn shares outside known vault flows. */
 async function hasExternalShareTransfer(
   tidx: Tidx.Client,
@@ -1995,6 +2871,7 @@ async function hasExternalShareTransfer(
           SELECT count()
           FROM token_transfers
           WHERE token = '${options.shareToken.toLowerCase()}'
+            AND toUInt256(amount) > 0
             AND block_num > ${options.startBlockNumber}
             AND block_num <= ${options.blockNumber}
             AND (
@@ -2003,6 +2880,7 @@ async function hasExternalShareTransfer(
                 "to" = '${options.account}'
                 AND "from" != '${zeroAddress}'
                 AND "from" != '${options.vault}'
+                AND NOT (${options.rewardTransfer})
               )
             )
         ) + (
@@ -2011,6 +2889,7 @@ async function hasExternalShareTransfer(
             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}
@@ -2051,6 +2930,7 @@ async function hasExternalShareTransfer(
             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.vault}'
               AND "to" = '${options.account}'
               AND block_num > ${options.startBlockNumber}
@@ -2074,6 +2954,7 @@ async function hasExternalShareTransfer(
       redeemCancelledSignature,
       redeemedSignature,
       redeemRequestedSignature,
+      unspentReturnedSignature,
       withdrewExactSignature,
     ],
   })
@@ -2086,6 +2967,7 @@ declare namespace hasExternalShareTransfer {
   type Options = {
     account: z.output<typeof Schema.Address>
     blockNumber: number
+    rewardTransfer: string
     shareToken: z.output<typeof Schema.Address>
     startBlockNumber: number
     vault: z.output<typeof Schema.Address>
@@ -2111,6 +2993,7 @@ export function calculateActiveCostBasis(options: calculateActiveCostBasis.Optio
   }
 
   for (const action of options.actions) {
+    if (action.shares === 0n) continue
     if (action.kind === 'deposit') {
       if (costBasis !== undefined) costBasis += action.assets
       shares += action.shares
@@ -2273,7 +3156,7 @@ async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis
           AND block_num <= ${options.blockNumber}
         UNION ALL
         SELECT
-          'unknown' AS kind,
+          if(${options.rewardTransfer}, 'deposit', 'unknown') AS kind,
           block_num,
           log_idx,
           '' AS request_id,
@@ -2281,6 +3164,7 @@ async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis
           '0' AS assets
         FROM token_transfers
         WHERE token = '${options.shareToken.toLowerCase()}'
+          AND toUInt256(amount) > 0
           AND "to" = '${options.account}'
           AND "from" != '${zeroAddress}'
           AND "from" != '${options.vault}'
@@ -2295,6 +3179,7 @@ async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis
           '0' AS assets
         FROM token_transfers
         WHERE token = '${options.shareToken.toLowerCase()}'
+          AND toUInt256(amount) > 0
           AND "from" = '${options.account}'
           AND "to" != '${options.vault}'
           AND block_num <= ${options.blockNumber}
@@ -2306,6 +3191,7 @@ async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis
       redeemCancelledSignature,
       redeemRequestedSignature,
       redeemedSignature,
+      unspentReturnedSignature,
       venueSharesDepositedSignature,
       withdrewExactSignature,
     ],
@@ -2355,6 +3241,7 @@ declare namespace getActiveCostBasis {
   type Options = {
     account: z.output<typeof Schema.Address>
     blockNumber: number
+    rewardTransfer: string
     shareBalance: bigint
     shareToken: z.output<typeof Schema.Address>
     vault: z.output<typeof Schema.Address>
@@ -2458,7 +3345,7 @@ export async function listVaults(c: Context<App.Environment>, options: listVault
         apyByVault.has(vaultAddress.toLowerCase()) ? [] : [vaultAddress],
       )
     : []
-  const [missingApy, rates, tokens] = await Promise.all([
+  const [missingApy, rates, rewards, tokens] = await Promise.all([
     missingApyVaults.length > 0
       ? resolvePageApy(c, {
           chainId: options.chainId,
@@ -2468,12 +3355,27 @@ export async function listVaults(c: Context<App.Environment>, options: listVault
         })
       : undefined,
     resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+    resolvePageRewards(c, {
+      chainId: options.chainId,
+      include,
+      vaults: discoveries.map(({ vaultAddress }) => vaultAddress),
+    }),
     resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
   ])
   for (const [vault, apy] of missingApy ?? []) apyByVault.set(vault, apy)
   const apy = include.includes('apy') ? apyByVault : undefined
   const data = await Promise.all(
-    page.map((match) => resolveVault(c, { ...match, apy, include, rates, snapshot, tokens })),
+    page.map((match) =>
+      resolveVault(c, {
+        ...match,
+        apy,
+        include,
+        rates,
+        rewards: rewards?.get(match.discovery.vaultAddress),
+        snapshot,
+        tokens,
+      }),
+    ),
   )
   const last = matches[options.limit - 1]
   const nextPosition =
@@ -2557,7 +3459,7 @@ export async function listVerifiedVaults(
 
   const page = matches.slice(0, options.limit)
   const discoveries = page.map(({ discovery }) => discovery)
-  const [apy, rates, tokens] = await Promise.all([
+  const [apy, rates, rewards, tokens] = await Promise.all([
     resolvePageApy(c, {
       chainId: options.chainId,
       include,
@@ -2565,13 +3467,26 @@ export async function listVerifiedVaults(
       window: options['apy.window'],
     }),
     resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+    resolvePageRewards(c, {
+      chainId: options.chainId,
+      include,
+      vaults: discoveries.map(({ vaultAddress }) => vaultAddress),
+    }),
     resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
   ])
   const data = await Promise.all(
     page.map(async (match) =>
       Response.validated(
         schema.VerifiedVault,
-        await resolveVault(c, { ...match, apy, include, rates, snapshot, tokens }),
+        await resolveVault(c, {
+          ...match,
+          apy,
+          include,
+          rates,
+          rewards: rewards?.get(match.discovery.vaultAddress),
+          snapshot,
+          tokens,
+        }),
       ),
     ),
   )
@@ -2600,15 +3515,371 @@ export declare namespace listVerifiedVaults {
   }
 }
 
+/** Reads daily historical share prices for one Earn vault. */
+export async function getVaultSharePrices(
+  c: Context<App.Environment>,
+  options: getVaultSharePrices.Options,
+) {
+  const prices = await Timing.time(c, 'earn_share_prices', () =>
+    EarnSharePrices.resolve({
+      chainId: options.chainId,
+      from: options.from,
+      // This client is request-local so viem's stateful HTTP batch cannot cross Worker invocations.
+      getClient: (chainId = options.chainId) =>
+        Viem.createBatchClient({
+          chainId,
+          principal: Auth.getPrincipal(c),
+          rpc: c.get('rpc'),
+          zone: c.get('zones').get(chainId),
+        }),
+      getTidx: c.get('getTidx'),
+      shareDecimals: options.discovery.shareToken.decimals,
+      to: options.to,
+      vault: options.vault,
+    }),
+  )
+  return prices.map((price) => ({
+    sharePrice: {
+      amount: price.amount.toString(),
+      currency: options.discovery.assetToken.currency,
+      decimals: options.discovery.assetToken.decimals,
+      formatted: core_Value.format(price.amount, options.discovery.assetToken.decimals),
+    },
+    timestamp: price.timestamp,
+  }))
+}
+
+/** Classifies an Earn share-price dependency failure for request metrics. */
+export function sharePriceProviderFailure(
+  options: sharePriceProviderFailure.Options,
+): Log.ProviderFailure | undefined {
+  if (options.cause instanceof EarnSharePrices.MalformedResponseError)
+    return {
+      chainId: options.chainId,
+      failure: 'payload',
+      id: 'tidx',
+      operation: 'query',
+    }
+  if (options.cause instanceof EarnSharePrices.TidxRequestError)
+    return { ...Tidx.providerFailure(options.cause.cause), chainId: options.chainId }
+  const failure = Viem.requestFailure(options.cause)
+  if (failure) return { ...failure, chainId: options.chainId, id: 'rpc', operation: 'eth_call' }
+  return undefined
+}
+
+export declare namespace sharePriceProviderFailure {
+  /** Failure and chain used to derive bounded dependency metadata. */
+  type Options = {
+    /** Chain whose dependency call failed. */
+    chainId: number
+    /** Error returned by TIDX parsing or the RPC client. */
+    cause: unknown
+  }
+}
+
+export declare namespace getVaultSharePrices {
+  /** Inputs selecting one Earn vault share-price series. */
+  type Options = z.output<typeof schema.getEarnVaultSharePrices.Query> & {
+    /** Chain containing the Earn vault. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** Current compatible vault and token metadata. */
+    discovery: EarnVaults.Discovery
+    /** Earn vault contract address. */
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+async function resolveSharePriceVaultDiscovery(
+  c: Context<App.Environment>,
+  options: resolveSharePriceVaultDiscovery.Options,
+): Promise<EarnVaults.Discovery | undefined> {
+  const result = await Store.memoize(
+    async () => {
+      try {
+        return {
+          discovery: await readVaultDiscovery(c, { ...options, include: [] }),
+          status: 'found',
+        } as const
+      } catch (cause) {
+        if (isIncompatible(cause)) return { status: 'not_found' } as const
+        throw cause
+      }
+    },
+    {
+      key: `earn-share-price-vault:v1:${options.chainId}:${options.vaultAddress.toLowerCase()}`,
+      store: c.get('store'),
+      ttl: Ttl.seconds(5),
+    },
+  )
+  return result.status === 'found' ? result.discovery : undefined
+}
+
+declare namespace resolveSharePriceVaultDiscovery {
+  type Options = {
+    /** Chain containing the candidate Earn vault. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** Candidate Earn vault contract address. */
+    vaultAddress: z.output<typeof Schema.Address>
+  }
+}
+
+/** Reads one direct or Zone-routed account position in a parent-chain Earn vault. */
+export async function getVaultPosition(
+  c: Context<App.Environment>,
+  options: getVaultPosition.Options,
+): 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)
+    const position = await c
+      .get('getClient')(options.chainId)
+      .earn.getPosition({
+        account: options.account,
+        ...(block ? { blockNumber: BigInt(block.number) } : {}),
+        vault: options.vault,
+      })
+    return { ...position, block, valueToken: position.assetToken }
+  }
+
+  const route = await resolveZonePositionRoute(c, {
+    chainId: options.chainId,
+    vault: options.vault,
+  })
+  const block =
+    options.asOf === undefined
+      ? undefined
+      : await getIndexedBlockAtOrBefore(c.get('getTidx')(options.chainId), options.asOf)
+  const zoneClient = c.get('getClient')(options.chainId)
+  const blockNumber = block ? BigInt(block.number) : await zoneClient.getBlockNumber()
+  const [assetBalance, shareBalance, importedParentBlockNumber] = await Promise.all([
+    readZoneBalance(zoneClient, {
+      account: options.account,
+      blockNumber,
+      token: route.privateAsset,
+    }),
+    readZoneBalance(zoneClient, {
+      account: options.account,
+      blockNumber,
+      token: route.shareToken,
+    }),
+    readZoneSourceBlock(c, {
+      blockNumber,
+      historical: block !== undefined,
+      portal: route.portal,
+      sourceChainId: route.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,
+    })
+  return {
+    assetAllowance: 0n,
+    assetBalance,
+    assetToken: route.privateAsset,
+    block,
+    shareAllowance: 0n,
+    shareBalance,
+    shareToken: route.shareToken,
+    value,
+    valueToken: route.vaultAsset,
+  }
+}
+
+export declare namespace getVaultPosition {
+  /** Inputs selecting one direct or Zone-routed account position. */
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    asOf?: string | undefined
+    chainId: z.output<typeof Schema.ChainId>
+    vault: z.output<typeof Schema.Address>
+  }
+
+  /** Normalized position state across a direct chain or private Zone. */
+  type ReturnType = Actions.earn.getPosition.ReturnValue & {
+    block?: { number: number; timestamp: string } | undefined
+    valueToken: z.output<typeof Schema.Address>
+  }
+}
+
+/** Reads a private Zone token balance with the holder as the authorized RPC caller. */
+async function readZoneBalance(
+  client: ReturnType<App.Environment['Variables']['getClient']>,
+  options: readZoneBalance.Options,
+) {
+  return client.readContract({
+    abi: tokenPositionAbi,
+    account: options.account,
+    address: options.token,
+    args: [options.account],
+    ...(options.blockNumber === undefined ? {} : { blockNumber: options.blockNumber }),
+    functionName: 'balanceOf',
+  })
+}
+
+declare namespace readZoneBalance {
+  /** Private balance selector and optional historical Zone block. */
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber?: bigint | undefined
+    token: z.output<typeof Schema.Address>
+  }
+}
+
+/** Reads the parent Tempo checkpoint imported by one Zone observation. */
+async function readZoneSourceBlock(
+  c: Context<App.Environment>,
+  options: readZoneSourceBlock.Options,
+): Promise<bigint> {
+  const verifiedPromise = c.get('getClient')(options.sourceChainId).readContract({
+    abi: zonePortalAbi,
+    address: options.portal,
+    functionName: 'lastSyncedTempoBlockNumber',
+  })
+  // A historical Zone without TempoState rejects before awaiting the portal.
+  void verifiedPromise.catch(() => undefined)
+  const reported = await (async () => {
+    try {
+      return await options.zoneClient.readContract({
+        abi: tempoStateAbi,
+        address: tempoStateAddress,
+        blockNumber: options.blockNumber,
+        functionName: 'tempoBlockNumber',
+      })
+    } catch (cause) {
+      if (
+        !(cause instanceof ContractFunctionExecutionError) ||
+        !(cause.cause instanceof ContractFunctionZeroDataError)
+      )
+        throw cause
+      if (options.historical) throw new ZoneHistoricalAlignmentError()
+      return undefined
+    }
+  })()
+  const verified = await verifiedPromise
+  return alignZoneSourceBlock({ reported, verified })
+}
+
+declare namespace readZoneSourceBlock {
+  /** Zone observation and parent Portal used to resolve one synchronization boundary. */
+  type Options = {
+    blockNumber: bigint
+    historical: boolean
+    portal: z.output<typeof Schema.Address>
+    sourceChainId: number
+    zoneClient: ReturnType<App.Environment['Variables']['getClient']>
+  }
+}
+
+/** Caps a Zone-reported parent checkpoint at the L1 portal's verified watermark. */
+export function alignZoneSourceBlock(options: alignZoneSourceBlock.Options): bigint {
+  if (options.reported === undefined || options.verified < options.reported) return options.verified
+  return options.reported
+}
+
+export declare namespace alignZoneSourceBlock {
+  /** Zone-reported and L1-verified parent checkpoints. */
+  type Options = {
+    /** Parent checkpoint reported by the Zone, when available. */
+    reported?: bigint | undefined
+    /** Latest parent checkpoint verified by the L1 portal. */
+    verified: bigint
+  }
+}
+
+/** Resolves the verified parent vault and token pair for one Zone route. */
+async function resolveZonePositionRoute(
+  c: Context<App.Environment>,
+  options: resolveZonePositionRoute.Options,
+): Promise<resolveZonePositionRoute.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,
+  })
+  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()
+  return {
+    deploymentBlock: route.deploymentBlock,
+    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. */
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    vault: z.output<typeof Schema.Address>
+  }
+
+  /** Verified addresses needed to read and value a Zone position. */
+  type ReturnType = {
+    deploymentBlock: number
+    privateAsset: z.output<typeof Schema.Address>
+    portal: z.output<typeof Schema.Address>
+    shareToken: z.output<typeof Schema.Address>
+    sourceChainId: number
+    vaultAsset: z.output<typeof Schema.Address>
+  }
+}
+
 /** 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']
+  const zone = c.get('zones').get(options.chainId)
+  if (zone && options.include.includes('earnings')) throw new ZoneEarningsUnsupportedError()
+  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: options.chainId })
+  const recordsPromise = core_EarnVaults
+    .list(db, { chainId: sourceChainId })
+    .then((records) =>
+      zone
+        ? records.filter((record) =>
+            record.zones.some((route) => route.chainId === options.chainId),
+          )
+        : records,
+    )
   // The verified page needs no index: the registry is the candidate set.
-  const heldPromise = options.verified
-    ? undefined
-    : queryHeldVaults(c, { address: options.address, chainId: options.chainId })
+  const heldPromise =
+    options.verified || zone
+      ? undefined
+      : queryHeldVaults(c, { address: options.address, chainId: options.chainId })
   // Observing these branches prevents unhandled rejections while the
   // denomination validates; the later await still propagates them.
   void recordsPromise.catch(() => undefined)
@@ -2647,13 +3918,14 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
         batch.map(async (vault) => {
           const record = registry.get(vault)
           try {
-            const position = await readPosition(c, {
-              address: options.address,
+            const position = await getVaultPosition(c, {
+              account: options.address,
               chainId: options.chainId,
-              vaultAddress: Schema.Address.parse(vault),
+              vault: Schema.Address.parse(vault),
             })
             return { position, record, vaultAddress: vault }
           } catch (cause) {
+            if (cause instanceof EarnVaults.NotFoundError) return undefined
             if (!record && isIncompatible(cause)) return undefined
             throw cause
           }
@@ -2668,10 +3940,10 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
 
   const page = matches.slice(0, options.limit)
   const indexedBlock =
-    page.length > 0 && options.include.includes('earnings')
+    !zone && page.length > 0 && options.include.includes('earnings')
       ? await getLatestIndexedBlock(c.get('getTidx')(options.chainId))
       : undefined
-  const [cashFlows, tokens, snapshot] = await Promise.all([
+  const [cashFlows, tokens, valueTokens, snapshot] = await Promise.all([
     indexedBlock
       ? getVaultLifetimeCashFlows(c.get('getTidx')(options.chainId), {
           account: options.address,
@@ -2694,13 +3966,20 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
         )
       return new Map(groups.flatMap((group) => [...group]))
     })(),
-    denomination ? VerifiedTokens.snapshot(c, options.chainId) : undefined,
+    zone
+      ? Tokens.resolveTokens(c, {
+          addresses: [...new Set(page.map(({ position }) => position.valueToken))],
+          chainId: sourceChainId,
+          include: ['token.verified'],
+        })
+      : undefined,
+    denomination ? VerifiedTokens.snapshot(c, sourceChainId) : undefined,
   ])
   const rates =
     denomination && snapshot
       ? await Valuation.ratesFor(c, {
           currencies: page.flatMap(({ position }) => {
-            const currency = snapshot.byAddress.get(position.assetToken.toLowerCase())?.currency
+            const currency = snapshot.byAddress.get(position.valueToken.toLowerCase())?.currency
             return currency === undefined ? [] : [currency]
           }),
           denomination,
@@ -2720,11 +3999,13 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
     data: page.map((match) =>
       serializePosition({
         cashFlows: cashFlows?.get(match.vaultAddress),
+        chainId: options.chainId,
         denomination,
         position: match.position,
         rates,
         snapshot,
         tokens,
+        valueTokens,
         vaultAddress: match.vaultAddress,
         verified: match.record !== undefined,
       }),
@@ -2737,7 +4018,7 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
 export declare namespace listPositions {
   /** One candidate vault holding a non-zero position. */
   type Match = {
-    position: Actions.earn.getPosition.ReturnValue
+    position: getVaultPosition.ReturnType
     record?: RegistryRecord | undefined
     vaultAddress: string
   }
@@ -2757,12 +4038,11 @@ async function queryHeldVaults(
   c: Context<App.Environment>,
   options: queryHeldVaults.Options,
 ): Promise<readonly string[]> {
+  const factories = deploymentFactories[options.chainId] ?? []
+  if (factories.length === 0) return []
   const tidx = c.get('getTidx')(options.chainId)
-  // Each vault's newest deployment binds its current share token; joining it
-  // against the account's holder deltas server-side turns holdings into vault
-  // candidates in one round trip, with no literal list to overflow the request.
-  // Earn shares are factory-minted TIP-20s, so the `0x20c0` prefix bounds the
-  // subquery. Stale delta rows are fine: the live read drops them.
+  // Filter emitters before ranking so forged events cannot replace share bindings.
+  // TIP-20 prefixes bound holder scans; live reads discard exited positions.
   const result = await Timing.time(c, 'earn_positions_discovery', () =>
     tidx.fetch({
       chainId: options.chainId,
@@ -2778,6 +4058,7 @@ async function queryHeldVaults(
               ORDER BY block_num DESC, log_idx DESC
             ) AS deployment_rank
           FROM EarnStackDeployed
+          WHERE address IN (${factories.map((address) => `'${address}'`).join(', ')})
         )
         WHERE deployment_rank = 1 AND lower("earnShare") IN (
           SELECT DISTINCT lower(token)
@@ -2804,34 +4085,17 @@ declare namespace queryHeldVaults {
   }
 }
 
-/** Reads one account's live position in one vault. */
-function readPosition(
-  c: Context<App.Environment>,
-  options: readPosition.Options,
-): Promise<Actions.earn.getPosition.ReturnValue> {
-  return c
-    .get('getClient')(options.chainId)
-    .earn.getPosition({ account: options.address, vault: options.vaultAddress })
-}
-
-declare namespace readPosition {
-  /** Inputs selecting one vault position. */
-  type Options = {
-    address: z.output<typeof Schema.Address>
-    chainId: z.output<typeof Schema.ChainId>
-    vaultAddress: z.output<typeof Schema.Address>
-  }
-}
-
 /** 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 shareToken = getToken(tokens, position.shareToken)
+  const valueToken = getToken(options.valueTokens ?? tokens, position.valueToken)
   const vaultAddress = Schema.Address.parse(options.vaultAddress.toLowerCase())
   return {
-    assetAmount: valueFor(position.value, assetToken),
+    assetAmount: valueFor(position.value, valueToken),
     assetToken,
+    chainId: options.chainId,
     id: vaultAddress,
     ...(options.cashFlows ? { lifetimeCashFlows: options.cashFlows } : {}),
     shareAmount: valueFor(position.shareBalance, shareToken),
@@ -2842,10 +4106,11 @@ function serializePosition(options: serializePosition.Options) {
             amount: position.value,
             denomination: options.denomination,
             rates: options.rates,
-            token: options.snapshot?.byAddress.get(assetToken.address),
+            token: options.snapshot?.byAddress.get(valueToken.address),
           }),
         }
       : {}),
+    valueToken,
     vaultAddress,
     verified: options.verified,
   }
@@ -2858,14 +4123,16 @@ declare namespace serializePosition {
     cashFlows?: z.output<
       typeof schema.getEarnAddressPositions.Response
     >['data'][number]['lifetimeCashFlows']
+    chainId: z.output<typeof Schema.ChainId>
     /** Currency the row valuation is denominated in (uppercase). */
     denomination?: string | undefined
-    position: Actions.earn.getPosition.ReturnValue
+    position: getVaultPosition.ReturnType
     /** Consulted FX rate set, or undefined when unavailable or unnecessary. */
     rates: Awaited<ReturnType<typeof Valuation.ratesFor>>
     /** Curated token snapshot backing valuation, present when requested. */
     snapshot?: VerifiedTokens.Snapshot | undefined
     tokens: Tokens.resolveTokens.ReturnType
+    valueTokens?: Tokens.resolveTokens.ReturnType | undefined
     vaultAddress: string
     verified: boolean
   }
@@ -3054,7 +4321,7 @@ export async function getVault(c: Context<App.Environment>, options: getVault.Op
       record,
     })
     const discoveries = [discovery]
-    const [apy, rates, tokens] = await Promise.all([
+    const [apy, rates, rewards, tokens] = await Promise.all([
       resolvePageApy(c, {
         chainId: options.chainId,
         include,
@@ -3062,6 +4329,11 @@ export async function getVault(c: Context<App.Environment>, options: getVault.Op
         window: options['apy.window'],
       }),
       resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+      resolveVaultRewards(c, {
+        chainId: options.chainId,
+        include,
+        vault: discovery.vaultAddress,
+      }),
       resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
     ])
     return {
@@ -3071,6 +4343,7 @@ export async function getVault(c: Context<App.Environment>, options: getVault.Op
         include,
         rates,
         record,
+        rewards,
         snapshot,
         tokens,
         zoneRoutes,
@@ -3148,29 +4421,36 @@ async function resolveVaultDiscovery(
   c: Context<App.Environment>,
   options: resolveVaultDiscovery.Options,
 ) {
-  return Store.memoize(
-    () =>
-      Timing.time(c, 'earn_vault_discovery', () =>
-        EarnVaults.resolve({
-          getClient: c.get('getClient'),
-          include: options.include,
-          input: {
-            chainId: options.chainId,
-            vaultAddress: options.vaultAddress,
-          },
-          zones: [...c.get('zones').values()],
-        }),
-      ),
-    {
-      key: `earn-vault:v3:${options.chainId}:${options.vaultAddress.toLowerCase()}:include:${options.include.join(',') || 'base'}`,
-      store: c.get('store'),
-      // Matches the routes' `state` policy `max-age` so the two cache layers do
-      // not compound staleness on live vault state.
-      ttl: Ttl.seconds(30),
-    },
+  return Store.memoize(() => readVaultDiscovery(c, options), {
+    key: `earn-vault:v3:${options.chainId}:${options.vaultAddress.toLowerCase()}:include:${options.include.join(',') || 'base'}`,
+    store: c.get('store'),
+    // Matches the routes' `state` policy `max-age` so the two cache layers do
+    // not compound staleness on live vault state.
+    ttl: Ttl.seconds(30),
+  })
+}
+
+async function readVaultDiscovery(
+  c: Context<App.Environment>,
+  options: readVaultDiscovery.Options,
+) {
+  return Timing.time(c, 'earn_vault_discovery', () =>
+    EarnVaults.resolve({
+      getClient: c.get('getClient'),
+      include: options.include,
+      input: {
+        chainId: options.chainId,
+        vaultAddress: options.vaultAddress,
+      },
+      zones: [...c.get('zones').values()],
+    }),
   )
 }
 
+declare namespace readVaultDiscovery {
+  type Options = resolveVaultDiscovery.Options
+}
+
 declare namespace resolveVaultDiscovery {
   type Options = {
     chainId: z.output<typeof Schema.ChainId>
@@ -3233,6 +4513,129 @@ declare namespace resolveVaultRoutes {
   }
 }
 
+async function resolvePositionApy(
+  c: Context<App.Environment>,
+  options: resolvePositionApy.Options,
+): Promise<RewardRead.PositionApy | null> {
+  const sourceChainId = c.get('zones').get(options.chainId)?.sourceId ?? options.chainId
+  const recordFailure = (failure: Log.ProviderFailure) => {
+    Cache.setPolicy(c, Cache.policies.noStore)
+    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, {
+      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
+    }),
+  ])
+  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')), {
+        chainId: options.chainId,
+        vaultAddress: options.vault,
+      }),
+    ])
+    // 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))
+    return RewardRead.positionApy({
+      assetDecimals: discovery.assetToken.decimals,
+      baseNet: base.net,
+      chainId: options.chainId,
+      db: c.get('db'),
+      excludedAddresses: [
+        discovery.engine.address,
+        earnFees,
+        ...(record?.zones.map((zone) => zone.earnRouter) ?? []),
+        ...zoneContracts,
+      ],
+      recipient: options.recipient,
+      shareBalance: options.shareBalance.toString(),
+      value: options.value.toString(),
+      vaultAddress: options.vault,
+    })
+  }).catch((cause) => {
+    recordFailure(
+      sharePriceProviderFailure({ cause, chainId: sourceChainId }) ?? {
+        chainId: options.chainId,
+        failure: 'unknown',
+        id: 'earn-rewards',
+        operation: 'getPositionApy',
+      },
+    )
+    return null
+  })
+}
+
+declare namespace resolvePositionApy {
+  /** Current wallet position used to resolve its effective APY. */
+  type Options = {
+    /** Chain containing the vault position. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** 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>
+  }
+}
+
+function positionApyContractAddresses(contract: unknown): string[] {
+  if (!contract || typeof contract !== 'object') return []
+  const value = contract as Record<string, unknown>
+  const address = value['address']
+  if (typeof address === 'string' && isAddress(address)) return [address]
+  return Object.values(value).flatMap(positionApyContractAddresses)
+}
+
 // Measuring a rate costs indexer boundary queries plus historical quotes against
 // an archive node, so an unrequested rate reaches neither.
 function resolvePageApy(c: Context<App.Environment>, options: resolvePageApy.Options) {
@@ -3249,6 +4652,64 @@ function resolvePageApy(c: Context<App.Environment>, options: resolvePageApy.Opt
   )
 }
 
+function resolvePageRewards(c: Context<App.Environment>, options: resolvePageRewards.Options) {
+  if (!options.include.includes('apy')) return undefined
+  return Timing.time(c, 'earn_rewards_apy', () =>
+    RewardRead.resolveCollection({
+      chainId: options.chainId,
+      db: c.get('dbCached'),
+      vaults: options.vaults,
+    }).catch(() => {
+      Cache.setPolicy(c, Cache.policies.noStore)
+      const failure = {
+        chainId: options.chainId,
+        failure: 'unknown',
+        id: 'earn-rewards',
+        operation: 'listVaultRewards',
+      } satisfies Log.ProviderFailure
+      c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure])
+      return new Map<string, readonly RewardRead.Reward[]>()
+    }),
+  )
+}
+
+function resolveVaultRewards(c: Context<App.Environment>, options: resolveVaultRewards.Options) {
+  if (!options.include.includes('apy')) return undefined
+  return Timing.time(c, 'earn_rewards_apy', () =>
+    RewardRead.get({
+      chainId: options.chainId,
+      db: c.get('dbCached'),
+      vaultAddress: options.vault,
+    }).catch(() => {
+      Cache.setPolicy(c, Cache.policies.noStore)
+      const failure = {
+        chainId: options.chainId,
+        failure: 'unknown',
+        id: 'earn-rewards',
+        operation: 'getVaultRewards',
+      } satisfies Log.ProviderFailure
+      c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure])
+      return undefined
+    }),
+  )
+}
+
+declare namespace resolveVaultRewards {
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    include: z.output<typeof schema.getEarnVault.Query>['include']
+    vault: z.output<typeof Schema.Address>
+  }
+}
+
+declare namespace resolvePageRewards {
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    include: z.output<typeof schema.getEarnVault.Query>['include']
+    vaults: readonly z.output<typeof Schema.Address>[]
+  }
+}
+
 declare namespace resolvePageApy {
   type Options = {
     chainId: z.output<typeof Schema.ChainId>
@@ -3351,6 +4812,7 @@ async function resolveVault(c: Context<App.Environment>, options: resolveVault.O
         }
       : null,
     record,
+    rewards: options.rewards,
     shareToken: getToken(options.tokens, discovery.shareToken.address),
     tvl: valued
       ? {
@@ -3372,6 +4834,7 @@ declare namespace resolveVault {
     include: z.output<typeof schema.getEarnVault.Query>['include']
     rates: Awaited<ReturnType<typeof Valuation.ratesFor>>
     record?: RegistryRecord | undefined
+    rewards?: readonly RewardRead.Reward[] | undefined
     snapshot: VerifiedTokens.Snapshot
     tokens: Tokens.resolveTokens.ReturnType
     zoneRoutes: readonly EarnVaults.ResolvedZoneRoute[]
@@ -3386,9 +4849,41 @@ export function serializeVault(options: serializeVault.Options): z.output<typeof
   if (options.include.includes('capabilities') && !discovery.capabilities)
     throw new Error('Earn vault capabilities were not resolved.')
   const vaultAddress = Schema.Address.parse(discovery.vaultAddress.toLowerCase())
+  const rewards = options.rewards?.map((reward) => ({
+    apr:
+      reward.currentRewardsAprBps === null ? null : RewardRead.ratio(reward.currentRewardsAprBps),
+    asset: reward.asset,
+    ...(reward.calculatedThrough !== undefined
+      ? { calculatedThrough: reward.calculatedThrough }
+      : {}),
+    campaignId: reward.campaignId,
+    endsAt: reward.endsAt,
+    startsAt: reward.startsAt,
+    targetTotalApr: RewardRead.ratio(reward.targetTotalAprBps),
+  }))
+  const startedRewards = options.rewards?.filter(
+    (reward) => reward.startsAt <= Math.floor(Date.now() / 1_000),
+  )
+  const targetTotalAprBps = startedRewards?.reduce(
+    (target, reward) => Math.max(target, reward.targetTotalAprBps),
+    0,
+  )
+  const apy = options.apy
+    ? {
+        ...options.apy,
+        net: (() => {
+          if (!startedRewards || startedRewards.length === 0) return options.apy.net
+          const target = targetTotalAprBps ?? 0
+          if (parseUnits(options.apy.net, 6) >= BigInt(target) * 100n) return options.apy.net
+          return RewardRead.ratio(target)
+        })(),
+        ...(rewards ? { rewards } : {}),
+        vault: options.apy.net,
+      }
+    : null
   return Response.validated(schema.Vault, {
     ...(options.include.includes('access') ? { access: discovery.access } : {}),
-    ...(options.include.includes('apy') ? { apy: options.apy } : {}),
+    ...(options.include.includes('apy') ? { apy } : {}),
     assetToken: options.assetToken,
     ...(options.include.includes('capabilities') ? { capabilities: discovery.capabilities } : {}),
     description: record?.description ?? null,
@@ -3449,6 +4944,8 @@ export declare namespace serializeVault {
     instantLiquidityValue: z.output<typeof schema.Vault>['instantLiquidityValue']
     /** Curated registry row, when verified. */
     record?: core_EarnVaults.Record | undefined
+    /** Enabled, registered Merkle rewards, or undefined when enrichment is unavailable. */
+    rewards?: readonly RewardRead.Reward[] | undefined
     /** Resolved share token. */
     shareToken: z.output<typeof Tokens.schema.Token>
     /** USD value of the assets, or null when unpriced; omitted unless `include` carries `tvl`. */
@@ -3517,6 +5014,8 @@ async function queryDeployments(
   c: Context<App.Environment>,
   options: queryDeployments.Options,
 ): Promise<queryDeployments.Result> {
+  const factories = deploymentFactories[options.chainId] ?? []
+  if (factories.length === 0) return { hasMore: false, items: [] }
   const filters: string[] = []
   if (options.asset) filters.push(`lower(asset) = '${options.asset.toLowerCase()}'`)
   if (options.cursor)
@@ -3535,7 +5034,8 @@ async function queryDeployments(
       ]),
     )
 
-  // Deduplicate before outer filters so every vault is filtered by its latest deployment.
+  // Authenticate emitters before deduplication so a forged newer event cannot
+  // replace a factory deployment or suppress it through outer filters.
   const result = await c
     .get('getTidx')(options.chainId)
     .fetch({
@@ -3550,6 +5050,7 @@ async function queryDeployments(
           block_num,
           log_idx
         FROM EarnStackDeployed
+        WHERE address IN (${factories.map((address) => `'${address}'`).join(', ')})
         ORDER BY block_num DESC, log_idx DESC
         LIMIT 1 BY lower("earnVault")
       )
@@ -3664,3 +5165,19 @@ class IndexedCoverageError extends Error {
     super(`Indexed history does not yet cover ${asOf}.`)
   }
 }
+
+class ZoneHistoricalAlignmentError extends Error {
+  override name = 'Earn.ZoneHistoricalAlignmentError'
+
+  constructor() {
+    super('This Zone does not expose historical parent-chain synchronization checkpoints.')
+  }
+}
+
+class ZoneEarningsUnsupportedError extends Error {
+  override name = 'Earn.ZoneEarningsUnsupportedError'
+
+  constructor() {
+    super('Zone positions do not support the earnings include.')
+  }
+}