tapimo 0.12.0 → 0.14.0

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

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import { Value as core_Value } from 'ox';
+import { Abis } from 'viem/tempo';
 import { ContractFunctionExecutionError, ContractFunctionRevertedError, ContractFunctionZeroDataError, zeroAddress, } from 'viem';
 import * as z from 'zod/mini';
 import * as Scope from '../../../Scope.js';
@@ -70,12 +71,12 @@ export var schema;
         .enum(['erc4626', 'veda'])
         .check(z.describe('Inferred vault engine type.'), z.meta({ examples: ['erc4626'] }));
     const engine = Schema.describe(z.strictObject({
-        address: Schema.Address.check(z.describe('Current vault engine contract address.'), z.meta({ examples: ['0xd85fc943333a6cd7c0e3391acd54fc4e572f0baf'] })),
+        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.');
     const include = z
@@ -90,34 +91,34 @@ export var schema;
     const baseIncludeQuery = Schema.includeQuery(baseInclude, 'Comma-separated vault fields to include, such as `access,zone`.');
     const zone = z
         .strictObject({
-        chainId: Schema.ChainId.check(z.describe('Private Zone chain id.'), z.meta({ examples: [1424310001] })),
+        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: [['0x20c000000000000000000000ff04042ee92fd449']] })),
+            .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: [['0x20c000000000000000000000ff04042ee92fd449']] })),
+            .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
         .strictObject({
-        chainId: Schema.ChainId.check(z.describe('Private Zone chain id.'), z.meta({ examples: [1424310001] })),
+        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: [31039238] })),
-        earnRouter: Schema.Address.check(z.describe('Parent-chain router for this Zone and Earn vault.'), z.meta({ examples: ['0x9144086a79dea966d8bf1b52125ebed8919fc45c'] })),
+            .check(z.int(), z.nonnegative(), z.describe('Parent-chain block that deployed the Earn router.'), z.meta({ examples: [35816964] })),
+        earnRouter: Schema.Address.check(z.describe('Parent-chain router for this Zone and Earn vault.'), z.meta({ examples: ['0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6'] })),
         inputTokens: z
             .array(Schema.Address)
-            .check(z.describe('Tokens accepted by private deposits.'), z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] })),
+            .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: [['0x20c000000000000000000000ff04042ee92fd449']] })),
+            .check(z.describe('Tokens returned by private redemptions.'), z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] })),
     })
         .check(z.describe('Verified Earn route through one private Zone.'));
     const value = z.strictObject({
@@ -139,31 +140,58 @@ export var schema;
         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.')),
+        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,12 +202,12 @@ export var schema;
             examples: [
                 [
                     {
-                        chainId: 1424310001,
-                        deploymentBlock: 31039238,
-                        earnRouter: '0x9144086a79dea966d8bf1b52125ebed8919fc45c',
-                        inputTokens: ['0x20c000000000000000000000ff04042ee92fd449'],
-                        name: 'zone-moderato-internal',
-                        outputTokens: ['0x20c000000000000000000000ff04042ee92fd449'],
+                        chainId: 421700001,
+                        deploymentBlock: 35816964,
+                        earnRouter: '0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6',
+                        inputTokens: ['0x20c0000000000000000000006fd9a167923ba194'],
+                        name: 'zone-mainnet-internal',
+                        outputTokens: ['0x20c0000000000000000000006fd9a167923ba194'],
                     },
                 ],
             ],
@@ -200,25 +228,42 @@ export var schema;
     const position = z.strictObject({
         account: Schema.Address.check(z.describe('Account whose earn position was read.'), z.meta({ examples: ['0xbe058e1c4df8a4366a387bf595b284246a93039e'] })),
         assetAllowance: Schema.DecimalString.check(z.describe('Assets the vault may spend from 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'] })),
+        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.')),
         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'] })),
+        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 asset base units.'), z.meta({ examples: ['100000000'] })),
     });
