tapimo 0.15.1 → 0.18.0

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

@@ -185,7 +185,7 @@ describe('POST /v1/earn/rewards/eligibility', () => {
     vaultAddress: `0x${'Aa'.repeat(20)}`,
     walletAddress: `0x${'Bb'.repeat(20)}`,
   }
-  const legacyKey = {
+  const scopedKey = {
     id: 'key_rewards_writer',
     orgId: 'org_test',
     scopes: ['rewards:write'],
@@ -223,20 +223,62 @@ describe('POST /v1/earn/rewards/eligibility', () => {
     expect(response.status).toBe(403)
   })
 
-  test('rejects a legacy rewards writer key', async () => {
-    const response = await TestApp.create({ auth: { keys: [legacyKey] } }).request(
+  test('accepts a rewards writer key', async () => {
+    const response = await TestApp.create({ auth: { keys: [scopedKey] } }).request(
       '/v1/earn/rewards/eligibility',
       {
         body: JSON.stringify(body),
         headers: {
-          authorization: `Bearer ${legacyKey.token}`,
+          authorization: `Bearer ${scopedKey.token}`,
           'content-type': 'application/json',
         },
         method: 'POST',
       },
     )
 
-    expect(response.status).toBe(403)
+    expect(response.status).toBe(200)
+  })
+
+  test('uses the body chain for sandbox authorization', async () => {
+    const sandbox = { ...scopedKey, environment: 'sandbox' } satisfies TestApp.kvStore.Key
+    const app = TestApp.create({ auth: { keys: [sandbox] } })
+    const request = (chainId: number) =>
+      app.request('/v1/earn/rewards/eligibility', {
+        body: JSON.stringify({ ...body, chainId }),
+        headers: {
+          authorization: `Bearer ${sandbox.token}`,
+          'content-type': 'application/json',
+        },
+        method: 'POST',
+      })
+
+    expect([
+      (await request(Viem.chainId.testnet)).status,
+      (await request(Viem.chainId.mainnet)).status,
+    ]).toEqual([200, 403])
+  })
+
+  test('rejects Zone chain IDs for rewards registration', async () => {
+    const zone = TestApp.zone({ chainId: 421_700_001, rpcUrl: 'https://zone.example' })
+    const response = await TestApp.create({ auth: { keys: [scopedKey] }, zones: [zone] }).request(
+      '/v1/earn/rewards/eligibility',
+      {
+        body: JSON.stringify({ ...body, chainId: zone.id }),
+        headers: {
+          authorization: `Bearer ${scopedKey.token}`,
+          'content-type': 'application/json',
+        },
+        method: 'POST',
+      },
+    )
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({
+      error: {
+        code: 'chain_id_unsupported',
+        message: `Zone chain ID ${zone.id} is not supported for rewards registration.`,
+      },
+    })
   })
 
   test('accepts a provisioned wildcard key', async () => {
@@ -337,7 +379,7 @@ describe('POST /v1/earn/rewards/eligibility', () => {
     expect(response.status).toBe(200)
   })
 
-  test('accepts configured Zones for super admins', async () => {
+  test('rejects configured Zones for super admins', async () => {
     const zone = TestApp.zone({
       chainId: 421_700_001,
       rpcUrl: 'https://zone.example',
@@ -352,7 +394,13 @@ describe('POST /v1/earn/rewards/eligibility', () => {
       method: 'POST',
     })
 
-    expect(response.status).toBe(200)
+    expect(response.status).toBe(400)
+    expect(await response.json()).toMatchObject({
+      error: {
+        code: 'chain_id_unsupported',
+        message: `Zone chain ID ${zone.id} is not supported for rewards registration.`,
+      },
+    })
   })
 
   test('surfaces database failures as operational errors', async () => {
@@ -674,6 +722,11 @@ describe('schema.getEarnVaultEarnings.Response', () => {
       currentValue: '1000000',
       id: TestEarn.earningsAddress,
     }
+    const window = {
+      ...response,
+      end: '2026-09-18T00:00:00.000Z',
+      start: '2026-09-11T00:00:00.000Z',
+    }
 
     expect({
       active: Earn.schema.getEarnVaultEarnings.Response.safeParse({
@@ -699,7 +752,7 @@ describe('schema.getEarnVaultEarnings.Response', () => {
         status: 'incomplete_cost_basis',
       }).success,
       incompleteWindow: Earn.schema.getEarnVaultEarnings.Response.safeParse({
-        ...response,
+        ...window,
         period: '30d',
         status: 'incomplete_cost_basis',
       }).success,
@@ -728,7 +781,7 @@ describe('schema.getEarnVaultEarnings.Response', () => {
         status: 'pending_redemption',
       }).success,
       pendingWindow: Earn.schema.getEarnVaultEarnings.Response.safeParse({
-        ...response,
+        ...window,
         period: '30d',
         status: 'pending_redemption',
       }).success,
@@ -740,19 +793,19 @@ describe('schema.getEarnVaultEarnings.Response', () => {
         totalWithdrawn: '500000',
       }).success,
       window: Earn.schema.getEarnVaultEarnings.Response.safeParse({
-        ...response,
+        ...window,
         period: '30d',
         status: 'complete',
         windowEarnings: '0',
       }).success,
       windowWithActiveEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
-        ...response,
+        ...window,
         activeEarnings: '0',
         period: '30d',
         status: 'complete',
       }).success,
       windowWithoutEarnings: Earn.schema.getEarnVaultEarnings.Response.safeParse({
-        ...response,
+        ...window,
         period: '30d',
         status: 'complete',
       }).success,
@@ -972,9 +1025,38 @@ describe('schema.getEarnVaultEarnings.Query', () => {
   test('defaults to lifetime and accepts active and trailing earnings', () => {
     expect([
       Earn.schema.getEarnVaultEarnings.Query.parse({}).period,
+      Earn.schema.getEarnVaultEarnings.Query.parse({ period: '7d' }).period,
       Earn.schema.getEarnVaultEarnings.Query.parse({ period: '30d' }).period,
       Earn.schema.getEarnVaultEarnings.Query.parse({ period: 'active' }).period,
-    ]).toStrictEqual(['lifetime', '30d', 'active'])
+    ]).toStrictEqual(['lifetime', '7d', '30d', 'active'])
+  })
+
+  test('requires an ordered explicit interval only for custom periods', () => {
+    const start = '2026-09-11T00:00:00.000Z'
+    const end = '2026-09-18T00:00:00.000Z'
+    expect(Earn.schema.getEarnVaultEarnings.Query.parse({ end, period: 'custom', start }))
+      .toMatchInlineSnapshot(`
+        {
+          "end": "2026-09-18T00:00:00.000Z",
+          "period": "custom",
+          "start": "2026-09-11T00:00:00.000Z",
+        }
+      `)
+    for (const query of [
+      { period: 'custom' },
+      { period: 'custom', start },
+      { end, period: 'custom' },
+      { end: start, period: 'custom', start },
+      { end: start, period: 'custom', start: end },
+      { end, period: 'custom', start: '2026-02-30T00:00:00Z' },
+      { end, period: 'custom', start: '2026-09-11T00:00:00' },
+      { end, start },
+      { end, period: '7d', start },
+      { end, period: 'lifetime', start },
+      // The local dates look ordered, but their UTC instants are reversed.
+      { end: '2026-09-18T01:00:00+02:00', period: 'custom', start: '2026-09-18T00:00:00Z' },
+    ])
+      expect(Earn.schema.getEarnVaultEarnings.Query.safeParse(query).success).toBe(false)
   })
 })
 
@@ -1146,110 +1228,6 @@ describe('GET /v1/earn/vaults/verified', () => {
     })
   })
 
-  test.runIf(Runtime.get().mode === 'testnet')(
-    'folds scoped Zone routes into vault capabilities',
-    async () => {
-      const db = TestApp.database()
-      await core_EarnVaults.upsert(db, TestEarn.zoneVerifiedVault)
-      const otherZoneId = TestEarn.zone.id + 1
-      const scopedKey = {
-        ...TestApp.key,
-        id: 'key_earn_zones',
-        scopes: ['data:read', `zone:${otherZoneId}:read`, `zone:${TestEarn.zone.id}:read`],
-        token: 'secret_earn_zones',
-      } satisfies TestApp.kvStore.Key
-      const unrelatedKey = {
-        ...TestApp.key,
-        id: 'key_earn_other_zone',
-        scopes: ['data:read', `zone:${otherZoneId}:read`],
-        token: 'secret_earn_other_zone',
-      } satisfies TestApp.kvStore.Key
-      const writeOnlyKey = {
-        ...TestApp.key,
-        id: 'key_earn_write_zone',
-        scopes: ['data:read', `zone:${TestEarn.zone.id}:write`],
-        token: 'secret_earn_write_zone',
-      } satisfies TestApp.kvStore.Key
-      const wildcardKey = {
-        ...TestApp.key,
-        id: 'key_earn_all_zones',
-        scopes: ['*'],
-        token: 'secret_earn_all_zones',
-      } satisfies TestApp.kvStore.Key
-      const app = TestApp.create({
-        auth: { keys: [scopedKey, unrelatedKey, wildcardKey, writeOnlyKey] },
-        cache,
-        db,
-        zones: [TestEarn.zone],
-      })
-      const base = `/v1/earn/vaults/verified?chainId=${TestEarn.chain.id}&limit=5`
-      const included = `${base}&include=capabilities,zone,zones`
-      const filtered = `${included}&capability=privateRouting`
-      // Fill the query-credential cache entry before checking callers without its Zone scope.
-      const scopedResponse = await app.request(`${filtered}&key=${scopedKey.token}`)
-      const [
-        defaultResponse,
-        unrelatedResponse,
-        publicResponse,
-        wildcardResponse,
-        writeOnlyResponse,
-      ] = await Promise.all([
-        app.request(base, { headers: { 'tempo-api-key': scopedKey.token } }),
-        app.request(included, { headers: { 'tempo-api-key': unrelatedKey.token } }),
-        app.request(filtered),
-        app.request(filtered, { headers: { 'tempo-api-key': wildcardKey.token } }),
-        app.request(filtered, { headers: { 'tempo-api-key': writeOnlyKey.token } }),
-      ])
-
-      expect([
-        defaultResponse.status,
-        scopedResponse.status,
-        unrelatedResponse.status,
-        publicResponse.status,
-        wildcardResponse.status,
-        writeOnlyResponse.status,
-      ]).toStrictEqual([200, 200, 200, 200, 200, 200])
-      const [defaultBody, scopedBody, unrelatedBody, publicBody, wildcardBody, writeOnlyBody] =
-        await Promise.all([
-          TestApp.json(defaultResponse, Earn.schema.getVerifiedEarnVaults.Response),
-          TestApp.json(scopedResponse, Earn.schema.getVerifiedEarnVaults.Response),
-          TestApp.json(unrelatedResponse, Earn.schema.getVerifiedEarnVaults.Response),
-          TestApp.json(publicResponse, Earn.schema.getVerifiedEarnVaults.Response),
-          TestApp.json(wildcardResponse, Earn.schema.getVerifiedEarnVaults.Response),
-          TestApp.json(writeOnlyResponse, Earn.schema.getVerifiedEarnVaults.Response),
-        ])
-      expect(defaultBody.data[0]).not.toHaveProperty('zone')
-      expect(defaultBody.data[0]).not.toHaveProperty('zones')
-      expect(unrelatedBody.data[0]).toMatchObject({
-        capabilities: { privateRouting: true, routerSwaps: true },
-        zone: null,
-        zones: [],
-      })
-      expect(publicBody.data[0]).toMatchObject({
-        capabilities: { privateRouting: true, routerSwaps: true },
-        zone: null,
-        zones: [],
-      })
-      expect(writeOnlyBody.data[0]).toMatchObject({ zone: null, zones: [] })
-      const vault = scopedBody.data[0]
-      expect(vault?.capabilities).toMatchObject({ privateRouting: true, routerSwaps: true })
-      expect(vault?.zones).toHaveLength(1)
-      expect(vault?.zones?.[0]).toMatchObject(TestEarn.zoneRoute)
-      expect(vault?.zone).toStrictEqual(
-        vault?.zones?.[0]
-          ? {
-              chainId: vault.zones[0].chainId,
-              inputTokens: vault.zones[0].inputTokens,
-              name: vault.zones[0].name,
-              outputTokens: vault.zones[0].outputTokens,
-            }
-          : null,
-      )
-      expect(wildcardBody.data[0]).toStrictEqual(vault)
-    },
-    90_000,
-  )
-
   test.runIf(Runtime.get().mode === 'testnet')(
     'returns null for an inaccessible legacy Zone route',
     async () => {
@@ -2305,6 +2283,13 @@ describe('GET /v1/earn/vaults/:vaultId/share-prices', () => {
 })
 
 describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
+  const zoneKey = {
+    ...TestApp.key,
+    id: 'key_earn_zone_vault_position',
+    scopes: ['data:read', `zone:${TestEarn.zone.id}:read`],
+    token: 'secret_earn_zone_vault_position',
+  } satisfies TestApp.kvStore.Key
+
   test('accepts and validates the wallet APY include', () => {
     expect(Earn.schema.getEarnVaultPosition.Query.safeParse({ include: ['apy'] }).success).toBe(
       true,
@@ -2354,6 +2339,26 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
     })
   })
 
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'returns not found for an incompatible public parent vault selected through a Zone',
+    async () => {
+      const response = await TestApp.create({
+        auth: { keys: [zoneKey] },
+        cache,
+        zones: [TestEarn.zone],
+      }).request(
+        `/v1/earn/vaults/${TestEarn.assetTokenAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.zone.id}`,
+        { headers: { 'tempo-api-key': zoneKey.token } },
+      )
+
+      expect(response.status).toBe(404)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: { code: 'earn_vault_not_found' },
+      })
+    },
+    60_000,
+  )
+
   test('rejects invalid as-of timestamps', async () => {
     const app = TestApp.create({ auth: false, cache })
     const [malformed, unix] = await Promise.all([
@@ -2631,6 +2636,26 @@ describe('GET /v1/earn/vaults/:vaultId/positions/:address', () => {
         now: startsAt - 1,
         vaultAddress: TestEarn.vaultAddress,
       })
+      await RewardEligibilityAssociations.upsert(db, {
+        chainId: TestEarn.chain.id,
+        vaultAddress: TestEarn.vaultAddress,
+        walletAddress: TestEarn.positionAddress,
+      })
+      const freshResponse = await TestApp.create({ auth: false, cache, db }).request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/positions/${TestEarn.positionAddress}?chainId=${TestEarn.chain.id}&include=apy`,
+      )
+      expect(freshResponse.status).toBe(200)
+      const fresh = await TestApp.json(freshResponse, Earn.schema.getEarnVaultPosition.Response)
+      expect(fresh.apy?.breakdown).toMatchObject([
+        {
+          assetAmount: { baseUnits: '0', decimals: 6, formatted: '0' },
+          net: '0.0700',
+          type: 'boost',
+        },
+        { assetAmount: { baseUnits: fresh.value }, type: 'base' },
+      ])
+      expect(Number(fresh.apy?.net)).toBe(Number(fresh.apy?.breakdown[1]?.net))
+
       await RewardAccounts.replace(db, {
         accounts: [
           {
@@ -2791,7 +2816,95 @@ 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',
+    'recognizes card withdrawals with only incoming rewards configured and no campaign',
+    async () => {
+      const account = '0x504a128461f2ee15b52a9d33812769e8cc31bc0d'
+      const vaultAddress = '0xd730394f3bb85a4828e35fc5e361dcc9f894fa4f'
+      const chainId = Viem.chainId.mainnet
+      const db = TestApp.database()
+      const tidx = {
+        auth: process.env.TIDX_AUTH,
+        baseUrl: Viem.resolveUrl(process.env.TIDX_URL, chainId) ?? Tidx.url[chainId],
+      }
+      const errors: Error[] = []
+      const app = TestApp.create({
+        auth: false,
+        cache,
+        db,
+        logger: (_, error) => {
+          if (error) errors.push(error)
+        },
+        tidx,
+      })
+      const input = {
+        chainId,
+        description: null,
+        label: 'Tempo Cash',
+        privateInputTokens: [],
+        privateOutputTokens: [],
+        vaultAddress,
+        zones: [],
+      } as const
+      const read = async (period: '30d' | 'lifetime' | 'active') => {
+        const response = await app.request(
+          `/v1/earn/vaults/${vaultAddress}/earnings/${account}?chainId=${chainId}&period=${period}`,
+          { headers: { 'cache-control': 'no-store' } },
+        )
+        expect(response.status, errors.map((error) => error.message).join('\n')).toBe(200)
+        return TestApp.json(response, Earn.schema.getEarnVaultEarnings.Response)
+      }
+      await core_EarnVaults.upsert(db, {
+        ...input,
+        earnings: { rewardDistributors: [] },
+      })
+      // Lifetime history retains the known rewards after they leave the trailing window.
+      expect((await read('lifetime')).status).toBe('incomplete_cost_basis')
+      await core_EarnVaults.upsert(db, {
+        ...input,
+        earnings: {
+          rewardDistributors: ['0xa65c6ed737b52543123817977d8d2c0e554bfc2d'],
+        },
+      })
+      expect((await read('30d')).status).toBe('complete')
+      expect((await read('active')).status).toBe('complete')
+      // Sample direct exits before lifetime earnings so later activity cannot increase only the baseline.
+      const direct = await Tidx.getClient({ chainId, tidx }).fetch({
+        engine: 'clickhouse',
+        query: `SELECT toString(sum(toUInt256(assets))) AS assets FROM (
+          SELECT assets FROM Redeemed WHERE address = '${vaultAddress}' AND caller = '${account}'
+          UNION ALL SELECT assets FROM WithdrewExact WHERE address = '${vaultAddress}' AND caller = '${account}'
+        )`,
+        signatures: [
+          'event Redeemed(address indexed caller,address indexed receiver,uint256 earnShares,uint256 assets)',
+          'event WithdrewExact(address indexed caller,address indexed receiver,uint256 assets,uint256 earnSharesBurned)',
+        ],
+      })
+      const lifetime = await read('lifetime')
+      if (lifetime.status !== 'complete' || lifetime.period !== 'lifetime')
+        throw new Error('Expected complete lifetime earnings.')
+      // This live wallet can spend again; EarnWithdrawals.read's fixed-block regression proves the captured $1 is counted exactly once.
+      expect(
+        BigInt(lifetime.totalWithdrawn) - BigInt(String(direct.rows[0]?.['assets'])),
+      ).toBeGreaterThanOrEqual(1_000_000n)
+      const positions = await app.request(
+        `/v1/earn/addresses/${account}/positions?chainId=${chainId}&include=earnings&verified=true`,
+        { headers: { 'cache-control': 'no-store' } },
+      )
+      expect(positions.status).toBe(200)
+      const body = await TestApp.json(positions, Earn.schema.getEarnAddressPositions.Response)
+      expect(
+        body.data.find((position) => position.vaultAddress === vaultAddress)?.lifetimeCashFlows,
+      ).toEqual({
+        status: 'complete',
+        totalDeposited: lifetime.totalDeposited,
+        totalWithdrawn: lifetime.totalWithdrawn,
+      })
+    },
+    180_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'combines additional distributors with campaign history without erasing past rewards',
     async () => {
       const account = '0xa3b9eb50b9d1a3f584fbe1122a7bc82084eaae2f'
       const chainId = Viem.chainId.mainnet
@@ -2815,6 +2928,7 @@ describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
       const read = async (period: 'lifetime' | '30d' | 'active') => {
         const response = await app.request(
           `/v1/earn/vaults/${vaultAddress}/earnings/${account}?chainId=${chainId}&period=${period}`,
+          { headers: { 'cache-control': 'no-store' } },
         )
         expect(response.status, errors.map((error) => error.message).join('\n')).toBe(200)
         return TestApp.json(response, Earn.schema.getEarnVaultEarnings.Response)
@@ -2822,7 +2936,7 @@ describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
 
       // 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, {
+      const vault = await core_EarnVaults.upsert(db, {
         chainId,
         description: null,
         label: 'Tempo Cash',
@@ -2859,8 +2973,19 @@ describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
         distributorAddress: previousDistributorAddress,
         vaultAddress,
       })
+      // Neither the old campaign distributor nor the extra alone covers this account's receipts.
+      expect((await read('lifetime')).status).toBe('incomplete_cost_basis')
+      await core_EarnVaults.upsert(db, {
+        ...vault,
+        earnings: { rewardDistributors: [distributorAddress] },
+      })
+      for (const period of ['lifetime', '30d', 'active'] as const)
+        expect((await read(period)).status).toBe('complete')
+
+      // Recording a future campaign binding keeps its history even after clearing the extra list.
       await RewardCampaigns.setBindings(db, { chainId, distributorAddress, vaultAddress })
       await RewardCampaigns.setPaused(db, { chainId, paused: true, vaultAddress })
+      await core_EarnVaults.upsert(db, { ...vault, earnings: { rewardDistributors: [] } })
 
       // 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))
@@ -2888,8 +3013,10 @@ describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
           BigInt(lifetime.totalWithdrawn) -
           BigInt(lifetime.totalDeposited),
       )
+      await core_EarnVaults.upsert(db, { ...vault, earnings: null })
+      expect((await read('lifetime')).status).toBe('complete')
     },
-    120_000,
+    180_000,
   )
 
   test('returns chain selection errors', async () => {
@@ -2991,6 +3118,148 @@ describe('GET /v1/earn/vaults/:vaultId/earnings/:address', () => {
     60_000,
   )
 
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'matches weekly and explicit windows and preserves historical cash-flow boundaries',
+    async () => {
+      const account = '0x504a128461f2ee15b52a9d33812769e8cc31bc0d'
+      const vaultAddress = '0xd730394f3bb85a4828e35fc5e361dcc9f894fa4f'
+      const chainId = Viem.chainId.mainnet
+      const db = TestApp.database()
+      await core_EarnVaults.upsert(db, {
+        chainId,
+        description: null,
+        earnings: { rewardDistributors: ['0xa65c6ed737b52543123817977d8d2c0e554bfc2d'] },
+        label: 'Tempo Cash',
+        privateInputTokens: [],
+        privateOutputTokens: [],
+        vaultAddress,
+        zones: [],
+      })
+      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 path = `/v1/earn/vaults/${vaultAddress}/earnings/${account}`
+      const read = async (query: Record<string, string>) => {
+        const response = await app.request(
+          `${path}?${new URLSearchParams({ chainId: String(chainId), ...query })}`,
+          { headers: { 'cache-control': 'no-store' } },
+        )
+        expect(response.status, errors.map((error) => error.stack).join('\n')).toBe(200)
+        const body = await TestApp.json(response, Earn.schema.getEarnVaultEarnings.Response)
+        if (body.status !== 'complete' || !('windowEarnings' in body))
+          throw new Error('Expected complete window earnings.')
+        return body
+      }
+      const week = await read({ period: '7d' })
+      expect(Date.parse(week.end) - Date.parse(week.start)).toBe(7 * 24 * 60 * 60 * 1000)
+      const explicit = await read({ end: week.end, period: 'custom', start: week.start })
+      expect(explicit).toEqual({ ...week, period: 'custom' })
+
+      // This fixed historical interval includes deposits, rewards and card exits.
+      const start = '2026-09-11T00:00:00.000Z'
+      const middle = '2026-09-15T00:00:00.000Z'
+      const end = '2026-09-18T00:00:00.000Z'
+      const full = await read({ end, period: 'custom', start })
+      const left = await read({ end: middle, period: 'custom', start })
+      const right = await read({ end, period: 'custom', start: middle })
+      expect(BigInt(full.windowEarnings)).toBeGreaterThan(0n)
+      expect(BigInt(left.windowEarnings) + BigInt(right.windowEarnings)).toBe(
+        BigInt(full.windowEarnings),
+      )
+      expect(left.currentValue).not.toBe(full.currentValue)
+      expect(right.currentValue).toBe(full.currentValue)
+      const historical = await app.request(
+        `/v1/earn/vaults/${vaultAddress}/positions/${account}?${new URLSearchParams({
+          asOf: end,
+          chainId: String(chainId),
+        })}`,
+      )
+      expect(historical.status).toBe(200)
+      expect(
+        (await TestApp.json(historical, Earn.schema.getEarnVaultPosition.Response)).value,
+      ).toBe(full.currentValue)
+      const offset = await read({
+        end: '2026-09-18T02:00:00+02:00',
+        period: 'custom',
+        start: '2026-09-10T19:00:00-05:00',
+      })
+      expect(offset).toEqual(full)
+    },
+    180_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'rejects earnings windows beyond indexed coverage',
+    async () => {
+      const end = new Date(Date.now() + Ttl.days(365)).toISOString()
+      const response = await TestApp.create({ auth: false, cache }).request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/earnings/${TestEarn.earningsAddress}?${new URLSearchParams(
+          {
+            chainId: String(TestEarn.chain.id),
+            end,
+            period: 'custom',
+            start: '2026-09-11T00:00:00.000Z',
+          },
+        )}`,
+      )
+      expect(response.status).toBe(400)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: { code: 'query_invalid', message: `Indexed history does not yet cover ${end}.` },
+      })
+      expect(response.headers.get('cache-control')).toBe('no-store')
+    },
+    60_000,
+  )
+
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'reports historical earnings dependency failures through request alerts',
+    async () => {
+      const entries: Log.Entry[] = []
+      const errors: Error[] = []
+      const app = TestApp.create({
+        auth: false,
+        cache,
+        logger: (entry, error) => {
+          entries.push(entry)
+          if (error) errors.push(error)
+        },
+        tidx: { baseUrl: 'http://127.0.0.1:1' },
+      })
+      const response = await app.request(
+        `/v1/earn/vaults/${TestEarn.vaultAddress}/earnings/${TestEarn.earningsAddress}?${new URLSearchParams(
+          {
+            chainId: String(TestEarn.chain.id),
+            end: '2026-09-18T00:00:00.000Z',
+            period: 'custom',
+            start: '2026-09-11T00:00:00.000Z',
+          },
+        )}`,
+      )
+      expect(response.status).toBe(502)
+      expect(await TestApp.json(response, Schema.ErrorResponse)).toMatchObject({
+        error: { code: 'upstream_error' },
+      })
+      expect(errors).toHaveLength(1)
+      expect(entries[0]).toMatchObject({
+        errorCode: 'upstream_error',
+        route: '/v1/earn/vaults/:vaultId/earnings/:address',
+        status: 502,
+      })
+      expect(response.headers.get('cache-control')).toBe('no-store')
+    },
+    60_000,
+  )
+
   test.runIf(Runtime.get().mode === 'testnet')(
     'omits lifetime earnings when venue shares make the cost basis incomplete',
     async () => {
@@ -3367,7 +3636,9 @@ describe('OpenAPI', () => {
     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('Public vault assets held by this account at the observation block')
+    expect(response).toContain('Private Zone assets held by this account at the observation block')
+    expect(response).toContain('TIP-20 private asset used by the validated Zone route')
     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`')
@@ -3442,17 +3713,24 @@ describe('OpenAPI', () => {
     const period = operation?.parameters?.find((parameter) => parameter.name === 'period')
     const response = JSON.stringify(resolveSchema(spec, successSchema(operation)))
 
-    expect(operation?.description).toContain('the trailing 30 days')
-    expect(period?.description).toContain('trailing 30 days')
-    expect(period?.schema?.enum).toStrictEqual(['30d', 'active', 'lifetime'])
+    expect(operation?.description).toContain('rolling or custom time window')
+    expect(period?.description).toContain('trailing 7 or 30 days')
+    expect(period?.schema?.enum).toStrictEqual(['7d', '30d', 'active', 'custom', 'lifetime'])
     expect(period?.schema?.examples).toStrictEqual(['lifetime'])
+    for (const name of ['start', 'end']) {
+      const parameter = operation?.parameters?.find((parameter) => parameter.name === name)
+      expect(parameter?.description).toContain('Required with period=custom')
+      expect(parameter?.schema?.examples).toHaveLength(1)
+    }
     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(
+      'Current share value plus withdrawals, including outgoing shares valued when transferred',
+    )
     expect(response).toContain('Assets deposited with this account as receiver')
-    expect(response).toContain('Assets returned by completed redemptions')
+    expect(response).toContain('regardless of recipient or spender')
     expect(response).toContain('weighted-average asset cost basis')
-    expect(response).toContain('Ending share value plus realized assets')
+    expect(response).toContain('Ending share value plus withdrawals')
     expect(response).toContain('cannot reconstruct the asset cost basis for the requested period')
     expect(response).toContain('"active"')
     expect(response).toContain('"30d"')