tapimo 0.13.0 → 0.15.0

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

@@ -1,16 +1,22 @@
 import { Hono } from 'hono';
 import { Value as core_Value } from 'ox';
-import { ContractFunctionExecutionError, ContractFunctionRevertedError, ContractFunctionZeroDataError, zeroAddress, } from 'viem';
+import { Abis } from 'viem/tempo';
+import { ContractFunctionExecutionError, ContractFunctionRevertedError, ContractFunctionZeroDataError, isAddress, parseAbi, parseUnits, zeroAddress, } from 'viem';
 import * as z from 'zod/mini';
 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 * 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';
@@ -19,10 +25,31 @@ 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';
 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 = {
+    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)';
 const redeemedSignature = 'event Redeemed(address indexed caller,address indexed receiver,uint256 earnShares,uint256 assets)';
 const withdrewExactSignature = 'event WithdrewExact(address indexed caller,address indexed receiver,uint256 assets,uint256 earnSharesBurned)';
@@ -30,17 +57,28 @@ const redeemFinalizedSignature = 'event RedeemFinalized(bytes32 indexed requestI
 const redeemCancelledSignature = 'event RedeemCancelled(bytes32 indexed requestId,address indexed receiver,uint256 earnShares)';
 const redeemRequestedSignature = 'event RedeemRequested(bytes32 indexed requestId,address indexed requester,address indexed receiver,uint256 earnShares)';
 const venueSharesDepositedSignature = 'event VenueSharesDeposited(address indexed caller,address indexed receiver,uint256 requestedVenueShares,uint256 receivedVenueShares,uint256 earnShares)';
+const 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;
 /** Vault TVL is reported in USD only; the API exposes no denomination parameter. */
 const tvlDenomination = 'USD';
 /** `Valuation.valuationFor` floors to 6 dp, so 6 is the precision a valued amount carries. */
 const tvlDecimals = 6;
+function toRewardEligibilityAssociation(record) {
+    return {
+        ...record,
+        id: `${record.vaultAddress}-${record.walletAddress}`,
+    };
+}
 /** Returns the smallest useful live-discovery batch. */
 export function discoveryBatchLimit(options) {
     const needed = options.limit + 1 - options.matches;
@@ -54,6 +92,78 @@ export function hasZoneAccess(options) {
 /** Zod schemas owned by the public Earn-vault resource. */
 export var schema;
 (function (schema) {
+    /** Schemas for the registerRewardEligibility operation. */
+    let registerRewardEligibility;
+    (function (registerRewardEligibility) {
+        /** Wallet and vault association to register for reward eligibility. */
+        registerRewardEligibility.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. */
+        registerRewardEligibility.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. */
+        registerRewardEligibility.Response = z
+            .strictObject({
+            association: registerRewardEligibility.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.'));
+    })(registerRewardEligibility = schema.registerRewardEligibility || (schema.registerRewardEligibility = {}));
+    /** Schemas for the getRewardEligibility operation. */
+    let getRewardEligibility;
+    (function (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. */
+        getRewardEligibility.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. */
+        getRewardEligibility.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.'));
+    })(getRewardEligibility = schema.getRewardEligibility || (schema.getRewardEligibility = {}));
     const capability = z
         .enum([
         'asyncRedeem',
@@ -69,57 +179,97 @@ export var schema;
     const engineType = z
         .enum(['erc4626', 'veda'])
         .check(z.describe('Inferred vault engine type.'), z.meta({ examples: ['erc4626'] }));
-    const engine = Schema.describe(z.strictObject({
-        address: Schema.Address.check(z.describe('Current vault engine contract address.'), z.meta({ examples: ['0xd85fc943333a6cd7c0e3391acd54fc4e572f0baf'] })),
+    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: ['0xa8b4f0e69cd4b0e56b676343f02acd8c3b355322'] })))
+            .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.');
+    }), 'Current vault engine.'), 'EarnVaultEngine');
     const include = z
         .enum(['access', 'apy', 'capabilities', 'token.logoUri', 'tvl', 'zone', 'zones'])
         .check(z.describe('Optional vault fields to embed via `include`.'));
     const includeQuery = Schema.includeQuery(include, 'Comma-separated vault fields to include, such as `apy,tvl`.');
+    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
         .enum(['access', 'capabilities', 'token.logoUri', 'zone', 'zones'])
         .check(z.describe('Optional vault fields to embed via `include`.'));
     const baseIncludeQuery = Schema.includeQuery(baseInclude, 'Comma-separated vault fields to include, such as `access,zone`.');
-    const zone = z
+    const zone = OpenApi.component(z
         .strictObject({
-        chainId: Schema.ChainId.check(z.describe('Private Zone chain id.'), z.meta({ examples: [1424310003] })),
+        chainId: Schema.ChainId.check(z.describe('Private Zone chain id.'), z.meta({ examples: [421700001] })),
         inputTokens: z
             .array(Schema.Address)
-            .check(z.describe('Tokens accepted by private deposits.'), z.meta({ examples: [['0x20c0000000000000000000002139993d5f625d59']] })),
+            .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-moderato-internal'] })),
+            .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: [['0x20c0000000000000000000002139993d5f625d59']] })),
+            .check(z.describe('Tokens supported by private redemptions.'), z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] })),
     })
