tapimo 0.7.1 → 0.8.0

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,37 @@ 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 }),
+    ...(context.zone && config?.zoneHeaders ? { zoneHeaders: config.zoneHeaders } : {}),
     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 } : {}),
   }
 }
 
@@ -59,18 +62,25 @@ export declare namespace resolve {
     basicAuth?: string | undefined
     /** Bearer auth credential, or undefined to send no Bearer auth. */
     bearerAuth?: string | undefined
+    /** Headers sent to Zone indexer upstreams. */
+    zoneHeaders?: Viem.ZoneHeaders | undefined
   }
 }
 
 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, zoneHeaders } = resolve(tidx, {
+    chainId,
+    principal,
+    zone,
+  })
   return withTransientRetry(
     Tidx.create({
       baseUrl,
       basicAuth,
       bearerAuth,
       chainId,
+      headers: zoneHeaders,
     }),
   )
 }
@@ -79,7 +89,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 +100,20 @@ 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 cacheKey = `${baseUrl}|${basicAuth ?? ''}|${bearerAuth ?? ''}|${chainId}`
+    const { baseUrl, basicAuth, bearerAuth, zoneHeaders } = resolve(tidx, {
+      chainId,
+      principal,
+      zone,
+    })
+    const cacheKey = `${baseUrl}|${basicAuth ?? ''}|${bearerAuth ?? ''}|${JSON.stringify(zoneHeaders)}|${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 +201,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 +308,32 @@ 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
+        /** Headers sent to Zone indexer upstreams. */
+        zoneHeaders?: Viem.ZoneHeaders | 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
+        /** Headers sent to Zone indexer upstreams. */
+        zoneHeaders?: Viem.ZoneHeaders | 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', () => {

package/src/internal/Viem.test.ts

@@ -1,3 +1,7 @@
+import { ZoneRpcAuthentication } from 'ox/tempo'
+import { defineChain, type Chain } from 'viem'
+import { tempoTestnet } from 'viem/tempo/chains'
+
 import type * as Auth from './Auth.js'
 import * as Viem from './Viem.js'
 
@@ -11,6 +15,21 @@ const apiKeyPrincipal: Auth.Principal = {
   orgId: 'org_test',
   type: 'api_key',
 }
+const zone = defineChain({
+  ...tempoTestnet,
+  contracts: {
+    ...tempoTestnet.contracts,
+    messenger: { address: '0x0000000000000000000000000000000000000001' },
+    portal: { address: '0x0000000000000000000000000000000000000002' },
+  },
+  id: 421_700_001,
+  name: 'Zone E',
+  rpcUrls: {
+    default: { http: ['https://zone.rpc.test'] },
+    internal: { http: ['https://internal.zone.rpc.test'] },
+  },
+  sourceId: tempoTestnet.id,
+}) satisfies Chain
 
 describe('isMainnet', () => {
   test('is true only for the mainnet chain id', () => {
@@ -24,15 +43,41 @@ describe('isMainnet', () => {
   })
 })
 
-describe('resolve', () => {
+describe('configuredChainIds', () => {
+  test('returns ids from object and serialized URL maps', () => {
+    expect(Viem.configuredChainIds({ 31_318: 'https://nextfork.tidx.test' })).toEqual([31_318])
+    expect(
+      Viem.configuredChainIds(
+        JSON.stringify({
+          31_318: 'https://nextfork.tidx.test',
+          421_700_002: 'https://zone.tidx.test',
+        }),
+      ),
+    ).toEqual([31_318, 421_700_002])
+  })
+
+  test('returns no ids for shared URLs and dynamic resolvers', () => {
+    expect(Viem.configuredChainIds('https://tidx.test')).toEqual([])
+    expect(Viem.configuredChainIds(() => 'https://tidx.test')).toEqual([])
+  })
+
+  test('rejects malformed chain-id maps', () => {
+    for (const chainId of ['-1', '0', '031318', '0x7a56', '1e3', '9007199254740992', 'devnet'])
+      expect(() =>
+        Viem.configuredChainIds(JSON.stringify({ [chainId]: 'https://tidx.test' })),
+      ).toThrow('Expected a URL or a chain-id-to-URL JSON object.')
+  })
+})
+
+describe('resolveRpc', () => {
   test('defaults to the per-chain RPC URL', () => {
-    expect(Viem.resolve(undefined, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+    expect(Viem.resolveRpc(undefined, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
         "url": "https://rpc.tempo.xyz",
       }
     `)
