tapimo 0.11.0 → 0.13.0

package/src/apps/Zones.test.ts

@@ -5,11 +5,11 @@ describe('chains', () => {
     expect(Zones.chains).toMatchObject([
       {
         contracts: {
-          messenger: { address: '0x2fB7Aba18510622cd88F5f45B3AC0E7Dd70606a5' },
-          portal: { address: '0x5765e8B9003054e479df44D12D3dEeaADEfa8b7c' },
-          verifier: { address: '0xfa16b9C6A356a096F0e7ceF0135C393A81d4a355' },
+          messenger: { address: '0x5A4d000000000000000000000000000000000000' },
+          portal: { address: '0x5Ad0000000000000000000000000000000000003' },
+          verifier: { address: '0x5a56000000000000000000000000000000000000' },
         },
-        id: 1_424_310_001,
+        id: 1_424_310_003,
         name: 'zone-moderato-internal',
         rpcUrls: {
           default: { http: ['https://zone-internal-rpc.testnet.tempo.xyz'] },

package/src/apps/Zones.ts

@@ -6,11 +6,11 @@ export const zoneModeratoInternal = defineChain({
   ...tempoTestnet,
   contracts: {
     ...tempoTestnet.contracts,
-    messenger: { address: '0x2fB7Aba18510622cd88F5f45B3AC0E7Dd70606a5' },
-    portal: { address: '0x5765e8B9003054e479df44D12D3dEeaADEfa8b7c' },
-    verifier: { address: '0xfa16b9C6A356a096F0e7ceF0135C393A81d4a355' },
+    messenger: { address: '0x5A4d000000000000000000000000000000000000' },
+    portal: { address: '0x5Ad0000000000000000000000000000000000003' },
+    verifier: { address: '0x5a56000000000000000000000000000000000000' },
   },
-  id: 1_424_310_001,
+  id: 1_424_310_003,
   name: 'zone-moderato-internal',
   rpcUrls: {
     default: { http: ['https://zone-internal-rpc.testnet.tempo.xyz'] },

package/src/apps/composition.test.ts

@@ -197,7 +197,7 @@ describe('data()', () => {
           42431,
           421700001,
           421700006,
-          1424310001,
+          1424310003,
         ],
       }
     `)

package/src/apps/data/App.test.ts

@@ -149,14 +149,54 @@ describe('MPP session management', () => {
       PaymentRequest.serialize({ _mppx_scope: 'GET /v1/scopes' }),
     )
   })
+
+  test('applies POST auth overrides to QUERY aliases', async () => {
+    const app = TestApp.create({
+      auth: {
+        overrides: {
+          'POST /v1/exchange/quotes': { mpp: false, public: false },
+        },
+      },
+    })
+
+    const post = await app.request('/v1/exchange/quotes', { method: 'POST' })
+    const query = await app.request('/v1/exchange/quotes', { method: 'QUERY' })
+
+    expect([post.status, query.status]).toEqual([401, 401])
+  })
+
+  test('prefers an explicit QUERY auth override', async () => {
+    const app = TestApp.create({
+      auth: {
+        overrides: {
+          'POST /v1/exchange/quotes': { mpp: false, public: false },
+          'QUERY /v1/exchange/quotes': false,
+        },
+      },
+    })
+
+    const post = await app.request('/v1/exchange/quotes', { method: 'POST' })
+    const query = await app.request('/v1/exchange/quotes', { method: 'QUERY' })
+
+    expect([post.status, query.status]).toEqual([401, 400])
+  })
 })
 
 describe('zone chain gate', () => {
+  const legacyModerato = 1_424_310_001
+  const moderato = 1_424_310_003
   /** A consumer-supplied zone chain id (the API never derives these). */
   const zone = 421_700_001
   /** A second zone, isolating per-zone grants. */
   const zoneB = 4_217_000_002
 
+  const legacyModeratoReader = {
+    id: 'key_legacy_moderato',
+    orgId: 'org_test',
+    scopes: ['data:read', 'indexer:query', `zone:${legacyModerato}:read`],
+    token: 'secret_legacy_moderato',
+  } satisfies TestApp.kvStore.Key
+
   function zoneOptions(chainId: number) {
     return TestApp.zone({
       chainId,
@@ -261,6 +301,38 @@ describe('zone chain gate', () => {
     expect(response.status).toBe(200)
   })
 
+  test('the legacy Moderato id and read scope route to current upstreams', async () => {
+    const fetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValueOnce(Response.json({ id: 1, jsonrpc: '2.0', result: '0x54e89ac3' }))
+      .mockResolvedValueOnce(Response.json({ columns: [], ok: true, row_count: 0, rows: [] }))
+    try {
+      const app = TestApp.create({
+        auth: { keys: [legacyModeratoReader] },
+        rpc: { url: (chainId) => `https://${chainId}.rpc.test` },
+        tidx: { baseUrl: (chainId) => `https://${chainId}.tidx.test` },
+        zones: true,
+      })
+      const rpc = await app.request(`/rpc/${legacyModerato}`, {
+        body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+        headers: as(legacyModeratoReader).headers,
+        method: 'POST',
+      })
+      const tidx = await app.request(
+        `/v1/indexer/query?chainId=${legacyModerato}&sql=select%201`,
+        as(legacyModeratoReader),
+      )
+      const tidxUpstream = new URL((fetch.mock.calls[1]![0] as Request).url)
+
+      expect([rpc.status, tidx.status]).toEqual([200, 200])
+      expect((fetch.mock.calls[0]![0] as Request).url).toBe(`https://${moderato}.rpc.test/`)
+      expect(tidxUpstream.origin).toBe(`https://${moderato}.tidx.test`)
+      expect(tidxUpstream.searchParams.get('chainId')).toBe(String(moderato))
+    } finally {
+      fetch.mockRestore()
+    }
+  })
+
   test('a Zone write scope reads Zone data', async () => {
     const response = await zoneApp().request(`/v1/tokenlist?chainId=${zone}`, as(zoneWriter))
     expect(response.status).toBe(200)

package/src/apps/data/App.ts

@@ -3,7 +3,7 @@ import { matchedRoutes } from 'hono/route'
 import { ZoneRpcAuthentication } from 'ox/tempo'
 import * as z from 'zod/mini'
 
-import type * as Assets from '../../Assets.js'
+import * as Assets from '../../Assets.js'
 import type * as App from '../../App.js'
 import * as Auth from '../../internal/Auth.js'
 import * as EdgeCache from '../../internal/EdgeCache.js'
@@ -17,6 +17,7 @@ import * as Scope from '../../Scope.js'
 import * as Metadata from '../metadata.js'
 
 import type * as FxOracle from './FxOracle.js'
+import * as ZoneSelection from './ZoneSelection.js'
 
 import { transactions as transactionActivities } from './routes/activities.js'
 import { addresses } from './routes/addresses.js'
@@ -58,9 +59,17 @@ export function data(options: data.Options = {}) {
   const dataRouteHandlers = new Set<unknown>()
 
   const getTidx = Tidx.createGetClient({ tidx })
+  const addresses_routes = addresses({ fx: options.fx })
   const earn_routes = earn({ fx: options.fx })
   const indexer_routes = indexer()
+  const transactionActivities_routes = transactionActivities({ fx: options.fx })
   const indexerRouteHandlers = new Set(indexer_routes.routes.map((route) => route.handler))
+  const inferredZoneRouteHandlers = new Set([
+    ...addresses_routes.routes
+      .filter((route) => route.path === '/v1/addresses/:address/activities')
+      .map((route) => route.handler),
+    ...transactionActivities_routes.routes.map((route) => route.handler),
+  ])
   const rpcOnlyRouteHandlers = new Set(
     earn_routes.routes
       .filter((route) => route.path === '/v1/earn/vaults/:vaultId/positions/:address')
@@ -106,6 +115,7 @@ export function data(options: data.Options = {}) {
         c,
         defaultChainId,
         handlers: dataRouteHandlers,
+        inferredZoneHandlers: inferredZoneRouteHandlers,
         indexerHandlers: indexerRouteHandlers,
         rpcOnlyHandlers: rpcOnlyRouteHandlers,
       })
@@ -135,6 +145,30 @@ export function data(options: data.Options = {}) {
       c.set('supportedChainIds', narrowedChainIds)
       if (!narrowedChainIds.has(selection.chainId))
         return Response.unsupportedChainId(c, selection.chainId, narrowedChainIds)
+      if (selection.inferredZones) {
+        if (principal?.type !== 'api_key')
+          return Response.error(c, {
+            code: 'api_key_forbidden',
+            message: '`include=zones` requires an API key with readable Zone scopes.',
+            status: 403,
+          })
+        const zoneChainIds = ZoneSelection.readableChainIds({
+          parentChainId: selection.chainId,
+          principal,
+          rpc: rpc_config,
+          tidx: tidx_config,
+          zones,
+        })
+        if (zoneChainIds.length === 0)
+          return Response.error(c, {
+            code: 'api_key_forbidden',
+            message: 'The API key has no readable configured Zones.',
+            status: 403,
+          })
+        c.set('supportedChainIds', new Set([selection.chainId, ...zoneChainIds]))
+        c.set('zoneChainIds', zoneChainIds)
+        return next()
+      }
       c.set('chainId', selection.chainId)
       return next()
     })
@@ -147,10 +181,12 @@ export function data(options: data.Options = {}) {
         c,
         defaultChainId: c.get('chainId'),
         handlers: dataRouteHandlers,
+        inferredZoneHandlers: inferredZoneRouteHandlers,
         indexerHandlers: indexerRouteHandlers,
         rpcOnlyHandlers: rpcOnlyRouteHandlers,
       })
       if (!selection.matched) return next()
+      if (selection.inferredZones) return next()
       const chainId = c.get('chainId')
       if (!zones.has(chainId)) return next()
 
@@ -165,8 +201,8 @@ export function data(options: data.Options = {}) {
         return Response.error(c, {
           code: 'api_key_forbidden',
           message: selection.rpc
-            ? `Chain id ${chainId} is a zone. Use an API key granting \`zone:${chainId}:read\` or \`zone:${chainId}:write\`, or pass a Zone token via \`X-Authorization-Token\`.`
-            : `Chain id ${chainId} is a zone. Use an API key granting \`zone:${chainId}:read\` or \`zone:${chainId}:write\`.`,
+            ? `Chain ID ${chainId} is a Zone. Use an API key granting \`zone:${chainId}:read\` or \`zone:${chainId}:write\`, or pass a Zone token via \`X-Authorization-Token\`.`
+            : `Chain ID ${chainId} is a Zone. Use an API key granting \`zone:${chainId}:read\` or \`zone:${chainId}:write\`.`,
           status: 403,
         })
 
@@ -187,10 +223,12 @@ export function data(options: data.Options = {}) {
         c,
         defaultChainId: c.get('chainId'),
         handlers: dataRouteHandlers,
+        inferredZoneHandlers: inferredZoneRouteHandlers,
         indexerHandlers: indexerRouteHandlers,
         rpcOnlyHandlers: rpcOnlyRouteHandlers,
       })
-      if (!selection.matched || !Viem.isMainnet(c.get('chainId'))) return next()
+      if (!selection.matched || selection.inferredZones || !Viem.isMainnet(c.get('chainId')))
+        return next()
 
       return Response.error(c, {
         code: 'api_key_forbidden',
@@ -211,7 +249,7 @@ export function data(options: data.Options = {}) {
         'Content-Type': asset.contentType,
       })
     })
-    .route('/', addresses({ fx: options.fx }))
+    .route('/', addresses_routes)
     .route('/', blocks())
     .route('/', earn_routes)
     .route('/', exchanges({ fx: options.fx }))
@@ -221,7 +259,7 @@ export function data(options: data.Options = {}) {
     .route('/', tokenlist())
     .route('/', tokens())
     .route('/', transactions())
-    .route('/', transactionActivities({ fx: options.fx }))
+    .route('/', transactionActivities_routes)
     .route('/', transfers({ fx: options.fx }))
     .route('/', verifiedTokens())
     .route(
@@ -240,14 +278,16 @@ export function data(options: data.Options = {}) {
       c,
       defaultChainId: c.get('chainId'),
       handlers: dataRouteHandlers,
+      inferredZoneHandlers: inferredZoneRouteHandlers,
       indexerHandlers: indexerRouteHandlers,
       rpcOnlyHandlers: rpcOnlyRouteHandlers,
     })
-    if (selection.matched && !selection.conflict && !selection.invalid)
+    if (selection.matched && !selection.conflict && !selection.inferredZones && !selection.invalid)
       c.set('chainId', selection.chainId)
     return (
       selection.matched &&
       !selection.conflict &&
+      !selection.inferredZones &&
       !selection.invalid &&
       !c.get('zones').has(selection.chainId)
     )
@@ -302,6 +342,7 @@ function resolveChainSelector(options: {
   c: Context<App.Environment>
   defaultChainId: Viem.ChainId
   handlers: ReadonlySet<unknown>
+  inferredZoneHandlers: ReadonlySet<unknown>
   indexerHandlers: ReadonlySet<unknown>
   rpcOnlyHandlers: ReadonlySet<unknown>
 }) {
@@ -310,9 +351,11 @@ function resolveChainSelector(options: {
   let rpc = false
   let rpcOnly = false
   let indexer = false
+  let inferredZonesAllowed = false
   for (const route of matchedRoutes(options.c)) {
     if (!options.handlers.has(route.handler)) continue
     matched = true
+    if (options.inferredZoneHandlers.has(route.handler)) inferredZonesAllowed = true
     if (options.indexerHandlers.has(route.handler)) indexer = true
     if (options.rpcOnlyHandlers.has(route.handler)) rpcOnly = true
     const selector = pathChainSelector(route.path, options.c.req.path)
@@ -326,6 +369,7 @@ function resolveChainSelector(options: {
     return {
       chainId: options.defaultChainId,
       conflict: false,
+      inferredZones: false,
       indexer: false,
       invalid: false,
       matched: false,
@@ -334,6 +378,10 @@ function resolveChainSelector(options: {
     }
 
   const search = new URL(options.c.req.url).searchParams
+  const include = inferredZonesAllowed
+    ? search.getAll('include').flatMap((value) => value.split(',').map((part) => part.trim()))
+    : []
+  const inferredZones = include.includes('zones')
   const raw = [
     ...(path === undefined ? [] : [path]),
     ...(rpc ? [] : search.getAll('chainId')),
@@ -344,6 +392,7 @@ function resolveChainSelector(options: {
   return {
     chainId: chainIds[0] ?? options.defaultChainId,
     conflict: chainIds.length > 1,
+    inferredZones,
     indexer,
     invalid: parsed.some((result) => !result.success),
     matched: true,
@@ -473,7 +522,6 @@ function createGetAsset(options: createGetAsset.Options): App.GetAsset {
   const { assets, basePath, origin } = options
   if (!assets) return () => undefined
   const getAsset: App.GetAsset = async (chainId, path) => {
-    const pathname = Path.join(basePath, 'assets', String(chainId), path)
     // `path` may be absolute (`Path.join` returns a leading slash); strip it so
     // the key is `:chainId/:path`, not `:chainId//:path`.
     const key = `${chainId}/${path.replace(/^\/+/, '')}`
@@ -483,7 +531,7 @@ function createGetAsset(options: createGetAsset.Options): App.GetAsset {
       response: new globalThis.Response(asset.body, {
         headers: { 'Content-Type': asset.contentType },
       }),
-      uri: new URL(pathname, origin).toString(),
+      uri: Assets.url({ basePath, chainId, origin, path }),
     }
   }
   const list = assets.list
@@ -492,7 +540,7 @@ function createGetAsset(options: createGetAsset.Options): App.GetAsset {
       const prefix = `${chainId}/${path.replace(/^\/+/, '')}`
       return (await list(prefix)).map((key) => ({
         key,
-        uri: new URL(Path.join(basePath, 'assets', key), origin).toString(),
+        uri: Assets.url({ basePath, chainId, origin, path: key.slice(String(chainId).length + 1) }),
       }))
     }
   return getAsset

package/src/apps/data/ZoneSelection.test.ts

@@ -0,0 +1,196 @@
+import * as ApiKey from '../../ApiKey.js'
+import * as App from '../../App.js'
+import * as Db from '../../db/Db.js'
+import type * as Auth from '../../internal/Auth.js'
+import * as Viem from '../../internal/Viem.js'
+import * as Zones from '../Zones.js'
+
+import * as Data from './App.js'
+import * as ZoneSelection from './ZoneSelection.js'
+import * as Activities from './routes/activities.js'
+
+describe('transaction activity Zone query', () => {
+  test('accepts the Zones include with an optional parent chain', () => {
+    expect(
+      Activities.schema.getTransactionActivities.Query.parse({ include: 'zones' }).include,
+    ).toStrictEqual(['zones'])
+    expect(
+      Activities.schema.getTransactionActivities.Query.parse({
+        chainId: '4217',
+        include: 'zones',
+      }),
+    ).toMatchObject({ chainId: 4217, include: ['zones'] })
+    expect(
+      Activities.schema.getTransactionActivities.Query.safeParse({ includeZones: 'true' }).success,
+    ).toBe(false)
+  })
+
+  test('opts in only activity routes and accepts a parent chain', async () => {
+    const app = App.create({
+      auth: false,
+      db: Db.postgres({ connectionString: 'postgresql://unused@127.0.0.1:1/unused' }),
+      zones: [Zones.zoneModeratoInternal],
+    }).route('/', Data.data({ webhook: false }))
+    const address = '0x0000000000000000000000000000000000000001'
+    const hash = `0x${'00'.repeat(32)}`
+    const addressScoped = await app.request(
+      `/v1/addresses/${address}/activities?include=zones&chainId=${Viem.chainId.testnet}`,
+    )
+    const forbidden = await app.request(`/v1/transactions/${hash}/activities?include=zones`)
+    const scoped = await app.request(
+      `/v1/transactions/${hash}/activities?include=zones&chainId=${Viem.chainId.testnet}`,
+    )
+    const unsupported = await app.request('/v1/tokenlist?include=zones')
+
+    expect(forbidden.status).toBe(403)
+    expect(forbidden.headers.get('cache-control')).toBe('no-store')
+    expect(await addressScoped.json()).toMatchObject({ error: { code: 'api_key_forbidden' } })
+    expect(await scoped.json()).toMatchObject({ error: { code: 'api_key_forbidden' } })
+    expect(await unsupported.json()).toMatchObject({ error: { code: 'query_invalid' } })
+  })
+})
+
+describe('readableChainIds', () => {
+  test('intersects the parent chain, scopes, and configured routable Zones', () => {
+    const principal = apiKeyPrincipal({
+      scopes: [
+        'data:read',
+        `zone:${Zones.zoneMainnetInternal.id}:read`,
+        `zone:${Zones.zoneModeratoInternal.id}:write`,
+      ],
+    })
+
+    expect(
+      ZoneSelection.readableChainIds({
+        parentChainId: Viem.chainId.testnet,
+        principal,
+        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
+      }),
+    ).toStrictEqual([Zones.zoneModeratoInternal.id])
+    expect(
+      ZoneSelection.readableChainIds({
+        parentChainId: Viem.chainId.mainnet,
+        principal,
+        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
+      }),
+    ).toStrictEqual([Zones.zoneMainnetInternal.id])
+  })
+
+  test('lets wildcard keys read every configured routable Zone of the parent chain', () => {
+    expect(
+      ZoneSelection.readableChainIds({
+        parentChainId: Viem.chainId.testnet,
+        principal: apiKeyPrincipal({ scopes: ['*'] }),
+        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
+      }),
+    ).toStrictEqual([Zones.zoneModeratoInternal.id])
+  })
+
+  test('filters sandbox keys by each Zone parent chain', () => {
+    const principal = apiKeyPrincipal({
+      environment: 'sandbox',
+      scopes: [
+        'data:read',
+        `zone:${Zones.zoneMainnetInternal.id}:read`,
+        `zone:${Zones.zoneModeratoInternal.id}:read`,
+      ],
+    })
+
+    expect(
+      ZoneSelection.readableChainIds({
+        parentChainId: Viem.chainId.testnet,
+        principal,
+        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
+      }),
+    ).toStrictEqual([Zones.zoneModeratoInternal.id])
+    expect(
+      ZoneSelection.readableChainIds({
+        parentChainId: Viem.chainId.mainnet,
+        principal,
+        zones: new Map(Zones.chains.map((zone) => [zone.id, zone])),
+      }),
+    ).toStrictEqual([])
+  })
+
+  test('requires data read access and both upstreams', () => {
+    const zone = {
+      ...Zones.zoneModeratoInternal,
+      id: 1_424_310_099,
+      rpcUrls: { default: { http: ['https://zone.rpc.test'] } },
+    }
+    const zones = new Map([[zone.id, zone]])
+
+    expect(
+      ZoneSelection.readableChainIds({
+        parentChainId: zone.sourceId,
+        principal: apiKeyPrincipal({ scopes: [`zone:${zone.id}:read`] }),
+        zones,
+      }),
+    ).toStrictEqual([])
+    expect(
+      ZoneSelection.readableChainIds({
+        parentChainId: zone.sourceId,
+        principal: apiKeyPrincipal({ scopes: ['data:read', `zone:${zone.id}:read`] }),
+        zones,
+      }),
+    ).toStrictEqual([])
+  })
+})
+
+describe('uniqueMatch', () => {
+  test('selects one match after every chain completes', () => {
+    expect(
+      ZoneSelection.uniqueMatch([
+        { chainId: 1, value: null },
+        { chainId: 2, value: 'receipt' },
+      ]),
+    ).toStrictEqual({ chainId: 2, kind: 'selected', value: 'receipt' })
+  })
+
+  test('distinguishes no match from ambiguous matches', () => {
+    expect(ZoneSelection.uniqueMatch([{ chainId: 1, value: null }])).toStrictEqual({
+      kind: 'not_found',
+    })
+    expect(
+      ZoneSelection.uniqueMatch([
+        { chainId: 1, value: 'first' },
+        { chainId: 2, value: 'second' },
+      ]),
+    ).toStrictEqual({ kind: 'ambiguous' })
+  })
+
+  test('fails the selection when any chain lookup fails', () => {
+    const cause = new Error('unavailable')
+    expect(
+      ZoneSelection.uniqueMatch([
+        { chainId: 1, value: 'receipt' },
+        { cause, chainId: 2 },
+      ]),
+    ).toStrictEqual({ failures: [{ cause, chainId: 2 }], kind: 'failed' })
+  })
+})
+
+function apiKeyPrincipal(
+  options: apiKeyPrincipal.Options,
+): Extract<Auth.Principal, { type: 'api_key' }> {
+  const apiKey = ApiKey.schema.ApiKey.parse({
+    environment: options.environment,
+    id: 'key_test',
+    orgId: 'org_test',
+    scopes: options.scopes,
+  })
+  return {
+    apiKey,
+    environment: apiKey.environment,
+    id: apiKey.id,
+    orgId: apiKey.orgId,
+    type: 'api_key',
+  }
+}
+
+declare namespace apiKeyPrincipal {
+  type Options = {
+    environment?: 'production' | 'sandbox' | undefined
+    scopes: readonly string[]
+  }
+}

package/src/apps/data/ZoneSelection.ts

@@ -0,0 +1,108 @@
+import type { Chain } from 'viem'
+
+import type * as Auth from '../../internal/Auth.js'
+import * as Tidx from '../../internal/Tidx.js'
+import * as Viem from '../../internal/Viem.js'
+import * as Scope from '../../Scope.js'
+
+/** Returns configured and routable Zones that an API key may read. */
+export function readableChainIds(options: readableChainIds.Options): readonly number[] {
+  const { parentChainId, principal, zones } = options
+  const scopes = principal.apiKey.scopes
+  if (!scopes.includes(Scope.wildcard) && !scopes.includes('data:read')) return []
+
+  const chainIds = [...zones.values()].flatMap((zone) => {
+    if (zone.sourceId !== parentChainId) return []
+    const allowed =
+      scopes.includes(Scope.wildcard) ||
+      scopes.includes(`zone:${zone.id}:read`) ||
+      scopes.includes(`zone:${zone.id}:write`)
+    if (!allowed) return []
+    if (
+      principal.environment === 'sandbox' &&
+      (zone.sourceId === undefined || Viem.isMainnet(zone.sourceId))
+    )
+      return []
+
+    const context = { chainId: zone.id, principal, zone }
+    if (Viem.resolveRpc(options.rpc, context).url === undefined) return []
+    if (Tidx.resolve(options.tidx, context).baseUrl === undefined) return []
+    return [zone.id]
+  })
+  return chainIds.sort((a, b) => a - b)
+}
+
+export declare namespace readableChainIds {
+  /** Inputs for resolving the readable inferred-Zone set. */
+  type Options = {
+    /** Parent Tempo chain whose Zones may be selected. */
+    parentChainId: Viem.ChainId
+    /** Authenticated API-key principal selecting Zones. */
+    principal: Extract<Auth.Principal, { type: 'api_key' }>
+    /** RPC configuration used to exclude unroutable Zones. */
+    rpc?: Viem.getClient.Rpc | undefined
+    /** TIDX configuration used to exclude unroutable Zones. */
+    tidx?: Tidx.getClient.Tidx | undefined
+    /** Hosted Zone metadata keyed by chain id. */
+    zones: ReadonlyMap<number, Chain>
+  }
+}
+
+/** Resolves chain receipt probes without treating partial upstream results as complete. */
+export function uniqueMatch<const value>(
+  probes: readonly uniqueMatch.Probe<value>[],
+): uniqueMatch.Result<value> {
+  const failures = probes.flatMap((probe) => ('cause' in probe ? [probe] : []))
+  if (failures.length > 0) return { failures, kind: 'failed' }
+
+  const matches = probes.flatMap((probe) =>
+    'value' in probe && probe.value !== null
+      ? [{ chainId: probe.chainId, value: probe.value }]
+      : [],
+  )
+  if (matches.length === 0) return { kind: 'not_found' }
+  if (matches.length > 1) return { kind: 'ambiguous' }
+  return { ...matches[0]!, kind: 'selected' }
+}
+
+export declare namespace uniqueMatch {
+  /** One completed chain lookup. */
+  type Probe<value> =
+    | {
+        /** Chain that completed the lookup. */
+        chainId: number
+        /** Matching value, or null when the chain did not contain the resource. */
+        value: value | null
+      }
+    | {
+        /** Upstream failure from this chain. */
+        cause: unknown
+        /** Chain that failed the lookup. */
+        chainId: number
+      }
+
+  /** Unique-match decision across every requested chain. */
+  type Result<value> =
+    | {
+        /** Chain containing the unique match. */
+        chainId: number
+        /** Unique match result. */
+        kind: 'selected'
+        /** Value found in the selected Zone. */
+        value: value
+      }
+    | {
+        /** Every failed Zone lookup. */
+        failures: readonly Extract<Probe<value>, { cause: unknown }>[]
+        /** Partial failure result. */
+        kind: 'failed'
+      }
+    | {
+        /** Ambiguous match result. */
+        kind: 'ambiguous'
+      }
+    | {
+        /** No-match result. */
+        kind: 'not_found'
+      }
+}