tapimo 0.13.0 → 0.15.0

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

@@ -1,11 +1,14 @@
 import { type Context, Hono } from 'hono'
 import { Value as core_Value } from 'ox'
-import type { Actions } from 'viem/tempo'
+import { Abis, type Actions } from 'viem/tempo'
 import {
   type Chain,
   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: ['0xd85fc943333a6cd7c0e3391acd54fc4e572f0baf'] }),
-      ),
-      type: z
-        .nullable(engineType)
-        .check(z.describe('Inferred engine type, or null when it is unknown.')),
-      venue: z
-        .nullable(
-          Schema.Address.check(
-            z.describe('Yield venue contract bound to the engine.'),
-            z.meta({ examples: ['0xa8b4f0e69cd4b0e56b676343f02acd8c3b355322'] }),
-          ),
-        )
-        .check(z.describe('Yield venue, or null when the engine does not expose one.')),
-    }),
-    'Current vault engine.',
+  const 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: [1424310003] }),
-      ),
-      inputTokens: z
-        .array(Schema.Address)
-        .check(
-          z.describe('Tokens accepted by private deposits.'),
-          z.meta({ examples: [['0x20c0000000000000000000002139993d5f625d59']] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Private Zone name.'), z.meta({ examples: ['zone-moderato-internal'] })),
-      outputTokens: z
-        .array(Schema.Address)
-        .check(
-          z.describe('Tokens supported by private redemptions.'),
-          z.meta({ examples: [['0x20c0000000000000000000002139993d5f625d59']] }),
+  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: [1424310003] }),
-      ),
-      deploymentBlock: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('Parent-chain block that deployed the Earn router.'),
-          z.meta({ examples: [31730087] }),
-        ),
-      earnRouter: Schema.Address.check(
-        z.describe('Parent-chain router for this Zone and Earn vault.'),
-        z.meta({ examples: ['0xebedc74ffeead186acc6cac05eb82fb9e093a7c7'] }),
-      ),
-      inputTokens: z
-        .array(Schema.Address)
-        .check(
-          z.describe('Tokens accepted by private deposits.'),
-          z.meta({ examples: [['0x20c0000000000000000000002139993d5f625d59']] }),
+  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-moderato-internal'] })),
-      outputTokens: z
-        .array(Schema.Address)
-        .check(
-          z.describe('Tokens returned by private redemptions.'),
-          z.meta({ examples: [['0x20c0000000000000000000002139993d5f625d59']] }),
+        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,13 +502,28 @@ 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(z.describe('Asset accepted by the vault.')),
+    assetToken: Tokens.schema.Token.check(
+      z.describe('Asset accepted by the vault.'),
+      z.meta({
+        examples: [
+          {
+            address: '0x20c0000000000000000000000000000000000000',
+            currency: 'USD',
+            decimals: 6,
+            id: '0x20c0000000000000000000000000000000000000',
+            name: 'PathUSD',
+            symbol: 'pathUSD',
+            verified: true,
+          },
+        ],
+      }),
+    ),
     capabilities: z
       .optional(EarnVaults.schema.Discovery.shape.capabilities)
       .check(z.describe('Vault capabilities, when requested.')),
@@ -271,21 +531,28 @@ export namespace schema {
       .nullable(z.string())
       .check(
         z.describe('Curated vault description, or null when the vault is not verified.'),
-        z.meta({ examples: ['Bridge test PATHUSD deposited into Tempo Earn.'] }),
+        z.meta({ examples: ['deelUSD deposited into the canonical Tempo Earn deployment.'] }),
       ),
     engine,
     id: Schema.Address.check(
       z.describe('Stable vault id, equal to the lowercase vault address.'),
-      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
     ),
     instantLiquidity: EarnVaults.schema.Discovery.shape.instantLiquidity.check(
       z.describe(
         'Assets the venue would release right now, capped at the vault backing, in asset base units. Null when the engine interface cannot report a reliable number.',
       ),
     ),
+    instantLiquidityValue: z
+      .optional(z.nullable(value))
+      .check(
+        z.describe(
+          'Instant liquidity valued in USD, when requested via `include=tvl`, or null when liquidity is unavailable or the asset has no priced display currency.',
+        ),
+      ),
     label: z
       .string()
-      .check(z.describe('Vault display label.'), z.meta({ examples: ['btPATHUSD Earn'] })),
+      .check(z.describe('Vault display label.'), z.meta({ examples: ['deelUSD Earn'] })),
     sharePrice: z
       .nullable(value)
       .check(
@@ -293,12 +560,27 @@ export namespace schema {
           'Assets returned for one whole earn share, in the asset display currency, or null when the engine cannot quote an exit.',
         ),
       ),
-    shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
+    shareToken: Tokens.schema.Token.check(
+      z.describe('Token representing vault shares.'),
+      z.meta({
+        examples: [
+          {
+            address: '0x20c000000000000000000000c3268d803b51d448',
+            currency: 'USD',
+            decimals: 6,
+            id: '0x20c000000000000000000000c3268d803b51d448',
+            name: 'Sentora pathUSD (Earn)',
+            symbol: 'senpathUSDE',
+            verified: false,
+          },
+        ],
+      }),
+    ),
     slug: z
       .nullable(z.string())
       .check(
         z.describe('Curated URL slug, or null when the vault is not verified.'),
-        z.meta({ examples: ['btpathusd-earn-h8k2m4n6'] }),
+        z.meta({ examples: ['deelusd-earn'] }),
       ),
     state: EarnVaults.schema.Discovery.shape.state,
     tvl: z
@@ -310,7 +592,7 @@ export namespace schema {
       ),
     vaultAddress: Schema.Address.check(
       z.describe('Earn vault contract address.'),
-      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
     ),
     verified: z
       .boolean()
@@ -327,12 +609,12 @@ export namespace schema {
         examples: [
           [
             {
-              chainId: 1424310003,
-              deploymentBlock: 31730087,
-              earnRouter: '0xebedc74ffeead186acc6cac05eb82fb9e093a7c7',
-              inputTokens: ['0x20c0000000000000000000002139993d5f625d59'],
-              name: 'zone-moderato-internal',
-              outputTokens: ['0x20c0000000000000000000002139993d5f625d59'],
+              chainId: 421700001,
+              deploymentBlock: 35822949,
+              earnRouter: '0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6',
+              inputTokens: ['0x20c0000000000000000000006fd9a167923ba194'],
+              name: 'zone-mainnet-internal',
+              outputTokens: ['0x20c0000000000000000000006fd9a167923ba194'],
             },
           ],
         ],
@@ -341,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({
@@ -369,26 +657,34 @@ 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(
-      z.describe('Assets this account currently holds, in asset base units.'),
+      z.describe('Assets held by this account at the observation block, in asset base units.'),
       z.meta({ examples: ['250000000'] }),
     ),
     assetToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(
-      z.describe('TIP-20 asset token accepted by the vault.'),
+      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(
-      z.describe('Earn shares this account currently holds, in share base units.'),
+      z.describe('Earn shares held by this account at the observation block, in share base units.'),
       z.meta({ examples: ['99500000'] }),
     ),
     shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(
@@ -396,44 +692,165 @@ export namespace schema {
     ),
     value: Schema.DecimalString.check(
       z.describe(
-        'Current asset value of this account’s earn shares, 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 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: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
-    ),
-    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 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'] }),
       ),
-    vaultAddress: Schema.Address.check(
-      z.describe('Earn vault contract address holding this position.'),
-      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
-    ),
-    verified: z
-      .boolean()
-      .check(
-        z.describe('Whether the vault is in the curated earn registry.'),
-        z.meta({ examples: [true] }),
+    })
+    .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
+        .literal('complete')
+        .check(
+          z.describe('Cash flows are complete through the indexed boundary.'),
+          z.meta({ examples: ['complete'] }),
+        ),
+      totalDeposited: Schema.DecimalString.check(
+        z.describe('Assets deposited with this account as receiver over indexed vault history.'),
+      ),
+      totalWithdrawn: Schema.DecimalString.check(
+        z.describe('Assets returned by completed withdrawals over indexed vault history.'),
+      ),
+    }),
+    z.strictObject({
+      status: z
+        .literal('incomplete_history')
+        .check(
+          z.describe('Cash flows are omitted because asset deposit history is incomplete.'),
+          z.meta({ examples: ['incomplete_history'] }),
+        ),
+    }),
+  ])
+
+  const addressPosition = OpenApi.component(
+    z
+      .strictObject({
+        assetAmount: value.check(
+          z.describe(
+            'Current asset value of the held shares, including fees, in `valueToken` units.',
+          ),
+        ),
+        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(
@@ -476,6 +893,18 @@ export namespace schema {
           ),
           z.meta({ examples: ['0'] }),
         ),
+      totalDeposited: Schema.DecimalString.check(
+        z.describe(
+          'Assets deposited with this account as receiver over complete indexed vault history.',
+        ),
+        z.meta({ examples: ['1000000'] }),
+      ),
+      totalWithdrawn: Schema.DecimalString.check(
+        z.describe(
+          'Assets returned by completed redemptions and exact withdrawals initiated by this account over complete indexed vault history.',
+        ),
+        z.meta({ examples: ['1000000'] }),
+      ),
       period: z
         .literal('lifetime')
         .check(
@@ -548,9 +977,23 @@ export namespace schema {
     }),
     z.extend(earningsBase, {
       period: z
-        .enum(['30d', 'lifetime'])
+        .literal('30d')
         .check(
-          z.describe('Earnings period with an unresolved async redemption.'),
+          z.describe('Trailing period with an unresolved async redemption.'),
+          z.meta({ examples: ['30d'] }),
+        ),
+      status: z
+        .literal('pending_redemption')
+        .check(
+          z.describe('Earnings are unavailable while an async redemption remains open.'),
+          z.meta({ examples: ['pending_redemption'] }),
+        ),
+    }),
+    z.extend(earningsBase, {
+      period: z
+        .literal('lifetime')
+        .check(
+          z.describe('Lifetime period with an unresolved async redemption.'),
           z.meta({ examples: ['lifetime'] }),
         ),
       status: z
@@ -559,6 +1002,12 @@ export namespace schema {
           z.describe('Earnings are unavailable while an async redemption remains open.'),
           z.meta({ examples: ['pending_redemption'] }),
         ),
+      totalDeposited: Schema.DecimalString.check(
+        z.describe('Assets deposited over complete indexed vault history.'),
+      ),
+      totalWithdrawn: Schema.DecimalString.check(
+        z.describe('Assets withdrawn over complete indexed vault history.'),
+      ),
     }),
   ])
 
@@ -606,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. */
@@ -629,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. */
@@ -654,6 +1109,10 @@ export namespace schema {
       .strictObject({
         chainId: Schema.ChainIdQuery,
         cursor: Schema.Cursor,
+        include: Schema.includeQuery(
+          z.enum(['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(
           z.describe(
@@ -687,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. */
@@ -719,19 +1181,115 @@ 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',
     )
   }
 
   /** Schemas for the getEarnVaultPosition operation. */
   export namespace getEarnVaultPosition {
+    const asOf = z.iso.datetime({ offset: true })
+
     /** Path parameters identifying the Earn vault and account. */
     export const Params = z
       .strictObject({
         address: Schema.Address.check(z.describe('Account whose earn position to read.')),
-        vaultId: Schema.address('0xdb48b00fb28d9a8db881fcd671c3fb1bf8c486b6').check(
+        vaultId: Schema.address('0x4f94590b636f5878bce585e82379de81e1ec174f').check(
           z.describe('Earn vault contract address.'),
         ),
       })
@@ -739,13 +1297,116 @@ export namespace schema {
 
     /** Query parameters selecting the chain containing the vault. */
     export const Query = z
-      .strictObject({ chainId: Schema.ChainIdQuery })
+      .strictObject({
+        asOf: z
+          .optional(asOf)
+          .check(
+            z.describe(
+              'ISO 8601 timestamp at which to read the position. Resolves the latest indexed block at or before this time.',
+            ),
+            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.'))
 
-    /** Current asset and Earn-share state for one account in one vault. */
-    export const Response = Schema.describe(
-      position,
-      'Current asset and earn-share balances, allowances, and asset value for an account in one earn vault.',
+    const Block = z
+      .strictObject({
+        number: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('Indexed observation block.'),
+            z.meta({ examples: [31039238] }),
+          ),
+        timestamp: z.iso
+          .datetime()
+          .check(
+            z.describe('Timestamp of the indexed observation block.'),
+            z.meta({ examples: ['2026-07-21T09:00:00.000Z'] }),
+          ),
+      })
+      .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. */
+    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('Current payout delivery exception.'),
+            z.meta({ examples: ['transfer_unavailable'] }),
+          ),
+        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(
+              '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',
+                },
+              ],
+            }),
+          ),
+          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',
     )
   }
 
@@ -770,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',
     )
   }
 }
@@ -781,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 }),
@@ -793,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,
@@ -807,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:v3',
+        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',
@@ -839,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,
@@ -851,67 +1644,166 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => vaultCacheKey(c, schema.getVerifiedEarnVaults.Query),
-        name: 'tempo-api:earn-vaults:v3',
+        name: 'tempo-api:earn-vaults:v4',
+      }),
+      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',
+            message: 'Invalid query parameters',
+          })
+
+        const query = c.req.valid('query')
+        try {
+          const chainId = query.chainId ?? c.get('chainId')
+          const data = await listVerifiedVaults(c, {
+            ...query,
+            chainId,
+            oracle,
+          })
+          return c.json(Response.validated(schema.getVerifiedEarnVaults.Response, data), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/earn/addresses/:address/positions',
+      Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+      OpenApi.validate('param', schema.getEarnAddressPositions.Params, {
+        code: 'positions_invalid',
+        message: 'Invalid address positions',
+      }),
+      OpenApi.validate('query', schema.getEarnAddressPositions.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+      }),
+      OpenApi.describeRoute({
+        description:
+          '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: {
+            400: {
+              codes: [
+                'chain_id_invalid',
+                'chain_id_unsupported',
+                'positions_invalid',
+                'query_invalid',
+              ],
+            },
+            502: 'Could not read earn deployment or position data.',
+          },
+          success: {
+            description: 'A page of the account’s earn vault positions.',
+            schema: schema.getEarnAddressPositions.Response,
+          },
+        }),
+        summary: 'List account positions',
+        tags: ['Earn'],
+      }),
+      // `noStore` matches the address balances listing: account holdings must
+      // read fresh immediately after a deposit or redemption.
+      Cache.response<App.Environment>({
+        cacheControl: Cache.policies.noStore,
+        key: (c) => Cache.urlKey(c, schema.getEarnAddressPositions.Query),
+        name: 'tempo-api:earn-address-positions:v2',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_invalid',
+            message: 'Invalid chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return Response.error(c, {
+            code: 'chain_id_unsupported',
+            message: 'Unsupported chain id',
+            status: 400,
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'positions_invalid',
+            message: 'Invalid request parameters',
+          })
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
             code: 'query_invalid',
             message: 'Invalid query parameters',
           })
 