-        .check(z.describe('Private Zone route configured for a verified vault.'));
-    const zoneRoute = z
+        .check(z.describe('Private Zone route configured for a verified vault.')), 'EarnVaultZone');
+    const zoneRoute = OpenApi.component(z
         .strictObject({
-        chainId: Schema.ChainId.check(z.describe('Private Zone chain id.'), z.meta({ examples: [1424310003] })),
+        chainId: Schema.ChainId.check(z.describe('Private Zone chain id.'), z.meta({ examples: [421700001] })),
         deploymentBlock: z
             .number()
-            .check(z.int(), z.nonnegative(), z.describe('Parent-chain block that deployed the Earn router.'), z.meta({ examples: [31730087] })),
-        earnRouter: Schema.Address.check(z.describe('Parent-chain router for this Zone and Earn vault.'), z.meta({ examples: ['0xebedc74ffeead186acc6cac05eb82fb9e093a7c7'] })),
+            .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'] })),
         inputTokens: z
             .array(Schema.Address)
-            .check(z.describe('Tokens accepted by private deposits.'), z.meta({ examples: [['0x20c0000000000000000000002139993d5f625d59']] })),
+            .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-moderato-internal'] })),
+            .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: [['0x20c0000000000000000000002139993d5f625d59']] })),
+            .check(z.describe('Tokens returned by private redemptions.'), z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] })),
     })
-        .check(z.describe('Verified Earn route through one private Zone.'));
+        .check(z.describe('Verified Earn route through one private Zone.')), 'EarnVaultZoneRoute');
     const value = z.strictObject({
         amount: Schema.DecimalString.check(z.describe('Value in base units at `decimals` precision.'), z.meta({ examples: ['125288750000'] })),
         currency: z
@@ -137,33 +287,60 @@ export var schema;
             .optional(EarnVaults.schema.Discovery.shape.access)
             .check(z.describe('Vault share-token access, when requested.')),
         apy: z
-            .optional(z.nullable(EarnRates.schema.Apy))
-            .check(z.describe('Annualized share-price growth over the selected window, when requested via `include=apy` or by selecting `apy.window`. Null when the rate could not be measured: the vault predates the window, a boundary or historical quote is unavailable, the engine changed inside the window, or the growth is too extreme to annualize as a ratio.')),
-        assetToken: Tokens.schema.Token.check(z.describe('Asset accepted by the vault.')),
+            .optional(z.nullable(apy))
+            .check(z.describe('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.'), 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.')),
         description: z
             .nullable(z.string())
-            .check(z.describe('Curated vault description, or null when the vault is not verified.'), z.meta({ examples: ['Bridge test PATHUSD deposited into Tempo Earn.'] })),
+            .check(z.describe('Curated vault description, or null when the vault is not verified.'), 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'] })),
+        id: Schema.Address.check(z.describe('Stable vault id, equal to the lowercase vault address.'), 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(z.describe('Assets returned for one whole earn share, in the asset display currency, or null when the engine cannot quote an exit.')),
-        shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
+        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'] })),
+            .check(z.describe('Curated URL slug, or null when the vault is not verified.'), z.meta({ examples: ['deelusd-earn'] })),
         state: EarnVaults.schema.Discovery.shape.state,
         tvl: z
             .optional(z.nullable(value))
             .check(z.describe('Total assets valued in USD, when requested via `include=tvl`, or null when the asset has no priced display currency.')),
-        vaultAddress: Schema.Address.check(z.describe('Earn vault contract address.'), z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] })),
+        vaultAddress: Schema.Address.check(z.describe('Earn vault contract address.'), z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] })),
         verified: z
             .boolean()
             .check(z.describe('Whether this vault is in the curated earn registry.'), z.meta({ examples: [true] })),
@@ -174,21 +351,21 @@ export var 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'],
                     },
                 ],
             ],
         })),
     });
     /** One compatible Earn vault resolved from current chain state. */
-    schema.Vault = Schema.describe(vault, 'A compatible earn vault resolved from chain state.');
+    schema.Vault = OpenApi.component(Schema.describe(vault, 'A compatible earn vault resolved from chain state.'), 'EarnVault');
     /** One registry-curated Earn vault. */
