tapimo 0.7.0 → 0.7.2

package/src/internal/Tidx.local.test.ts

@@ -1,13 +1,18 @@
+/** @module-tag localnet */
+
 import * as TestApp from '../../test/App.js'
 import * as Runtime from '../../test/runtime.js'
 import * as Indexer from '../apps/data/routes/indexer.js'
+import type * as Log from './Log.js'
+import * as Tidx from './Tidx.js'
 
 describe('local TIDX runtime', () => {
   test.runIf(Runtime.get().mode === 'localnet')(
-    'proxies queries to a disposable TIDX',
+    'observes queries through a disposable TIDX',
     async () => {
       const runtime = Runtime.get()
-      const client = TestApp.client()
+      const entries: Log.Entry[] = []
+      const client = TestApp.client({ logger: (entry) => void entries.push(entry) })
       const response = await client.v1.indexer.query.$get(
         { query: { chainId: String(runtime.chainId), sql: 'select 1 as value' } },
         TestApp.auth,
@@ -20,7 +25,7 @@ describe('local TIDX runtime', () => {
       [
         "value",
       ]
-    `)
+      `)
       expect(body.rows).toMatchInlineSnapshot(`
       [
         [
@@ -28,6 +33,76 @@ describe('local TIDX runtime', () => {
         ],
       ]
     `)
+      expect(entries[0]?.provider).toBeUndefined()
+      expect(entries[0]?.timings?.['tidx']).toBeGreaterThan(0)
+    },
+  )
+
+  test.runIf(Runtime.get().mode === 'localnet')(
+    'does not record caller query rejections as provider failures',
+    async () => {
+      const runtime = Runtime.get()
+      const entries: Log.Entry[] = []
+      const client = TestApp.client({ logger: (entry) => void entries.push(entry) })
+      const response = await client.v1.indexer.query.$get(
+        {
+          query: {
+            chainId: String(runtime.chainId),
+            sql: 'select * from missing_observability_table',
+          },
+        },
+        TestApp.auth,
+      )
+
+      expect(response.status).toBe(422)
+      expect(entries[0]?.provider).toBeUndefined()
+      expect(entries[0]?.timings?.['tidx']).toBeGreaterThan(0)
+    },
+  )
+
+  test.runIf(Runtime.get().mode === 'localnet')(
+    'clears a handled failure after a successful query',
+    async () => {
+      const runtime = Runtime.get()
+      const failures: (Log.ProviderFailure | undefined)[] = []
+      const timings: number[] = []
+      const client = Tidx.observe(
+        Tidx.getClient({
+          chainId: runtime.chainId,
+          tidx: { baseUrl: runtime.tidxUrl },
+        }),
+        {
+          record: (failure) => void failures.push(failure),
+          time: async (fn) => {
+            const start = performance.now()
+            try {
+              return await fn()
+            } finally {
+              timings.push(performance.now() - start)
+            }
+          },
+        },
+      )
+
+      await expect(
+        client.fetch({
+          chainId: runtime.chainId,
+          query: 'select * from missing_observability_table',
+        }),
+      ).rejects.toThrow()
+      await client.fetch({ chainId: runtime.chainId, query: 'select 1' })
+
+      expect(failures).toEqual([
+        {
+          failure: 'query',
+          id: 'tidx',
+          operation: 'query',
+          status: 422,
+        },
+        undefined,
+      ])
+      expect(timings).toHaveLength(2)
+      expect(timings.every((duration) => duration > 0)).toBe(true)
     },
   )
 })

package/src/internal/Tidx.test.ts

@@ -1,5 +1,6 @@
 import { Tidx as TidxClient } from 'tidx.ts'
 
+import * as Zones from '../apps/Zones.js'
 import type * as Auth from './Auth.js'
 import * as Tidx from './Tidx.js'
 import type * as Viem from './Viem.js'
@@ -25,6 +26,115 @@ function fakeClient(fetch: Tidx.Client['fetch']): Tidx.Client {
   return { fetch } as never
 }
 
+describe('providerFailure', () => {
+  test('classifies failed 200 bodies as payload failures', () => {
+    expect(Tidx.providerFailure(appError('secret upstream detail'))).toEqual({
+      failure: 'payload',
+      id: 'tidx',
+      operation: 'query',
+    })
+  })
+
+  test('classifies query and HTTP failures', () => {
+    expect([
+      Tidx.providerFailure(appError('secret upstream detail', 422)),
+      Tidx.providerFailure(appError('secret upstream detail', 503)),
+    ]).toMatchInlineSnapshot(`
+      [
+        {
+          "failure": "query",
+          "id": "tidx",
+          "operation": "query",
+          "status": 422,
+        },
+        {
+          "failure": "http",
+          "id": "tidx",
+          "operation": "query",
+          "status": 503,
+        },
+      ]
+    `)
+  })
+
+  test('classifies timeout and rate-limit statuses', () => {
+    expect([
+      Tidx.providerFailure(appError('secret upstream detail', 408)),
+      Tidx.providerFailure(appError('secret upstream detail', 429)),
+    ]).toMatchInlineSnapshot(`
+      [
+        {
+          "failure": "timeout",
+          "id": "tidx",
+          "operation": "query",
+          "status": 408,
+        },
+        {
+          "failure": "rate_limit",
+          "id": "tidx",
+          "operation": "query",
+          "status": 429,
+        },
+      ]
+    `)
+  })
+
+  test('classifies transport failures without their messages', () => {
+    expect([
+      Tidx.providerFailure(new DOMException('secret timeout detail', 'TimeoutError')),
+      Tidx.providerFailure(new TypeError('secret network detail')),
+      Tidx.providerFailure(new Error('secret unknown detail')),
+    ]).toMatchInlineSnapshot(`
+      [
+        {
+          "failure": "timeout",
+          "id": "tidx",
+          "operation": "query",
+        },
+        {
+          "failure": "network",
+          "id": "tidx",
+          "operation": "query",
+        },
+        {
+          "failure": "unknown",
+          "id": "tidx",
+          "operation": "query",
+        },
+      ]
+    `)
+  })
+})
+
+describe('responseFailure', () => {
+  test('classifies failed 200 bodies without consuming the response', async () => {
+    const response = Response.json({ error: 'secret upstream detail', ok: false })
+
+    expect(await Tidx.responseFailure(response)).toEqual({
+      failure: 'payload',
+      id: 'tidx',
+      operation: 'query',
+    })
+    expect(await response.json()).toEqual({ error: 'secret upstream detail', ok: false })
+  })
+
+  test('ignores successful 200 bodies', async () => {
+    const response = Response.json({ ok: true })
+
+    expect(await Tidx.responseFailure(response)).toBeUndefined()
+  })
+})
+
+describe('isQueryRejection', () => {
+  test('matches caller-caused query statuses only', () => {
+    expect(
+      [400, 422, 408, 429, 500].map((status) =>
+        Tidx.isQueryRejection(new Response(null, { status })),
+      ),
+    ).toEqual([true, true, false, false, false])
+  })
+})
+
 describe('escape', () => {
   test('doubles quotes for ANSI string literals, leaving backslashes alone', () => {
     expect(Tidx.escape('USD')).toMatchInlineSnapshot(`"USD"`)
@@ -145,6 +255,19 @@ describe('withTransientRetry', () => {
   })
 })
 
+describe('isDeterministicError', () => {
+  test('flags indexer failures a retry cannot fix', () => {
+    // The planner rejects the query shape outright (e.g. 422 `db error`).
+    expect(Tidx.isDeterministicError(appError('db error', 422))).toBe(true)
+    expect(Tidx.isDeterministicError(appError('syntax error near "SELCT"'))).toBe(true)
+    // Transient failures retry instead.
+    expect(Tidx.isDeterministicError(appError('db error'))).toBe(false)
+    expect(Tidx.isDeterministicError(appError('bad gateway', 502))).toBe(false)
+    // Non-indexer errors are not indexer failures at all.
+    expect(Tidx.isDeterministicError(new Error('db error'))).toBe(false)
+  })
+})
+
 describe('resolve', () => {
   test('defaults to the per-chain indexer URL', () => {
     expect(Tidx.resolve(undefined, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
@@ -185,8 +308,42 @@ describe('resolve', () => {
     `)
   })
 
+  test('selects a serialized base URL by chain id', () => {
+    const tidx = {
+      baseUrl: JSON.stringify({ 4217: 'https://mainnet.indexer.test', 42431: 'https://testnet.indexer.test' }), // prettier-ignore
+    }
+
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://mainnet.indexer.test",
+        "basicAuth": undefined,
+      }
+    `)
+    expect(Tidx.resolve(tidx, { chainId: 42431, principal: null })).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://testnet.indexer.test",
+        "basicAuth": undefined,
+      }
+    `)
+  })
+
+  test('passes Zone metadata to the resolver', () => {
+    expect(
+      Tidx.resolve(({ zone }) => ({ baseUrl: zone ? 'http://tidx:8080' : undefined }), {
+        chainId: Zones.zoneE.id,
+        principal: null,
+        zone: Zones.zoneE,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "http://tidx:8080",
+        "basicAuth": undefined,
+      }
+    `)
+  })
+
   test('the static form ignores the principal', () => {
-    const tidx = { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+    const tidx = { auth: 'user:pass', baseUrl: 'https://internal.indexer' }
     expect(Tidx.resolve(tidx, { chainId: 4217, principal: publicPrincipal }))
       .toMatchInlineSnapshot(`
       {
@@ -206,7 +363,7 @@ describe('resolve', () => {
   test('resolves Bearer auth', () => {
     expect(
       Tidx.resolve(
-        { baseUrl: 'https://internal.indexer', bearerAuth: 'zone-secret' },
+        { auth: 'zone-secret', baseUrl: 'https://internal.indexer' },
         { chainId: 4217, principal: apiKeyPrincipal },
       ),
     ).toMatchInlineSnapshot(`
@@ -218,11 +375,36 @@ describe('resolve', () => {
     `)
   })
 
+  test('selects Bearer auth by chain id', () => {
+    const tidx = {
+      auth: { 4217: 'mainnet-secret', 42431: 'testnet-secret' },
+      baseUrl: 'https://internal.indexer',
+    }
+
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: null }).bearerAuth).toBe('mainnet-secret')
+    expect(Tidx.resolve(tidx, { chainId: 42431, principal: null }).bearerAuth).toBe(
+      'testnet-secret',
+    )
+    expect(Tidx.resolve(tidx, { chainId: 421_700_001, principal: null }).bearerAuth).toBeUndefined()
+  })
+
+  test('parses serialized Bearer auth by chain id', () => {
+    const tidx = {
+      auth: JSON.stringify({ 421_700_001: 'zone-secret' }),
+      baseUrl: 'https://internal.indexer',
+    }
+
+    expect(Tidx.resolve(tidx, { chainId: 421_700_001, principal: null }).bearerAuth).toBe(
+      'zone-secret',
+    )
+    expect(Tidx.resolve(tidx, { chainId: 4217, principal: null }).bearerAuth).toBeUndefined()
+  })
+
   test('the resolver form routes anonymous callers to a separate upstream', () => {
-    const tidx = ({ principal }: Viem.resolve.Context) =>
+    const tidx = ({ principal }: Viem.resolveRpc.Context) =>
       principal?.type === 'public'
         ? { baseUrl: 'https://indexer.tempo.xyz' }
-        : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+        : { auth: 'user:pass', baseUrl: 'https://internal.indexer' }
     expect(Tidx.resolve(tidx, { chainId: 4217, principal: publicPrincipal }))
       .toMatchInlineSnapshot(`
       {
@@ -268,7 +450,7 @@ describe('getClient', () => {
     try {
       const client = Tidx.getClient({
         chainId: 4217,
-        tidx: { baseUrl: 'https://internal.indexer', bearerAuth: 'zone-secret' },
+        tidx: { auth: 'zone-secret', baseUrl: 'https://internal.indexer' },
       })
       await client.fetch({ query: 'select 1' })
 
@@ -286,33 +468,45 @@ describe('createGetClient', () => {
       tidx: ({ principal }) =>
         principal?.type === 'public'
           ? { baseUrl: 'https://indexer.tempo.xyz' }
-          : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' },
+          : { auth: 'user:pass', baseUrl: 'https://internal.indexer' },
     })
     // Callers resolving to the same upstream share a client; distinct upstreams
     // (and chain ids) get distinct clients.
-    expect(getTidx(4217, apiKeyPrincipal)).toBe(getTidx(4217, apiKeyPrincipal))
-    expect(getTidx(4217, publicPrincipal)).toBe(getTidx(4217, publicPrincipal))
-    expect(getTidx(4217, publicPrincipal)).not.toBe(getTidx(4217, apiKeyPrincipal))
-    expect(getTidx(4217, apiKeyPrincipal)).not.toBe(getTidx(42431, apiKeyPrincipal))
+    expect(getTidx(4217, { principal: apiKeyPrincipal })).toBe(
+      getTidx(4217, { principal: apiKeyPrincipal }),
+    )
+    expect(getTidx(4217, { principal: publicPrincipal })).toBe(
+      getTidx(4217, { principal: publicPrincipal }),
+    )
+    expect(getTidx(4217, { principal: publicPrincipal })).not.toBe(
+      getTidx(4217, { principal: apiKeyPrincipal }),
+    )
+    expect(getTidx(4217, { principal: apiKeyPrincipal })).not.toBe(
+      getTidx(42431, { principal: apiKeyPrincipal }),
+    )
   })
 
   test('shares a client across principals when the resolver ignores them', () => {
     const getTidx = Tidx.createGetClient()
     // With no resolver the upstream is identical for every caller, so the key
     // (resolved output) collapses and all principals share one client.
-    expect(getTidx(4217, publicPrincipal)).toBe(getTidx(4217, apiKeyPrincipal))
-    expect(getTidx(4217, null)).toBe(getTidx(4217, publicPrincipal))
+    expect(getTidx(4217, { principal: publicPrincipal })).toBe(
+      getTidx(4217, { principal: apiKeyPrincipal }),
+    )
+    expect(getTidx(4217, { principal: null })).toBe(getTidx(4217, { principal: publicPrincipal }))
   })
 
   test('does not share clients across Bearer credentials', () => {
     const getTidx = Tidx.createGetClient({
       tidx: ({ principal }) => ({
+        auth: principal?.type === 'public' ? 'public-secret' : 'private-secret',
         baseUrl: 'https://internal.indexer',
-        bearerAuth: principal?.type === 'public' ? 'public-secret' : 'private-secret',
       }),
     })
 
-    expect(getTidx(4217, publicPrincipal)).not.toBe(getTidx(4217, apiKeyPrincipal))
+    expect(getTidx(4217, { principal: publicPrincipal })).not.toBe(
+      getTidx(4217, { principal: apiKeyPrincipal }),
+    )
   })
 
   test('consults the resolver on every call but builds one client per upstream', () => {
@@ -322,14 +516,14 @@ describe('createGetClient', () => {
         const config =
           principal?.type === 'public'
             ? { baseUrl: 'https://indexer.tempo.xyz' }
-            : { baseUrl: 'https://internal.indexer', basicAuth: 'user:pass' }
+            : { auth: 'user:pass', baseUrl: 'https://internal.indexer' }
         seen.push(principal?.type)
         return config
       },
     })
-    const first = getTidx(4217, apiKeyPrincipal)
-    const second = getTidx(4217, apiKeyPrincipal)
-    getTidx(4217, publicPrincipal)
+    const first = getTidx(4217, { principal: apiKeyPrincipal })
+    const second = getTidx(4217, { principal: apiKeyPrincipal })
+    getTidx(4217, { principal: publicPrincipal })
     // The resolver is consulted on every call (it derives the cache key from its
     // resolved output) — including the repeat that hits the cache — so a
     // per-request principal is always honored.

package/src/internal/Tidx.ts

@@ -1,6 +1,9 @@
 import { Tidx } from 'tidx.ts'
+import type { Chain } from 'viem'
 
-import type * as Auth from './Auth.js'
+import * as Auth from './Auth.js'
+import * as Errors from './Errors.js'
+import type * as Log from './Log.js'
 import * as Viem from './Viem.js'
 
 /** Default Tempo indexer (TIDX) base URLs. */
@@ -12,37 +15,36 @@ export const url: Record<number, string> = {
 /** TIDX query client. */
 export type Client = Tidx.Tidx
 
-/** Gets a TIDX query client for a Tempo chain id and request principal. */
-export type GetClient = (chainId?: Viem.ChainId, principal?: Auth.Principal | null) => Client
+/** Gets a TIDX query client for a Tempo chain id and request context. */
+export type GetClient = (
+  chainId?: Viem.ChainId,
+  options?: Pick<getClient.Options, 'principal' | 'zone'>,
+) => Client
 
-/**
- * Resolves a TIDX base URL for a Tempo chain id. May return `undefined` to fall
- * back to the built-in {@link url} map (e.g. for a chain the resolver doesn't
- * serve).
- */
-export type UrlResolver = (chainId: Viem.ChainId) => string | undefined
+/** Shared, per-chain, or dynamically resolved TIDX URLs. */
+export type UrlResolver = Viem.UrlResolver
 
 /**
  * Resolves the effective TIDX config for a single request.
  *
  * Accepts either a static config object or a per-request resolver function that
- * receives a {@link Viem.resolve.Context} (`chainId` plus the request
+ * receives a {@link Viem.resolveRpc.Context} (`chainId` plus the request
  * `principal`), so callers can route traffic per caller — e.g. send anonymous
  * (`principal.type === 'public'`) traffic to a separate, no-auth indexer. A
  * missing `baseUrl` falls back to the built-in public host map ({@link url});
- * missing auth fields send no Authorization header.
+ * missing `auth` sends no Authorization header.
  */
 export function resolve(
   tidx: getClient.Tidx | undefined,
-  context: Viem.resolve.Context,
+  context: Viem.resolveRpc.Context,
 ): resolve.Resolved {
   const config = typeof tidx === 'function' ? tidx(context) : tidx
   return {
+    ...Auth.resolveCredential({ chainId: context.chainId, value: config?.auth }),
     baseUrl:
-      (typeof config?.baseUrl === 'function' ? config.baseUrl(context.chainId) : config?.baseUrl) ??
+      Viem.resolveUrl(config?.baseUrl, context.chainId) ??
+      context.zone?.rpcUrls['tidx']?.http[0] ??
       url[context.chainId],
-    basicAuth: config?.basicAuth,
-    ...(config?.bearerAuth ? { bearerAuth: config.bearerAuth } : {}),
   }
 }
 
@@ -63,8 +65,8 @@ export declare namespace resolve {
 }
 
 export function getClient(options: getClient.Options): Client {
-  const { chainId = Viem.defaultChainId, principal = null, tidx } = options
-  const { baseUrl, basicAuth, bearerAuth } = resolve(tidx, { chainId, principal })
+  const { chainId = Viem.defaultChainId, principal = null, tidx, zone } = options
+  const { baseUrl, basicAuth, bearerAuth } = resolve(tidx, { chainId, principal, zone })
   return withTransientRetry(
     Tidx.create({
       baseUrl,
@@ -79,7 +81,7 @@ export function getClient(options: getClient.Options): Client {
  * Builds a memoized {@link GetClient} that constructs one TIDX client per
  * resolved upstream and reuses it. Clients are stateless HTTP transports, so
  * reusing them avoids per-call construction cost. The cache key is the resolved
- * output (`baseUrl` + `basicAuth` + `chainId`), not the principal, so a resolver
+ * output (`baseUrl` + auth + `chainId`), not the principal, so a resolver
  * `tidx` may branch on any principal field while client cardinality stays
  * bounded by the number of distinct upstreams — callers that resolve to the same
  * upstream share a client. Shared by `data()` (per-request reads) and
@@ -90,15 +92,16 @@ export function createGetClient(options: createGetClient.Options = {}): GetClien
   const { defaultChainId = Viem.defaultChainId, tidx } = options
   const clients = new Map<string, Client>()
 
-  return (chainId = defaultChainId, principal = null) => {
+  return (chainId = defaultChainId, options = {}) => {
+    const { principal = null, zone } = options
     // Resolve to derive the cache key; `getClient` re-resolves to build the
     // client on a miss. `resolve` is pure and cheap, so the extra call is free.
-    const { baseUrl, basicAuth, bearerAuth } = resolve(tidx, { chainId, principal })
+    const { baseUrl, basicAuth, bearerAuth } = resolve(tidx, { chainId, principal, zone })
     const cacheKey = `${baseUrl}|${basicAuth ?? ''}|${bearerAuth ?? ''}|${chainId}`
     const existing = clients.get(cacheKey)
     if (existing) return existing
 
-    const client = getClient({ chainId, principal, tidx })
+    const client = getClient({ chainId, principal, tidx, zone })
     clients.set(cacheKey, client)
     return client
   }
@@ -186,6 +189,85 @@ export function withTransientRetry(client: Client): Client {
   }
 }
 
+/** Adds request-scoped timing and redacted failure diagnostics to a TIDX client. */
+export function observe(client: Client, options: observe.Options): Client {
+  const fetch = client.fetch.bind(client)
+  return {
+    ...client,
+    fetch: (parameters) =>
+      options.time(async () => {
+        try {
+          const result = await fetch(parameters)
+          options.record(undefined)
+          return result
+        } catch (cause) {
+          options.record(providerFailure(cause))
+          throw cause
+        }
+      }),
+  }
+}
+
+export declare namespace observe {
+  /** Request-scoped observability hooks for TIDX calls. */
+  type Options = {
+    /** Records a failure, or clears one after a later successful query. */
+    record: (failure: Log.ProviderFailure | undefined) => void
+    /** Measures the complete TIDX call, including retries. */
+    time: <value>(fn: () => Promise<value>) => Promise<value>
+  }
+}
+
+/** Returns bounded failure metadata for a TIDX request. */
+export function providerFailure(cause: unknown): Log.ProviderFailure {
+  const base = { id: 'tidx', operation: 'query' } as const
+  if (
+    cause instanceof DOMException &&
+    (cause.name === 'AbortError' || cause.name === 'TimeoutError')
+  )
+    return { ...base, failure: 'timeout' }
+
+  const status = Errors.getStatus(cause)
+  if (status !== undefined && status >= 200 && status < 300) return { ...base, failure: 'payload' }
+  if (status === 408) return { ...base, failure: 'timeout', status }
+  if (status === 422) return { ...base, failure: 'query', status }
+  if (status === 429) return { ...base, failure: 'rate_limit', status }
+  if (status !== undefined) return { ...base, failure: 'http', status }
+  if (cause instanceof TypeError) return { ...base, failure: 'network' }
+  return { ...base, failure: 'unknown' }
+}
+
+/** Returns bounded failure metadata when a TIDX response represents a failed query. */
+export async function responseFailure(
+  response: Response,
+): Promise<Log.ProviderFailure | undefined> {
+  if (!response.ok) return providerFailure(response)
+
+  // Parsing is observational; clone the response so the raw route can return its body unchanged.
+  const body: unknown = await response
+    .clone()
+    .json()
+    .catch(() => undefined)
+  if (typeof body === 'object' && body !== null && 'ok' in body && body.ok === true)
+    return undefined
+  return { failure: 'payload', id: 'tidx', operation: 'query' }
+}
+
+/** Whether a TIDX response is a deterministic rejection of the caller's query. */
+export function isQueryRejection(cause: unknown): boolean {
+  const status = Errors.getStatus(cause)
+  return status === 400 || status === 422
+}
+
+/**
+ * True for deterministic indexer failures a retry cannot fix: a
+ * `FetchRequestError` outside {@link isTransientError}'s transient classes,
+ * e.g. an HTTP 422 `db error` for a query shape the planner cannot execute.
+ */
+export function isDeterministicError(error: unknown): boolean {
+  return error instanceof Tidx.FetchRequestError && !isTransientError(error)
+}
+
 /**
  * True for transient indexer errors: an HTTP-level transient failure
  * (408/429/5xx), or a `FetchRequestError` that came back on a **2xx** HTTP
@@ -214,30 +296,28 @@ export declare namespace getClient {
     principal?: Auth.Principal | null | undefined
     /** TIDX query client options. */
     tidx?: Tidx | undefined
+    /** Zone chain metadata used for TIDX URL resolution. */
+    zone?: Chain | undefined
   }
 
   /**
    * TIDX query client options: either a static config, or a per-request
-   * resolver function that receives a {@link Viem.resolve.Context} and returns
+   * resolver function that receives a {@link Viem.resolveRpc.Context} and returns
    * the config to use (e.g. routing anonymous callers to a public, no-auth
    * indexer).
    */
   type Tidx =
     | {
+        /** Shared or per-chain TIDX credentials. Values containing `:` use Basic auth; others use Bearer auth. */
+        auth?: Auth.ChainCredential | undefined
         /** Resolves the TIDX base URL for a Tempo chain id, or a static base URL. */
-        baseUrl?: UrlResolver | string | undefined
-        /** Basic auth credentials for TIDX requests. */
-        basicAuth?: string | undefined
-        /** Bearer auth credential for TIDX requests. */
-        bearerAuth?: string | undefined
+        baseUrl?: UrlResolver | undefined
       }
-    | ((context: Viem.resolve.Context) => {
+    | ((context: Viem.resolveRpc.Context) => {
+        /** Shared or per-chain TIDX credentials, or undefined for none. */
+        auth?: Auth.ChainCredential | undefined
         /** TIDX base URL to use; falls back to the built-in public host when omitted. */
         baseUrl?: string | undefined
-        /** Basic auth credentials for TIDX requests, or undefined for none. */
-        basicAuth?: string | undefined
-        /** Bearer auth credential for TIDX requests, or undefined for none. */
-        bearerAuth?: string | undefined
       })
 }
 

package/src/internal/VerifiedTokens.test.ts

@@ -126,6 +126,21 @@ describe('read', () => {
     expect(snapshot?.version).toBe('v2')
     expect(snapshot?.list.map((token) => token.symbol)).toEqual(['aUSD'])
   })
+
+  test('round-trips a Zone chain id above the signed 32-bit range', async () => {
+    const chainId = 421_700_001
+    const db = TestApp.database()
+    await seed(db, chainId, 'zone', tokens)
+    const [head, rows, snapshot] = await Promise.all([
+      core_VerifiedTokens.head(db, chainId),
+      core_VerifiedTokens.list(db, chainId),
+      VerifiedTokens.read(db, chainId),
+    ])
+
+    expect(head?.chainId).toBe(chainId)
+    expect(rows.map((row) => row.chainId)).toEqual(tokens.map(() => chainId))
+    expect(snapshot?.chainId).toBe(chainId)
+  })
 })
 
 describe('snapshot', () => {