+        const { address } = c.req.valid('param')
         const query = c.req.valid('query')
+        const chainId = query.chainId ?? c.get('chainId')
         try {
-          const chainId = query.chainId ?? c.get('chainId')
-          const data = await listVerifiedVaults(c, { ...query, chainId, oracle })
-          return c.json(Response.validated(schema.getVerifiedEarnVaults.Response, data), 200)
+          const data = await listPositions(c, { ...query, address, chainId, oracle })
+          return c.json(Response.validated(schema.getEarnAddressPositions.Response, data), 200)
         } 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/addresses/:address/positions',
+      '/v1/earn/vaults/:vaultId/share-prices',
       Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
-      OpenApi.validate('param', schema.getEarnAddressPositions.Params, {
-        code: 'positions_invalid',
-        message: 'Invalid address positions',
+      OpenApi.validate('param', schema.getEarnVaultSharePrices.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
       }),
-      OpenApi.validate('query', schema.getEarnAddressPositions.Query, {
+      OpenApi.validate('query', schema.getEarnVaultSharePrices.Query, {
         code: 'query_invalid',
         message: 'Invalid query parameters',
       }),
       OpenApi.describeRoute({
-        description:
-          'Lists every earn vault where an account currently holds shares, with the current balance and value of each position.',
-        operationId: 'getEarnAddressPositions',
+        description: 'Lists daily historical share prices for one earn vault.',
+        operationId: 'getEarnVaultSharePrices',
         responses: OpenApi.responses({
           errors: {
             400: {
               codes: [
                 'chain_id_invalid',
                 'chain_id_unsupported',
-                'positions_invalid',
                 'query_invalid',
+                'vault_id_invalid',
               ],
             },
-            502: 'Could not read earn deployment or position data.',
+            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: 'A page of the account’s earn vault positions.',
-            schema: schema.getEarnAddressPositions.Response,
+            description: 'Daily historical share prices for one earn vault.',
+            schema: schema.getEarnVaultSharePrices.Response,
           },
         }),
-        summary: 'List account positions',
+        summary: 'List share prices',
         tags: ['Earn'],
       }),
-      // `noStore` matches the address balances listing: account holdings must
-      // read fresh immediately after a deposit or redemption.
       Cache.response<App.Environment>({
-        cacheControl: Cache.policies.noStore,
-        key: (c) => Cache.urlKey(c, schema.getEarnAddressPositions.Query),
-        name: 'tempo-api:earn-address-positions:v1',
+        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)
@@ -929,8 +1821,8 @@ export function earn(options: earn.Options = {}) {
           })
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
-            code: 'positions_invalid',
-            message: 'Invalid request parameters',
+            code: 'vault_id_invalid',
+            message: 'Invalid vault id',
           })
         if (OpenApi.narrowValidation)
           return OpenApi.validationError(c, {
@@ -938,15 +1830,35 @@ export function earn(options: earn.Options = {}) {
             message: 'Invalid query parameters',
           })
 
-        const { address } = c.req.valid('param')
+        const { vaultId } = c.req.valid('param')
         const query = c.req.valid('query')
         const chainId = query.chainId ?? c.get('chainId')
         try {
-          const data = await listPositions(c, { ...query, address, chainId, oracle })
-          return c.json(Response.validated(schema.getEarnAddressPositions.Response, data), 200)
+          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 Valuation.UnsupportedDenominationError)
+          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)
         }
       },