+    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 = z.strictObject({
         assetAmount: value.check(z.describe('Current asset value of the held shares, including fees, in `assetToken` units.')),
         assetToken: Tokens.schema.Token.check(z.describe('Asset accepted by the vault.')),
-        id: Schema.Address.check(z.describe('Stable resource ID for this position, equal to the vault address.'), z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] })),
+        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'] })),
+        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] })),
@@ -237,6 +282,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,11 +321,21 @@ 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
@@ -356,6 +413,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`.'),
             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.')),
@@ -405,19 +463,42 @@ export var schema;
     /** 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,
+        })
             .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. */
+        getEarnVaultPosition.Response = Schema.describe(z.extend(position, {
+            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.')),
+        }), 'Current or historical asset and earn-share balances, allowances, and asset value for an account in one earn vault.');
     })(getEarnVaultPosition = schema.getEarnVaultPosition || (schema.getEarnVaultPosition = {}));
     /** Schemas for the getEarnVaultEarnings operation. */
     let getEarnVaultEarnings;
@@ -465,7 +546,7 @@ 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:v4',
     }), async (c) => {
         if (Auth.narrowAccess)
             return Auth.paidAccessError(c);
@@ -502,7 +583,7 @@ 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);
@@ -528,7 +609,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, with current balances and optional lifetime cash flows.',
         operationId: 'getEarnAddressPositions',
         responses: OpenApi.responses({
             errors: {
@@ -555,7 +636,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);
@@ -601,7 +682,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 asset and earn-share balances, allowances, and asset value for one earn vault, optionally at an ISO 8601 timestamp.',
         operationId: 'getEarnVaultPosition',
         responses: OpenApi.responses({
             errors: {
@@ -620,16 +701,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:v2',
     }), async (c) => {
         if (Auth.narrowAccess)
             return Auth.paidAccessError(c);
@@ -658,34 +741,85 @@ export function earn(options = {}) {
         const { address, vaultId } = c.req.valid('param');
         const query = c.req.valid('query');
         const chainId = query.chainId ?? c.get('chainId');
+        const client = c.get('getClient')(chainId);
         try {
-            const position = await c
-                .get('getClient')(chainId)
-                .earn.getPosition({ account: address, vault: vaultId });
-            return c.json(Response.validated(schema.getEarnVaultPosition.Response, {
-                account: address,
-                assetAllowance: position.assetAllowance.toString(),
-                assetBalance: position.assetBalance.toString(),
-                assetToken: position.assetToken,
-                id: address,
-                shareAllowance: position.shareAllowance.toString(),
-                shareBalance: position.shareBalance.toString(),
-                shareToken: position.shareToken,
-                value: position.value.toString(),
-            }), 200);
-        }
-        catch (cause) {
+            const block = query.asOf === undefined
+                ? undefined
+                : await getIndexedBlockAtOrBefore(c.get('getTidx')(chainId), query.asOf);
             try {
-                await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId });
+                const position = await client.earn.getPosition({
+                    account: address,
+                    ...(block ? { blockNumber: BigInt(block.number) } : {}),
+                    vault: vaultId,
+                });
+                return c.json(Response.validated(schema.getEarnVaultPosition.Response, {
+                    account: address,
+                    assetAllowance: position.assetAllowance.toString(),
+                    assetBalance: position.assetBalance.toString(),
+                    assetToken: position.assetToken,
+                    asOf: query.asOf,
+                    block,
+                    id: address,
+                    shareAllowance: position.shareAllowance.toString(),
+                    shareBalance: position.shareBalance.toString(),
+                    shareToken: position.shareToken,
+                    value: position.value.toString(),
+                }), 200);
             }
-            catch (vaultCause) {
-                if (isIncompatible(vaultCause))
-                    return Response.error(c, {
-                        code: 'earn_vault_not_found',
-                        message: 'Earn vault not found',
-                        status: 404,
-                    });
+            catch (cause) {
+                if (block) {
+                    try {
+                        // These immutable bindings establish historical vault identity
+                        // without repeating fallible token or redemption subreads.
+                        const [asset, shareToken] = await Promise.all([
+                            client.readContract({
+                                abi: Abis.earnVault,
+                                address: vaultId,
+                                blockNumber: BigInt(block.number),
+                                functionName: 'asset',
+                            }),
+                            client.readContract({
+                                abi: Abis.earnVault,
+                                address: vaultId,
+                                blockNumber: BigInt(block.number),
+                                functionName: 'earnShare',
+                            }),
+                        ]);
+                        if (asset === zeroAddress || shareToken === zeroAddress)
+                            return Response.error(c, {
+                                code: 'earn_vault_not_found',
+                                message: 'Earn vault not found',
+                                status: 404,
+                            });
+                    }
+                    catch (identityCause) {
+                        if (isIncompatible(identityCause))
+                            return Response.error(c, {
+                                code: 'earn_vault_not_found',
+                                message: 'Earn vault not found',
+                                status: 404,
+                            });
+                        return Response.upstream(c, identityCause);
+                    }
+                    return Response.upstream(c, cause);
+                }
+                try {
+                    await resolveVaultDiscovery(c, { chainId, include: [], vaultAddress: vaultId });
+                }
+                catch (vaultCause) {
+                    if (isIncompatible(vaultCause))
+                        return Response.error(c, {
+                            code: 'earn_vault_not_found',
+                            message: 'Earn vault not found',
+                            status: 404,
+                        });
+                }
+                return Response.upstream(c, cause);
             }
+        }
+        catch (cause) {
+            if (cause instanceof IndexedBlockNotFoundError || cause instanceof IndexedCoverageError)
+                return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 });
             return Response.upstream(c, cause);
         }
     })
@@ -724,7 +858,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);
@@ -804,7 +938,7 @@ 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);
@@ -911,10 +1045,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) {
@@ -1003,6 +1147,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 +1319,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),
@@ -1779,7 +1971,17 @@ export async function listPositions(c, options) {
         }
     }
     const page = matches.slice(0, options.limit);
-    const [tokens, snapshot] = await Promise.all([
+    const indexedBlock = page.length > 0 && options.include.includes('earnings')
+        ? await getLatestIndexedBlock(c.get('getTidx')(options.chainId))
+        : undefined;
+    const [cashFlows, tokens, 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])),
@@ -1815,6 +2017,7 @@ export async function listPositions(c, options) {
             : undefined;
     return {
         data: page.map((match) => serializePosition({
+            cashFlows: cashFlows?.get(match.vaultAddress),
             denomination,
             position: match.position,
             rates,
@@ -1881,6 +2084,7 @@ function serializePosition(options) {
         assetAmount: valueFor(position.value, assetToken),
         assetToken,
         id: vaultAddress,
+        ...(options.cashFlows ? { lifetimeCashFlows: options.cashFlows } : {}),
         shareAmount: valueFor(position.shareBalance, shareToken),
         shareToken,
         ...(options.denomination
@@ -1897,6 +2101,129 @@ function serializePosition(options) {
         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 {
@@ -2104,11 +2431,27 @@ 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,
         shareToken: getToken(options.tokens, discovery.shareToken.address),
         tvl: valued
@@ -2144,6 +2487,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
@@ -2301,4 +2647,17 @@ 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}.`);
+    }
+}
 //# sourceMappingURL=earn.js.map