tapimo 0.14.0 → 0.15.0

package/src/internal/EarnRates.ts

@@ -1,18 +1,20 @@
+import { Hash, Hex } from 'ox'
 import type { Address } from 'viem'
 import * as z from 'zod/mini'
 
+import type * as Log from './Log.js'
 import * as Schema from './Schema.js'
 import * as Store from './Store.js'
-import type * as Tidx from './Tidx.js'
+import * as Tidx from './Tidx.js'
 import * as Ttl from './Ttl.js'
 import * as Value from './Value.js'
-import type * as Viem from './Viem.js'
+import * as Viem from './Viem.js'
 
 const migratedSignature =
   'event EngineMigrated(address indexed oldEngine,address indexed newEngine,uint256 oldEngineShares,uint256 assetsMoved,uint256 newEngineShares,uint256 totalEarnShares,uint256 anchorEngineShares,uint256 anchorEarnShares)'
 
-/** Identifier of the rate calculation, versioned so a change is visible to callers. */
-const methodology = 'share-price-growth-annualized:v1' as const
+/** Identifier of the observed Earn APY calculation. */
+export const methodology = 'share-price-growth-annualized:v1' as const
 
 /** Width of the UTC bucket every measurement is anchored to. */
 const bucketWidth = Ttl.minutes(15)
@@ -20,8 +22,8 @@ const bucketWidth = Ttl.minutes(15)
 /** Withheld from the anchor so an unconfirmed head block cannot move a boundary. */
 const confirmationDelay = Ttl.seconds(30)
 
-/** Default window, used when the caller does not select one. */
-const defaultWindow = '7d'
+/** Preferred observed Earn APY measurement window. */
+export const defaultWindow = '7d'
 
 /**
  * Selectable measurement windows. A closed set bounds both the rate cache and
@@ -30,6 +32,9 @@ const defaultWindow = '7d'
  */
 const windows = ['1h', '1d', '7d', '30d'] as const
 