@@ -964,7 +1876,7 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Gets an account’s asset and earn-share balances, allowances, and current asset value for one earn vault.',
+          '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: {
@@ -983,17 +1895,18 @@ export function earn(options: earn.Options = {}) {
             502: 'Could not read the earn vault position.',
           },
           success: {
-            description: 'Current earn position for one account in one vault.',
+            description: 'Current or historical earn position for one account in one vault.',
             schema: schema.getEarnVaultPosition.Response,
           },
         }),
         summary: 'Get account position',
         tags: ['Earn'],
       }),
+      // Account holdings must read fresh immediately after a deposit or redemption.
       Cache.response<App.Environment>({
-        cacheControl: Cache.policies.state,
+        cacheControl: Cache.policies.noStore,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultPosition.Query),
-        name: 'tempo-api:earn-vault-positions:v1',
+        name: 'tempo-api:earn-vault-positions:v3',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -1023,25 +1936,123 @@ 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')
+        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 position = await c
-            .get('getClient')(chainId)
-            .earn.getPosition({ account: address, vault: vaultId })
+          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,
+              ...(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,
+            })
+          const zone = c.get('zones').get(chainId)
+          if (query.asOf && !zone) {
+            try {
+              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)
+          }
+          if (zone) return Response.upstream(c, cause)
           try {
             await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId })
           } catch (vaultCause) {
@@ -1098,7 +2109,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultEarnings.Query),
-        name: 'tempo-api:earn-vault-earnings:v3',
+        name: 'tempo-api:earn-vault-earnings:v4',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -1168,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.',
@@ -1185,10 +2204,22 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => vaultCacheKey(c, schema.getEarnVault.Query),
-        name: 'tempo-api:earn-vaults:v3',
+        name: 'tempo-api:earn-vaults:v4',
       }),
       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',
