tapimo 0.12.0 → 0.14.0

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

@@ -1,6 +1,6 @@
 import { type Context, Hono } from 'hono'
 import { Value as core_Value } from 'ox'
-import type { Actions } from 'viem/tempo'
+import { Abis, type Actions } from 'viem/tempo'
 import {
   type Chain,
   ContractFunctionExecutionError,
@@ -130,7 +130,7 @@ export namespace schema {
     z.strictObject({
       address: Schema.Address.check(
         z.describe('Current vault engine contract address.'),
-        z.meta({ examples: ['0xd85fc943333a6cd7c0e3391acd54fc4e572f0baf'] }),
+        z.meta({ examples: ['0x59d27987bc7cc1521bba5f688a170c65840cbf43'] }),
       ),
       type: z
         .nullable(engineType)
@@ -139,7 +139,7 @@ export namespace schema {
         .nullable(
           Schema.Address.check(
             z.describe('Yield venue contract bound to the engine.'),
-            z.meta({ examples: ['0xa8b4f0e69cd4b0e56b676343f02acd8c3b355322'] }),
+            z.meta({ examples: ['0x9a044ae05e5e6290dcf56afd69548565e957a626'] }),
           ),
         )
         .check(z.describe('Yield venue, or null when the engine does not expose one.')),
@@ -171,22 +171,22 @@ export namespace schema {
     .strictObject({
       chainId: Schema.ChainId.check(
         z.describe('Private Zone chain id.'),
-        z.meta({ examples: [1424310001] }),
+        z.meta({ examples: [421700001] }),
       ),
       inputTokens: z
         .array(Schema.Address)
         .check(
           z.describe('Tokens accepted by private deposits.'),
-          z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] }),
+          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']] }),
+          z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
         ),
     })
     .check(z.describe('Private Zone route configured for a verified vault.'))
@@ -195,7 +195,7 @@ export namespace schema {
     .strictObject({
       chainId: Schema.ChainId.check(
         z.describe('Private Zone chain id.'),
-        z.meta({ examples: [1424310001] }),
+        z.meta({ examples: [421700001] }),
       ),
       deploymentBlock: z
         .number()
@@ -203,26 +203,26 @@ export namespace schema {
           z.int(),
           z.nonnegative(),
           z.describe('Parent-chain block that deployed the Earn router.'),
-          z.meta({ examples: [31039238] }),
+          z.meta({ examples: [35816964] }),
         ),
       earnRouter: Schema.Address.check(
         z.describe('Parent-chain router for this Zone and Earn vault.'),
-        z.meta({ examples: ['0x9144086a79dea966d8bf1b52125ebed8919fc45c'] }),
+        z.meta({ examples: ['0x8117e0ba6239b9695f780deb010f72a2fa4bdfb6'] }),
       ),
       inputTokens: z
         .array(Schema.Address)
         .check(
           z.describe('Tokens accepted by private deposits.'),
-          z.meta({ examples: [['0x20c000000000000000000000ff04042ee92fd449']] }),
+          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']] }),
+          z.meta({ examples: [['0x20c0000000000000000000006fd9a167923ba194']] }),
         ),
     })
     .check(z.describe('Verified Earn route through one private Zone.'))
@@ -263,7 +263,22 @@ export namespace schema {
           '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.')),
@@ -271,21 +286,28 @@ export namespace schema {
       .nullable(z.string())
       .check(
         z.describe('Curated vault description, or null when the vault is not verified.'),
-        z.meta({ examples: ['Bridge test PATHUSD deposited into Tempo Earn.'] }),
+        z.meta({ examples: ['deelUSD deposited into the canonical Tempo Earn deployment.'] }),
       ),
     engine,
     id: Schema.Address.check(
       z.describe('Stable vault id, equal to the lowercase vault address.'),
-      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
     ),
     instantLiquidity: EarnVaults.schema.Discovery.shape.instantLiquidity.check(
       z.describe(
         'Assets the venue would release right now, capped at the vault backing, in asset base units. Null when the engine interface cannot report a reliable number.',
       ),
     ),
+    instantLiquidityValue: z
+      .optional(z.nullable(value))
+      .check(
+        z.describe(
+          'Instant liquidity valued in USD, when requested via `include=tvl`, or null when liquidity is unavailable or the asset has no priced display currency.',
+        ),
+      ),
     label: z
       .string()
-      .check(z.describe('Vault display label.'), z.meta({ examples: ['btPATHUSD Earn'] })),
+      .check(z.describe('Vault display label.'), z.meta({ examples: ['deelUSD Earn'] })),
     sharePrice: z
       .nullable(value)
       .check(
@@ -293,12 +315,27 @@ export namespace schema {
           'Assets returned for one whole earn share, in the asset display currency, or null when the engine cannot quote an exit.',
         ),
       ),
-    shareToken: Tokens.schema.Token.check(z.describe('Token representing vault shares.')),
+    shareToken: Tokens.schema.Token.check(
+      z.describe('Token representing vault shares.'),
+      z.meta({
+        examples: [
+          {
+            address: '0x20c000000000000000000000c3268d803b51d448',
+            currency: 'USD',
+            decimals: 6,
+            id: '0x20c000000000000000000000c3268d803b51d448',
+            name: 'Sentora pathUSD (Earn)',
+            symbol: 'senpathUSDE',
+            verified: false,
+          },
+        ],
+      }),
+    ),
     slug: z
       .nullable(z.string())
       .check(
         z.describe('Curated URL slug, or null when the vault is not verified.'),
-        z.meta({ examples: ['btpathusd-earn-h8k2m4n6'] }),
+        z.meta({ examples: ['deelusd-earn'] }),
       ),
     state: EarnVaults.schema.Discovery.shape.state,
     tvl: z
@@ -310,7 +347,7 @@ export namespace schema {
       ),
     vaultAddress: Schema.Address.check(
       z.describe('Earn vault contract address.'),
-      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
     ),
     verified: z
       .boolean()
@@ -327,12 +364,12 @@ export namespace 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'],
             },
           ],
         ],
@@ -373,7 +410,7 @@ export namespace schema {
       z.meta({ examples: ['0'] }),
     ),
     assetBalance: Schema.DecimalString.check(
-      z.describe('Assets this account currently holds, in asset base units.'),
+      z.describe('Assets held by this account at the observation block, in asset base units.'),
       z.meta({ examples: ['250000000'] }),
     ),
     assetToken: Schema.tokenAddress('0x20c000000000000000000000b9537d11c60e8b50').check(
@@ -388,7 +425,7 @@ export namespace schema {
       z.meta({ examples: ['0'] }),
     ),
     shareBalance: Schema.DecimalString.check(
-      z.describe('Earn shares this account currently holds, in share base units.'),
+      z.describe('Earn shares held by this account at the observation block, in share base units.'),
       z.meta({ examples: ['99500000'] }),
     ),
     shareToken: Schema.tokenAddress('0x20c000000000000000000000300e14ab91a10769').check(
@@ -396,12 +433,37 @@ export namespace schema {
     ),
     value: Schema.DecimalString.check(
       z.describe(
-        'Current asset value of this account’s earn shares, including fees, in asset base units.',
+        'Asset value of this account’s earn shares at the observation block, including fees, in 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.'),
@@ -409,8 +471,11 @@ export namespace schema {
     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'] }),
+      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.'),
     ),
@@ -425,7 +490,7 @@ export namespace schema {
       ),
     vaultAddress: Schema.Address.check(
       z.describe('Earn vault contract address holding this position.'),
-      z.meta({ examples: ['0xf4ae63687d6753a78e7f551d2eda1d0d31a5ea3a'] }),
+      z.meta({ examples: ['0x4f94590b636f5878bce585e82379de81e1ec174f'] }),
     ),
     verified: z
       .boolean()
@@ -476,6 +541,18 @@ export namespace schema {
           ),
           z.meta({ examples: ['0'] }),
         ),
+      totalDeposited: Schema.DecimalString.check(
+        z.describe(
+          'Assets deposited with this account as receiver over complete indexed vault history.',
+        ),
+        z.meta({ examples: ['1000000'] }),
+      ),
+      totalWithdrawn: Schema.DecimalString.check(
+        z.describe(
+          'Assets returned by completed redemptions and exact withdrawals initiated by this account over complete indexed vault history.',
+        ),
+        z.meta({ examples: ['1000000'] }),
+      ),
       period: z
         .literal('lifetime')
         .check(
@@ -548,9 +625,23 @@ export namespace schema {
     }),
     z.extend(earningsBase, {
       period: z
-        .enum(['30d', '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('Earnings period with an unresolved async redemption.'),
+          z.describe('Lifetime period with an unresolved async redemption.'),
           z.meta({ examples: ['lifetime'] }),
         ),
       status: z
@@ -559,6 +650,12 @@ export namespace schema {
           z.describe('Earnings are unavailable while an async redemption remains open.'),
           z.meta({ examples: ['pending_redemption'] }),
         ),
+      totalDeposited: Schema.DecimalString.check(
+        z.describe('Assets deposited over complete indexed vault history.'),
+      ),
+      totalWithdrawn: Schema.DecimalString.check(
+        z.describe('Assets withdrawn over complete indexed vault history.'),
+      ),
     }),
   ])
 
@@ -654,6 +751,10 @@ export namespace schema {
       .strictObject({
         chainId: Schema.ChainIdQuery,
         cursor: Schema.Cursor,
+        include: Schema.includeQuery(
+          z.enum(['earnings']),
+          'Comma-separated position fields to include, such as `earnings`.',
+        ),
         limit: Schema.Limit,
         'valuation.currency': Schema.Denomination.check(
           z.describe(
@@ -727,11 +828,13 @@ export namespace schema {
 
   /** Schemas for the getEarnVaultPosition operation. */
   export namespace getEarnVaultPosition {
+    const asOf = z.iso.datetime({ offset: true })
+
     /** Path parameters identifying the Earn vault and account. */
     export const Params = z
       .strictObject({
         address: Schema.Address.check(z.describe('Account whose earn position to read.')),
-        vaultId: Schema.address('0xdb48b00fb28d9a8db881fcd671c3fb1bf8c486b6').check(
+        vaultId: Schema.address('0x4f94590b636f5878bce585e82379de81e1ec174f').check(
           z.describe('Earn vault contract address.'),
         ),
       })
@@ -739,13 +842,56 @@ export namespace schema {
 
     /** Query parameters selecting the chain containing the vault. */
     export const Query = z
-      .strictObject({ chainId: Schema.ChainIdQuery })
+      .strictObject({
+        asOf: z
+          .optional(asOf)
+          .check(
+            z.describe(
+              'ISO 8601 timestamp at which to read the position. Resolves the latest indexed block at or before this time.',
+            ),
+            z.meta({ examples: ['2026-07-21T09:00:00.000Z'] }),
+          ),
+        chainId: Schema.ChainIdQuery,
+      })
       .check(z.describe('Query parameters selecting an earn vault position.'))
 
-    /** Current asset and Earn-share state for one account in one 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. */
     export const Response = Schema.describe(
-      position,
-      'Current asset and earn-share balances, allowances, and asset value for an account in one earn vault.',
+      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.',
     )
   }
 
@@ -807,7 +953,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => vaultCacheKey(c, schema.getEarnVaults.Query),
-        name: 'tempo-api:earn-vaults:v3',
+        name: 'tempo-api:earn-vaults:v4',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -851,7 +997,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => vaultCacheKey(c, schema.getVerifiedEarnVaults.Query),
-        name: 'tempo-api:earn-vaults:v3',
+        name: 'tempo-api:earn-vaults:v4',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -884,7 +1030,7 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Lists every earn vault where an account currently holds shares, with the current balance and value of each position.',
+          'Lists every earn vault where an account currently holds shares, with current balances and optional lifetime cash flows.',
         operationId: 'getEarnAddressPositions',
         responses: OpenApi.responses({
           errors: {
@@ -911,7 +1057,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         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)
@@ -964,7 +1110,7 @@ export function earn(options: earn.Options = {}) {
       }),
       OpenApi.describeRoute({
         description:
-          'Gets an account’s asset and earn-share balances, allowances, and current asset value for one earn vault.',
+          'Gets an account’s 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: {
@@ -983,17 +1129,18 @@ export function earn(options: earn.Options = {}) {
             502: 'Could not read the earn vault position.',
           },
           success: {
-            description: 'Current earn position for one account in one vault.',
+            description: 'Current or historical earn position for one account in one vault.',
             schema: schema.getEarnVaultPosition.Response,
           },
         }),
         summary: 'Get account position',
         tags: ['Earn'],
       }),
+      // Account holdings must read fresh immediately after a deposit or redemption.
       Cache.response<App.Environment>({
-        cacheControl: Cache.policies.state,
+        cacheControl: Cache.policies.noStore,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultPosition.Query),
-        name: 'tempo-api:earn-vault-positions:v1',
+        name: 'tempo-api:earn-vault-positions:v2',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -1023,35 +1170,85 @@ export function earn(options: earn.Options = {}) {
         const { address, vaultId } = c.req.valid('param')
         const query = c.req.valid('query')
         const chainId = query.chainId ?? c.get('chainId')
+        const client = c.get('getClient')(chainId)
         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 })
-          } catch (vaultCause) {
-            if (isIncompatible(vaultCause))
-              return Response.error(c, {
-                code: 'earn_vault_not_found',
-                message: 'Earn vault not found',
-                status: 404,
-              })
+            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 (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)
         }
       },
@@ -1098,7 +1295,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => Cache.urlKey(c, schema.getEarnVaultEarnings.Query),
-        name: 'tempo-api:earn-vault-earnings:v3',
+        name: 'tempo-api:earn-vault-earnings:v4',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -1185,7 +1382,7 @@ export function earn(options: earn.Options = {}) {
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.state,
         key: (c) => vaultCacheKey(c, schema.getEarnVault.Query),
-        name: 'tempo-api:earn-vaults:v3',
+        name: 'tempo-api:earn-vaults:v4',
       }),
       async (c) => {
         if (Auth.narrowAccess) return Auth.paidAccessError(c)
@@ -1304,10 +1501,20 @@ export async function getVaultEarnings(
   }
   if (history.incompleteCostBasis || externalShareTransfer)
     return { ...base, status: 'incomplete_cost_basis' as const }
-  if (history.pendingRedemption) return { ...base, status: 'pending_redemption' as const }
-  const lifetimeEarnings =
-    current.value + history.redeemed + history.withdrewExact + history.finalized - history.deposited
-  return { ...base, lifetimeEarnings: lifetimeEarnings.toString(), status: 'complete' as const }
+  const totalWithdrawn = history.redeemed + history.withdrewExact + history.finalized
+  const cashFlows = {
+    totalDeposited: history.deposited.toString(),
+    totalWithdrawn: totalWithdrawn.toString(),
+  }
+  if (history.pendingRedemption)
+    return { ...base, ...cashFlows, status: 'pending_redemption' as const }
+  const lifetimeEarnings = current.value + totalWithdrawn - history.deposited
+  return {
+    ...base,
+    ...cashFlows,
+    lifetimeEarnings: lifetimeEarnings.toString(),
+    status: 'complete' as const,
+  }
 }
 
 /** Reads cash-flow-adjusted earnings over a trailing indexed window. */
@@ -1453,6 +1660,62 @@ async function getLatestIndexedBlock(tidx: Tidx.Client) {
   return { number, timestamp }
 }
 
+/** Resolves the latest indexed block at or before a historical position timestamp. */
+async function getIndexedBlockAtOrBefore(tidx: Tidx.Client, asOf: string) {
+  const timestamp = new Date(asOf).toISOString().replace('T', ' ').replace(/Z$/, '')
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    // SAFETY: Zod restricts `asOf` to ISO 8601, so the formatted timestamp cannot alter SQL.
+    query: `
+      SELECT 'boundary' AS kind, num, timestamp
+      FROM (
+        SELECT num, timestamp
+        FROM blocks
+        WHERE timestamp <= '${timestamp}'
+        ORDER BY timestamp DESC, num DESC
+        LIMIT 1
+      )
+      UNION ALL
+      SELECT 'head' AS kind, num, timestamp
+      FROM (
+        SELECT num, timestamp
+        FROM blocks
+        ORDER BY num DESC
+        LIMIT 1
+      )
+    ` as string,
+  })
+  return parseIndexedBlockAtOrBefore({ asOf, rows: result.rows })
+}
+
+/** Decodes the indexed head and historical position boundary from TIDX rows. */
+export function parseIndexedBlockAtOrBefore(options: parseIndexedBlockAtOrBefore.Options) {
+  const head = options.rows.find((row) => row['kind'] === 'head')
+  if (!head) throw new Error('TIDX returned no indexed head for a historical Earn position.')
+  const headNumber = Value.toNumber(head['num'])
+  const headAt = Value.toIsoDateTime(head['timestamp'])
+  if (headNumber === undefined || headAt === undefined)
+    throw new Error('TIDX returned a malformed indexed head for a historical Earn position.')
+  const boundary = options.rows.find((row) => row['kind'] === 'boundary')
+  if (!boundary) throw new IndexedBlockNotFoundError(options.asOf)
+  const number = Value.toNumber(boundary['num'])
+  const indexedAt = Value.toIsoDateTime(boundary['timestamp'])
+  if (number === undefined || indexedAt === undefined)
+    throw new Error('TIDX returned a malformed historical Earn position boundary.')
+  if (Date.parse(headAt) < Date.parse(options.asOf)) throw new IndexedCoverageError(options.asOf)
+  return { number, timestamp: indexedAt }
+}
+
+export declare namespace parseIndexedBlockAtOrBefore {
+  /** Inputs returned by the historical boundary query. */
+  type Options = {
+    /** Requested historical observation timestamp. */
+    asOf: string
+    /** Indexed head and optional boundary rows. */
+    rows: readonly Record<string, unknown>[]
+  }
+}
+
 /** Resolves the last indexed block at or before a trailing-day boundary. */
 async function getWindowStartBlockNumber(
   tidx: Tidx.Client,
@@ -1596,6 +1859,7 @@ async function getVaultEarningsHistory(
   return {
     deposited: BigInt(deposited),
     finalized: BigInt(finalized),
+    incompleteCashFlows: venueDeposits > 0,
     incompleteCostBasis: transferredCancellations > 0 || venueDeposits > 0,
     pendingRedemption: pendingRedemptions > 0,
     redeemed: BigInt(redeemed),
@@ -2403,7 +2667,18 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
   }
 
   const page = matches.slice(0, options.limit)
-  const [tokens, snapshot] = await Promise.all([
+  const indexedBlock =
+    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])),
@@ -2444,6 +2719,7 @@ export async function listPositions(c: Context<App.Environment>, options: listPo
   return {
     data: page.map((match) =>
       serializePosition({
+        cashFlows: cashFlows?.get(match.vaultAddress),
         denomination,
         position: match.position,
         rates,
@@ -2557,6 +2833,7 @@ function serializePosition(options: serializePosition.Options) {
     assetAmount: valueFor(position.value, assetToken),
     assetToken,
     id: vaultAddress,
+    ...(options.cashFlows ? { lifetimeCashFlows: options.cashFlows } : {}),
     shareAmount: valueFor(position.shareBalance, shareToken),
     shareToken,
     ...(options.denomination
@@ -2577,6 +2854,10 @@ function serializePosition(options: serializePosition.Options) {
 declare namespace serializePosition {
   /** Values used to serialize one account position row. */
   type Options = {
+    /** Indexed lifetime cash flows, when requested. */
+    cashFlows?: z.output<
+      typeof schema.getEarnAddressPositions.Response
+    >['data'][number]['lifetimeCashFlows']
     /** Currency the row valuation is denominated in (uppercase). */
     denomination?: string | undefined
     position: Actions.earn.getPosition.ReturnValue
@@ -2590,6 +2871,155 @@ declare namespace serializePosition {
   }
 }
 
+/** Reads complete protocol cash flows for one account and a set of vaults. */
+export async function getVaultLifetimeCashFlows(
+  tidx: Tidx.Client,
+  options: getVaultLifetimeCashFlows.Options,
+) {
+  const vaults = [...new Set(options.vaults.map((vault) => vault.toLowerCase()))]
+  const cashFlows = new Map<string, getVaultLifetimeCashFlows.CashFlows>()
+  if (vaults.length === 0) return cashFlows
+  const addresses = vaults.map((vault) => `'${vault}'`).join(', ')
+  const seeds = vaults
+    .map(
+      (vault) => `
+        SELECT '${vault}' AS vault,
+               toUInt256(0) AS deposited_assets,
+               toUInt256(0) AS finalized_assets,
+               toUInt256(0) AS redeemed_assets,
+               toUInt64(0) AS venue_deposits,
+               toUInt256(0) AS withdrew_exact`,
+    )
+    .join('\n        UNION ALL')
+  const result = await tidx.fetch({
+    engine: 'clickhouse',
+    query: `
+      SELECT vault,
+             toString(sum(deposited_assets)) AS deposited_assets,
+             toString(sum(finalized_assets)) AS finalized_assets,
+             toString(sum(redeemed_assets)) AS redeemed_assets,
+             sum(venue_deposits) AS venue_deposits,
+             toString(sum(withdrew_exact)) AS withdrew_exact
+      FROM (
+        ${seeds}
+        UNION ALL
+        SELECT address AS vault, sum(toUInt256(assets)) AS deposited_assets,
+               toUInt256(0) AS finalized_assets, toUInt256(0) AS redeemed_assets,
+               toUInt64(0) AS venue_deposits, toUInt256(0) AS withdrew_exact
+        FROM Deposited
+        WHERE address IN (${addresses})
+          AND receiver = '${options.account}'
+          AND block_num > ${beforeFirstBlockNumber}
+          AND block_num <= ${options.blockNumber}
+        GROUP BY address
+        UNION ALL
+        SELECT finalized.address AS vault, toUInt256(0) AS deposited_assets,
+               sum(toUInt256(finalized.assets)) AS finalized_assets,
+               toUInt256(0) AS redeemed_assets, toUInt64(0) AS venue_deposits,
+               toUInt256(0) AS withdrew_exact
+        FROM RedeemFinalized AS finalized
+        INNER JOIN RedeemRequested AS requested
+          ON requested.address = finalized.address
+          AND requested."requestId" = finalized."requestId"
+        WHERE finalized.address IN (${addresses})
+          AND requested.requester = '${options.account}'
+          AND finalized.block_num > ${beforeFirstBlockNumber}
+          AND finalized.block_num <= ${options.blockNumber}
+          AND requested.block_num <= ${options.blockNumber}
+        GROUP BY finalized.address
+        UNION ALL
+        SELECT address AS vault, toUInt256(0) AS deposited_assets,
+               toUInt256(0) AS finalized_assets, sum(toUInt256(assets)) AS redeemed_assets,
+               toUInt64(0) AS venue_deposits,
+               toUInt256(0) AS withdrew_exact
+        FROM Redeemed
+        WHERE address IN (${addresses})
+          AND caller = '${options.account}'
+          AND block_num > ${beforeFirstBlockNumber}
+          AND block_num <= ${options.blockNumber}
+        GROUP BY address
+        UNION ALL
+        SELECT address AS vault, toUInt256(0) AS deposited_assets,
+               toUInt256(0) AS finalized_assets, toUInt256(0) AS redeemed_assets,
+               count() AS venue_deposits, toUInt256(0) AS withdrew_exact
+        FROM VenueSharesDeposited
+        WHERE address IN (${addresses})
+          AND receiver = '${options.account}'
+          AND block_num > ${beforeFirstBlockNumber}
+          AND block_num <= ${options.blockNumber}
+        GROUP BY address
+        UNION ALL
+        SELECT address AS vault, toUInt256(0) AS deposited_assets,
+               toUInt256(0) AS finalized_assets, toUInt256(0) AS redeemed_assets,
+               toUInt64(0) AS venue_deposits, sum(toUInt256(assets)) AS withdrew_exact
+        FROM WithdrewExact
+        WHERE address IN (${addresses})
+          AND caller = '${options.account}'
+          AND block_num > ${beforeFirstBlockNumber}
+          AND block_num <= ${options.blockNumber}
+        GROUP BY address
+      ) AS histories
+      GROUP BY vault
+    ` as string,
+    signatures: [
+      depositedSignature,
+      redeemFinalizedSignature,
+      redeemRequestedSignature,
+      redeemedSignature,
+      venueSharesDepositedSignature,
+      withdrewExactSignature,
+    ],
+  })
+  for (const row of result.rows) {
+    const vault = Schema.Address.safeParse(Value.toText(row['vault']))
+    const deposited = Value.toIntegerString(row['deposited_assets'])
+    const finalized = Value.toIntegerString(row['finalized_assets'])
+    const redeemed = Value.toIntegerString(row['redeemed_assets'])
+    const venueDeposits = Value.toNumber(row['venue_deposits'])
+    const withdrewExact = Value.toIntegerString(row['withdrew_exact'])
+    if (
+      !vault.success ||
+      deposited === undefined ||
+      finalized === undefined ||
+      redeemed === undefined ||
+      venueDeposits === undefined ||
+      withdrewExact === undefined
+    )
+      throw new Error('TIDX returned invalid Earn lifetime cash flows.')
+    cashFlows.set(
+      vault.data.toLowerCase(),
+      venueDeposits > 0
+        ? { status: 'incomplete_history' }
+        : {
+            status: 'complete',
+            totalDeposited: deposited,
+            totalWithdrawn: (
+              BigInt(finalized) +
+              BigInt(redeemed) +
+              BigInt(withdrewExact)
+            ).toString(),
+          },
+    )
+  }
+  if (cashFlows.size !== vaults.length)
+    throw new Error('TIDX returned incomplete Earn lifetime cash flows.')
+  return cashFlows
+}
+
+export declare namespace getVaultLifetimeCashFlows {
+  /** Lifetime cash-flow state for one vault. */
+  type CashFlows = NonNullable<
+    z.output<typeof schema.getEarnAddressPositions.Response>['data'][number]['lifetimeCashFlows']
+  >
+
+  /** Indexed boundary and account whose protocol cash flows are read. */
+  type Options = {
+    account: z.output<typeof Schema.Address>
+    blockNumber: number
+    vaults: readonly z.output<typeof Schema.Address>[]
+  }
+}
+
 /** Renders a base-unit amount in the token's display currency and precision. */
 function valueFor(amount: bigint, token: z.output<typeof Tokens.schema.Token>) {
   return {
@@ -2898,11 +3328,28 @@ async function resolveVault(c: Context<App.Environment>, options: resolveVault.O
         token: options.snapshot.byAddress.get(discovery.assetToken.address),
       })
     : undefined
+  const liquidityValue =
+    options.include.includes('tvl') && discovery.instantLiquidity !== null
+      ? Valuation.valuationFor({
+          amount: BigInt(discovery.instantLiquidity),
+          denomination: tvlDenomination,
+          rates: options.rates,
+          token: options.snapshot.byAddress.get(discovery.assetToken.address),
+        })
+      : undefined
   return serializeVault({
     apy: options.apy?.get(discovery.vaultAddress) ?? null,
     assetToken: getToken(options.tokens, discovery.assetToken.address),
     discovery,
     include: options.include,
+    instantLiquidityValue: liquidityValue
+      ? {
+          amount: core_Value.from(liquidityValue.amount, tvlDecimals).toString(),
+          currency: liquidityValue.currency,
+          decimals: tvlDecimals,
+          formatted: liquidityValue.amount,
+        }
+      : null,
     record,
     shareToken: getToken(options.tokens, discovery.shareToken.address),
     tvl: valued
@@ -2952,6 +3399,9 @@ export function serializeVault(options: serializeVault.Options): z.output<typeof
     },
     id: vaultAddress,
     instantLiquidity: discovery.instantLiquidity,
+    ...(options.include.includes('tvl')
+      ? { instantLiquidityValue: options.instantLiquidityValue }
+      : {}),
     label: record?.label ?? options.shareToken.name,
     sharePrice:
       discovery.sharePrice === null
@@ -2995,6 +3445,8 @@ export declare namespace serializeVault {
     discovery: EarnVaults.Discovery
     /** Optional vault fields selected by the request. */
     include: z.output<typeof schema.getEarnVault.Query>['include']
+    /** USD value of instant liquidity, or null when unavailable; omitted unless `include` carries `tvl`. */
+    instantLiquidityValue: z.output<typeof schema.Vault>['instantLiquidityValue']
     /** Curated registry row, when verified. */
     record?: core_EarnVaults.Record | undefined
     /** Resolved share token. */
@@ -3195,3 +3647,20 @@ type RegistryRecord = Awaited<ReturnType<typeof core_EarnVaults.list>>[number]
 export class NotFoundError extends Error {
   override name = 'Earn.NotFoundError'
 }
+
+/** Thrown when a historical position boundary is not indexed. */
+class IndexedBlockNotFoundError extends Error {
+  override name = 'Earn.IndexedBlockNotFoundError'
+
+  constructor(asOf: string) {
+    super(`No indexed block exists at or before ${asOf}.`)
+  }
+}
+
+class IndexedCoverageError extends Error {
+  override name = 'Earn.IndexedCoverageError'
+
+  constructor(asOf: string) {
+    super(`Indexed history does not yet cover ${asOf}.`)
+  }
+}