tapimo 0.13.0 → 0.14.0

package/src/apps/Zones.test.ts

@@ -20,9 +20,9 @@ describe('chains', () => {
       },
       {
         contracts: {
-          messenger: { address: '0x171699d2B5211414C23E5Cd306d05046b78FdD16' },
-          portal: { address: '0xe5208b9604972CA6a2E1EF656a9d2bDF2e530B9A' },
-          verifier: { address: '0x3E7C1cC9C049052eb061116A4Ee7a7C281fa1F30' },
+          messenger: { address: '0x5A4d000000000000000000000000000000000000' },
+          portal: { address: '0x5ad0000000000000000000000000000000000001' },
+          verifier: { address: '0x5a56000000000000000000000000000000000000' },
         },
         id: 421_700_001,
         name: 'zone-mainnet-internal',

package/src/apps/Zones.ts

@@ -25,9 +25,9 @@ export const zoneMainnetInternal = defineChain({
   ...tempo,
   contracts: {
     ...tempo.contracts,
-    messenger: { address: '0x171699d2B5211414C23E5Cd306d05046b78FdD16' },
-    portal: { address: '0xe5208b9604972CA6a2E1EF656a9d2bDF2e530B9A' },
-    verifier: { address: '0x3E7C1cC9C049052eb061116A4Ee7a7C281fa1F30' },
+    messenger: { address: '0x5A4d000000000000000000000000000000000000' },
+    portal: { address: '0x5ad0000000000000000000000000000000000001' },
+    verifier: { address: '0x5a56000000000000000000000000000000000000' },
   },
   id: 421_700_001,
   name: 'zone-mainnet-internal',

package/src/apps/composition.test.ts

@@ -309,6 +309,7 @@ describe('funding()', () => {
         '/v1/funding/transfers/vault',
         '/v1/funding/transfers/zone',
         '/v1/funding/transfers/{id}',
+        '/v1/funding/transfers/{id}/source-transactions',
       ].sort(),
     )
     expect(Object.keys(spec.paths).some((path) => path.startsWith('/v1/tokens'))).toBe(false)

package/src/apps/data/App.ts

@@ -23,7 +23,7 @@ import { transactions as transactionActivities } from './routes/activities.js'
 import { addresses } from './routes/addresses.js'
 import { blocks, blocksByTimestampCompat } from './routes/blocks.js'
 import { coingecko } from './routes/coingecko.js'
-import { earn } from './routes/earn.js'
+import * as Earn from './routes/earn.js'
 import { exchanges } from './routes/exchanges.js'
 import { feeAmm } from './routes/fee-amm.js'
 import { indexer } from './routes/indexer.js'
@@ -60,7 +60,7 @@ export function data(options: data.Options = {}) {
 
   const getTidx = Tidx.createGetClient({ tidx })
   const addresses_routes = addresses({ fx: options.fx })
-  const earn_routes = earn({ fx: options.fx })
+  const earn_routes = Earn.earn({ fx: options.fx })
   const indexer_routes = indexer()
   const transactionActivities_routes = transactionActivities({ fx: options.fx })
   const indexerRouteHandlers = new Set(indexer_routes.routes.map((route) => route.handler))
@@ -130,14 +130,23 @@ export function data(options: data.Options = {}) {
       const rpc_config = c.get('rpc')
       const tidx_config = c.get('tidx')
       const zones = c.get('zones')
-      // Raw passthroughs and RPC-only reads need only RPC; composed data routes
-      // require both upstreams to avoid falling through to unrelated defaults.
+      const query = Earn.schema.getEarnVaultPosition.Query.safeParse(
+        Object.fromEntries(
+          Object.entries(c.req.queries()).map(([key, values]) => [
+            key,
+            values.length === 1 ? values[0] : values,
+          ]),
+        ),
+      )
+      const requiresTidx = selection.rpcOnly && query.success && query.data.asOf !== undefined
+      // Raw passthroughs and current RPC-only reads need RPC. Historical
+      // position reads and composed data routes require both upstreams.
       const narrowedChainIds = new Set(
         [...supportedChainIds].filter((chainId) => {
           const context = { chainId, principal, zone: zones.get(chainId) }
           const hasRpc = Viem.resolveRpc(rpc_config, context).url !== undefined
           const hasTidx = Tidx.resolve(tidx_config, context).baseUrl !== undefined
-          if (selection.rpc || selection.rpcOnly) return hasRpc
+          if (selection.rpc || (selection.rpcOnly && !requiresTidx)) return hasRpc
           if (selection.indexer) return hasTidx
           return hasRpc && hasTidx
         }),
@@ -500,7 +509,7 @@ function webhooksBlock() {
             'tempo-event-id',
             'A unique, stable id for this event (`evt_…`). The same event may be delivered more than once, so use this id to skip duplicates.',
           ),
-          header('tempo-event-type', 'What happened: `token:transfer`, `transaction:included`, `log:emitted`, `block:created`, `funding:deposit.updated`, or `ping`.'), // prettier-ignore
+          header('tempo-event-type', 'What happened: `token:transfer`, `transaction:included`, `log:emitted`, `block:created`, `funding:deposit.updated`, `funding:transfer.updated`, or `ping`.'), // prettier-ignore
         ],
         requestBody: {
           content: { 'application/json': { schema: envelope } },

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

@@ -7,6 +7,8 @@ import * as TestEarn from '../../../../test/Earn.js'
 import * as Runtime from '../../../../test/runtime.js'
 import * as Cursor from '../../../internal/Cursor.js'
 import * as Store from '../../../internal/Store.js'
+import * as Tidx from '../../../internal/Tidx.js'
+import * as Value from '../../../internal/Value.js'
 import * as Earn from './earn.js'
 
 /**
@@ -32,7 +34,10 @@ type OpenApiOperation = {
     name?: string
     schema?: { enum?: readonly unknown[]; examples?: readonly unknown[]; pattern?: string }
   }[]
-  responses?: Record<string, { content?: { 'application/json'?: { schema?: OpenApiSchema } } }>
+  responses?: Record<
+    string,
+    { content?: { 'application/json'?: { schema?: OpenApiSchema } }; description?: string }
+  >
 }
 
 type OpenApiDocument = {
@@ -106,6 +111,40 @@ describe('schema.getEarnVaults.Query', () => {
   })
 })
 
+describe('parseIndexedBlockAtOrBefore', () => {
+  test('rejects an empty upstream result before classifying the boundary', () => {
+    expect(() =>
+      Earn.parseIndexedBlockAtOrBefore({
+        asOf: '2026-07-21T09:00:00.000Z',
+        rows: [],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Error: TIDX returned no indexed head for a historical Earn position.]`,
+    )
+  })
+
+  test('classifies a missing boundary only after validating the indexed head', () => {
+    expect(() =>
+      Earn.parseIndexedBlockAtOrBefore({
+        asOf: '2026-07-21T09:00:00.000Z',
+        rows: [{ kind: 'head', num: 10, timestamp: '2026-07-21T10:00:00.000Z' }],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Earn.IndexedBlockNotFoundError: No indexed block exists at or before 2026-07-21T09:00:00.000Z.]`,
+    )
+  })
+})
+
+describe('schema.getEarnVaultPosition.Query', () => {
+  test('accepts offset-bearing ISO 8601 timestamps', () => {
+    expect(
+      Earn.schema.getEarnVaultPosition.Query.parse({
+        asOf: '2026-07-21T10:00:00+01:00',
+      }).asOf,
+    ).toBe('2026-07-21T10:00:00+01:00')
+  })
+})
+
 describe('schema.getEarnAddressPositions.Query', () => {
   test('parses collection filters', () => {
     const query = Earn.schema.getEarnAddressPositions.Query.parse({
@@ -181,6 +220,8 @@ describe('schema.getEarnVaultEarnings.Response', () => {
         lifetimeEarnings: '0',
         period: 'lifetime',
         status: 'complete',
+        totalDeposited: '1000000',
+        totalWithdrawn: '500000',
       }).success,
       pending: Earn.schema.getEarnVaultEarnings.Response.safeParse({
         ...response,
@@ -199,9 +240,10 @@ describe('schema.getEarnVaultEarnings.Response', () => {
       }).success,
       pendingWithEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
         ...response,
-        lifetimeEarnings: '0',
         period: 'lifetime',
         status: 'pending_redemption',
+        totalDeposited: '1000000',
+        totalWithdrawn: '500000',
       }).success,
       window: Earn.schema.getEarnVaultEarnings.Response.safeParse({
         ...response,
@@ -229,10 +271,10 @@ describe('schema.getEarnVaultEarnings.Response', () => {
         "incompleteWindow": true,
         "incompleteWithEarnings": false,
         "lifetime": true,
-        "pending": true,
+        "pending": false,
         "pendingActive": false,
         "pendingWindow": true,
-        "pendingWithEarnings": false,
+        "pendingWithEarnings": true,
         "window": true,
         "windowWithActiveEarnings": false,
         "windowWithoutEarnings": false,
@@ -241,6 +283,75 @@ describe('schema.getEarnVaultEarnings.Response', () => {
   })
 })
 
+describe('serializeVault', () => {
+  test('includes a non-null instant-liquidity valuation with TVL', () => {
+    const assetToken = {
+      address: TestEarn.assetTokenAddress,
+      currency: 'USD',
+      decimals: 6,
+      id: TestEarn.assetTokenAddress,
+      name: 'Bridge Test PATHUSD',
+      symbol: 'btPATHUSD',
+      verified: true,
+    } as const
+    const shareTokenAddress = `0x20c0${'11'.repeat(18)}` as const
+    const vault = Earn.serializeVault({
+      apy: null,
+      assetToken,
+      discovery: {
+        assetToken,
+        chainId: TestEarn.chain.id,
+        engine: { address: TestEarn.vaultAddress, type: 'erc4626', venue: null },
+        instantLiquidity: '500000000',
+        sharePrice: '1000000',
+        shareToken: {
+          address: shareTokenAddress,
+          currency: 'USD',
+          decimals: 6,
+          name: 'Bridge Test PATHUSD Earn',
+          symbol: 'btPATHUSDE',
+        },
+        state: {
+          depositsPaused: false,
+          engineShares: '1000000000',
+          feesActive: true,
+          isAccountingAligned: true,
+          openRedeemRequestCount: 0,
+          totalAssets: '1000000000',
+          totalEarnShares: '1000000000',
+        },
+        vaultAddress: TestEarn.vaultAddress,
+      },
+      include: ['tvl'],
+      instantLiquidityValue: {
+        amount: '500000000',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '500',
+      },
+      shareToken: {
+        address: shareTokenAddress,
+        currency: 'USD',
+        decimals: 6,
+        id: shareTokenAddress,
+        name: 'Bridge Test PATHUSD Earn',
+        symbol: 'btPATHUSDE',
+        verified: false,
+      },
+      tvl: { amount: '1000000000', currency: 'USD', decimals: 6, formatted: '1000' },
+      zoneRoutes: [],
+      zones: [],
+    })
+
+    expect(vault.instantLiquidityValue).toStrictEqual({
+      amount: '500000000',
+      currency: 'USD',
+      decimals: 6,
+      formatted: '500',
+    })
+  })
+})
+
 describe('schema.getEarnVaultEarnings.Query', () => {
   test('defaults to lifetime and accepts active and trailing earnings', () => {
     expect([
@@ -721,6 +832,45 @@ describe('GET /v1/earn/vaults/verified', () => {
 })
 
 describe('GET /v1/earn/addresses/:address/positions', () => {
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'batches lifetime cash flows for multiple positions into one query',
+    async () => {
+      const tidx = Tidx.getClient({
+        chainId: TestEarn.chain.id,
+        tidx: { auth: process.env.TIDX_AUTH, baseUrl: Runtime.get().tidxUrl },
+      })
+      let queryCount = 0
+      const client = new Proxy(tidx, {
+        get(target, property, receiver) {
+          if (property !== 'fetch') return Reflect.get(target, property, receiver)
+          return (...options: Parameters<Tidx.Client['fetch']>) => {
+            queryCount += 1
+            return target.fetch(...options)
+          }
+        },
+      })
+      const emptyVault = Schema.Address.parse(`0x${'11'.repeat(20)}`)
+      const cashFlows = await Earn.getVaultLifetimeCashFlows(client, {
+        account: TestEarn.earningsAddress,
+        blockNumber: 1_000_000_000,
+        vaults: [TestEarn.vaultAddress, emptyVault],
+      })
+
+      expect(queryCount).toBe(1)
+      expect(cashFlows.get(TestEarn.vaultAddress)).toMatchObject({
+        status: 'complete',
+        totalDeposited: expect.stringMatching(/^[1-9]\d*$/),
+        totalWithdrawn: expect.stringMatching(/^\d+$/),
+      })
+      expect(cashFlows.get(emptyVault)).toStrictEqual({
+        status: 'complete',
+        totalDeposited: '0',
+        totalWithdrawn: '0',
+      })
+    },
+    60_000,
+  )
+
   test('returns chain selection errors', async () => {
     const app = TestApp.create({ auth: false, cache })
     const invalid = await app.request(
@@ -750,7 +900,7 @@ describe('GET /v1/earn/addresses/:address/positions', () => {
   test('returns an empty verified page without curated vaults', async () => {
     const app = TestApp.create({ auth: false, cache })
     const response = await app.request(
-      `/v1/earn/addresses/${TestEarn.positionAddress}/positions?verified=true`,
+      `/v1/earn/addresses/${TestEarn.positionAddress}/positions?include=earnings&verified=true`,
     )
 
     expect(response.status).toBe(200)
@@ -774,7 +924,7 @@ describe('GET /v1/earn/addresses/:address/positions', () => {
       })
       const app = TestApp.create({ auth: false, cache, db, zones: [TestEarn.zone] })
       const response = await app.request(
-        `/v1/earn/addresses/${TestEarn.activeEarningsAddress}/positions?chainId=${TestEarn.chain.id}&verified=true&valuation.currency=USD`,
+        `/v1/earn/addresses/${TestEarn.activeEarningsAddress}/positions?chainId=${TestEarn.chain.id}&include=earnings&verified=true&valuation.currency=USD`,
       )
 
       expect(response.status).toBe(200)
@@ -790,6 +940,7 @@ describe('GET /v1/earn/addresses/:address/positions', () => {
       expect(row.shareAmount.decimals).toBe(row.shareToken.decimals)
       expect(row.assetAmount.currency).toBe(row.assetToken.currency)
       expect(row.assetAmount.decimals).toBe(row.assetToken.decimals)
+      expect(row.lifetimeCashFlows?.status).toMatch(/^(complete|incomplete_history)$/)
       // A USD-denominated asset values identically without consulting rates.
       expect(row.valuation).toStrictEqual({ amount: row.assetAmount.formatted, currency: 'USD' })
       expect(body.meta).toBeUndefined()
@@ -1008,6 +1159,7 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
         // The pinned venue exposes no withdrawal-limit view, so liquidity is
         // absent rather than a restatement of the backing.
         instantLiquidity: vault.instantLiquidity,
+        instantLiquidityValue: vault.instantLiquidityValue,
         isAccountingAligned: vault.state.isAccountingAligned,
         openRedeemRequestCount: vault.state.openRedeemRequestCount,
         pricedPerShare: vault.sharePrice !== null && BigInt(vault.sharePrice.amount) > 0n,
@@ -1019,6 +1171,7 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
           "engineType": "erc4626",
           "feesActive": true,
           "instantLiquidity": null,
+          "instantLiquidityValue": null,
           "isAccountingAligned": true,
           "openRedeemRequestCount": 0,
           "pricedPerShare": true,
@@ -1089,16 +1242,22 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
   )
 
   test.runIf(Runtime.get().mode === 'testnet')(
-    'leaves the rate unmeasured before the vault was deployed',
+    'leaves the rate unmeasured when the window starts before deployment',
     async () => {
-      const app = TestApp.create({ auth: false, cache, zones: [TestEarn.zone] })
-      const response = await app.request(
-        `/v1/earn/vaults/${TestEarn.vaultAddress}?chainId=${TestEarn.chain.id}&apy.window=30d`,
-      )
+      // This vault was deployed on 2026-07-23, so the pinned window begins before deployment.
+      vi.useFakeTimers({ now: new Date('2026-07-24T10:00:00Z'), toFake: ['Date'] })
+      try {
+        const app = TestApp.create({ auth: false, cache, zones: [TestEarn.zone] })
+        const response = await app.request(
+          `/v1/earn/vaults/${TestEarn.vaultAddress}?chainId=${TestEarn.chain.id}&apy.window=30d`,
+        )
 
-      expect(response.status).toBe(200)
-      const vault = await TestApp.json(response, Earn.schema.getEarnVault.Response)
-      expect(vault.apy).toBeNull()
+        expect(response.status).toBe(200)
+        const vault = await TestApp.json(response, Earn.schema.getEarnVault.Response)
+        expect(vault.apy).toBeNull()
+      } finally {
+        vi.useRealTimers()
+      }
     },
     60_000,
   )
@@ -1300,6 +1459,25 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
 })
 
 describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
+  test('rejects invalid as-of timestamps', async () => {
+    const app = TestApp.create({ auth: false, cache })
+    const [malformed, unix] = await Promise.all([
+      app.request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?asOf=not-a-time`,
+      ),
+      app.request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?asOf=1787312400`,
+      ),
+    ])
+
+    for (const response of [malformed, unix]) {
+      expect(response.status).toBe(400)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: { code: 'query_invalid' },
+      })
+    }
+  })
+
   test('returns chain selection errors', async () => {
     const app = TestApp.create({ auth: false, cache })
     const invalid = await app.request(
@@ -1329,6 +1507,59 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
     })
   })
 
+  test('requires TIDX for historical reads on an RPC-only chain', async () => {
+    const response = await TestApp.create({
+      auth: false,
+      cache,
+      rpc: { url: { 31_337: 'http://127.0.0.1:1' } },
+      tidx: {},
+    }).request(
+      `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=31337&asOf=2026-07-21T09%3A00Z`,
+    )
+
+    expect(response.status).toBe(400)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: { code: 'chain_id_unsupported' },
+    })
+  })
+
+  test('validates malformed historical timestamps on an RPC-only chain', async () => {
+    const response = await TestApp.create({
+      auth: false,
+      cache,
+      rpc: { url: { 31_337: 'http://127.0.0.1:1' } },
+      tidx: {},
+    }).request(
+      `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=31337&asOf=not-a-time`,
+    )
+
+    expect(response.status).toBe(400)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: { code: 'query_invalid' },
+    })
+  })
+
+  test('validates the complete historical query on an RPC-only chain', async () => {
+    const app = TestApp.create({
+      auth: false,
+      cache,
+      rpc: { url: { 31_337: 'http://127.0.0.1:1' } },
+      tidx: {},
+    })
+    const path = `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=31337&asOf=2026-07-21T09%3A00Z`
+    const [duplicate, unknown] = await Promise.all([
+      app.request(`${path}&asOf=2026-07-21T10%3A00Z`),
+      app.request(`${path}&unknown=1`),
+    ])
+
+    for (const response of [duplicate, unknown]) {
+      expect(response.status).toBe(400)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: { code: 'query_invalid' },
+      })
+    }
+  })
+
   test('rejects malformed vault position parameters', async () => {
     const response = await TestApp.create({ auth: false, cache }).request(
       '/v1/earn/vaults/not-an-address/positions/not-an-address',
@@ -1349,6 +1580,7 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
       )
 
       expect(response.status).toBe(200)
+      expect(response.headers.get('cache-control')).toBe('no-store')
       const position = await TestApp.json(response, Earn.schema.getEarnVaultPosition.Response)
       expect({
         account: position.account,
@@ -1389,6 +1621,107 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
     },
     60_000,
   )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'returns a position as of an indexed ISO 8601 timestamp',
+    async () => {
+      const runtime = Runtime.get()
+      const tidx = Tidx.getClient({
+        chainId: runtime.chainId,
+        tidx: { auth: process.env.TIDX_AUTH, baseUrl: runtime.tidxUrl },
+      })
+      const indexed = await tidx.fetch({
+        engine: 'clickhouse',
+        query: 'SELECT num, timestamp FROM blocks ORDER BY num DESC LIMIT 1 OFFSET 100',
+      })
+      const blockNumber = Value.toNumber(indexed.rows[0]?.['num'])
+      const asOf = Value.toIsoDateTime(indexed.rows[0]?.['timestamp'])
+      if (blockNumber === undefined || asOf === undefined)
+        throw new Error('expected an indexed block')
+      const response = await TestApp.create({ auth: false, cache }).request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.chain.id}&asOf=${encodeURIComponent(asOf)}`,
+      )
+
+      expect(response.status).toBe(200)
+      const position = await TestApp.json(response, Earn.schema.getEarnVaultPosition.Response)
+      expect(position.asOf).toBe(asOf)
+      expect(position.block?.number).toBeGreaterThanOrEqual(blockNumber)
+      expect(position.block?.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/)
+      expect(Date.parse(position.block?.timestamp ?? '')).toBeLessThanOrEqual(Date.parse(asOf))
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'returns not found before the vault was deployed',
+    async () => {
+      const runtime = Runtime.get()
+      const tidx = Tidx.getClient({
+        chainId: runtime.chainId,
+        tidx: { auth: process.env.TIDX_AUTH, baseUrl: runtime.tidxUrl },
+      })
+      const indexed = await tidx.fetch({
+        engine: 'clickhouse',
+        query: 'SELECT timestamp FROM blocks ORDER BY num ASC LIMIT 1',
+      })
+      const asOf = Value.toIsoDateTime(indexed.rows[0]?.['timestamp'])
+      if (asOf === undefined) throw new Error('expected the pre-deployment block to be indexed')
+      const response = await TestApp.create({ auth: false, cache }).request(
+        `/v1/earn/vaults/${TestEarn.indexedDeployment.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.chain.id}&asOf=${encodeURIComponent(asOf)}`,
+      )
+
+      expect(response.status).toBe(404)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: { code: 'earn_vault_not_found' },
+      })
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'returns not found for a deployed incompatible contract at a historical block',
+    async () => {
+      const runtime = Runtime.get()
+      const tidx = Tidx.getClient({
+        chainId: runtime.chainId,
+        tidx: { auth: process.env.TIDX_AUTH, baseUrl: runtime.tidxUrl },
+      })
+      const indexed = await tidx.fetch({
+        engine: 'clickhouse',
+        query: 'SELECT timestamp FROM blocks ORDER BY num DESC LIMIT 1',
+      })
+      const asOf = Value.toIsoDateTime(indexed.rows[0]?.['timestamp'])
+      if (asOf === undefined) throw new Error('expected an indexed block')
+      const response = await TestApp.create({ auth: false, cache }).request(
+        `/v1/earn/vaults/${TestEarn.assetTokenAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.chain.id}&asOf=${encodeURIComponent(asOf)}`,
+      )
+
+      expect(response.status).toBe(404)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: { code: 'earn_vault_not_found' },
+      })
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'rejects timestamps beyond indexed coverage',
+    async () => {
+      const asOf = new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()
+      const response = await TestApp.create({ auth: false, cache }).request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.chain.id}&asOf=${encodeURIComponent(asOf)}`,
+      )
+
+      expect(response.status).toBe(400)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: {
+          code: 'query_invalid',
+          message: `Indexed history does not yet cover ${asOf}.`,
+        },
+      })
+    },
+    60_000,
+  )
 })
 
 describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
@@ -1437,6 +1770,8 @@ describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
         lifetimeEarnings: expect.stringMatching(/^-?\d+$/),
         period: 'lifetime',
         status: 'complete',
+        totalDeposited: expect.stringMatching(/^\d+$/),
+        totalWithdrawn: expect.stringMatching(/^\d+$/),
       })
     },
     60_000,
@@ -1747,6 +2082,9 @@ describe('OpenAPI', () => {
     expect(JSON.stringify(include?.schema)).toContain('"apy"')
     expect(JSON.stringify(include?.schema)).toContain('"tvl"')
     expect(JSON.stringify(include?.schema)).toContain('"zones"')
+    expect(JSON.stringify(spec.paths['/v1/earn/vaults/{vaultId}']?.get?.responses)).toContain(
+      'Instant liquidity valued in USD',
+    )
   })
 
   test('documents vault-position inputs and responses', async () => {
@@ -1754,6 +2092,7 @@ describe('OpenAPI', () => {
     const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
     const operation = spec.paths['/v1/earn/vaults/{vaultId}/positions/{address}']?.get
     const address = operation?.parameters?.find((parameter) => parameter.name === 'address')
+    const asOf = operation?.parameters?.find((parameter) => parameter.name === 'asOf')
     const errors = errorSchemas(spec, operation)
     const response = JSON.stringify(operation?.responses)
     const vaultId = operation?.parameters?.find((parameter) => parameter.name === 'vaultId')
@@ -1767,6 +2106,17 @@ describe('OpenAPI', () => {
     expect(response).toContain('0x20c000000000000000000000b9537d11c60e8b50')
     expect(response).toContain('0x20c000000000000000000000300e14ab91a10769')
     expect(address?.schema?.examples).toStrictEqual([TestEarn.positionAddress])
+    expect(asOf?.description).toContain('latest indexed block at or before')
+    expect(asOf?.schema?.examples).toStrictEqual(['2026-07-21T09:00:00.000Z'])
+    expect(response).toContain('Indexed block used for a historical Earn position observation')
+    expect(response).toContain('Assets held by this account at the observation block')
+    expect(response).toContain('Earn shares held by this account at the observation block')
+    expect(response).toContain('Asset value of this account’s earn shares at the observation block')
+    expect(response).not.toContain('Assets this account currently holds')
+    expect(response).not.toContain('Earn shares this account currently holds')
+    expect(operation?.responses?.['200']?.description).toBe(
+      'Current or historical earn position for one account in one vault.',
+    )
     expect(vaultId?.schema?.examples).toStrictEqual([TestEarn.mainnetVaultAddress])
   })
 
@@ -1778,6 +2128,7 @@ describe('OpenAPI', () => {
     const denomination = operation?.parameters?.find(
       (parameter) => parameter.name === 'valuation.currency',
     )
+    const include = operation?.parameters?.find((parameter) => parameter.name === 'include')
     const verified = operation?.parameters?.find((parameter) => parameter.name === 'verified')
     const errors = errorSchemas(spec, operation)
     const response = JSON.stringify(operation?.responses)
@@ -1786,6 +2137,7 @@ describe('OpenAPI', () => {
     expect(operation?.description).toContain('currently holds shares')
     expect(address?.schema?.examples).toStrictEqual([TestEarn.positionAddress])
     expect(denomination?.description).toContain('nominal value')
+    expect(include?.description).toContain('`earnings`')
     expect(verified?.description).toContain('registry-curated')
     expect(verified?.schema?.examples).toStrictEqual([true])
     expect(errors).toContain('"chain_id_invalid"')
@@ -1796,6 +2148,7 @@ describe('OpenAPI', () => {
     expect(response).toContain('Current asset value of the held shares')
     expect(response).toContain('"assetAmount"')
     expect(response).toContain('"shareAmount"')
+    expect(response).toContain('"lifetimeCashFlows"')
     expect(response).toContain('"valuation"')
     expect(response).toContain('"vaultAddress"')
     expect(response).toContain('"nextCursor"')
@@ -1819,6 +2172,8 @@ describe('OpenAPI', () => {
     expect(errors).toContain('"earn_vault_not_found"')
     expect(response).toContain('Stable resource ID for these vault earnings')
     expect(response).toContain('Current share value plus completed redemptions')
+    expect(response).toContain('Assets deposited with this account as receiver')
+    expect(response).toContain('Assets returned by completed redemptions')
     expect(response).toContain('weighted-average asset cost basis')
     expect(response).toContain('Ending share value plus realized assets')
     expect(response).toContain('cannot reconstruct the asset cost basis for the requested period')