@@ -1240,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, {
@@ -1248,6 +2282,7 @@ export async function getVaultEarnings(
       blockNumber,
       chainId: options.chainId,
       period: options.period,
+      rewardTransfer,
       timestamp: block.timestamp,
       vault: options.vault,
     })
@@ -1268,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,
@@ -1291,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,
@@ -1304,10 +2341,20 @@ export async function getVaultEarnings(
   }
   if (history.incompleteCostBasis || externalShareTransfer)
     return { ...base, status: 'incomplete_cost_basis' as const }
-  if (history.pendingRedemption) return { ...base, status: 'pending_redemption' as const }
-  const lifetimeEarnings =
-    current.value + history.redeemed + history.withdrewExact + history.finalized - history.deposited
-  return { ...base, lifetimeEarnings: lifetimeEarnings.toString(), status: 'complete' as const }
+  const totalWithdrawn = history.redeemed + history.withdrewExact + history.finalized
+  const cashFlows = {
+    totalDeposited: history.deposited.toString(),
+    totalWithdrawn: totalWithdrawn.toString(),
+  }
+  if (history.pendingRedemption)
+    return { ...base, ...cashFlows, status: 'pending_redemption' as const }
+  const lifetimeEarnings = current.value + totalWithdrawn - history.deposited
+  return {
+    ...base,
+    ...cashFlows,
+    lifetimeEarnings: lifetimeEarnings.toString(),
+    status: 'complete' as const,
+  }
 }
 
 /** Reads cash-flow-adjusted earnings over a trailing indexed window. */
