tapimo 0.14.0 → 0.15.0

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

@@ -1,14 +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'
 
 /**
@@ -29,10 +37,16 @@ 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,
@@ -46,6 +60,7 @@ type OpenApiDocument = {
     string,
     {
       get?: OpenApiOperation
+      post?: OpenApiOperation
     }
   >
 }
@@ -62,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({
@@ -135,6 +579,30 @@ describe('parseIndexedBlockAtOrBefore', () => {
   })
 })
 
+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(
@@ -172,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 = {
@@ -283,8 +777,18 @@ 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 a non-null instant-liquidity valuation with TVL', () => {
+  test('includes valuations and uses the reward target as the net APY floor', () => {
     const assetToken = {
       address: TestEarn.assetTokenAddress,
       currency: 'USD',
@@ -295,8 +799,13 @@ describe('serializeVault', () => {
       verified: true,
     } as const
     const shareTokenAddress = `0x20c0${'11'.repeat(18)}` as const
-    const vault = Earn.serializeVault({
-      apy: null,
+    const options = {
+      apy: {
+        asOf: '2026-08-26T14:00:00.000Z',
+        methodology: 'share-price-growth-annualized:v1',
+        net: '0.041200',
+        window: '7d',
+      },
       assetToken,
       discovery: {
         assetToken,
@@ -322,13 +831,28 @@ describe('serializeVault', () => {
         },
         vaultAddress: TestEarn.vaultAddress,
       },
-      include: ['tvl'],
+      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',
@@ -341,7 +865,8 @@ describe('serializeVault', () => {
       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',
@@ -349,6 +874,97 @@ describe('serializeVault', () => {
       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()
+    }
   })
 })
 
@@ -378,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({
@@ -391,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({
@@ -870,6 +1522,40 @@ describe('GET /v1/earn/addresses/:address/positions', () => {
     },
     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 })
@@ -1222,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),
@@ -1263,7 +1949,7 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
   )
 
   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}`
@@ -1280,6 +1966,39 @@ describe('GET /v1/earn/vaults/:vaultId', () => {
     60_000,
   )
 
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'falls back to one hour when the preferred window is unavailable',
+    async () => {
+      // 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 () => {
@@ -1458,7 +2177,183 @@ 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([
@@ -1560,6 +2455,25 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
     }
   })
 
+  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',
@@ -1603,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,
   )
@@ -1725,6 +2790,108 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
 })
 
 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(
@@ -2019,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([
@@ -2034,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')
@@ -2082,9 +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(spec.paths['/v1/earn/vaults/{vaultId}']?.get?.responses)).toContain(
-      'Instant liquidity valued in USD',
-    )
+    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 () => {
@@ -2094,7 +3350,7 @@ describe('OpenAPI', () => {
     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"')
@@ -2103,6 +3359,8 @@ 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])
@@ -2112,6 +3370,7 @@ describe('OpenAPI', () => {
     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(
@@ -2120,6 +3379,20 @@ describe('OpenAPI', () => {
     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
@@ -2131,7 +3404,7 @@ describe('OpenAPI', () => {
     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')
@@ -2146,13 +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"')
   })
@@ -2163,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')