-    schema.VerifiedVault = Schema.describe(z.extend(vault, {
+    schema.VerifiedVault = OpenApi.component(Schema.describe(z.extend(vault, {
         engine: z.extend(engine, { type: engineType }),
         slug: z
             .string()
@@ -196,33 +373,98 @@ export var schema;
         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.');
+    }), 'A registry-curated earn vault resolved from chain state.'), 'VerifiedEarnVault');
     const position = z.strictObject({
         account: Schema.Address.check(z.describe('Account whose earn position was read.'), z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] })),
-        assetAllowance: Schema.DecimalString.check(z.describe('Assets the vault may spend from this account, in asset base units.'), z.meta({ examples: ['0'] })),
-        assetBalance: Schema.DecimalString.check(z.describe('Assets this account currently holds, in asset base units.'), z.meta({ examples: ['250000000'] })),
-        assetToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(z.describe('TIP-20 asset token accepted by the vault.')),
+        assetAllowance: Schema.DecimalString.check(z.describe('Assets the vault may spend from a direct account, in asset base units. Always zero for Zone-routed positions, which use Zone withdrawals instead of approvals.'), z.meta({ examples: ['0'] })),
+        assetBalance: Schema.DecimalString.check(z.describe('Assets held by this account at the observation block, in asset base units.'), z.meta({ examples: ['250000000'] })),
+        assetToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(z.describe('TIP-20 asset token accepted by the vault or its selected Zone route.')),
+        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.meta({ examples: ['0'] })),
-        shareBalance: Schema.DecimalString.check(z.describe('Earn shares this account currently holds, in share base units.'), z.meta({ examples: ['99500000'] })),
+        shareAllowance: Schema.DecimalString.check(z.describe('Earn shares the vault may spend from a direct account, in share base units. Always zero for Zone-routed positions, which use Zone withdrawals instead of approvals.'), z.meta({ examples: ['0'] })),
+        shareBalance: Schema.DecimalString.check(z.describe('Earn shares held by this account at the observation block, in share base units.'), z.meta({ examples: ['99500000'] })),
         shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(z.describe('TIP-20 token representing earn shares.')),
-        value: Schema.DecimalString.check(z.describe('Current asset value of this account’s earn shares, including fees, in asset base units.'), z.meta({ examples: ['100000000'] })),
+        value: Schema.DecimalString.check(z.describe('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.')),
+    const positionApy = z
+        .strictObject({
+        breakdown: z
+            .array(z
+            .strictObject({
+            assetAmount: z
+                .strictObject({
+                baseUnits: Schema.DecimalString.check(z.describe('Position amount in vault asset base units.'), z.meta({ examples: ['25000000000'] })),
+                decimals: z
+                    .number()
+                    .check(z.int(), z.nonnegative(), z.describe('Vault asset decimal places.'), z.meta({ examples: [6] })),
+                formatted: z
+                    .string()
+                    .check(z.regex(/^\d+(\.\d+)?$/), z.describe('Position amount rendered in whole vault asset units.'), z.meta({ examples: ['25000'] })),
+            })
+                .check(z.describe('Vault asset amount receiving this annual rate.'), z.meta({
+                examples: [{ baseUnits: '25000000000', decimals: 6, formatted: '25000' }],
+            })),
+            net: EarnRates.schema.Apy.shape.net.check(z.describe('Annual rate applied to this position amount.'), z.meta({ examples: ['0.07'] })),
+            type: z
+                .enum(['base', 'boost'])
+                .check(z.describe('Base vault yield or qualified depositor boost.'), z.meta({ examples: ['boost'] })),
+        })
+            .check(z.describe('Position component receiving one annual rate.')))
+            .check(z.describe('Position amounts grouped by the annual rate they receive.'), z.meta({
+            examples: [
+                [
+                    {
+                        assetAmount: {
+                            baseUnits: '25000000000',
+                            decimals: 6,
+                            formatted: '25000',
+                        },
+                        net: '0.07',
+                        type: 'boost',
+                    },
+                ],
+            ],
+        })),
+        net: EarnRates.schema.Apy.shape.net.check(z.describe('Balance-weighted annual rate for this wallet position.'), z.meta({ examples: ['0.0616666666666667'] })),
+    })
+        .check(z.describe('Wallet-specific effective APY combining live position amounts with qualification from the latest delivered reward snapshot.'));
+    const lifetimeCashFlows = z.union([
+        z.strictObject({
+            status: z
+                .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.')),
-        id: Schema.Address.check(z.describe('Stable resource ID for this position, equal to the vault address.'), z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] })),
+        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.')),
-        vaultAddress: Schema.Address.check(z.describe('Earn vault contract address holding this position.'), z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] })),
+        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(z.describe('Account whose vault earnings were calculated.'), z.meta({ examples: ['0x68f94cfca22e5969c0553bbeab00a2acde88939b'] })),
         assetToken: Schema.TokenAddress.check(z.describe('TIP-20 asset token accepted by the vault.'), z.meta({ examples: ['0x20c000000000000000000000ff04042ee92fd449'] })),
@@ -237,6 +479,8 @@ export var schema;
             lifetimeEarnings: z
                 .string()
                 .check(z.regex(/^-?\d+$/), z.describe('Current share value plus completed redemptions, exact withdrawals, and finalized async assets, minus asset deposits, at the latest indexed block.'), z.meta({ examples: ['0'] })),
+            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(z.describe('Returns lifetime net asset earnings.'), z.meta({ examples: ['lifetime'] })),
@@ -274,12 +518,22 @@ export var schema;
         }),
         z.extend(earningsBase, {
             period: z
-                .enum(['30d', 'lifetime'])
-                .check(z.describe('Earnings period with an unresolved async redemption.'), z.meta({ examples: ['lifetime'] })),
+                .literal('30d')
+                .check(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
+                .literal('pending_redemption')
+                .check(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.')),
+        }),
     ]);
     const meta = z
         .object({
@@ -314,7 +568,7 @@ export var schema;
         /** Query parameters for all compatible deployed Earn vaults. */
         getEarnVaults.Query = collectionQuery;
         /** Paginated list of compatible deployed Earn vaults. */
-        getEarnVaults.Response = z
+        getEarnVaults.Response = OpenApi.component(z
             .strictObject({
             data: z
                 .array(schema.Vault)
@@ -322,7 +576,7 @@ export var schema;
             meta: z.optional(meta),
             nextCursor: Schema.NextCursor,
         })
-            .check(z.describe('A page of compatible deployed earn vaults.'));
+            .check(z.describe('A page of compatible deployed earn vaults.')), 'EarnVaultList');
     })(getEarnVaults = schema.getEarnVaults || (schema.getEarnVaults = {}));
     /** Schemas for the getVerifiedEarnVaults operation. */
     let getVerifiedEarnVaults;
@@ -332,7 +586,7 @@ export var schema;
         /** Query parameters for registry-curated Earn vaults. */
         getVerifiedEarnVaults.Query = collectionQuery;
         /** Paginated list of registry-curated Earn vaults. */
-        getVerifiedEarnVaults.Response = z
+        getVerifiedEarnVaults.Response = OpenApi.component(z
             .strictObject({
             data: z
                 .array(schema.VerifiedVault)
@@ -340,7 +594,7 @@ export var schema;
             meta: z.optional(meta),
             nextCursor: Schema.NextCursor,
         })
-            .check(z.describe('A page of registry-curated earn vaults.'));
+            .check(z.describe('A page of registry-curated earn vaults.')), 'VerifiedEarnVaultList');
     })(getVerifiedEarnVaults = schema.getVerifiedEarnVaults || (schema.getVerifiedEarnVaults = {}));
     /** Schemas for the getEarnAddressPositions operation. */
     let getEarnAddressPositions;
@@ -356,6 +610,7 @@ export var 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('When present, include each position’s nominal value in this denomination. ' +
                 'Case-insensitive and must be priced by the configured FX oracle.')),
@@ -374,7 +629,7 @@ export var schema;
         })
             .check(z.describe('Page-level valuation rate provenance.'));
         /** Paginated list of the account's earn vault positions. */