@@ -1329,6 +2376,7 @@ async function getWindowVaultEarnings(
     hasExternalShareTransfer(tidx, {
       account: options.account,
       blockNumber: options.blockNumber,
+      rewardTransfer: options.rewardTransfer,
       shareToken: current.shareToken,
       startBlockNumber,
       vault: options.vault,
@@ -1393,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. */
@@ -1453,6 +2503,62 @@ async function getLatestIndexedBlock(tidx: Tidx.Client) {
   return { number, timestamp }
 }
 
+/** Resolves the latest indexed block at or before a historical position timestamp. */
+async function getIndexedBlockAtOrBefore(tidx: Tidx.Client, asOf: string) {
+  const timestamp = new Date(asOf).toISOString().replace('T', ' ').replace(/Z$/, '')
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    // SAFETY: Zod restricts `asOf` to ISO 8601, so the formatted timestamp cannot alter SQL.
+    query: `
+      SELECT 'boundary' AS kind, num, timestamp
+      FROM (
+        SELECT num, timestamp
+        FROM blocks
+        WHERE timestamp <= '${timestamp}'
+        ORDER BY timestamp DESC, num DESC
+        LIMIT 1
+      )
+      UNION ALL
+      SELECT 'head' AS kind, num, timestamp
+      FROM (
+        SELECT num, timestamp
+        FROM blocks
+        ORDER BY num DESC
+        LIMIT 1
+      )
+    ` as string,
+  })
+  return parseIndexedBlockAtOrBefore({ asOf, rows: result.rows })
+}
+
+/** Decodes the indexed head and historical position boundary from TIDX rows. */
+export function parseIndexedBlockAtOrBefore(options: parseIndexedBlockAtOrBefore.Options) {
+  const head = options.rows.find((row) => row['kind'] === 'head')
+  if (!head) throw new Error('TIDX returned no indexed head for a historical Earn position.')
+  const headNumber = Value.toNumber(head['num'])
+  const headAt = Value.toIsoDateTime(head['timestamp'])
+  if (headNumber === undefined || headAt === undefined)
+    throw new Error('TIDX returned a malformed indexed head for a historical Earn position.')
+  const boundary = options.rows.find((row) => row['kind'] === 'boundary')
+  if (!boundary) throw new IndexedBlockNotFoundError(options.asOf)
+  const number = Value.toNumber(boundary['num'])
+  const indexedAt = Value.toIsoDateTime(boundary['timestamp'])
+  if (number === undefined || indexedAt === undefined)
+    throw new Error('TIDX returned a malformed historical Earn position boundary.')
+  if (Date.parse(headAt) < Date.parse(options.asOf)) throw new IndexedCoverageError(options.asOf)
+  return { number, timestamp: indexedAt }
+}
+
+export declare namespace parseIndexedBlockAtOrBefore {
+  /** Inputs returned by the historical boundary query. */
+  type Options = {
+    /** Requested historical observation timestamp. */
+    asOf: string
+    /** Indexed head and optional boundary rows. */
+    rows: readonly Record<string, unknown>[]
+  }
+}
+
 /** Resolves the last indexed block at or before a trailing-day boundary. */
 async function getWindowStartBlockNumber(
   tidx: Tidx.Client,
@@ -1596,6 +2702,7 @@ async function getVaultEarningsHistory(
   return {
     deposited: BigInt(deposited),
     finalized: BigInt(finalized),
+    incompleteCashFlows: venueDeposits > 0,
     incompleteCostBasis: transferredCancellations > 0 || venueDeposits > 0,
     pendingRedemption: pendingRedemptions > 0,
     redeemed: BigInt(redeemed),
@@ -1717,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,
@@ -1731,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 (
@@ -1739,6 +2880,7 @@ async function hasExternalShareTransfer(
                 "to" = '${options.account}'
                 AND "from" != '${zeroAddress}'
                 AND "from" != '${options.vault}'
+                AND NOT (${options.rewardTransfer})
               )
             )
         ) + (
@@ -1747,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}
@@ -1787,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}
@@ -1810,6 +2954,7 @@ async function hasExternalShareTransfer(
       redeemCancelledSignature,
       redeemedSignature,
       redeemRequestedSignature,
+      unspentReturnedSignature,
       withdrewExactSignature,
     ],
   })