+/** Stable preferred window and current-rate fallback used when none is selected. */
+const defaultWindows = [defaultWindow, '1h'] as const
+
 /** Length of every selectable window in whole hours. */
 const windowHours = {
   '1h': 1,
@@ -100,7 +105,7 @@ export namespace schema {
     .optional(z.enum(windows))
     .check(
       z.describe(
-        'Rate measurement window. Selecting a window includes `apy`, which measures `7d` on its own.',
+        'Rate measurement window. Selecting one includes `apy`; omission prefers `7d` and falls back to `1h` when unavailable.',
       ),
       z.meta({ examples: [defaultWindow] }),
     )
@@ -123,18 +128,48 @@ export function asOf(): string {
  * vault address. A vault maps to `null` when its rate cannot be measured.
  */
 export async function resolve(options: resolve.Options): Promise<Map<string, Apy | null>> {
-  const { chainId, store } = options
-  const window = options.window ?? defaultWindow
   const vaults = [...new Set(options.vaults.map((vault) => Schema.Address.parse(vault)))]
   if (vaults.length === 0) return new Map()
 
   const measuredAt = asOf()
+  const resolved = new Map<string, Apy | null>(vaults.map((vault) => [vault, null]))
+  let missing = vaults
+  const candidates = options.window === undefined ? defaultWindows : [options.window]
+  for (const window of candidates) {
+    const rates = await resolveWindow({ ...options, measuredAt, vaults: missing, window })
+    missing = missing.filter((vault) => {
+      const apy = rates.get(vault) ?? null
+      if (apy === null) return true
+      resolved.set(vault, apy)
+      return false
+    })
+    if (missing.length === 0) break
+  }
+  return resolved
+}
+
+async function resolveWindow(options: resolveWindow.Options): Promise<Map<string, Apy | null>> {
+  const { chainId, measuredAt, store, vaults, window } = options
+  let failureReported = false
   let pending: Promise<Measurement | undefined> | undefined
   // Boundary blocks, the migration scan, and both quote batches load once per
   // page, and only when a vault misses its cached rate. Rate enrichment never
   // fails a page, so an unreadable window leaves every vault unmeasured.
   const measure = () =>
-    (pending ??= measurePage({ ...options, measuredAt, vaults, window }).catch(() => undefined))
+    (pending ??= measurePage({
+      ...options,
+      measuredAt,
+      onFailure: (failure) => {
+        failureReported = true
+        options.onFailure?.(failure)
+      },
+      vaults,
+      window,
+    }).catch(() => {
+      if (!failureReported)
+        options.onFailure?.({ failure: 'unknown', id: 'earn-apy', operation: 'resolve' })
+      return undefined
+    }))
 
   const entries = await Promise.all(
     vaults.map(async (vault) => {
@@ -162,6 +197,14 @@ export async function resolve(options: resolve.Options): Promise<Map<string, Apy
   return new Map(entries)
 }
 
+declare namespace resolveWindow {
+  type Options = Omit<resolve.Options, 'vaults' | 'window'> & {
+    measuredAt: string
+    vaults: readonly Address[]
+    window: Window
+  }
+}
+
 export declare namespace resolve {
   /** Options for resolving a page of Earn vault rates. */
   type Options = {
@@ -171,11 +214,13 @@ export declare namespace resolve {
     getClient: Viem.GetClient
     /** Resolves the indexer client used for block and migration history. */
     getTidx: Tidx.GetClient
+    /** Observes dependency failures while preserving best-effort rate resolution. */
+    onFailure?: ((failure: Log.ProviderFailure) => void) | undefined
     /** Cache backing measured rates. */
     store: Store.Store
     /** Vault addresses appearing on the page. */
     vaults: readonly Address[]
-    /** Canonical measurement window, defaulting to `7d`. */
+    /** Exact measurement window; omission prefers `7d` and falls back to `1h`. */
     window?: Window | undefined
   }
 }
@@ -243,7 +288,14 @@ async function measurePage(options: measurePage.Options): Promise<Measurement |
   const quote = (blockNumber: bigint, vault: Address) =>
     client.earn.getRedeemQuote({ blockNumber, shareAmount: quotedShares, vault }).then(
       (price) => price,
-      () => undefined,
+      (cause) => {
+        options.onFailure?.({
+          ...(Viem.requestFailure(cause) ?? { failure: 'unknown' }),
+          id: 'rpc',
+          operation: 'eth_call',
+        })
+        return undefined
+      },
     )
 
   // The migration scan is independent of historical quotes, so keep its TIDX
@@ -309,14 +361,20 @@ async function boundaryBlocks(options: boundaryBlocks.Options): Promise<Boundari
       // `blocks` indexes every block, empty ones included, so the last row at or
       // before an instant is the exact boundary. Both boundaries share one
       // request because the indexer sheds load by request count, not rows read.
-      const result = await options.getTidx(chainId).fetch({
-        chainId,
-        query: `
+      const result = await options
+        .getTidx(chainId)
+        .fetch({
+          chainId,
+          query: `
           (SELECT num, timestamp FROM blocks WHERE timestamp <= '${endInstant}' ORDER BY timestamp DESC, num DESC LIMIT 1)
           UNION ALL
           (SELECT num, timestamp FROM blocks WHERE timestamp <= '${startInstant}' ORDER BY timestamp DESC, num DESC LIMIT 1)
         ` as string,
-      })
+        })
+        .catch((cause) => {
+          options.onFailure?.(Tidx.providerFailure(cause))
+          throw cause
+        })
       const rows = result.rows.flatMap((row) => {
         const number = Value.toIntegerString(row['num'])
         const timestamp = Value.toIsoDateTime(row['timestamp'])
@@ -353,7 +411,7 @@ async function boundaryBlocks(options: boundaryBlocks.Options): Promise<Boundari
 }
 
 declare namespace boundaryBlocks {
-  type Options = Pick<resolve.Options, 'chainId' | 'getTidx' | 'store'> & {
+  type Options = Pick<resolve.Options, 'chainId' | 'getTidx' | 'onFailure' | 'store'> & {
     /** Instant the window ends at, in milliseconds. */
     endAt: number
     /** Instant the window starts at, in milliseconds. */
@@ -364,34 +422,42 @@ declare namespace boundaryBlocks {
 }
 
 /**
- * Engine migrations indexed over the longest selectable window, so one scan
- * serves every window and page anchored to the same instant. Returns undefined
- * when the scan filled its row cap and a migration may be missing.
+ * Engine migrations indexed over the longest selectable window for the
+ * requested vaults. Returns undefined when the scan filled its row cap and a
+ * migration may be missing.
  */
 async function recentMigrations(
   options: recentMigrations.Options,
 ): Promise<readonly Migration[] | undefined> {
-  const { chainId, measuredAt } = options
+  const { chainId, measuredAt, vaults } = options
   // One bucket of slack because this scan and the boundaries expire
   // independently; scanning further back only resets more windows.
   const since = new Date(
     Date.parse(measuredAt) - maxWindowHours * Ttl.hour(1) - bucketWidth,
   ).toISOString()
+  const scope = migrationScope({ vaults })
   const migrations = await Store.memoize(
     async () => {
-      // The emitting `address` is the vault; page and window filtering happens
-      // on the scanned rows so this stays one query per anchor.
-      const result = await options.getTidx(chainId).fetch({
-        chainId,
-        query: `
+      // Filter emitters before applying the cap so unrelated forged logs cannot
+      // invalidate rates for requested vaults.
+      const result = await options
+        .getTidx(chainId)
+        .fetch({
+          chainId,
+          query: `
           SELECT address, block_num
           FROM EngineMigrated
-          WHERE block_timestamp > '${since}' AND block_timestamp <= '${measuredAt}'
+          WHERE address IN (${scope.addresses})
+            AND block_timestamp > '${since}' AND block_timestamp <= '${measuredAt}'
           ORDER BY block_num DESC
           LIMIT ${migrationScanLimit + 1}
         ` as string,
-        signatures: [migratedSignature],
-      })
+          signatures: [migratedSignature],
+        })
+        .catch((cause) => {
+          options.onFailure?.(Tidx.providerFailure(cause))
+          throw cause
+        })
       const rows: readonly Record<string, unknown>[] = result.rows
       if (rows.length > migrationScanLimit) return null
       return rows.flatMap((row) => {
@@ -401,7 +467,7 @@ async function recentMigrations(
       })
     },
     {
-      key: `earn-apy:v1:${chainId}:migrations`,
+      key: `earn-apy:v1:${chainId}:migrations:${scope.key}`,
       store: options.store,
       ttl: bucketWidth,
     },
@@ -411,5 +477,32 @@ async function recentMigrations(
 }
 
 declare namespace recentMigrations {
-  type Options = Pick<measurePage.Options, 'chainId' | 'getTidx' | 'measuredAt' | 'store'>
+  type Options = Pick<
+    measurePage.Options,
+    'chainId' | 'getTidx' | 'measuredAt' | 'onFailure' | 'store' | 'vaults'
+  >
+}
+
+/** Builds the bounded query and cache identity for a set of Earn vault emitters. */
+export function migrationScope(options: migrationScope.Options): migrationScope.Result {
+  const normalized = [...new Set(options.vaults.map((vault) => vault.toLowerCase()))].sort()
+  return {
+    addresses: normalized.map((vault) => `'${vault}'`).join(', '),
+    key: Hash.sha256(Hex.fromString(normalized.join(','))).slice(2),
+  }
+}
+
+export declare namespace migrationScope {
+  /** Inputs selecting the requested Earn vault emitters. */
+  type Options = {
+    /** Earn vault emitters included in the migration scan. */
+    vaults: readonly Address[]
+  }
+  /** Bounded migration-query scope derived from requested vault addresses. */
+  type Result = {
+    /** SQL literals restricting migration emitters to requested vaults. */
+    addresses: string
+    /** Stable cache identity for the normalized vault set. */
+    key: string
+  }
 }

package/src/internal/EarnSharePrices.test.ts

@@ -0,0 +1,182 @@
+import {
+  BaseError,
+  ContractFunctionExecutionError,
+  ContractFunctionRevertedError,
+  ContractFunctionZeroDataError,
+  parseAbi,
+} from 'viem'
+
+import * as EarnSharePrices from './EarnSharePrices.js'
+
+const abi = parseAbi(['function previewRedeem(uint256 shares) view returns (uint256 assets)'])
+
+function executionError(cause: BaseError) {
+  return new ContractFunctionExecutionError(cause, {
+    abi,
+    args: [1n],
+    functionName: 'previewRedeem',
+  })
+}
+
+describe('timestamps', () => {
+  test('anchors daily observations to the requested start', () => {
+    expect(
+      EarnSharePrices.timestamps({
+        from: '2026-07-01T09:30:00Z',
+        to: '2026-07-03T12:00:00Z',
+      }),
+    ).toMatchInlineSnapshot(`
+      [
+        "2026-07-01T09:30:00.000Z",
+        "2026-07-02T09:30:00.000Z",
+        "2026-07-03T09:30:00.000Z",
+      ]
+    `)
+  })
+})
+
+describe('isUnavailable', () => {
+  test('accepts only contract execution failures that prove a quote is unavailable', () => {
+    expect([
+      EarnSharePrices.isUnavailable(
+        executionError(new ContractFunctionRevertedError({ abi, functionName: 'previewRedeem' })),
+      ),
+      EarnSharePrices.isUnavailable(
+        executionError(new ContractFunctionZeroDataError({ functionName: 'previewRedeem' })),
+      ),
+      EarnSharePrices.isUnavailable(executionError(new BaseError('RPC request timed out.'))),
+      EarnSharePrices.isUnavailable(new Error('RPC request timed out.')),
+    ]).toMatchInlineSnapshot(`
+      [
+        true,
+        true,
+        false,
+        false,
+      ]
+    `)
+  })
+})
+
+describe('quoteShareAmount', () => {
+  test('returns one whole share through the uint256 decimal limit', () => {
+    expect([
+      EarnSharePrices.quoteShareAmount({ shareDecimals: 0 }).toString(),
+      EarnSharePrices.quoteShareAmount({ shareDecimals: 18 }).toString(),
+      EarnSharePrices.quoteShareAmount({ shareDecimals: 77 }).toString(),
+    ]).toMatchInlineSnapshot(`
+      [
+        "1",
+        "1000000000000000000",
+        "100000000000000000000000000000000000000000000000000000000000000000000000000000",
+      ]
+    `)
+  })
+
+  test('rejects a whole share that exceeds uint256', () => {
+    expect(() =>
+      EarnSharePrices.quoteShareAmount({ shareDecimals: 78 }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[EarnSharePrices.UnsupportedShareDecimalsError: Share tokens with 78 decimals cannot represent one whole share as a uint256.]`,
+    )
+  })
+})
+
+describe('parseCoverage', () => {
+  test('accepts the latest indexed timestamp at the requested observation', () => {
+    expect(
+      EarnSharePrices.parseCoverage({
+        row: { timestamp: '2026-07-02T00:00:00.000Z' },
+        timestamp: '2026-07-02T00:00:00.000Z',
+      }),
+    ).toBeUndefined()
+  })
+
+  test('rejects observations beyond indexed coverage', () => {
+    expect(() =>
+      EarnSharePrices.parseCoverage({
+        row: { timestamp: '2026-07-01T00:00:00.000Z' },
+        timestamp: '2026-07-02T00:00:00.000Z',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[EarnSharePrices.IndexedCoverageError: Indexed history does not yet cover 2026-07-02T00:00:00.000Z.]`,
+    )
+  })
+
+  test('rejects malformed indexed coverage', () => {
+    expect(() =>
+      EarnSharePrices.parseCoverage({
+        row: { timestamp: 'not-a-timestamp' },
+        timestamp: '2026-07-02T00:00:00.000Z',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[EarnSharePrices.MalformedResponseError: TIDX returned no indexed coverage timestamp.]`,
+    )
+  })
+})
+
+describe('parseBlocks', () => {
+  test('returns boundaries in requested order', () => {
+    const timestamps = ['2026-07-01T00:00:00.000Z', '2026-07-02T00:00:00.000Z']
+    expect(
+      EarnSharePrices.parseBlocks({
+        rows: [
+          {
+            kind: 'boundary',
+            num: 20,
+            requested_at: timestamps[1],
+            timestamp: '2026-07-01T23:59:59.000Z',
+          },
+          {
+            kind: 'boundary',
+            num: 10,
+            requested_at: timestamps[0],
+            timestamp: '2026-06-30T23:59:59.000Z',
+          },
+        ],
+        timestamps,
+      }),
+    ).toMatchInlineSnapshot(`
+      [
+        {
+          "number": 10,
+          "requestedAt": "2026-07-01T00:00:00.000Z",
+          "timestamp": "2026-06-30T23:59:59.000Z",
+        },
+        {
+          "number": 20,
+          "requestedAt": "2026-07-02T00:00:00.000Z",
+          "timestamp": "2026-07-01T23:59:59.000Z",
+        },
+      ]
+    `)
+  })
+
+  test('classifies an absent boundary separately from malformed data', () => {
+    expect(() =>
+      EarnSharePrices.parseBlocks({
+        rows: [],
+        timestamps: ['2026-07-02T00:00:00.000Z'],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[EarnSharePrices.IndexedBlockNotFoundError: No indexed block exists at or before 2026-07-02T00:00:00.000Z.]`,
+    )
+  })
+
+  test('rejects malformed boundary rows as upstream data failures', () => {
+    expect(() =>
+      EarnSharePrices.parseBlocks({
+        rows: [
+          {
+            kind: 'boundary',
+            num: 'not-a-number',
+            requested_at: '2026-07-02T00:00:00.000Z',
+            timestamp: '2026-07-01T23:59:59.000Z',
+          },
+        ],
+        timestamps: ['2026-07-02T00:00:00.000Z'],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[EarnSharePrices.MalformedResponseError: TIDX returned a malformed share-price boundary.]`,
+    )
+  })
+})