tapimo 0.13.0 → 0.15.0

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

@@ -1,12 +1,22 @@
-import { Schema } from 'tapimo'
+import { Db, Schema } from 'tapimo/server'
 import type * as z from 'zod/mini'
 
+import * as Scope from '../../../Scope.js'
 import * as core_EarnVaults from '../../../db/tables/earnVaults.js'
+import * as RewardAccounts from '../../../db/tables/rewardAccounts.js'
+import * as RewardCampaigns from '../../../db/tables/rewardCampaigns.js'
+import * as RewardEligibilityAssociations from '../../../db/tables/rewardEligibilityAssociations.js'
 import * as TestApp from '../../../../test/App.js'
 import * as TestEarn from '../../../../test/Earn.js'
 import * as Runtime from '../../../../test/runtime.js'
 import * as Cursor from '../../../internal/Cursor.js'
+import * as EarnSharePrices from '../../../internal/EarnSharePrices.js'
+import type * as Log from '../../../internal/Log.js'
 import * as Store from '../../../internal/Store.js'
+import * as Tidx from '../../../internal/Tidx.js'
+import * as Ttl from '../../../internal/Ttl.js'
+import * as Value from '../../../internal/Value.js'
+import * as Viem from '../../../internal/Viem.js'
 import * as Earn from './earn.js'
 
 /**
@@ -27,12 +37,21 @@ type OpenApiSchema = { $ref?: string }
 
 type OpenApiOperation = {
   description?: string
+  operationId?: string
   parameters?: readonly {
     description?: string
     name?: string
-    schema?: { enum?: readonly unknown[]; examples?: readonly unknown[]; pattern?: string }
+    schema?: {
+      const?: unknown
+      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 = {
@@ -41,6 +60,7 @@ type OpenApiDocument = {
     string,
     {
       get?: OpenApiOperation
+      post?: OpenApiOperation
     }
   >
 }
@@ -57,6 +77,435 @@ function errorSchemas(document: OpenApiDocument, operation: OpenApiOperation | u
   )
 }
 
+function successSchema(operation: OpenApiOperation | undefined) {
+  return operation?.responses?.['200']?.content?.['application/json']?.schema
+}
+
+function resolveSchema(
+  document: OpenApiDocument,
+  value: unknown,
+  seen: ReadonlySet<string> = new Set(),
+): unknown {
+  if (Array.isArray(value)) return value.map((item) => resolveSchema(document, item, seen))
+  if (!value || typeof value !== 'object') return value
+  const object = value as Record<string, unknown>
+  if (typeof object['$ref'] === 'string') {
+    const name = object['$ref'].split('/').at(-1)
+    if (!name || seen.has(name)) return value
+    return resolveSchema(document, document.components?.schemas?.[name], new Set([...seen, name]))
+  }
+  return Object.fromEntries(
+    Object.entries(object).map(([key, item]) => [key, resolveSchema(document, item, seen)]),
+  )
+}
+
+describe('schema.registerRewardEligibility.Body', () => {
+  test('parses a reward eligibility registration', () => {
+    expect(
+      Earn.schema.registerRewardEligibility.Body.parse({
+        chainId: 4217,
+        vaultAddress: `0x${'11'.repeat(20)}`,
+        walletAddress: `0x${'22'.repeat(20)}`,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "chainId": 4217,
+        "vaultAddress": "0x1111111111111111111111111111111111111111",
+        "walletAddress": "0x2222222222222222222222222222222222222222",
+      }
+    `)
+  })
+
+  test('rejects missing, invalid, and unknown fields', () => {
+    expect({
+      invalidAddress: Earn.schema.registerRewardEligibility.Body.safeParse({
+        chainId: 4217,
+        vaultAddress: `0x${'11'.repeat(20)}`,
+        walletAddress: 'invalid',
+      }).success,
+      invalidChainId: Earn.schema.registerRewardEligibility.Body.safeParse({
+        chainId: 0,
+        vaultAddress: `0x${'11'.repeat(20)}`,
+        walletAddress: `0x${'22'.repeat(20)}`,
+      }).success,
+      invalidTransactionHash: Earn.schema.registerRewardEligibility.Body.safeParse({
+        chainId: 4217,
+        transactionHash: '0x1234',
+        vaultAddress: `0x${'11'.repeat(20)}`,
+        walletAddress: `0x${'22'.repeat(20)}`,
+      }).success,
+      missing: Earn.schema.registerRewardEligibility.Body.safeParse({
+        chainId: 4217,
+        vaultAddress: `0x${'11'.repeat(20)}`,
+      }).success,
+      unknown: Earn.schema.registerRewardEligibility.Body.safeParse({
+        chainId: 4217,
+        source: 'other',
+        sourceInteractionId: 'interaction_1',
+        transactionHash: `0x${'33'.repeat(32)}`,
+        vaultAddress: `0x${'11'.repeat(20)}`,
+        walletAddress: `0x${'22'.repeat(20)}`,
+      }).success,
+    }).toEqual({
+      invalidAddress: false,
+      invalidChainId: false,
+      invalidTransactionHash: false,
+      missing: false,
+      unknown: false,
+    })
+  })
+})
+
+describe('schema.getRewardEligibility.Query', () => {
+  test('accepts up to 100 items per page', () => {
+    expect([
+      Earn.schema.getRewardEligibility.Query.parse({
+        chainId: 4217,
+        limit: '100',
+        vaultAddress: `0x${'11'.repeat(20)}`,
+      }).limit,
+      Earn.schema.getRewardEligibility.Query.parse({
+        chainId: 4217,
+        limit: '101',
+        vaultAddress: `0x${'11'.repeat(20)}`,
+      }).limit,
+    ]).toMatchInlineSnapshot(`
+      [
+        100,
+        100,
+      ]
+    `)
+  })
+})
+
+describe('POST /v1/earn/rewards/eligibility', () => {
+  const body = {
+    chainId: Viem.chainId.mainnet,
+    transactionHash: Schema.Hash.parse(`0x${'33'.repeat(32)}`),
+    vaultAddress: `0x${'Aa'.repeat(20)}`,
+    walletAddress: `0x${'Bb'.repeat(20)}`,
+  }
+  const legacyKey = {
+    id: 'key_rewards_writer',
+    orgId: 'org_test',
+    scopes: ['rewards:write'],
+    token: 'secret_rewards_writer',
+  } satisfies TestApp.kvStore.Key
+  const superAdminSecret = 'secret_rewards_super_admin'
+  const auth = { headers: { authorization: `Bearer ${superAdminSecret}` } }
+
+  test('is omitted from public OpenAPI documentation', async () => {
+    const app = TestApp.create()
+    // SAFETY: `/openapi.json` is the app's generated OpenAPI document.
+    const document = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+
+    expect(document.paths['/v1/earn/rewards/eligibility']?.post).toBeUndefined()
+  })
+
+  test('requires authentication', async () => {
+    const response = await TestApp.create().request('/v1/earn/rewards/eligibility', {
+      body: JSON.stringify(body),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(401)
+  })
+
+  test('rejects an ordinary authenticated key', async () => {
+    const response = await TestApp.create().request('/v1/earn/rewards/eligibility', {
+      ...TestApp.auth,
+      body: JSON.stringify(body),
+      headers: { ...TestApp.auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(403)
+  })
+
+  test('rejects a legacy rewards writer key', async () => {
+    const response = await TestApp.create({ auth: { keys: [legacyKey] } }).request(
+      '/v1/earn/rewards/eligibility',
+      {
+        body: JSON.stringify(body),
+        headers: {
+          authorization: `Bearer ${legacyKey.token}`,
+          'content-type': 'application/json',
+        },
+        method: 'POST',
+      },
+    )
+
+    expect(response.status).toBe(403)
+  })
+
+  test('accepts a provisioned wildcard key', async () => {
+    const key = {
+      id: 'key_rewards_operator',
+      orgId: 'org_tempo',
+      scopes: [Scope.wildcard],
+      token: 'secret_rewards_operator',
+    } satisfies TestApp.kvStore.Key
+    const response = await TestApp.create({ auth: { keys: [key] } }).request(
+      '/v1/earn/rewards/eligibility',
+      {
+        body: JSON.stringify(body),
+        headers: {
+          authorization: `Bearer ${key.token}`,
+          'content-type': 'application/json',
+        },
+        method: 'POST',
+      },
+    )
+
+    expect(response.status).toBe(200)
+  })
+
+  test('persists the first write and idempotently refreshes a replay', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({ auth: { superAdmin: { secret: superAdminSecret } }, db })
+    const request = (input = body) =>
+      app.request('/v1/earn/rewards/eligibility', {
+        ...auth,
+        body: JSON.stringify(input),
+        headers: { ...auth.headers, 'content-type': 'application/json' },
+        method: 'POST',
+      })
+
+    const first = await TestApp.json(
+      await request(),
+      Earn.schema.registerRewardEligibility.Response,
+    )
+    const replay = await TestApp.json(
+      await request({
+        ...body,
+        transactionHash: `0x${'44'.repeat(32)}`,
+      }),
+      Earn.schema.registerRewardEligibility.Response,
+    )
+
+    expect({ first, replay }).toMatchObject({
+      first: {
+        association: {
+          vaultAddress: body.vaultAddress.toLowerCase(),
+          walletAddress: body.walletAddress.toLowerCase(),
+        },
+        created: true,
+      },
+      replay: {
+        association: {
+          firstRegisteredAt: first.association.firstRegisteredAt,
+          transactionHash: `0x${'44'.repeat(32)}`,
+        },
+        created: false,
+      },
+    })
+  })
+
+  test('rejects invalid and unsupported chain input', async () => {
+    const app = TestApp.create({ auth: { superAdmin: { secret: superAdminSecret } } })
+    const invalid = await app.request('/v1/earn/rewards/eligibility', {
+      ...auth,
+      body: JSON.stringify({ ...body, walletAddress: 'invalid' }),
+      headers: { ...auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+    const unsupported = await app.request('/v1/earn/rewards/eligibility', {
+      ...auth,
+      body: JSON.stringify({ ...body, chainId: 9_999_999 }),
+      headers: { ...auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect([invalid.status, unsupported.status]).toEqual([400, 400])
+  })
+
+  test('accepts supported chains without data upstreams', async () => {
+    const chainId = 31_337
+    const response = await TestApp.create({
+      auth: { superAdmin: { secret: superAdminSecret } },
+      rpc: { url: {} },
+      supportedChainIds: [chainId],
+      tidx: { baseUrl: {} },
+    }).request('/v1/earn/rewards/eligibility', {
+      ...auth,
+      body: JSON.stringify({ ...body, chainId }),
+      headers: { ...auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(200)
+  })
+
+  test('accepts configured Zones for super admins', async () => {
+    const zone = TestApp.zone({
+      chainId: 421_700_001,
+      rpcUrl: 'https://zone.example',
+    })
+    const response = await TestApp.create({
+      auth: { superAdmin: { secret: superAdminSecret } },
+      zones: [zone],
+    }).request('/v1/earn/rewards/eligibility', {
+      ...auth,
+      body: JSON.stringify({ ...body, chainId: zone.id }),
+      headers: { ...auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(200)
+  })
+
+  test('surfaces database failures as operational errors', async () => {
+    const app = TestApp.create({
+      auth: { superAdmin: { secret: superAdminSecret } },
+      db: () => {
+        throw new Error('database unavailable')
+      },
+    })
+    const response = await app.request('/v1/earn/rewards/eligibility', {
+      ...auth,
+      body: JSON.stringify(body),
+      headers: { ...auth.headers, 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toBe(500)
+  })
+})
+
+describe('GET /v1/earn/rewards/eligibility', () => {
+  const readKey = {
+    id: 'key_rewards_reader',
+    orgId: 'org_test',
+    scopes: ['rewards:read'],
+    token: 'secret_rewards_reader',
+  } satisfies TestApp.kvStore.Key
+  const vaultAddress = Schema.Address.parse(`0x${'Aa'.repeat(20)}`)
+  const input = {
+    chainId: Viem.chainId.mainnet,
+    transactionHash: Schema.Hash.parse(`0x${'33'.repeat(32)}`),
+    vaultAddress,
+    walletAddress: Schema.Address.parse(`0x${'Bb'.repeat(20)}`),
+  } as const
+
+  test('is omitted from public OpenAPI documentation', async () => {
+    const app = TestApp.create({ auth: { keys: [readKey] } })
+    // SAFETY: `/openapi.json` is the app's generated OpenAPI document.
+    const document = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+
+    expect(document.paths['/v1/earn/rewards/eligibility']?.get).toBeUndefined()
+  })
+
+  test('requires the read scope', async () => {
+    const response = await TestApp.create().request(
+      `/v1/earn/rewards/eligibility?chainId=4217&vaultAddress=${vaultAddress}`,
+      TestApp.auth,
+    )
+
+    expect(response.status).toBe(403)
+  })
+
+  test('reads supported chains without data upstreams', async () => {
+    const chainId = 31_337
+    const db = TestApp.database()
+    await RewardEligibilityAssociations.upsert(db, { ...input, chainId })
+    const response = await TestApp.create({
+      auth: { keys: [readKey] },
+      db,
+      rpc: { url: {} },
+      supportedChainIds: [chainId],
+      tidx: { baseUrl: {} },
+    }).request(`/v1/earn/rewards/eligibility?chainId=${chainId}&vaultAddress=${vaultAddress}`, {
+      headers: { authorization: `Bearer ${readKey.token}` },
+    })
+
+    expect(response.status).toBe(200)
+  })
+
+  test('rejects sandbox reads from mainnet-backed Zones', async () => {
+    const zone = TestApp.zone({
+      chainId: 421_700_001,
+      rpcUrl: 'https://mainnet-zone.example',
+      sourceChainId: Viem.chainId.mainnet,
+    })
+    const key = {
+      ...readKey,
+      environment: 'sandbox',
+      scopes: [...readKey.scopes, `zone:${zone.id}:read`],
+    } satisfies TestApp.kvStore.Key
+    const response = await TestApp.create({ auth: { keys: [key] }, zones: [zone] }).request(
+      `/v1/earn/rewards/eligibility?chainId=${zone.id}&vaultAddress=${vaultAddress}`,
+      { headers: { authorization: `Bearer ${key.token}` } },
+    )
+
+    expect(response.status).toBe(403)
+  })
+
+  test('rejects sandbox reads from Zones without a source chain', async () => {
+    const { sourceId: _sourceId, ...zone } = TestApp.zone({
+      chainId: 421_700_001,
+      rpcUrl: 'https://unknown-zone.example',
+    })
+    const key = {
+      ...readKey,
+      environment: 'sandbox',
+      scopes: [...readKey.scopes, `zone:${zone.id}:read`],
+    } satisfies TestApp.kvStore.Key
+    const response = await TestApp.create({ auth: { keys: [key] }, zones: [zone] }).request(
+      `/v1/earn/rewards/eligibility?chainId=${zone.id}&vaultAddress=${vaultAddress}`,
+      { headers: { authorization: `Bearer ${key.token}` } },
+    )
+
+    expect(response.status).toBe(403)
+  })
+
+  test('returns checkpointed pages that exclude later registrations', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({ auth: { keys: [readKey] }, db })
+    const wallets = ['bb', 'cc', 'dd', 'ee', 'ff', '11']
+    for (const wallet of wallets)
+      await RewardEligibilityAssociations.upsert(db, {
+        ...input,
+        walletAddress: Schema.Address.parse(`0x${wallet.repeat(20)}`),
+      })
+    const request = (cursor?: string) => {
+      const query = new URLSearchParams({
+        chainId: String(input.chainId),
+        limit: '5',
+        vaultAddress,
+      })
+      if (cursor) query.set('cursor', cursor)
+      return app.request(`/v1/earn/rewards/eligibility?${query}`, {
+        headers: { authorization: `Bearer ${readKey.token}` },
+      })
+    }
+
+    const first = await TestApp.json(await request(), Earn.schema.getRewardEligibility.Response)
+    await RewardEligibilityAssociations.upsert(db, {
+      ...input,
+      walletAddress: Schema.Address.parse(`0x${'22'.repeat(20)}`),
+    })
+    if (!first.nextCursor) throw new Error('Expected another eligibility page.')
+    const next = await TestApp.json(
+      await request(first.nextCursor),
+      Earn.schema.getRewardEligibility.Response,
+    )
+
+    expect({ first, next }).toMatchObject({
+      first: {
+        chainId: input.chainId,
+        data: wallets.slice(0, 5).map((wallet) => `0x${wallet.repeat(20)}`),
+        vaultAddress,
+      },
+      next: {
+        chainId: input.chainId,
+        data: [`0x${'11'.repeat(20)}`],
+        nextCursor: null,
+        vaultAddress,
+      },
+    })
+  })
+})
 describe('schema.getEarnVaults.Query', () => {
   test('parses collection filters', () => {
     const query = Earn.schema.getEarnVaults.Query.parse({
@@ -106,6 +555,64 @@ 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.getEarnVaultSharePrices.Query', () => {
+  test('defaults to daily observations and accepts a 31-point range', () => {
+    expect(
+      Earn.schema.getEarnVaultSharePrices.Query.parse({
+        from: '2026-01-01T00:00:00Z',
+        to: '2026-01-31T00:00:00Z',
+      }).interval,
+    ).toBe('day')
+  })
+
+  test('rejects reversed and oversized ranges', () => {
+    expect({
+      oversized: Earn.schema.getEarnVaultSharePrices.Query.safeParse({
+        from: '2026-01-01T00:00:00Z',
+        to: '2026-02-01T00:00:00Z',
+      }).success,
+      reversed: Earn.schema.getEarnVaultSharePrices.Query.safeParse({
+        from: '2026-01-02T00:00:00Z',
+        to: '2026-01-01T00:00:00Z',
+      }).success,
+    }).toEqual({ oversized: false, reversed: false })
+  })
+})
+
+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({
@@ -133,6 +640,32 @@ describe('schema.getEarnAddressPositions.Query', () => {
   })
 })
 
+describe('schema.getEarnVaultPosition.Response', () => {
+  test('accepts distinct position and value tokens', () => {
+    const position = {
+      account: TestEarn.positionAddress,
+      assetAllowance: '0',
+      assetBalance: '250000000',
+      assetToken: TestEarn.assetTokenAddress,
+      chainId: TestEarn.chain.id,
+      id: TestEarn.positionAddress,
+      shareAllowance: '0',
+      shareBalance: '99500000',
+      shareToken: `0x20c0${'11'.repeat(18)}`,
+      value: '100000000',
+      valueToken: TestEarn.assetTokenAddress,
+    }
+
+    expect(
+      Earn.schema.getEarnVaultPosition.Response.safeParse({
+        ...position,
+        chainId: TestEarn.zone.id,
+        valueToken: `0x20c0${'22'.repeat(18)}`,
+      }).success,
+    ).toBe(true)
+  })
+})
+
 describe('schema.getEarnVaultEarnings.Response', () => {
   test('enforces status-specific earnings fields', () => {
     const response = {
@@ -181,6 +714,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 +734,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 +765,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 +777,197 @@ describe('schema.getEarnVaultEarnings.Response', () => {
   })
 })
 
+describe('alignZoneSourceBlock', () => {
+  test('caps Zone reports at the L1 portal watermark', () => {
+    expect([
+      Earn.alignZoneSourceBlock({ reported: 122n, verified: 123n }),
+      Earn.alignZoneSourceBlock({ reported: 124n, verified: 123n }),
+      Earn.alignZoneSourceBlock({ verified: 123n }),
+    ]).toStrictEqual([122n, 123n, 123n])
+  })
+})
+
+describe('serializeVault', () => {
+  test('includes valuations and uses the reward target as the net APY floor', () => {
+    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 options = {
+      apy: {
+        asOf: '2026-08-26T14:00:00.000Z',
+        methodology: 'share-price-growth-annualized:v1',
+        net: '0.041200',
+        window: '7d',
+      },
+      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: ['apy', 'tvl'],
+      instantLiquidityValue: {
+        amount: '500000000',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '500',
+      },
+      rewards: [
+        {
+          asset: {
+            address: shareTokenAddress,
+            chainId: TestEarn.chain.id,
+            decimals: 6,
+          },
+          calculatedThrough: 1788134700,
+          campaignId: 'rewards-test-moderato-boost-rewards',
+          currentRewardsAprBps: 195,
+          endsAt: 1790812800,
+          startsAt: 1788134400,
+          targetTotalAprBps: 700,
+        },
+      ],
+      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: [],
+    } satisfies Earn.serializeVault.Options
+    const vault = Earn.serializeVault(options)
+
+    expect(vault.instantLiquidityValue).toStrictEqual({
+      amount: '500000000',
+      currency: 'USD',
+      decimals: 6,
+      formatted: '500',
+    })
+    expect(vault.apy).toMatchInlineSnapshot(`
+      {
+        "asOf": "2026-08-26T14:00:00.000Z",
+        "methodology": "share-price-growth-annualized:v1",
+        "net": "0.0700",
+        "rewards": [
+          {
+            "apr": "0.0195",
+            "asset": {
+              "address": "0x20c0111111111111111111111111111111111111",
+              "chainId": 42431,
+              "decimals": 6,
+            },
+            "calculatedThrough": 1788134700,
+            "campaignId": "rewards-test-moderato-boost-rewards",
+            "endsAt": 1790812800,
+            "startsAt": 1788134400,
+            "targetTotalApr": "0.0700",
+          },
+        ],
+        "vault": "0.041200",
+        "window": "7d",
+      }
+    `)
+    const reward = options.rewards[0]
+    if (!reward) throw new Error('Expected reward fixture.')
+    // Rewards cannot produce a complete APY without a measured vault component.
+    expect(
+      Earn.serializeVault({
+        ...options,
+        apy: null,
+        rewards: [{ ...reward, currentRewardsAprBps: 700 }],
+      }).apy,
+    ).toBeNull()
+    expect(
+      Earn.serializeVault({
+        ...options,
+        apy: null,
+        rewards: [{ ...reward, currentRewardsAprBps: null }],
+      }).apy,
+    ).toBeNull()
+    expect(Earn.serializeVault({ ...options, apy: null, rewards: undefined }).apy).toBeNull()
+    expect(
+      Earn.serializeVault({
+        ...options,
+        rewards: [
+          ...options.rewards,
+          {
+            ...reward,
+            campaignId: 'second-reward',
+            currentRewardsAprBps: 5,
+            targetTotalAprBps: 800,
+          },
+        ],
+      }).apy?.net,
+    ).toBe('0.0800')
+    expect(Earn.serializeVault({ ...options, rewards: undefined }).apy).toMatchObject({
+      net: '0.041200',
+      vault: '0.041200',
+    })
+    expect(
+      Earn.serializeVault({
+        ...options,
+        rewards: [{ ...reward, currentRewardsAprBps: null }],
+      }).apy,
+    ).toMatchObject({
+      net: '0.0700',
+      rewards: [{ apr: null, targetTotalApr: '0.0700' }],
+      vault: '0.041200',
+    })
+    expect(
+      Earn.serializeVault({
+        ...options,
+        apy: { ...options.apy, net: '0.080000' },
+      }).apy?.net,
+    ).toBe('0.080000')
+    vi.useFakeTimers({ now: new Date('2026-09-01T01:30:00.000Z'), toFake: ['Date'] })
+    try {
+      expect(
+        Earn.serializeVault({
+          ...options,
+          rewards: [{ ...reward, startsAt: 1_788_229_800 }],
+        }).apy,
+      ).toMatchObject({
+        net: '0.041200',
+        rewards: [{ targetTotalApr: '0.0700' }],
+        vault: '0.041200',
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
+
 describe('schema.getEarnVaultEarnings.Query', () => {
   test('defaults to lifetime and accepts active and trailing earnings', () => {
     expect([
@@ -267,6 +994,19 @@ describe('calculateWindowEarnings', () => {
 })
 
 describe('calculateActiveCostBasis', () => {
+  test('ignores zero-share transfers', () => {
+    expect(
+      Earn.calculateActiveCostBasis({
+        actions: [
+          { assets: 100n, kind: 'deposit', shares: 100n },
+          { kind: 'unknown', shares: 0n },
+          { kind: 'redeem', shares: 0n },
+        ],
+        shareBalance: 100n,
+      }),
+    ).toBe(100n)
+  })
+
   test('allocates weighted-average basis across partial exits', () => {
     expect(
       Earn.calculateActiveCostBasis({
@@ -280,6 +1020,29 @@ describe('calculateActiveCostBasis', () => {
     ).toBe(200n)
   })
 
+  test('allocates zero-cost reward shares across partial exits without erasing unknown basis', () => {
+    const reward = { assets: 0n, kind: 'deposit', shares: 20n } as const
+    expect([
+      Earn.calculateActiveCostBasis({
+        actions: [
+          { assets: 100n, kind: 'deposit', shares: 100n },
+          reward,
+          { kind: 'redeem', shares: 60n },
+        ],
+        shareBalance: 60n,
+      }),
+      Earn.calculateActiveCostBasis({
+        actions: [{ kind: 'unknown', shares: 100n }, reward],
+        shareBalance: 120n,
+      }),
+    ]).toMatchInlineSnapshot(`
+      [
+        50n,
+        undefined,
+      ]
+    `)
+  })
+
   test('calculates remaining basis while an async redemption is pending', () => {
     expect(
       Earn.calculateActiveCostBasis({
@@ -721,6 +1484,79 @@ 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('requires read access to a selected Zone', async () => {
+    const app = TestApp.create({ cache, zones: [TestEarn.zone] })
+    const response = await app.request(
+      `/v1/earn/addresses/${TestEarn.positionAddress}/positions?chainId=${TestEarn.zone.id}`,
+      { headers: { 'tempo-api-key': TestApp.key.token } },
+    )
+
+    expect(response.status).toBe(403)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: { code: 'api_key_forbidden' },
+    })
+  })
+
+  test('rejects Zone earnings includes', async () => {
+    const key = {
+      ...TestApp.key,
+      id: 'key_earn_zone_positions',
+      scopes: ['data:read', `zone:${TestEarn.zone.id}:read`],
+      token: 'secret_earn_zone_positions',
+    } satisfies TestApp.kvStore.Key
+    const app = TestApp.create({ auth: { keys: [key] }, cache, zones: [TestEarn.zone] })
+    const response = await app.request(
+      `/v1/earn/addresses/${TestEarn.positionAddress}/positions?chainId=${TestEarn.zone.id}&include=earnings`,
+      { headers: { 'tempo-api-key': key.token } },
+    )
+
+    expect(response.status).toBe(400)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: {
+        code: 'query_invalid',
+        message: 'Zone positions do not support the earnings include.',
+      },
+    })
+  })
+
   test('returns chain selection errors', async () => {
     const app = TestApp.create({ auth: false, cache })
     const invalid = await app.request(
@@ -750,7 +1586,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 +1610,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 +1626,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 +1845,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 +1857,7 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
           "engineType": "erc4626",
           "feesActive": true,
           "instantLiquidity": null,
+          "instantLiquidityValue": null,
           "isAccountingAligned": true,
           "openRedeemRequestCount": 0,
           "pricedPerShare": true,
@@ -1069,7 +1908,7 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
       const apy = (await TestApp.json(response, Earn.schema.getEarnVault.Response)).apy
       expect(apy).toBeDefined()
       expect(apy).not.toBeNull()
-      if (!apy) return
+      if (!apy?.asOf || apy.net === null) throw new Error('Expected a measured APY.')
       expect({
         bucketed: apy.asOf === new Date(apy.asOf).toISOString() && apy.asOf.endsWith(':00.000Z'),
         measured: /^-?\d+\.\d{6}$/.test(apy.net),
@@ -1089,22 +1928,28 @@ 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,
   )
 
   test.runIf(Runtime.get().mode === 'testnet')(
-    'defaults to a seven-day window',
+    'uses a seven-day window when it is measurable',
     async () => {
       const app = TestApp.create({ auth: false, cache, zones: [TestEarn.zone] })
       const path = `/v1/earn/vaults/${TestEarn.vaultAddress}?chainId=${TestEarn.chain.id}`
@@ -1122,13 +1967,46 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
   )
 
   test.runIf(Runtime.get().mode === 'testnet')(
-    'measures rates and values assets only when requested',
+    'falls back to one hour when the preferred window is unavailable',
     async () => {
-      const app = TestApp.create({ auth: false, cache, zones: [TestEarn.zone] })
-      const path = `/v1/earn/vaults/${TestEarn.vaultAddress}?chainId=${TestEarn.chain.id}`
-      const request = { headers: { 'cache-control': 'no-store' } }
-      const [bare, requested] = await Promise.all([
-        app.request(path, request),
+      // The vault was deployed on 2026-07-23, so seven days has no opening
+      // quote while the current one-hour rate is measurable.
+      vi.useFakeTimers({ now: new Date('2026-07-24T10:00:00Z'), toFake: ['Date'] })
+      try {
+        const app = TestApp.create({
+          auth: false,
+          cache: { edge: false, store: Store.memory() },
+          zones: [TestEarn.zone],
+        })
+        const path = `/v1/earn/vaults/${TestEarn.vaultAddress}?chainId=${TestEarn.chain.id}`
+        const request = { headers: { 'cache-control': 'no-store' } }
+        const [defaulted, explicit] = await Promise.all([
+          app.request(`${path}&include=apy`, request),
+          app.request(`${path}&apy.window=7d`, request),
+        ])
+
+        expect([defaulted.status, explicit.status]).toStrictEqual([200, 200])
+        const [fallbackVault, explicitVault] = await Promise.all([
+          TestApp.json(defaulted, Earn.schema.getEarnVault.Response),
+          TestApp.json(explicit, Earn.schema.getEarnVault.Response),
+        ])
+        expect(fallbackVault.apy).toMatchObject({ window: '1h' })
+        expect(explicitVault.apy).toBeNull()
+      } finally {
+        vi.useRealTimers()
+      }
+    },
+    90_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'measures rates and values assets only when requested',
+    async () => {
+      const app = TestApp.create({ auth: false, cache, zones: [TestEarn.zone] })
+      const path = `/v1/earn/vaults/${TestEarn.vaultAddress}?chainId=${TestEarn.chain.id}`
+      const request = { headers: { 'cache-control': 'no-store' } }
+      const [bare, requested] = await Promise.all([
+        app.request(path, request),
         app.request(`${path}&include=apy,tvl`, request),
       ])
 
@@ -1299,7 +2177,202 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
   )
 })
 
+describe('GET /v1/earn/vaults/:vaultId/share-prices', () => {
+  test('classifies TIDX failures for dependency alerting', () => {
+    expect([
+      Earn.sharePriceProviderFailure({
+        cause: new EarnSharePrices.MalformedResponseError('malformed row'),
+        chainId: TestEarn.chain.id,
+      }),
+      Earn.sharePriceProviderFailure({
+        cause: new EarnSharePrices.TidxRequestError(new TypeError('network failed')),
+        chainId: TestEarn.chain.id,
+      }),
+    ]).toMatchInlineSnapshot(`
+      [
+        {
+          "chainId": 42431,
+          "failure": "payload",
+          "id": "tidx",
+          "operation": "query",
+        },
+        {
+          "chainId": 42431,
+          "failure": "network",
+          "id": "tidx",
+          "operation": "query",
+        },
+      ]
+    `)
+  })
+
+  test('validates the vault and daily range before reading upstreams', async () => {
+    const app = TestApp.create({ auth: false, cache })
+    const [range, vault] = await Promise.all([
+      app.request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/share-prices?from=2026-07-02T00%3A00Z&to=2026-07-01T00%3A00Z`,
+      ),
+      app.request(
+        '/v1/earn/vaults/not-an-address/share-prices?from=2026-07-01T00%3A00Z&to=2026-07-02T00%3A00Z',
+      ),
+    ])
+
+    expect([
+      (await TestApp.json(range, Schema.ErrorResponse)).error.code,
+      (await TestApp.json(vault, Schema.ErrorResponse)).error.code,
+    ]).toStrictEqual(['query_invalid', 'vault_id_invalid'])
+  })
+
+  test('requires both range boundaries', async () => {
+    const response = await TestApp.create({ auth: false, cache }).request(
+      `/v1/earn/vaults/${TestEarn.vaultAddress}/share-prices?from=2026-07-01T00%3A00Z`,
+    )
+
+    expect(response.status).toBe(400)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: { code: 'query_invalid' },
+    })
+  })
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'negative-caches incompatible vault discovery',
+    async () => {
+      const app = TestApp.create({ auth: false, cache })
+      const url = `/v1/earn/vaults/${TestEarn.assetTokenAddress}/share-prices?chainId=${TestEarn.chain.id}&from=2026-07-01T00%3A00Z&to=2026-07-02T00%3A00Z`
+      const first = await app.request(url)
+      const second = await app.request(url)
+
+      expect({
+        first: {
+          discovery: first.headers.get('server-timing')?.includes('earn_vault_discovery'),
+          status: first.status,
+        },
+        second: {
+          discovery: second.headers.get('server-timing')?.includes('earn_vault_discovery'),
+          status: second.status,
+        },
+      }).toMatchInlineSnapshot(`
+        {
+          "first": {
+            "discovery": true,
+            "status": 404,
+          },
+          "second": {
+            "discovery": false,
+            "status": 404,
+          },
+        }
+      `)
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'reads historical share prices through a deployed JSON-RPC batch',
+    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 OFFSET 100',
+      })
+      const timestamp = Value.toIsoDateTime(indexed.rows[0]?.['timestamp'])
+      if (timestamp === undefined) throw new Error('expected an indexed block')
+      const from = new Date(Date.parse(timestamp) - Ttl.days(1)).toISOString()
+      const response = await TestApp.create({ auth: false, cache }).request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/share-prices?chainId=${TestEarn.chain.id}&from=${encodeURIComponent(from)}&to=${encodeURIComponent(timestamp)}`,
+      )
+
+      expect(response.status).toBe(200)
+      const body = await TestApp.json(response, Earn.schema.getEarnVaultSharePrices.Response)
+      expect(body.data).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            sharePrice: expect.objectContaining({
+              amount: expect.stringMatching(/^\d+$/),
+              decimals: 6,
+            }),
+            timestamp,
+          }),
+        ]),
+      )
+    },
+    60_000,
+  )
+})
+
 describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
+  test('accepts and validates the wallet APY include', () => {
+    expect(Earn.schema.getEarnVaultPosition.Query.safeParse({ include: ['apy'] }).success).toBe(
+      true,
+    )
+    expect(
+      Earn.schema.getEarnVaultPosition.Response.safeParse({
+        account: TestEarn.positionAddress,
+        apy: {
+          breakdown: [
+            {
+              assetAmount: { baseUnits: '25000000000', decimals: 6, formatted: '25000' },
+              net: '0.07',
+              type: 'boost',
+            },
+            {
+              assetAmount: { baseUnits: '5000000000', decimals: 6, formatted: '5000' },
+              net: '0.02',
+              type: 'base',
+            },
+          ],
+          net: '0.0616666666666667',
+        },
+        assetAllowance: '0',
+        assetBalance: '0',
+        assetToken: TestEarn.assetTokenAddress,
+        chainId: TestEarn.chain.id,
+        id: TestEarn.positionAddress,
+        shareAllowance: '0',
+        shareBalance: '30000000000',
+        shareToken: '0x20c000000000000000000000300e14ab91a10769',
+        value: '30000000000',
+        valueToken: TestEarn.assetTokenAddress,
+      }).success,
+    ).toBe(true)
+  })
+
+  test('requires read access to a selected Zone', async () => {
+    const app = TestApp.create({ cache, zones: [TestEarn.zone] })
+    const response = await app.request(
+      `/v1/earn/vaults/${TestEarn.zoneVaultAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.zone.id}`,
+      { headers: { 'tempo-api-key': TestApp.key.token } },
+    )
+
+    expect(response.status).toBe(403)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: { code: 'api_key_forbidden' },
+    })
+  })
+
+  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 +2402,78 @@ 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 reward includes on historical positions', async () => {
+    const response = await TestApp.create({
+      auth: false,
+      cache,
+      rpc: { url: { 31_337: 'http://127.0.0.1:1' } },
+      tidx: { baseUrl: { 31_337: 'http://127.0.0.1:1' } },
+    }).request(
+      `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=31337&asOf=2026-07-21T09%3A00Z&include=rewards`,
+    )
+
+    expect(response.status).toBe(400)
+    expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+      error: {
+        code: 'query_invalid',
+        message: 'Historical position enrichments are not available.',
+      },
+    })
+  })
+
   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 +2494,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,
@@ -1371,6 +2517,157 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
           "shareToken": true,
         }
       `)
+      expect(position).not.toHaveProperty('apy')
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'preserves the current position when APY resolution fails',
+    async () => {
+      const entries: Log.Entry[] = []
+      const app = TestApp.create({
+        auth: false,
+        cache: { edge: false, store: Store.memory() },
+        logger: (entry) => void entries.push(entry),
+        tidx: { baseUrl: 'http://127.0.0.1:1' },
+      })
+      const path = `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.chain.id}`
+      const [bareResponse, response] = await Promise.all([
+        app.request(path),
+        app.request(`${path}&include=apy`),
+      ])
+
+      expect(bareResponse.status).toBe(200)
+      expect(response.status).toBe(200)
+      expect(response.headers.get('cache-control')).toBe('no-store')
+      const [bare, position] = await Promise.all([
+        TestApp.json(bareResponse, Earn.schema.getEarnVaultPosition.Response),
+        TestApp.json(response, Earn.schema.getEarnVaultPosition.Response),
+      ])
+      expect(position.apy).toBeNull()
+      expect({ shareBalance: position.shareBalance, value: position.value }).toStrictEqual({
+        shareBalance: bare.shareBalance,
+        value: bare.value,
+      })
+      expect(entries.find((entry) => entry.providerFailures)?.providerFailures).toEqual([
+        {
+          chainId: TestEarn.chain.id,
+          failure: 'network',
+          id: 'tidx',
+          operation: 'query',
+        },
+      ])
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'preserves the current position when reward APY resolution fails',
+    async () => {
+      const entries: Log.Entry[] = []
+      const app = TestApp.create({
+        auth: false,
+        cache,
+        db: Db.postgres({ connectionString: 'postgresql://127.0.0.1:1/unavailable' }),
+        logger: (entry) => void entries.push(entry),
+      })
+      const path = `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.chain.id}`
+      const [bareResponse, response] = await Promise.all([
+        app.request(path),
+        app.request(`${path}&include=apy`),
+      ])
+
+      expect(bareResponse.status).toBe(200)
+      expect(response.status).toBe(200)
+      expect(response.headers.get('cache-control')).toBe('no-store')
+      const [bare, position] = await Promise.all([
+        TestApp.json(bareResponse, Earn.schema.getEarnVaultPosition.Response),
+        TestApp.json(response, Earn.schema.getEarnVaultPosition.Response),
+      ])
+      expect(position.apy).toBeNull()
+      expect({ shareBalance: position.shareBalance, value: position.value }).toStrictEqual({
+        shareBalance: bare.shareBalance,
+        value: bare.value,
+      })
+      expect(entries.find((entry) => entry.providerFailures)?.providerFailures).toEqual([
+        {
+          chainId: TestEarn.chain.id,
+          failure: 'unknown',
+          id: 'earn-rewards',
+          operation: 'getPositionApy',
+        },
+      ])
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'includes current reward state from Postgres',
+    async () => {
+      const db = TestApp.database()
+      const now = Math.floor(Date.now() / 1_000)
+      const startsAt = Math.floor(now / 300) * 300
+      await core_EarnVaults.upsert(db, TestEarn.verifiedVault)
+      await RewardCampaigns.upsert(db, {
+        assetAddress: TestEarn.assetTokenAddress,
+        assetDecimals: 6,
+        chainId: TestEarn.chain.id,
+        config: {
+          boostRewards: {
+            endTimestamp: startsAt + 3_600,
+            excludedAddresses: [],
+            funding: { wallet: '0x5000000000000000000000000000000000000005' },
+            intervalSeconds: 300,
+            perUserPrincipalCapAssets: '1000000',
+            startTimestamp: startsAt,
+            targetAnnualRateBps: 700,
+            totalPrincipalCapAssets: '10000000',
+            treasury: '0x6000000000000000000000000000000000000006',
+          },
+        },
+        earnShareAddress: '0x2000000000000000000000000000000000000002',
+        earnShareDecimals: 18,
+        now: startsAt - 1,
+        vaultAddress: TestEarn.vaultAddress,
+      })
+      await RewardAccounts.replace(db, {
+        accounts: [
+          {
+            accrualRemainder: '0',
+            allocatedPrincipalAssets: '100',
+            cumulativeEntitlement: '15',
+            cumulativePaid: '10',
+            deferral: null,
+            eligibilityRegisteredAt: null,
+            lots: [],
+            pendingRewardAssets: '0',
+            publicEarnShares: '100',
+            qualifiedEarnShares: '100',
+            recipient: TestEarn.positionAddress,
+            registrationOrder: '1',
+            updatedAt: new Date().toISOString(),
+          },
+        ],
+        chainId: TestEarn.chain.id,
+        vaultAddress: TestEarn.vaultAddress,
+      })
+      const response = await TestApp.create({ auth: false, cache, db }).request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.chain.id}&include=apy,rewards.proof`,
+      )
+
+      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(position.apy).toMatchObject({
+        breakdown: expect.any(Array),
+        net: expect.any(String),
+      })
+      expect(position.rewards).toStrictEqual({
+        cumulativeEntitlement: '15',
+        cumulativePaid: '10',
+        pending: '5',
+      })
     },
     60_000,
   )
@@ -1389,9 +2686,212 @@ 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', () => {
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'counts registered reward payouts without treating external shares as deposits',
+    async () => {
+      const account = '0xa3b9eb50b9d1a3f584fbe1122a7bc82084eaae2f'
+      const chainId = Viem.chainId.mainnet
+      const previousDistributorAddress = '0x6c857bf1fe7de1bc1d5c639c721b2633f8fe34f3'
+      const distributorAddress = '0xa65c6ed737b52543123817977d8d2c0e554bfc2d'
+      const vaultAddress = '0xd730394f3bb85a4828e35fc5e361dcc9f894fa4f'
+      const db = TestApp.database()
+      const errors: Error[] = []
+      const app = TestApp.create({
+        auth: false,
+        cache,
+        db,
+        logger: (_, error) => {
+          if (error) errors.push(error)
+        },
+        tidx: {
+          auth: process.env.TIDX_AUTH,
+          baseUrl: Viem.resolveUrl(process.env.TIDX_URL, chainId) ?? Tidx.url[chainId],
+        },
+      })
+      const read = async (period: 'lifetime' | '30d' | 'active') => {
+        const response = await app.request(
+          `/v1/earn/vaults/${vaultAddress}/earnings/${account}?chainId=${chainId}&period=${period}`,
+        )
+        expect(response.status, errors.map((error) => error.message).join('\n')).toBe(200)
+        return TestApp.json(response, Earn.schema.getEarnVaultEarnings.Response)
+      }
+
+      // This account's indexed share receipts include both vault mints and distributor payouts.
+      expect((await read('lifetime')).status).toBe('incomplete_cost_basis')
+      await core_EarnVaults.upsert(db, {
+        chainId,
+        description: null,
+        label: 'Tempo Cash',
+        privateInputTokens: [],
+        privateOutputTokens: [],
+        vaultAddress,
+        zones: [],
+      })
+      await RewardCampaigns.upsert(db, {
+        assetAddress: '0x20c0000000000000000000000000000000000000',
+        assetDecimals: 6,
+        chainId,
+        config: {
+          boostRewards: {
+            enabled: false,
+            endTimestamp: 1790812800,
+            excludedAddresses: [],
+            funding: { wallet: account },
+            intervalSeconds: 300,
+            perUserPrincipalCapAssets: '25000000000',
+            startTimestamp: 1788206400,
+            targetAnnualRateBps: 700,
+            totalPrincipalCapAssets: '10000000000000',
+            treasury: account,
+          },
+        },
+        earnShareAddress: '0x20c000000000000000000000baac91f6ca72f768',
+        earnShareDecimals: 6,
+        now: 1788206399,
+        vaultAddress,
+      })
+      await RewardCampaigns.setBindings(db, {
+        chainId,
+        distributorAddress: previousDistributorAddress,
+        vaultAddress,
+      })
+      await RewardCampaigns.setBindings(db, { chainId, distributorAddress, vaultAddress })
+      await RewardCampaigns.setPaused(db, { chainId, paused: true, vaultAddress })
+
+      // Pausing new rewards must not erase the cost-basis treatment of already paid rewards.
+      const earnings = await Promise.all((['lifetime', '30d', 'active'] as const).map(read))
+      expect(earnings.map(({ period, status }) => ({ period, status }))).toMatchInlineSnapshot(`
+        [
+          {
+            "period": "lifetime",
+            "status": "complete",
+          },
+          {
+            "period": "30d",
+            "status": "complete",
+          },
+          {
+            "period": "active",
+            "status": "complete",
+          },
+        ]
+      `)
+      const lifetime = earnings[0]!
+      if (lifetime.status !== 'complete' || lifetime.period !== 'lifetime')
+        throw new Error('Expected complete lifetime earnings.')
+      expect(BigInt(lifetime.lifetimeEarnings)).toBe(
+        BigInt(lifetime.currentValue) +
+          BigInt(lifetime.totalWithdrawn) -
+          BigInt(lifetime.totalDeposited),
+      )
+    },
+    120_000,
+  )
+
   test('returns chain selection errors', async () => {
     const app = TestApp.create({ auth: false, cache })
     const invalid = await app.request(
@@ -1437,6 +2937,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,
@@ -1684,12 +3186,98 @@ describe('GET /v1/earn/vaults', () => {
 })
 
 describe('OpenAPI', () => {
+  test('publishes stable Earn components', async () => {
+    const app = TestApp.create({ auth: false, cache })
+    const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+
+    expect(
+      Object.fromEntries(
+        Object.entries(spec.paths)
+          .filter(([path]) => path.startsWith('/v1/earn/'))
+          .map(([path, item]) => [item.get?.operationId, [path, successSchema(item.get)?.$ref]]),
+      ),
+    ).toMatchInlineSnapshot(`
+      {
+        "getEarnAddressPositions": [
+          "/v1/earn/addresses/{address}/positions",
+          "#/components/schemas/EarnAddressPositionList",
+        ],
+        "getEarnVault": [
+          "/v1/earn/vaults/{vaultId}",
+          "#/components/schemas/EarnVaultDetail",
+        ],
+        "getEarnVaultEarnings": [
+          "/v1/earn/vaults/{vaultId}/earnings/{address}",
+          "#/components/schemas/EarnVaultEarnings",
+        ],
+        "getEarnVaultPosition": [
+          "/v1/earn/vaults/{vaultId}/positions/{address}",
+          "#/components/schemas/EarnVaultPosition",
+        ],
+        "getEarnVaultSharePrices": [
+          "/v1/earn/vaults/{vaultId}/share-prices",
+          "#/components/schemas/EarnVaultSharePriceList",
+        ],
+        "getEarnVaults": [
+          "/v1/earn/vaults",
+          "#/components/schemas/EarnVaultList",
+        ],
+        "getVerifiedEarnVaults": [
+          "/v1/earn/vaults/verified",
+          "#/components/schemas/VerifiedEarnVaultList",
+        ],
+      }
+    `)
+    expect(
+      Object.keys(spec.components?.schemas ?? {})
+        .filter((name) => name.startsWith('Earn') && !name.endsWith('Error'))
+        .sort(),
+    ).toMatchInlineSnapshot(`
+        [
+          "EarnAddressPosition",
+          "EarnAddressPositionList",
+          "EarnVault",
+          "EarnVaultDetail",
+          "EarnVaultEarnings",
+          "EarnVaultEngine",
+          "EarnVaultList",
+          "EarnVaultPosition",
+          "EarnVaultSharePriceList",
+          "EarnVaultZone",
+          "EarnVaultZoneRoute",
+        ]
+      `)
+    expect(spec.components?.schemas).toHaveProperty('VerifiedEarnVault')
+    expect(spec.components?.schemas).toHaveProperty('VerifiedEarnVaultList')
+    expect(JSON.stringify(spec.components?.schemas?.['EarnAddressPosition'])).toContain(
+      'An account’s position in one earn vault.',
+    )
+    expect({
+      detail:
+        spec.paths['/v1/earn/vaults/{vaultId}']?.get?.responses?.['400']?.content?.[
+          'application/json'
+        ]?.schema?.$ref,
+      list: spec.paths['/v1/earn/vaults']?.get?.responses?.['400']?.content?.['application/json']
+        ?.schema?.$ref,
+      verified:
+        spec.paths['/v1/earn/vaults/verified']?.get?.responses?.['400']?.content?.[
+          'application/json'
+        ]?.schema?.$ref,
+    }).toMatchInlineSnapshot(`
+      {
+        "detail": "#/components/schemas/ApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidOrVaultIdInvalidError",
+        "list": "#/components/schemas/ApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidError",
+        "verified": "#/components/schemas/ApiKeyMalformedOrChainIdInvalidOrChainIdUnsupportedOrQueryInvalidError",
+      }
+    `)
+  })
+
   test('publishes the flattened vault shape', async () => {
     const app = TestApp.create({ auth: false, cache })
     const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
     const operation = spec.paths['/v1/earn/vaults']?.get
     const parameters = operation?.parameters?.map((parameter) => parameter.name)
-    const response = JSON.stringify(operation?.responses?.['200'])
+    const response = JSON.stringify(resolveSchema(spec, successSchema(operation)))
 
     expect(Object.keys(spec.paths)).toEqual(
       expect.arrayContaining([
@@ -1699,6 +3287,7 @@ describe('OpenAPI', () => {
         '/v1/earn/vaults/{vaultId}',
         '/v1/earn/vaults/{vaultId}/earnings/{address}',
         '/v1/earn/vaults/{vaultId}/positions/{address}',
+        '/v1/earn/vaults/{vaultId}/share-prices',
       ]),
     )
     expect(parameters).toContain('apy.window')
@@ -1747,6 +3336,11 @@ 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(
+        resolveSchema(spec, successSchema(spec.paths['/v1/earn/vaults/{vaultId}']?.get)),
+      ),
+    ).toContain('Instant liquidity valued in USD')
   })
 
   test('documents vault-position inputs and responses', async () => {
@@ -1754,8 +3348,9 @@ 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 response = JSON.stringify(resolveSchema(spec, successSchema(operation)))
     const vaultId = operation?.parameters?.find((parameter) => parameter.name === 'vaultId')
 
     expect(errors).toContain('"chain_id_invalid"')
@@ -1764,12 +3359,40 @@ describe('OpenAPI', () => {
     expect(errors).toContain('"query_invalid"')
     expect(errors).toContain('"earn_vault_not_found"')
     expect(response).toContain('Stable resource ID for this vault position')
+    expect(response).toContain('Chain containing the account position')
+    expect(response).toContain('Always zero for Zone-routed positions')
     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).toContain('TIP-20 asset denominating `value`')
+    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])
   })
 
+  test('documents vault share-price inputs and responses', async () => {
+    const app = TestApp.create({ auth: false, cache })
+    const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
+    const operation = spec.paths['/v1/earn/vaults/{vaultId}/share-prices']?.get
+    const interval = operation?.parameters?.find((parameter) => parameter.name === 'interval')
+    const response = JSON.stringify(resolveSchema(spec, successSchema(operation)))
+
+    expect(interval?.schema?.const).toBe('day')
+    expect(interval?.schema?.examples).toStrictEqual(['day'])
+    expect(response).toContain('Assets returned for one whole Earn share')
+    expect(response).toContain('Daily Earn vault share prices')
+    expect(response).toContain('"formatted":"1"')
+  })
+
   test('documents address-position inputs and responses', async () => {
     const app = TestApp.create({ auth: false, cache })
     const spec = (await (await app.request('/openapi.json')).json()) as OpenApiDocument
@@ -1778,14 +3401,16 @@ 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)
+    const response = JSON.stringify(resolveSchema(spec, successSchema(operation)))
     const tokenReference = JSON.stringify(spec.components?.schemas?.['TokenReference'])
 
     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"')
@@ -1794,12 +3419,17 @@ describe('OpenAPI', () => {
     expect(errors).toContain('"query_invalid"')
     expect(response).toContain('Stable resource ID for this position')
     expect(response).toContain('Current asset value of the held shares')
+    expect(response).toContain('Chain containing the held shares')
     expect(response).toContain('"assetAmount"')
     expect(response).toContain('"shareAmount"')
+    expect(response).toContain('"lifetimeCashFlows"')
     expect(response).toContain('"valuation"')
+    expect(response).toContain('"valueToken"')
     expect(response).toContain('"vaultAddress"')
     expect(response).toContain('"nextCursor"')
-    expect(response).toContain('#/components/schemas/TokenReference')
+    expect(JSON.stringify(spec.components?.schemas?.['EarnAddressPosition'])).toContain(
+      '#/components/schemas/TokenReference',
+    )
     // Token references retain display metadata through the shared component.
     expect(tokenReference).toContain('"symbol"')
   })
@@ -1810,7 +3440,7 @@ describe('OpenAPI', () => {
     const operation = spec.paths['/v1/earn/vaults/{vaultId}/earnings/{address}']?.get
     const errors = errorSchemas(spec, operation)
     const period = operation?.parameters?.find((parameter) => parameter.name === 'period')
-    const response = JSON.stringify(operation?.responses)
+    const response = JSON.stringify(resolveSchema(spec, successSchema(operation)))
 
     expect(operation?.description).toContain('the trailing 30 days')
     expect(period?.description).toContain('trailing 30 days')
@@ -1819,6 +3449,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')