@@ -1822,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>
@@ -1847,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
@@ -2009,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,
@@ -2017,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}'
@@ -2031,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}
@@ -2042,6 +3191,7 @@ async function getActiveCostBasis(tidx: Tidx.Client, options: getActiveCostBasis
       redeemCancelledSignature,
       redeemRequestedSignature,
       redeemedSignature,
+      unspentReturnedSignature,
       venueSharesDepositedSignature,
       withdrewExactSignature,
     ],
@@ -2091,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>
@@ -2194,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,
@@ -2204,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 =
@@ -2291,60 +3457,429 @@ export async function listVerifiedVaults(
     }
   }
 
-  const page = matches.slice(0, options.limit)
-  const discoveries = page.map(({ discovery }) => discovery)
-  const [apy, rates, tokens] = await Promise.all([
-    resolvePageApy(c, {
-      chainId: options.chainId,
-      include,
-      vaults: discoveries.map(({ vaultAddress }) => vaultAddress),
-      window: options['apy.window'],
-    }),
-    resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
-    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 }),
-      ),
-    ),
+  const page = matches.slice(0, options.limit)
+  const discoveries = page.map(({ discovery }) => discovery)
+  const [apy, rates, rewards, tokens] = await Promise.all([
+    resolvePageApy(c, {
+      chainId: options.chainId,
+      include,
+      vaults: discoveries.map(({ vaultAddress }) => vaultAddress),
+      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,
+          rewards: rewards?.get(match.discovery.vaultAddress),
+          snapshot,
+          tokens,
+        }),
+      ),
+    ),
+  )
+  const last = matches[options.limit - 1]
+  return {
+    data,
+    ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
+    nextCursor:
+      matches.length > options.limit && last ? Cursor.encode([last.record.vaultAddress]) : null,
+  }
+}
+
+export declare namespace listVerifiedVaults {
+  /** One verified vault and its current onchain state. */
+  type Match = {
+    discovery: EarnVaults.Discovery
+    record: RegistryRecord
+    zoneRoutes: readonly EarnVaults.ResolvedZoneRoute[]
+  }
+
+  /** Options for listing verified Earn vaults. */
+  type Options = z.output<typeof schema.getVerifiedEarnVaults.Query> & {
+    chainId: z.output<typeof Schema.ChainId>
+    /** FX rate oracle backing TVL valuation. */
+    oracle: FxOracle.Oracle
+  }
+}
+
+/** 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,
   )
-  const last = matches[options.limit - 1]
+  if (!route || !privateAsset || !portal.success) throw new EarnVaults.NotFoundError()
   return {
-    data,
-    ...(rates ? { meta: { valuation: Valuation.pricing(rates, options.oracle) } } : {}),
-    nextCursor:
-      matches.length > options.limit && last ? Cursor.encode([last.record.vaultAddress]) : null,
+    deploymentBlock: route.deploymentBlock,
+    portal: portal.data,
+    privateAsset,
+    shareToken: discovery.shareToken.address,
+    sourceChainId: zone.sourceId,
+    vaultAsset: discovery.assetToken.address,
   }
 }
 
-export declare namespace listVerifiedVaults {
-  /** One verified vault and its current onchain state. */
-  type Match = {
-    discovery: EarnVaults.Discovery
-    record: RegistryRecord
-    zoneRoutes: readonly EarnVaults.ResolvedZoneRoute[]
+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>
   }
 
-  /** Options for listing verified Earn vaults. */
-  type Options = z.output<typeof schema.getVerifiedEarnVaults.Query> & {
-    chainId: z.output<typeof Schema.ChainId>
-    /** FX rate oracle backing TVL valuation. */
-    oracle: FxOracle.Oracle
+  /** 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)
@@ -2383,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
           }
@@ -2403,7 +3939,18 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
   }
 
   const page = matches.slice(0, options.limit)
-  const [tokens, snapshot] = await Promise.all([
+  const indexedBlock =
+    !zone && page.length > 0 && options.include.includes('earnings')
+      ? await getLatestIndexedBlock(c.get('getTidx')(options.chainId))
+      : undefined
+  const [cashFlows, tokens, valueTokens, snapshot] = await Promise.all([
+    indexedBlock
+      ? getVaultLifetimeCashFlows(c.get('getTidx')(options.chainId), {
+          account: options.address,
+          blockNumber: indexedBlock.number,
+          vaults: page.map(({ vaultAddress }) => Schema.Address.parse(vaultAddress)),
+        })
+      : undefined,
     (async () => {
       const addresses = [
         ...new Set(page.flatMap(({ position }) => [position.assetToken, position.shareToken])),
@@ -2419,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,
@@ -2444,11 +3998,14 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
   return {
     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,
       }),
@@ -2461,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
   }
@@ -2481,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,
@@ -2502,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)
@@ -2528,35 +4085,19 @@ 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),
     shareToken,
     ...(options.denomination
@@ -2565,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,
   }
@@ -2577,19 +4119,174 @@ function serializePosition(options: serializePosition.Options) {
 declare namespace serializePosition {
   /** Values used to serialize one account position row. */
   type Options = {
+    /** Indexed lifetime cash flows, when requested. */
+    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
   }
 }
 