-        getEarnAddressPositions.Response = z
+        getEarnAddressPositions.Response = OpenApi.component(z
             .strictObject({
             data: z
                 .array(addressPosition)
@@ -382,7 +637,7 @@ export var schema;
             meta: z.optional(getEarnAddressPositions.Meta),
             nextCursor: Schema.NextCursor,
         })
-            .check(z.describe('A page of the account’s earn vault positions.'));
+            .check(z.describe('A page of the account’s earn vault positions.')), 'EarnAddressPositionList');
     })(getEarnAddressPositions = schema.getEarnAddressPositions || (schema.getEarnAddressPositions = {}));
     /** Schemas for the getEarnVault operation. */
     let getEarnVault;
@@ -400,24 +655,145 @@ export var schema;
             .extend(vaultSelector, { 'apy.window': EarnRates.schema.Window })
             .check(z.describe('Query parameters selecting one earn vault.'));
         /** One compatible Earn vault resolved directly from current chain state. */
-        getEarnVault.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.');
+        getEarnVault.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');
     })(getEarnVault = schema.getEarnVault || (schema.getEarnVault = {}));
+    /** Schemas for the getEarnVaultSharePrices operation. */
+    let getEarnVaultSharePrices;
+    (function (getEarnVaultSharePrices) {
+        const timestamp = z.iso.datetime({ offset: true });
+        /** Path parameters identifying one Earn vault. */
+        getEarnVaultSharePrices.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. */
+        getEarnVaultSharePrices.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. */
+        getEarnVaultSharePrices.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');
+    })(getEarnVaultSharePrices = schema.getEarnVaultSharePrices || (schema.getEarnVaultSharePrices = {}));
     /** Schemas for the getEarnVaultPosition operation. */
     let getEarnVaultPosition;
     (function (getEarnVaultPosition) {
+        const asOf = z.iso.datetime({ offset: true });
         /** Path parameters identifying the Earn vault and account. */
         getEarnVaultPosition.Params = z
             .strictObject({
             address: Schema.Address.check(z.describe('Account whose earn position to read.')),
-            vaultId: Schema.address('0xdb48b00fb28d9a8db881fcd671c3fb1bf8c486b6').check(z.describe('Earn vault contract address.')),
+            vaultId: Schema.address('0x4f94590b636f5878bce585e82379de81e1ec174f').check(z.describe('Earn vault contract address.')),
         })
             .check(z.describe('Path parameters identifying an earn vault position.'));
         /** Query parameters selecting the chain containing the vault. */
         getEarnVaultPosition.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. */
-        getEarnVaultPosition.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.'));
+        getEarnVaultPosition.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');
     })(getEarnVaultPosition = schema.getEarnVaultPosition || (schema.getEarnVaultPosition = {}));
     /** Schemas for the getEarnVaultEarnings operation. */
     let getEarnVaultEarnings;
@@ -437,13 +813,98 @@ export var schema;
         })
             .check(z.describe('Query parameters selecting an earn vault account.'));
         /** Earnings for one account and period in one Earn vault. */