-    expect(Viem.resolve(undefined, { chainId: 42431, principal: null })).toMatchInlineSnapshot(`
+    expect(Viem.resolveRpc(undefined, { chainId: 42431, principal: null })).toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
         "url": "https://rpc.testnet.tempo.xyz",
@@ -42,8 +87,8 @@ describe('resolve', () => {
 
   test('uses a static config override', () => {
     expect(
-      Viem.resolve(
-        { basicAuth: 'user:pass', url: (chainId) => `https://${chainId}.rpc.test` },
+      Viem.resolveRpc(
+        { auth: 'user:pass', url: (chainId) => `https://${chainId}.rpc.test` },
         { chainId: 4217, principal: null },
       ),
     ).toMatchInlineSnapshot(`
@@ -54,15 +99,62 @@ describe('resolve', () => {
     `)
   })
 
+  test('selects RPC URLs by chain id', () => {
+    const rpc = {
+      publicZoneUrl: JSON.stringify({ 421_700_001: 'https://public.zone.rpc.test' }),
+      url: JSON.stringify({ 4217: 'https://mainnet.rpc.test' }),
+    }
+
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+      {
+        "basicAuth": undefined,
+        "url": "https://mainnet.rpc.test",
+      }
+    `)
+    expect(Viem.resolveRpc(rpc, { chainId: zone.id, principal: null, zone }))
+      .toMatchInlineSnapshot(`
+      {
+        "basicAuth": undefined,
+        "publicZoneUrl": "https://public.zone.rpc.test",
+        "url": "https://internal.zone.rpc.test",
+      }
+    `)
+  })
+
+  test('selects auth and scheme by chain id', () => {
+    const rpc = { auth: { 4217: 'mainnet:secret', 42431: 'testnet-token' } }
+
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: null }).basicAuth).toBe(
+      'mainnet:secret',
+    )
+    expect(Viem.resolveRpc(rpc, { chainId: 42431, principal: null }).bearerAuth).toBe(
+      'testnet-token',
+    )
+    expect(
+      Viem.resolveRpc(rpc, { chainId: 421_700_001, principal: null }).basicAuth,
+    ).toBeUndefined()
+  })
+
+  test('parses serialized Basic auth by chain id', () => {
+    const rpc = { auth: JSON.stringify({ 4217: 'mainnet:secret' }) }
+
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: null }).basicAuth).toBe(
+      'mainnet:secret',
+    )
+    expect(Viem.resolveRpc(rpc, { chainId: 42431, principal: null }).basicAuth).toBeUndefined()
+  })
+
   test('the static form ignores the principal', () => {
-    const rpc = { basicAuth: 'user:pass', url: () => 'https://internal.rpc' }
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: publicPrincipal })).toMatchInlineSnapshot(`
+    const rpc = { auth: 'user:pass', url: () => 'https://internal.rpc' }
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: publicPrincipal }))
+      .toMatchInlineSnapshot(`
       {
         "basicAuth": "user:pass",
         "url": "https://internal.rpc",
       }
     `)
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: apiKeyPrincipal })).toMatchInlineSnapshot(`
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: apiKeyPrincipal }))
+      .toMatchInlineSnapshot(`
       {
         "basicAuth": "user:pass",
         "url": "https://internal.rpc",
@@ -71,17 +163,19 @@ describe('resolve', () => {
   })
 
   test('the resolver form routes anonymous callers to a separate upstream', () => {
-    const rpc = ({ principal }: Viem.resolve.Context) =>
+    const rpc = ({ principal }: Viem.resolveRpc.Context) =>
       principal?.type === 'public'
         ? { url: 'https://rpc.tempo.xyz' }
-        : { basicAuth: 'user:pass', url: 'https://internal.rpc' }
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: publicPrincipal })).toMatchInlineSnapshot(`
+        : { auth: 'user:pass', url: 'https://internal.rpc' }
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: publicPrincipal }))
+      .toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
         "url": "https://rpc.tempo.xyz",
       }
     `)
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: apiKeyPrincipal })).toMatchInlineSnapshot(`
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: apiKeyPrincipal }))
+      .toMatchInlineSnapshot(`
       {
         "basicAuth": "user:pass",
         "url": "https://internal.rpc",
@@ -90,11 +184,11 @@ describe('resolve', () => {
   })
 
   test('a null principal (trusted poller) takes the non-public branch', () => {
-    const rpc = ({ principal }: Viem.resolve.Context) =>
+    const rpc = ({ principal }: Viem.resolveRpc.Context) =>
       principal?.type === 'public'
         ? { url: 'https://rpc.tempo.xyz' }
-        : { basicAuth: 'user:pass', url: 'https://internal.rpc' }
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+        : { auth: 'user:pass', url: 'https://internal.rpc' }
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
       {
         "basicAuth": "user:pass",
         "url": "https://internal.rpc",
@@ -104,7 +198,7 @@ describe('resolve', () => {
 
   test('a resolver that omits url falls back to the built-in public host', () => {
     const rpc = () => ({})
-    expect(Viem.resolve(rpc, { chainId: 42431, principal: publicPrincipal }))
+    expect(Viem.resolveRpc(rpc, { chainId: 42431, principal: publicPrincipal }))
       .toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
@@ -112,6 +206,93 @@ describe('resolve', () => {
       }
     `)
   })
+
+  test('a resolver that omits url falls back to the Zone internal host', () => {
+    expect(Viem.resolveRpc(() => ({}), { chainId: zone.id, principal: publicPrincipal, zone }))
+      .toMatchInlineSnapshot(`
+      {
+        "basicAuth": undefined,
+        "publicZoneUrl": "https://zone.rpc.test",
+        "url": "https://internal.zone.rpc.test",
+      }
+    `)
+  })
+})
+
+describe('getClient', () => {
+  test('sends inferred Bearer auth', async () => {
+    const fetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json({ id: 1, jsonrpc: '2.0', result: '0x1079' }))
+    try {
+      const client = Viem.getClient({
+        chainId: 4217,
+        rpc: { auth: 'rpc-token', url: 'https://internal.rpc.test' },
+      })
+      await client.getChainId()
+
+      const [input, init] = fetch.mock.calls[0]!
+      const upstream = new Request(input, init)
+      expect(upstream.headers.get('authorization')).toBe('Bearer rpc-token')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
+
+  test('does not send RPC auth to a public Zone URL', async () => {
+    const fetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json({ id: 1, jsonrpc: '2.0', result: '0x1079' }))
+    try {
+      const client = Viem.getClient({
+        chainId: zone.id,
+        rpc: {
+          auth: 'rpc:secret',
+          publicZoneUrl: 'https://public.zone.rpc.test',
+          url: 'https://internal.rpc.test',
+        },
+        zone,
+        zoneToken: 'zone-token',
+      })
+      await client.getChainId()
+
+      const [input, init] = fetch.mock.calls[0]!
+      const upstream = new Request(input, init)
+      expect(upstream.url).toBe('https://public.zone.rpc.test/')
+      expect(upstream.headers.get('authorization')).toBeNull()
+      expect(upstream.headers.get(ZoneRpcAuthentication.headerName)).toBe('zone-token')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
+
+  test('sends Zone headers to both internal and public Zone URLs', async () => {
+    const fetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json({ id: 1, jsonrpc: '2.0', result: '0x1079' }))
+    try {
+      const client = Viem.getClient({
+        chainId: zone.id,
+        rpc: {
+          publicZoneUrl: 'https://public.zone.rpc.test',
+          zoneHeaders: {
+            'CF-Access-Client-Id': 'client-id',
+            'CF-Access-Client-Secret': 'client-secret',
+          },
+        },
+        zone,
+        zoneToken: 'zone-token',
+      })
+      await client.getChainId()
+
+      const [input, init] = fetch.mock.calls[0]!
+      const upstream = new Request(input, init)
+      expect(upstream.headers.get('CF-Access-Client-Id')).toBe('client-id')
+      expect(upstream.headers.get('CF-Access-Client-Secret')).toBe('client-secret')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
 })
 
 describe('createGetClient', () => {
@@ -120,7 +301,7 @@ describe('createGetClient', () => {
       rpc: ({ principal }) =>
         principal?.type === 'public'
           ? { url: 'https://rpc.tempo.xyz' }
-          : { basicAuth: 'user:pass', url: 'https://internal.rpc' },
+          : { auth: 'user:pass', url: 'https://internal.rpc' },
     })
 
     expect(getClient(4217, apiKeyPrincipal)).toBe(getClient(4217, apiKeyPrincipal))