+/** Reads complete protocol cash flows for one account and a set of vaults. */
+export async function getVaultLifetimeCashFlows(
+  tidx: Tidx.Client,
+  options: getVaultLifetimeCashFlows.Options,
+) {
+  const vaults = [...new Set(options.vaults.map((vault) => vault.toLowerCase()))]
+  const cashFlows = new Map<string, getVaultLifetimeCashFlows.CashFlows>()
+  if (vaults.length === 0) return cashFlows
+  const addresses = vaults.map((vault) => `'${vault}'`).join(', ')
+  const seeds = vaults
+    .map(
+      (vault) => `
+        SELECT '${vault}' AS vault,
+               toUInt256(0) AS deposited_assets,
+               toUInt256(0) AS finalized_assets,
+               toUInt256(0) AS redeemed_assets,
+               toUInt64(0) AS venue_deposits,
+               toUInt256(0) AS withdrew_exact`,
+    )
+    .join('\n        UNION ALL')
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT vault,
+             toString(sum(deposited_assets)) AS deposited_assets,
+             toString(sum(finalized_assets)) AS finalized_assets,
+             toString(sum(redeemed_assets)) AS redeemed_assets,
+             sum(venue_deposits) AS venue_deposits,
+             toString(sum(withdrew_exact)) AS withdrew_exact
+      FROM (
+        ${seeds}
+        UNION ALL
+        SELECT address AS vault, sum(toUInt256(assets)) AS deposited_assets,
+               toUInt256(0) AS finalized_assets, toUInt256(0) AS redeemed_assets,
+               toUInt64(0) AS venue_deposits, toUInt256(0) AS withdrew_exact
+        FROM Deposited
+        WHERE address IN (${addresses})
+          AND receiver = '${options.account}'
+          AND block_num > ${beforeFirstBlockNumber}
+          AND block_num <= ${options.blockNumber}
+        GROUP BY address
+        UNION ALL
+        SELECT finalized.address AS vault, toUInt256(0) AS deposited_assets,
+               sum(toUInt256(finalized.assets)) AS finalized_assets,
+               toUInt256(0) AS redeemed_assets, toUInt64(0) AS venue_deposits,
+               toUInt256(0) AS withdrew_exact
+        FROM RedeemFinalized AS finalized
+        INNER JOIN RedeemRequested AS requested
+          ON requested.address = finalized.address
+          AND requested."requestId" = finalized."requestId"
+        WHERE finalized.address IN (${addresses})
+          AND requested.requester = '${options.account}'
+          AND finalized.block_num > ${beforeFirstBlockNumber}
+          AND finalized.block_num <= ${options.blockNumber}
+          AND requested.block_num <= ${options.blockNumber}
+        GROUP BY finalized.address
+        UNION ALL
+        SELECT address AS vault, toUInt256(0) AS deposited_assets,
+               toUInt256(0) AS finalized_assets, sum(toUInt256(assets)) AS redeemed_assets,
+               toUInt64(0) AS venue_deposits,
+               toUInt256(0) AS withdrew_exact
+        FROM Redeemed
+        WHERE address IN (${addresses})
+          AND caller = '${options.account}'
+          AND block_num > ${beforeFirstBlockNumber}
+          AND block_num <= ${options.blockNumber}
+        GROUP BY address
+        UNION ALL
+        SELECT address AS vault, toUInt256(0) AS deposited_assets,
+               toUInt256(0) AS finalized_assets, toUInt256(0) AS redeemed_assets,
+               count() AS venue_deposits, toUInt256(0) AS withdrew_exact
+        FROM VenueSharesDeposited
+        WHERE address IN (${addresses})
+          AND receiver = '${options.account}'
+          AND block_num > ${beforeFirstBlockNumber}
+          AND block_num <= ${options.blockNumber}
+        GROUP BY address
+        UNION ALL
+        SELECT address AS vault, toUInt256(0) AS deposited_assets,
+               toUInt256(0) AS finalized_assets, toUInt256(0) AS redeemed_assets,
+               toUInt64(0) AS venue_deposits, sum(toUInt256(assets)) AS withdrew_exact
+        FROM WithdrewExact
+        WHERE address IN (${addresses})
+          AND caller = '${options.account}'
+          AND block_num > ${beforeFirstBlockNumber}
+          AND block_num <= ${options.blockNumber}
+        GROUP BY address
+      ) AS histories
+      GROUP BY vault
+    ` as string,
+    signatures: [
+      depositedSignature,
+      redeemFinalizedSignature,
+      redeemRequestedSignature,
+      redeemedSignature,
+      venueSharesDepositedSignature,
+      withdrewExactSignature,
+    ],
+  })
+  for (const row of result.rows) {
+    const vault = Schema.Address.safeParse(Value.toText(row['vault']))
+    const deposited = Value.toIntegerString(row['deposited_assets'])
+    const finalized = Value.toIntegerString(row['finalized_assets'])
+    const redeemed = Value.toIntegerString(row['redeemed_assets'])
+    const venueDeposits = Value.toNumber(row['venue_deposits'])
+    const withdrewExact = Value.toIntegerString(row['withdrew_exact'])
+    if (
+      !vault.success ||
+      deposited === undefined ||
+      finalized === undefined ||
+      redeemed === undefined ||
+      venueDeposits === undefined ||
+      withdrewExact === undefined
+    )
+      throw new Error('TIDX returned invalid Earn lifetime cash flows.')
+    cashFlows.set(
+      vault.data.toLowerCase(),
+      venueDeposits > 0
+        ? { status: 'incomplete_history' }
+        : {
+            status: 'complete',
+            totalDeposited: deposited,
+            totalWithdrawn: (
+              BigInt(finalized) +
+              BigInt(redeemed) +
+              BigInt(withdrewExact)
+            ).toString(),
+          },
+    )
+  }
+  if (cashFlows.size !== vaults.length)
+    throw new Error('TIDX returned incomplete Earn lifetime cash flows.')
+  return cashFlows
+}
+
+export declare namespace getVaultLifetimeCashFlows {
+  /** Lifetime cash-flow state for one vault. */
+  type CashFlows = NonNullable<
+    z.output<typeof schema.getEarnAddressPositions.Response>['data'][number]['lifetimeCashFlows']
+  >
+
+  /** Indexed boundary and account whose protocol cash flows are read. */
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber: number
+    vaults: readonly z.output<typeof Schema.Address>[]
+  }
+}
+
 /** Renders a base-unit amount in the token's display currency and precision. */
 function valueFor(amount: bigint, token: z.output<typeof Tokens.schema.Token>) {
   return {
@@ -2624,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,
@@ -2632,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 {
@@ -2641,6 +4343,7 @@ export async function getVault(c: Context<App.Environment>, options: getVault.Op
         include,
         rates,
         record,
+        rewards,
         snapshot,
         tokens,
         zoneRoutes,
@@ -2718,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>
@@ -2803,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) {
@@ -2819,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>
@@ -2898,12 +4789,30 @@ async function resolveVault(c: Context<App.Environment>, options: resolveVault.O
         token: options.snapshot.byAddress.get(discovery.assetToken.address),
       })
     : undefined
+  const liquidityValue =
+    options.include.includes('tvl') && discovery.instantLiquidity !== null
+      ? Valuation.valuationFor({
+          amount: BigInt(discovery.instantLiquidity),
+          denomination: tvlDenomination,
+          rates: options.rates,
+          token: options.snapshot.byAddress.get(discovery.assetToken.address),
+        })
+      : undefined
   return serializeVault({
     apy: options.apy?.get(discovery.vaultAddress) ?? null,
     assetToken: getToken(options.tokens, discovery.assetToken.address),
     discovery,
     include: options.include,
+    instantLiquidityValue: liquidityValue
+      ? {
+          amount: core_Value.from(liquidityValue.amount, tvlDecimals).toString(),
+          currency: liquidityValue.currency,
+          decimals: tvlDecimals,
+          formatted: liquidityValue.amount,
+        }
+      : null,
     record,
+    rewards: options.rewards,
     shareToken: getToken(options.tokens, discovery.shareToken.address),
     tvl: valued
       ? {
@@ -2925,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[]
@@ -2939,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,
@@ -2952,6 +4894,9 @@ export function serializeVault(options: serializeVault.Options): z.output<typeof
     },
     id: vaultAddress,
     instantLiquidity: discovery.instantLiquidity,
+    ...(options.include.includes('tvl')
+      ? { instantLiquidityValue: options.instantLiquidityValue }
+      : {}),
     label: record?.label ?? options.shareToken.name,
     sharePrice:
       discovery.sharePrice === null
@@ -2995,8 +4940,12 @@ export declare namespace serializeVault {
     discovery: EarnVaults.Discovery
     /** Optional vault fields selected by the request. */
     include: z.output<typeof schema.getEarnVault.Query>['include']
+    /** USD value of instant liquidity, or null when unavailable; omitted unless `include` carries `tvl`. */
+    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`. */
@@ -3065,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)
@@ -3083,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({
@@ -3098,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")
       )
@@ -3195,3 +5148,36 @@ type RegistryRecord = Awaited<ReturnType<typeof core_EarnVaults.list>>[number]
 export class NotFoundError extends Error {
   override name = 'Earn.NotFoundError'
 }
+
+/** Thrown when a historical position boundary is not indexed. */
+class IndexedBlockNotFoundError extends Error {
+  override name = 'Earn.IndexedBlockNotFoundError'
+
+  constructor(asOf: string) {
+    super(`No indexed block exists at or before ${asOf}.`)
+  }
+}
+
+class IndexedCoverageError extends Error {
+  override name = 'Earn.IndexedCoverageError'
+
+  constructor(asOf: string) {
+    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.')
+  }
+}