-        getEarnVaultEarnings.Response = Schema.describe(earnings, 'Indexed asset value and cost-basis-aware earnings for an account in one earn vault.');
+        getEarnVaultEarnings.Response = OpenApi.component(Schema.describe(earnings, 'Indexed asset value and cost-basis-aware earnings for an account in one earn vault.'), 'EarnVaultEarnings');
     })(getEarnVaultEarnings = schema.getEarnVaultEarnings || (schema.getEarnVaultEarnings = {}));
 })(schema || (schema = {}));
 /** Creates the public Earn-vault handlers. */
 export function earn(options = {}) {
     const oracle = options.fx?.oracle ?? FxOracle.ecb();
     return new Hono()
+        .post('/v1/earn/rewards/eligibility', Auth.policy({ apiKey: { scopes: [Scope.wildcard] } }), OpenApi.validate('json', schema.registerRewardEligibility.Body, {
+        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 }), OpenApi.validate('query', schema.getEarnVaults.Query, {
         code: 'query_invalid',
         message: 'Invalid query parameters',
@@ -451,7 +912,12 @@ export function earn(options = {}) {
         description: 'Lists compatible earn vaults discovered from deployment events and resolved from current chain state.',
         operationId: 'getEarnVaults',
         responses: OpenApi.responses({
-            errors: { 502: 'Could not read earn deployment or vault data.' },
+            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,
@@ -465,10 +931,22 @@ export function earn(options = {}) {
     Cache.response({
         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',
@@ -491,7 +969,12 @@ export function earn(options = {}) {
         description: 'Lists registry-curated earn vaults after resolving their current onchain configuration.',
         operationId: 'getVerifiedEarnVaults',
         responses: OpenApi.responses({
-            errors: { 502: 'Could not read curated earn registry or vault data.' },
+            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,
@@ -502,10 +985,22 @@ export function earn(options = {}) {
     }), Cache.response({
         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',
@@ -514,7 +1009,11 @@ export function earn(options = {}) {
         const query = c.req.valid('query');
         try {
             const chainId = query.chainId ?? c.get('chainId');
-            const data = await listVerifiedVaults(c, { ...query, chainId, oracle });
+            const data = await listVerifiedVaults(c, {
+                ...query,
+                chainId,
+                oracle,
+            });
             return c.json(Response.validated(schema.getVerifiedEarnVaults.Response, data), 200);
         }
         catch (cause) {
@@ -528,7 +1027,7 @@ export function earn(options = {}) {
         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.',
+        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: {
@@ -555,7 +1054,7 @@ export function earn(options = {}) {
     Cache.response({
         cacheControl: Cache.policies.noStore,
         key: (c) => Cache.urlKey(c, schema.getEarnAddressPositions.Query),
-        name: 'tempo-api:earn-address-positions:v1',
+        name: 'tempo-api:earn-address-positions:v2',
     }), async (c) => {
         if (Auth.narrowAccess)
             return Auth.paidAccessError(c);
@@ -591,6 +1090,101 @@ export function earn(options = {}) {
         catch (cause) {
             if (cause instanceof Valuation.UnsupportedDenominationError)
                 return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 });
+            if (cause instanceof ZoneEarningsUnsupportedError)
+                return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 });
+            return Response.upstream(c, cause);
+        }
+    })
+        .get('/v1/earn/vaults/:vaultId/share-prices', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('param', schema.getEarnVaultSharePrices.Params, {
+        code: 'vault_id_invalid',
+        message: 'Invalid vault id',
+    }), OpenApi.validate('query', schema.getEarnVaultSharePrices.Query, {
+        code: 'query_invalid',
+        message: 'Invalid query parameters',
+    }), OpenApi.describeRoute({
+        description: 'Lists daily historical share prices for one earn vault.',
+        operationId: 'getEarnVaultSharePrices',
+        responses: OpenApi.responses({
+            errors: {
+                400: {
+                    codes: [
+                        'chain_id_invalid',
+                        'chain_id_unsupported',
+                        'query_invalid',
+                        'vault_id_invalid',
+                    ],
+                },
+                404: {
+                    codes: ['earn_vault_not_found'],
+                    description: 'No compatible earn vault was found at the supplied vault address.',
+                },
+                502: 'Could not read historical earn vault share prices.',
+            },
+            success: {
+                description: 'Daily historical share prices for one earn vault.',
+                schema: schema.getEarnVaultSharePrices.Response,
+            },
+        }),
+        summary: 'List share prices',
+        tags: ['Earn'],
+    }), Cache.response({
+        cacheControl: Cache.policies.state,
+        key: (c) => Cache.urlKey(c, schema.getEarnVaultSharePrices.Query),
+        name: 'tempo-api:earn-vault-share-prices:v1',
+    }), async (c) => {
+        if (Auth.narrowAccess)
+            return Auth.paidAccessError(c);
+        if (OpenApi.narrowValidation)
+            return Response.error(c, {
+                code: 'chain_id_invalid',
+                message: 'Invalid chain id',
+                status: 400,
+            });
+        if (OpenApi.narrowValidation)
+            return Response.error(c, {
+                code: 'chain_id_unsupported',
+                message: 'Unsupported chain id',
+                status: 400,
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'vault_id_invalid',
+                message: 'Invalid vault id',
+            });
+        if (OpenApi.narrowValidation)
+            return OpenApi.validationError(c, {
+                code: 'query_invalid',
+                message: 'Invalid query parameters',
+            });
+        const { vaultId } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const chainId = query.chainId ?? c.get('chainId');
+        try {
+            const discovery = await resolveSharePriceVaultDiscovery(c, {
+                chainId,
+                vaultAddress: vaultId,
+            });
+            if (!discovery)
+                return Response.error(c, {
+                    code: 'earn_vault_not_found',
+                    message: 'Earn vault not found',
+                    status: 404,
+                });
+            const data = await getVaultSharePrices(c, {
+                ...query,
+                chainId,
+                discovery,
+                vault: vaultId,
+            });
+            return c.json(Response.validated(schema.getEarnVaultSharePrices.Response, { data }), 200);
+        }
+        catch (cause) {
+            if (cause instanceof EarnSharePrices.IndexedBlockNotFoundError ||
+                cause instanceof EarnSharePrices.IndexedCoverageError)
+                return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 });
+            const failure = sharePriceProviderFailure({ cause, chainId });
+            if (failure)
+                c.set('providerFailure', failure);
             return Response.upstream(c, cause);
         }
     })
@@ -601,7 +1195,7 @@ export function earn(options = {}) {
         code: 'query_invalid',
         message: 'Invalid query parameters',
     }), OpenApi.describeRoute({
-        description: 'Gets an account’s asset and earn-share balances, allowances, and current asset value for one earn vault.',
+        description: '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: {
@@ -620,16 +1214,18 @@ export function 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'],
-    }), Cache.response({
-        cacheControl: Cache.policies.state,
+    }), 
+    // Account holdings must read fresh immediately after a deposit or redemption.
+    Cache.response({
+        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);
@@ -658,23 +1254,122 @@ export function 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 });
             }
@@ -724,7 +1419,7 @@ export function earn(options = {}) {
     }), Cache.response({
         cacheControl: Cache.policies.state,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultEarnings.Query),
-        name: 'tempo-api:earn-vault-earnings:v3',
+        name: 'tempo-api:earn-vault-earnings:v4',
     }), async (c) => {
         if (Auth.narrowAccess)
             return Auth.paidAccessError(c);
@@ -788,6 +1483,14 @@ export function 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.',
@@ -804,10 +1507,22 @@ export function earn(options = {}) {
     }), Cache.response({
         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',
@@ -846,7 +1561,10 @@ export function earn(options = {}) {
 export async function getVaultEarnings(c, options) {
     const client = c.get('getClient')(options.chainId);
     const tidx = c.get('getTidx')(options.chainId);
-    const block = 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, {
@@ -854,6 +1572,7 @@ export async function getVaultEarnings(c, options) {
             blockNumber,
             chainId: options.chainId,
             period: options.period,
+            rewardTransfer,
             timestamp: block.timestamp,
             vault: options.vault,
         });
@@ -874,6 +1593,7 @@ export async function getVaultEarnings(c, options) {
         const activeCostBasis = await getActiveCostBasis(tidx, {
             account: options.account,
             blockNumber,
+            rewardTransfer,
             shareBalance: current.shareBalance,
             shareToken: current.shareToken,
             vault: options.vault,
@@ -898,6 +1618,7 @@ export async function getVaultEarnings(c, options) {
     const externalShareTransfer = await hasExternalShareTransfer(tidx, {
         account: options.account,
         blockNumber,
+        rewardTransfer,
         shareToken: current.shareToken,
         startBlockNumber: beforeFirstBlockNumber,
         vault: options.vault,
@@ -911,10 +1632,20 @@ export async function getVaultEarnings(c, options) {
     };
     if (history.incompleteCostBasis || externalShareTransfer)
         return { ...base, status: 'incomplete_cost_basis' };
+    const totalWithdrawn = history.redeemed + history.withdrewExact + history.finalized;
+    const cashFlows = {
+        totalDeposited: history.deposited.toString(),
+        totalWithdrawn: totalWithdrawn.toString(),
+    };
     if (history.pendingRedemption)
-        return { ...base, status: 'pending_redemption' };
-    const lifetimeEarnings = current.value + history.redeemed + history.withdrewExact + history.finalized - history.deposited;
-    return { ...base, lifetimeEarnings: lifetimeEarnings.toString(), status: 'complete' };
+        return { ...base, ...cashFlows, status: 'pending_redemption' };
+    const lifetimeEarnings = current.value + totalWithdrawn - history.deposited;
+    return {
+        ...base,
+        ...cashFlows,
+        lifetimeEarnings: lifetimeEarnings.toString(),
+        status: 'complete',
+    };
 }
 /** Reads cash-flow-adjusted earnings over a trailing indexed window. */
 async function getWindowVaultEarnings(c, options) {
@@ -932,6 +1663,7 @@ async function getWindowVaultEarnings(c, options) {
         hasExternalShareTransfer(tidx, {
             account: options.account,
             blockNumber: options.blockNumber,
+            rewardTransfer: options.rewardTransfer,
             shareToken: current.shareToken,
             startBlockNumber,
             vault: options.vault,
@@ -1003,6 +1735,53 @@ async function getLatestIndexedBlock(tidx) {
         throw new Error('TIDX returned no indexed block.');
     return { number, timestamp };
 }
+/** Resolves the latest indexed block at or before a historical position timestamp. */
+async function getIndexedBlockAtOrBefore(tidx, asOf) {
+    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
+      )
+    `,
+    });
+    return parseIndexedBlockAtOrBefore({ asOf, rows: result.rows });
+}
+/** Decodes the indexed head and historical position boundary from TIDX rows. */
+export function 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 };
+}
 /** Resolves the last indexed block at or before a trailing-day boundary. */
 async function getWindowStartBlockNumber(tidx, options) {
     const cutoff = new Date(Date.parse(options.timestamp) - Ttl.days(options.days)).toISOString();
@@ -1128,6 +1907,7 @@ async function getVaultEarningsHistory(tidx, options) {
     return {
         deposited: BigInt(deposited),
         finalized: BigInt(finalized),
+        incompleteCashFlows: venueDeposits > 0,
         incompleteCostBasis: transferredCancellations > 0 || venueDeposits > 0,
         pendingRedemption: pendingRedemptions > 0,
         redeemed: BigInt(redeemed),
@@ -1221,6 +2001,36 @@ async function getWindowShareState(tidx, options) {
         startShares: receivedStartValue - sentStartValue,
     };
 }
+/** Builds a share-transfer predicate for the vault's verified reward distributors. */
+async function getRewardTransferPredicate(c, options) {
+    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, options) {
     // Vault exits pull shares into the vault before burning. Reconcile counts by transaction and amount so unmatched direct sends remain external.
@@ -1232,6 +2042,7 @@ async function hasExternalShareTransfer(tidx, options) {
           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 (
@@ -1240,6 +2051,7 @@ async function hasExternalShareTransfer(tidx, options) {
                 "to" = '${options.account}'
                 AND "from" != '${zeroAddress}'
                 AND "from" != '${options.vault}'
+                AND NOT (${options.rewardTransfer})
               )
             )
         ) + (
@@ -1248,6 +2060,7 @@ async function hasExternalShareTransfer(tidx, options) {
             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}
@@ -1288,6 +2101,7 @@ async function hasExternalShareTransfer(tidx, options) {
             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}
@@ -1311,6 +2125,7 @@ async function hasExternalShareTransfer(tidx, options) {
             redeemCancelledSignature,
             redeemedSignature,
             redeemRequestedSignature,
+            unspentReturnedSignature,
             withdrewExactSignature,
         ],
     });
@@ -1340,6 +2155,8 @@ export function calculateActiveCostBasis(options) {
         return { costBasis: removed };
     };
     for (const action of options.actions) {
+        if (action.shares === 0n)
+            continue;
         if (action.kind === 'deposit') {
             if (costBasis !== undefined)
                 costBasis += action.assets;
@@ -1456,7 +2273,7 @@ async function getActiveCostBasis(tidx, options) {
           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,
@@ -1464,6 +2281,7 @@ async function getActiveCostBasis(tidx, options) {
           '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}'
@@ -1478,6 +2296,7 @@ async function getActiveCostBasis(tidx, options) {
           '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}
@@ -1489,6 +2308,7 @@ async function getActiveCostBasis(tidx, options) {
             redeemCancelledSignature,
             redeemRequestedSignature,
             redeemedSignature,
+            unspentReturnedSignature,
             venueSharesDepositedSignature,
             withdrewExactSignature,
         ],
@@ -1631,7 +2451,7 @@ export async function listVaults(c, options) {
     const missingApyVaults = include.includes('apy')
         ? discoveries.flatMap(({ vaultAddress }) => 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,
@@ -1641,12 +2461,25 @@ export async function listVaults(c, options) {
             })
             : 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 })));
+    const data = await Promise.all(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 = matches.length > options.limit ? last?.position : hasMore ? position : undefined;
     return {
@@ -1699,7 +2532,7 @@ export async function listVerifiedVaults(c, options) {
     }
     const page = matches.slice(0, options.limit);
     const discoveries = page.map(({ discovery }) => discovery);
-    const [apy, rates, tokens] = await Promise.all([
+    const [apy, rates, rewards, tokens] = await Promise.all([
         resolvePageApy(c, {
             chainId: options.chainId,
             include,
@@ -1707,9 +2540,22 @@ export async function listVerifiedVaults(c, options) {
             window: options['apy.window'],
         }),
         resolvePageRates(c, { discoveries, include, oracle: options.oracle, snapshot }),
+        resolvePageRewards(c, {
+            chainId: options.chainId,
+            include,
+            vaults: discoveries.map(({ vaultAddress }) => vaultAddress),
+        }),
         resolvePageTokens(c, { chainId: options.chainId, discoveries, include, snapshot }),
     ]);
-    const data = await Promise.all(page.map(async (match) => Response.validated(schema.VerifiedVault, await resolveVault(c, { ...match, apy, include, rates, snapshot, tokens }))));
+    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,
@@ -1717,13 +2563,239 @@ export async function listVerifiedVaults(c, options) {
         nextCursor: matches.length > options.limit && last ? Cursor.encode([last.record.vaultAddress]) : null,
     };
 }
+/** Reads daily historical share prices for one Earn vault. */
+export async function getVaultSharePrices(c, 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) {
+    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;
+}
+async function resolveSharePriceVaultDiscovery(c, options) {
+    const result = await Store.memoize(async () => {
+        try {
+            return {
+                discovery: await readVaultDiscovery(c, { ...options, include: [] }),
+                status: 'found',
+            };
+        }
+        catch (cause) {
+            if (isIncompatible(cause))
+                return { status: 'not_found' };
+            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;
+}
+/** Reads one direct or Zone-routed account position in a parent-chain Earn vault. */
+export async function getVaultPosition(c, options) {
+    const zone = c.get('zones').get(options.chainId);
+    if (!zone) {
+        const block = options.asOf === undefined
+            ? undefined
+            : await getIndexedBlockAtOrBefore(c.get('getTidx')(options.chainId), options.asOf);
+        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,
+    };
+}
+/** Reads a private Zone token balance with the holder as the authorized RPC caller. */
+async function readZoneBalance(client, options) {
+    return client.readContract({
+        abi: tokenPositionAbi,
+        account: options.account,
+        address: options.token,
+        args: [options.account],
+        ...(options.blockNumber === undefined ? {} : { blockNumber: options.blockNumber }),
+        functionName: 'balanceOf',
+    });
+}
+/** Reads the parent Tempo checkpoint imported by one Zone observation. */
+async function readZoneSourceBlock(c, options) {
+    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 });
+}
+/** Caps a Zone-reported parent checkpoint at the L1 portal's verified watermark. */
+export function alignZoneSourceBlock(options) {
+    if (options.reported === undefined || options.verified < options.reported)
+        return options.verified;
+    return options.reported;
+}
+/** Resolves the verified parent vault and token pair for one Zone route. */
+async function resolveZonePositionRoute(c, options) {
+    const zone = c.get('zones').get(options.chainId);
+    if (!zone?.sourceId)
+        throw new EarnVaults.NotFoundError();
+    const db = Db.get(c.get('dbCached'));
+    const record = await core_EarnVaults.get(db, {
+        chainId: zone.sourceId,
+        vaultAddress: options.vault,
+    });
+    const configured = record?.zones.find((route) => route.chainId === options.chainId);
+    if (!record || !configured)
+        throw new EarnVaults.NotFoundError();
+    const discovery = await resolveVaultDiscovery(c, {
+        chainId: zone.sourceId,
+        include: [],
+        vaultAddress: options.vault,
+    });
+    const [route] = await EarnVaults.resolveZoneRoutes({
+        discovery,
+        getClient: c.get('getClient'),
+        routes: [configured],
+        zones: [...c.get('zones').values()],
+    });
+    const privateAsset = route?.inputTokens[0];
+    const portalContract = zone.contracts?.['portal'];
+    const portal = Schema.Address.safeParse(portalContract && 'address' in portalContract
+        ? portalContract.address
+        : portalContract?.[zone.sourceId]?.address);
+    if (!route || !privateAsset || !portal.success)
+        throw new EarnVaults.NotFoundError();
+    return {
+        deploymentBlock: route.deploymentBlock,
+        portal: portal.data,
+        privateAsset,
+        shareToken: discovery.shareToken.address,
+        sourceChainId: zone.sourceId,
+        vaultAsset: discovery.assetToken.address,
+    };
+}
 /** Lists every vault where an account holds earn shares, ordered by vault address. */
 export async function listPositions(c, 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
+    const heldPromise = options.verified || zone
         ? undefined
         : queryHeldVaults(c, { address: options.address, chainId: options.chainId });
     // Observing these branches prevents unhandled rejections while the
@@ -1759,14 +2831,16 @@ export async function listPositions(c, options) {
         const read = await Timing.time(c, 'earn_positions', () => Promise.all(batch.map(async (vault) => {
             const record = registry.get(vault);
             try {
-                const position = await 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;
@@ -1779,7 +2853,17 @@ export async function listPositions(c, options) {
         }
     }
     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])),
@@ -1793,12 +2877,19 @@ export async function listPositions(c, options) {
                 }));
             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,
@@ -1815,11 +2906,14 @@ export async function listPositions(c, options) {
             : undefined;
     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,
         })),
@@ -1829,12 +2923,12 @@ export async function listPositions(c, options) {
 }
 /** Finds vaults whose earn share token the account has ever held, by vault address. */
 async function queryHeldVaults(c, options) {
+    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,
         engine: 'clickhouse',
@@ -1849,6 +2943,7 @@ async function queryHeldVaults(c, options) {
               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)
@@ -1865,22 +2960,19 @@ async function queryHeldVaults(c, options) {
         return vault.success ? [vault.data.toLowerCase()] : [];
     });
 }
-/** Reads one account's live position in one vault. */
-function readPosition(c, options) {
-    return c
-        .get('getClient')(options.chainId)
-        .earn.getPosition({ account: options.address, vault: options.vaultAddress });
-}
 /** Serializes one live position into the address-scoped row contract. */
 function 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
@@ -1889,14 +2981,138 @@ function 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,
     };
 }
+/** Reads complete protocol cash flows for one account and a set of vaults. */
+export async function getVaultLifetimeCashFlows(tidx, options) {
+    const vaults = [...new Set(options.vaults.map((vault) => vault.toLowerCase()))];
+    const cashFlows = new Map();
+    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
+    `,
+        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;
+}
 /** Renders a base-unit amount in the token's display currency and precision. */
 function valueFor(amount, token) {
     return {
@@ -1930,7 +3146,7 @@ export async function getVault(c, options) {
             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,
@@ -1938,6 +3154,11 @@ export async function getVault(c, options) {
                 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 {
@@ -1947,6 +3168,7 @@ export async function getVault(c, options) {
                 include,
                 rates,
                 record,
+                rewards,
                 snapshot,
                 tokens,
                 zoneRoutes,
@@ -1993,7 +3215,16 @@ function discoveryInclude(options) {
     ];
 }
 async function resolveVaultDiscovery(c, options) {
-    return Store.memoize(() => Timing.time(c, 'earn_vault_discovery', () => EarnVaults.resolve({
+    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, options) {
+    return Timing.time(c, 'earn_vault_discovery', () => EarnVaults.resolve({
         getClient: c.get('getClient'),
         include: options.include,
         input: {
@@ -2001,13 +3232,7 @@ async function resolveVaultDiscovery(c, options) {
             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),
-    });
+    }));
 }
 async function resolveVaultRoutes(c, options) {
     const { discovery, record } = options;
@@ -2042,6 +3267,106 @@ async function resolveVaultRoutes(c, options) {
             : [],
     };
 }
+async function resolvePositionApy(c, options) {
+    const sourceChainId = c.get('zones').get(options.chainId)?.sourceId ?? options.chainId;
+    const recordFailure = (failure) => {
+        Cache.setPolicy(c, Cache.policies.noStore);
+        c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure]);
+    };
+    const rateFailures = [];
+    const [rates, discovery] = await Promise.all([
+        Timing.time(c, 'earn_apy', () => EarnRates.resolve({
+            chainId: sourceChainId,
+            getClient: c.get('getClient'),
+            getTidx: c.get('getTidx'),
+            onFailure: (failure) => {
+                rateFailures.push({ ...failure, chainId: sourceChainId });
+            },
+            store: c.get('store'),
+            vaults: [options.vault],
+        })).catch(() => {
+            rateFailures.push({
+                chainId: sourceChainId,
+                failure: 'unknown',
+                id: 'earn-apy',
+                operation: 'resolve',
+            });
+            return undefined;
+        }),
+        resolveVaultDiscovery(c, {
+            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;
+    });
+}
+function positionApyContractAddresses(contract) {
+    if (!contract || typeof contract !== 'object')
+        return [];
+    const value = contract;
+    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, options) {
@@ -2056,6 +3381,44 @@ function resolvePageApy(c, options) {
         window: options.window,
     }));
 }
+function resolvePageRewards(c, 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',
+        };
+        c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure]);
+        return new Map();
+    }));
+}
+function resolveVaultRewards(c, 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',
+        };
+        c.set('providerFailures', [...(c.get('providerFailures') ?? []), failure]);
+        return undefined;
+    }));
+}
 // The TVL denomination is a fixed constant, not caller input, so a rate set
 // lacking it leaves `tvl` unpriced instead of failing the whole vault read.
 function resolvePageRates(c, options) {
@@ -2104,12 +3467,29 @@ async function resolveVault(c, options) {
             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
             ? {
@@ -2131,9 +3511,37 @@ export function serializeVault(options) {
     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,
@@ -2144,6 +3552,9 @@ export function serializeVault(options) {
         },
         id: vaultAddress,
         instantLiquidity: discovery.instantLiquidity,
+        ...(options.include.includes('tvl')
+            ? { instantLiquidityValue: options.instantLiquidityValue }
+            : {}),
         label: record?.label ?? options.shareToken.name,
         sharePrice: discovery.sharePrice === null
             ? null
@@ -2214,6 +3625,9 @@ function getToken(tokens, address) {
     return Response.validated(Tokens.schema.Token, token);
 }
 async function queryDeployments(c, options) {
+    const factories = deploymentFactories[options.chainId] ?? [];
+    if (factories.length === 0)
+        return { hasMore: false, items: [] };
     const filters = [];
     if (options.asset)
         filters.push(`lower(asset) = '${options.asset.toLowerCase()}'`);
@@ -2230,7 +3644,8 @@ async function queryDeployments(c, options) {
                 order: 'desc',
             },
         ]));
-    // 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({
@@ -2245,6 +3660,7 @@ async function queryDeployments(c, options) {
           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")
       )
@@ -2301,4 +3717,29 @@ export function isIncompatible(cause) {
 export class NotFoundError extends Error {
     name = 'Earn.NotFoundError';
 }
+/** Thrown when a historical position boundary is not indexed. */
+class IndexedBlockNotFoundError extends Error {
+    name = 'Earn.IndexedBlockNotFoundError';
+    constructor(asOf) {
+        super(`No indexed block exists at or before ${asOf}.`);
+    }
+}
+class IndexedCoverageError extends Error {
+    name = 'Earn.IndexedCoverageError';
+    constructor(asOf) {
+        super(`Indexed history does not yet cover ${asOf}.`);
+    }
+}
+class ZoneHistoricalAlignmentError extends Error {
+    name = 'Earn.ZoneHistoricalAlignmentError';
+    constructor() {
+        super('This Zone does not expose historical parent-chain synchronization checkpoints.');
+    }
+}
+class ZoneEarningsUnsupportedError extends Error {
+    name = 'Earn.ZoneEarningsUnsupportedError';
+    constructor() {
+        super('Zone positions do not support the earnings include.');
+    }
+}
 //# sourceMappingURL=earn.js.map