tapimo 0.5.0 → 0.5.1

package/src/internal/FundingQuotes.test.ts

@@ -83,9 +83,11 @@ describe('listQuotes', () => {
       },
     })
 
-    await expect(quotes).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[FundingQuotes.ProviderQuoteError]`,
-    )
+    const cause = await quotes.catch((error: unknown) => error)
+    expect(cause).toMatchObject({
+      failures: [{ cause: expect.any(Error), provider: 'relay' }],
+      name: 'FundingQuotes.ProviderQuoteError',
+    })
   })
 
   test('rejects successful provider responses without output amounts', async () => {
@@ -145,6 +147,32 @@ describe('listQuotes', () => {
 
     expect(seen?.cache.bypass).toBe(true)
   })
+
+  test('returns successful quotes when another provider fails', async () => {
+    const quotes = await FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapters: {
+        across: {
+          async probeQuote() {
+            throw new Error('upstream unavailable')
+          },
+        },
+        relay: {
+          async probeQuote() {
+            return {
+              outputAmount: '990000',
+              sampledAt: '2026-01-01T00:00:00Z',
+              status: 'available',
+            }
+          },
+        },
+      },
+      provider: undefined,
+    })
+
+    expect(quotes).toHaveLength(1)
+    expect(quotes[0]?.provider.id).toBe('relay')
+  })
 })
 
 describe('listChains', () => {
@@ -153,14 +181,73 @@ describe('listChains', () => {
       'eip155:1',
       'eip155:8453',
       'eip155:56',
+      'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      'tron:0x2b6653dc',
     ])
   })
+
+  test('uses chain-specific token keys for non-EVM inventory', () => {
+    const chains = FundingQuotes.listChains()
+    expect(chains.find((chain) => chain.kind === 'solana')?.tokens[0]?.tokenKey).toBe(
+      'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    )
+    expect(chains.find((chain) => chain.kind === 'tron')?.tokens[0]?.tokenKey).toBe(
+      'tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+    )
+  })
+})
+
+describe('listQuoteCandidates', () => {
+  test('round-trips the advertised Solana chain and token ids', () => {
+    const [candidate] = FundingQuotes.listQuoteCandidates({
+      provider: 'rhino',
+      sourceAmount: '1000000',
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      sourceToken:
+        'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    })
+
+    expect(candidate?.id).toBe('solana-usdc-tempo-usdce-rhino')
+  })
+
+  test('keeps non-EVM token identifiers case-sensitive', () => {
+    expect(
+      FundingQuotes.listQuoteCandidates({
+        provider: 'rhino',
+        sourceAmount: '1000000',
+        sourceAmountUnits: 'baseUnits',
+        sourceChain: 'solana',
+        sourceToken: 'epjfwdd5aufqssqem2qn1xzybapc8g4wegkzwytdt1v',
+      }),
+    ).toEqual([])
+  })
+
+  test('resolves the complete Tron token key', () => {
+    const [candidate] = FundingQuotes.listQuoteCandidates({
+      destinationToken: 'USDT0',
+      provider: 'rhino',
+      sourceAmount: '1000000',
+      sourceAmountUnits: 'baseUnits',
+      sourceChain: 'tron:0x2b6653dc',
+      sourceToken: 'tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+    })
+
+    expect(candidate?.id).toBe('tron-usdt-tempo-usdt0-rhino')
+  })
 })
 
 describe('listProviders', () => {
   test('reports deployment configuration', () => {
     expect(FundingQuotes.listProviders()).toMatchInlineSnapshot(`
       [
+        {
+          "id": "across",
+          "kind": "intentBridge",
+          "name": "Across",
+          "requiresApiKey": true,
+          "status": "unconfigured",
+        },
         {
           "id": "relay",
           "kind": "solverNetwork",
@@ -168,6 +255,13 @@ describe('listProviders', () => {
           "requiresApiKey": false,
           "status": "unconfigured",
         },
+        {
+          "id": "rhino",
+          "kind": "bridge",
+          "name": "Rhino",
+          "requiresApiKey": false,
+          "status": "unconfigured",
+        },
       ]
     `)
   })

package/src/internal/FundingQuotes.ts

@@ -18,6 +18,7 @@ const sourceChains = [
     kind: 'evm',
     name: 'Ethereum',
     providerIds: {
+      across: '1',
       relay: '1',
     },
     slug: 'ethereum',
@@ -71,7 +72,9 @@ const sourceChains = [
     kind: 'evm',
     name: 'Base',
     providerIds: {
+      across: '8453',
       relay: '8453',
+      rhino: 'BASE',
     },
     slug: 'base',
     tokens: [
@@ -108,6 +111,7 @@ const sourceChains = [
     kind: 'evm',
     name: 'BNB Smart Chain',
     providerIds: {
+      across: '56',
       relay: '56',
     },
     slug: 'bnb',
@@ -130,6 +134,48 @@ const sourceChains = [
       },
     ],
   },
+  {
+    addressFormat: 'base58',
+    aliases: ['solana', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'],
+    id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+    kind: 'solana',
+    name: 'Solana',
+    providerIds: {
+      rhino: 'SOLANA',
+    },
+    slug: 'solana',
+    tokens: [
+      {
+        address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        coingeckoId: 'usd-coin',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'SPL',
+        symbol: 'USDC',
+      },
+    ],
+  },
+  {
+    addressFormat: 'base58check',
+    aliases: ['tron', 'tron:0x2b6653dc'],
+    id: 'tron:0x2b6653dc',
+    kind: 'tron',
+    name: 'Tron',
+    providerIds: {
+      rhino: 'TRON',
+    },
+    slug: 'tron',
+    tokens: [
+      {
+        address: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+        coingeckoId: 'tether',
+        decimals: 6,
+        name: 'Tether USD',
+        standard: 'TRC-20',
+        symbol: 'USDT',
+      },
+    ],
+  },
 ] as const
 
 /** Tempo destination tokens supported by funding quote providers. */
@@ -178,6 +224,13 @@ const destinationTokens = [
 
 /** Providers supported by live funding quotes. */
 const providers = [
+  {
+    id: 'across',
+    kind: 'intentBridge',
+    name: 'Across',
+    requiresApiKey: true,
+    status: 'unconfigured',
+  },
   {
     id: 'relay',
     kind: 'solverNetwork',
@@ -185,6 +238,13 @@ const providers = [
     requiresApiKey: false,
     status: 'unconfigured',
   },
+  {
+    id: 'rhino',
+    kind: 'bridge',
+    name: 'Rhino',
+    requiresApiKey: false,
+    status: 'unconfigured',
+  },
 ] as const
 
 type TokenInput = (typeof sourceChains)[number]['tokens'][number]
@@ -262,6 +322,8 @@ export type QuoteProbeInput = {
 
 /** Quote probe data returned by a provider adapter. */
 export type QuoteProbeResult = {
+  /** Timestamp after which the provider quote is no longer valid. */
+  expiresAt?: string | undefined
   /** Slippage-adjusted minimum destination amount in base units. */
   minimumOutputAmount?: string | undefined
   /** Expected destination amount in base units. */
@@ -294,9 +356,20 @@ export type ProviderAdapter = {
 /** Provider adapter registry, keyed by provider id. */
 export type ProviderAdapters = Partial<Record<ProviderId, ProviderAdapter>>
 
+/** A provider adapter failure retained for bounded request diagnostics. */
+export type ProviderFailure = {
+  /** Error thrown by the provider boundary. */
+  cause: unknown
+  /** Provider that failed. */
+  provider: ProviderId
+}
+
 /** Curated provider support rows used to select live quote probes. */
 const inventory: readonly InventoryEntry[] = [
+  { destinationToken: 'usdce', provider: 'across', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC'] }, // prettier-ignore
   { destinationToken: 'usdce', provider: 'relay', sourceChains: ['ethereum', 'base', 'bnb'], sourceTokens: ['USDC', 'USDT'] }, // prettier-ignore
+  { destinationToken: 'usdce', provider: 'rhino', sourceChains: ['base', 'solana'], sourceTokens: ['USDC'] }, // prettier-ignore
+  { destinationToken: 'usdt0', provider: 'rhino', sourceChains: ['tron'], sourceTokens: ['USDT'] }, // prettier-ignore
 ]
 
 type InventoryEntry = {
@@ -367,8 +440,12 @@ export async function listQuotes(options: listQuotes.Options) {
   const quotes = results.flatMap((result) =>
     result.status === 'fulfilled' && result.value ? [result.value] : [],
   )
-  if (quotes.length === 0 && results.some((result) => result.status === 'rejected'))
-    throw new ProviderQuoteError()
+  const failures = results.flatMap((result, index) =>
+    result.status === 'rejected'
+      ? [{ cause: result.reason, provider: candidates[index]!.provider.id }]
+      : [],
+  )
+  if (quotes.length === 0 && failures.length > 0) throw new ProviderQuoteError(failures)
   return quotes
 }
 
@@ -439,8 +516,13 @@ export declare namespace listQuotes {
 /** Source amount unit accepted by the funding quote request. */
 export type SourceAmountUnits = 'baseUnits' | 'decimal'
 
-function tokenKey(chain: { id: string }, token: TokenInput | DestinationTokenInput) {
-  return `${chain.id}/erc20:${token.address}`
+function tokenKey(chain: { id: string; kind: string }, token: TokenInput | DestinationTokenInput) {
+  const namespace = (() => {
+    if (chain.kind === 'solana') return 'token'
+    if (chain.kind === 'tron') return 'trc20'
+    return 'erc20'
+  })()
+  return `${chain.id}/${namespace}:${token.address}`
 }
 
 function decimalFromBaseUnits(baseUnits: string, decimals: number) {
@@ -485,7 +567,7 @@ async function quoteCandidate(
     quote.outputAmount === undefined ||
     quote.outputAmount === null
   )
-    throw new ProviderQuoteError()
+    throw new InvalidProviderQuoteError()
   return formatFundingQuote(candidate, {
     ...quote,
     outputAmount: quote.outputAmount,
@@ -595,6 +677,7 @@ function formatFundingQuote(candidate: QuoteCandidate, quote: SuccessfulQuotePro
       tier: quote.status === 'thin' ? ('thin' as const) : ('liquid' as const),
     },
     quote: {
+      ...(quote.expiresAt !== undefined ? { expiresAt: quote.expiresAt } : {}),
       inputAmount: candidate.sourceAmount.amount,
       ...(quote.minimumOutputAmount !== undefined
         ? { minimumOutputAmount: quote.minimumOutputAmount }
@@ -685,10 +768,13 @@ function matchesTokenIdentifier(
 }
 
 function resolveSourceChain(input: string) {
+  const trimmed = input.trim()
   const normalized = normalizeInput(input)
   const chain = sourceChains.find(
     (candidate) =>
-      candidate.id === normalized || (candidate.aliases as readonly string[]).includes(normalized),
+      candidate.id === trimmed ||
+      candidate.slug === normalized ||
+      (candidate.kind === 'evm' && (candidate.aliases as readonly string[]).includes(normalized)),
   )
   if (!chain) throw new UnsupportedSourceChainError()
   return chain
@@ -722,6 +808,14 @@ export class ProviderAdapterTimeoutError extends Error {
 /** Error thrown when every matching provider fails to produce a quote. */
 export class ProviderQuoteError extends Error {
   override name = 'FundingQuotes.ProviderQuoteError'
+
+  /** Provider failures that prevented a successful quote. */
+  failures: readonly ProviderFailure[]
+
+  constructor(failures: readonly ProviderFailure[]) {
+    super()
+    this.failures = failures
+  }
 }
 
 /** Error thrown when the caller filters to an unknown provider. */
@@ -733,3 +827,7 @@ export class UnsupportedProviderError extends Error {
 export class UnsupportedSourceChainError extends Error {
   override name = 'FundingQuotes.UnsupportedSourceChainError'
 }
+
+class InvalidProviderQuoteError extends Error {
+  override name = 'FundingQuotes.InvalidProviderQuoteError'
+}

package/src/internal/Log.ts

@@ -12,6 +12,8 @@ export type Variables = {
   errorCode?: string | undefined
   /** Redacted provider failure details recorded by an upstream adapter. */
   providerFailure?: Entry['provider'] | undefined
+  /** Redacted provider failures when multiple upstream adapters fail. */
+  providerFailures?: Entry['providerFailures'] | undefined
 }
 
 /** Hono environment shape used by the request logger. */
@@ -28,6 +30,20 @@ export type Environment = {
 /** Log level, derived from the response status. */
 export type Level = 'error' | 'info' | 'warn'
 
+/** Redacted upstream provider failure details. */
+export type ProviderFailure = {
+  /** Stable provider error code, when one is safe to retain. */
+  code?: string | undefined
+  /** Failure boundary that rejected the provider request. */
+  failure: 'http' | 'network' | 'payload' | 'timeout' | 'unknown'
+  /** Provider identifier. */
+  id: string
+  /** Provider operation identifier. */
+  operation: string
+  /** Upstream HTTP status, when a response was received. */
+  status?: number | undefined
+}
+
 /** One canonical request log entry. */
 export type Entry = {
   /** `'hit'` when the edge response cache served the request without reaching the origin handlers. */
@@ -64,20 +80,9 @@ export type Entry = {
       }
     | undefined
   /** Redacted upstream provider failure details, when an adapter request fails. */
-  provider?:
-    | {
-        /** Stable provider error code, when one is safe to retain. */
-        code?: string | undefined
-        /** Failure boundary that rejected the provider request. */
-        failure: 'http' | 'network' | 'payload' | 'unknown'
-        /** Provider identifier. */
-        id: string
-        /** Provider operation identifier. */
-        operation: string
-        /** Upstream HTTP status, when a response was received. */
-        status?: number | undefined
-      }
-    | undefined
+  provider?: ProviderFailure | undefined
+  /** Redacted failures for every provider when multiple adapters fail. */
+  providerFailures?: readonly ProviderFailure[] | undefined
   /** Raw query string (no leading `?`) with API-key tokens redacted, when present. */
   query?: string | undefined
   /** Rate limit state from the `RateLimit-*` response headers, when enforced. */
@@ -136,6 +141,7 @@ export function middleware<environment extends Environment = Environment>(
     const principal = c.get('principal' as never) as Auth.Principal | undefined
     const errorCode = c.get('errorCode' as never) as string | undefined
     const provider = c.get('providerFailure' as never) as Entry['provider']
+    const providerFailures = c.get('providerFailures' as never) as Entry['providerFailures']
 
     // The `request` total metric duplicates `duration` (measured here, one
     // layer further out), so only operation timings are kept.
@@ -186,6 +192,7 @@ export function middleware<environment extends Environment = Environment>(
             },
           }),
       ...(provider === undefined ? {} : { provider }),
+      ...(providerFailures === undefined ? {} : { providerFailures }),
       ...(query ? { query } : {}),
       ...(rateLimit === undefined ? {} : { rateLimit }),
       requestId: c.get('requestId' as never) as string,

package/src/internal/Tidx.test.ts

@@ -203,6 +203,21 @@ describe('resolve', () => {
     `)
   })
 
+  test('resolves Bearer auth', () => {
+    expect(
+      Tidx.resolve(
+        { baseUrl: 'https://internal.indexer', bearerAuth: 'zone-secret' },
+        { chainId: 4217, principal: apiKeyPrincipal },
+      ),
+    ).toMatchInlineSnapshot(`
+      {
+        "baseUrl": "https://internal.indexer",
+        "basicAuth": undefined,
+        "bearerAuth": "zone-secret",
+      }
+    `)
+  })
+
   test('the resolver form routes anonymous callers to a separate upstream', () => {
     const tidx = ({ principal }: Viem.resolve.Context) =>
       principal?.type === 'public'
@@ -243,6 +258,28 @@ describe('resolve', () => {
   })
 })
 
+describe('getClient', () => {
+  test('sends Bearer auth', async () => {
+    const fetch = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      new Response(JSON.stringify({ columns: [], ok: true, row_count: 0, rows: [] }), {
+        headers: { 'content-type': 'application/json' },
+      }),
+    )
+    try {
+      const client = Tidx.getClient({
+        chainId: 4217,
+        tidx: { baseUrl: 'https://internal.indexer', bearerAuth: 'zone-secret' },
+      })
+      await client.fetch({ query: 'select 1' })
+
+      const upstream = fetch.mock.calls[0]![0] as Request
+      expect(upstream.headers.get('authorization')).toBe('Bearer zone-secret')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
+})
+
 describe('createGetClient', () => {
   test('memoizes one client per resolved upstream', () => {
     const getTidx = Tidx.createGetClient({
@@ -267,6 +304,17 @@ describe('createGetClient', () => {
     expect(getTidx(4217, null)).toBe(getTidx(4217, publicPrincipal))
   })
 
+  test('does not share clients across Bearer credentials', () => {
+    const getTidx = Tidx.createGetClient({
+      tidx: ({ principal }) => ({
+        baseUrl: 'https://internal.indexer',
+        bearerAuth: principal?.type === 'public' ? 'public-secret' : 'private-secret',
+      }),
+    })
+
+    expect(getTidx(4217, publicPrincipal)).not.toBe(getTidx(4217, apiKeyPrincipal))
+  })
+
   test('consults the resolver on every call but builds one client per upstream', () => {
     const seen: (string | undefined)[] = []
     const getTidx = Tidx.createGetClient({

package/src/internal/Tidx.ts

@@ -29,8 +29,8 @@ export type UrlResolver = (chainId: Viem.ChainId) => string | undefined
  * receives a {@link Viem.resolve.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}); a
- * missing `basicAuth` means no Basic auth is sent.
+ * missing `baseUrl` falls back to the built-in public host map ({@link url});
+ * missing auth fields send no Authorization header.
  */
 export function resolve(
   tidx: getClient.Tidx | undefined,
@@ -42,6 +42,7 @@ export function resolve(
       (typeof config?.baseUrl === 'function' ? config.baseUrl(context.chainId) : config?.baseUrl) ??
       url[context.chainId],
     basicAuth: config?.basicAuth,
+    ...(config?.bearerAuth ? { bearerAuth: config.bearerAuth } : {}),
   }
 }
 
@@ -56,13 +57,22 @@ export declare namespace resolve {
     baseUrl: string | undefined
     /** Basic auth credentials, or undefined to send no Basic auth. */
     basicAuth?: string | undefined
+    /** Bearer auth credential, or undefined to send no Bearer auth. */
+    bearerAuth?: string | undefined
   }
 }
 
 export function getClient(options: getClient.Options): Client {
   const { chainId = Viem.defaultChainId, principal = null, tidx } = options
-  const { baseUrl, basicAuth } = resolve(tidx, { chainId, principal })
-  return withTransientRetry(Tidx.create({ baseUrl, basicAuth, chainId }))
+  const { baseUrl, basicAuth, bearerAuth } = resolve(tidx, { chainId, principal })
+  return withTransientRetry(
+    Tidx.create({
+      baseUrl,
+      basicAuth,
+      bearerAuth,
+      chainId,
+    }),
+  )
 }
 
 /**
@@ -72,7 +82,7 @@ export function getClient(options: getClient.Options): Client {
  * output (`baseUrl` + `basicAuth` + `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 `App.create` (per-request reads) and
+ * upstream share a client. Shared by `data()` (per-request reads) and
  * `Webhooks.createPoller` (the scheduled poller) so the resolver logic lives in
  * one place.
  */
@@ -83,8 +93,8 @@ export function createGetClient(options: createGetClient.Options = {}): GetClien
   return (chainId = defaultChainId, principal = null) => {
     // 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 } = resolve(tidx, { chainId, principal })
-    const cacheKey = `${baseUrl}|${basicAuth ?? ''}|${chainId}`
+    const { baseUrl, basicAuth, bearerAuth } = resolve(tidx, { chainId, principal })
+    const cacheKey = `${baseUrl}|${basicAuth ?? ''}|${bearerAuth ?? ''}|${chainId}`
     const existing = clients.get(cacheKey)
     if (existing) return existing
 
@@ -218,12 +228,16 @@ export declare namespace getClient {
         baseUrl?: UrlResolver | string | undefined
         /** Basic auth credentials for TIDX requests. */
         basicAuth?: string | undefined
+        /** Bearer auth credential for TIDX requests. */
+        bearerAuth?: string | undefined
       }
     | ((context: Viem.resolve.Context) => {
         /** 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/Viem.test.ts

@@ -113,3 +113,49 @@ describe('resolve', () => {
     `)
   })
 })
+
+describe('createGetClient', () => {
+  test('memoizes one client per resolved upstream', () => {
+    const getClient = Viem.createGetClient({
+      rpc: ({ principal }) =>
+        principal?.type === 'public'
+          ? { url: 'https://rpc.tempo.xyz' }
+          : { basicAuth: 'user:pass', url: 'https://internal.rpc' },
+    })
+
+    expect(getClient(4217, apiKeyPrincipal)).toBe(getClient(4217, apiKeyPrincipal))
+    expect(getClient(4217, publicPrincipal)).toBe(getClient(4217, publicPrincipal))
+    expect(getClient(4217, publicPrincipal)).not.toBe(getClient(4217, apiKeyPrincipal))
+    expect(getClient(4217, apiKeyPrincipal)).not.toBe(getClient(42431, apiKeyPrincipal))
+  })
+
+  test('shares a client across principals when they resolve identically', () => {
+    const getClient = Viem.createGetClient()
+
+    expect(getClient(4217, publicPrincipal)).toBe(getClient(4217, apiKeyPrincipal))
+    expect(getClient(4217, null)).toBe(getClient(4217, publicPrincipal))
+  })
+
+  test('consults the resolver on cache hits', () => {
+    const seen: (string | undefined)[] = []
+    const getClient = Viem.createGetClient({
+      rpc: ({ principal }) => {
+        seen.push(principal?.type)
+        return { url: 'https://internal.rpc' }
+      },
+    })
+
+    const first = getClient(4217, apiKeyPrincipal)
+    const second = getClient(4217, apiKeyPrincipal)
+    getClient(4217, publicPrincipal)
+
+    expect(seen).toMatchInlineSnapshot(`
+      [
+        "api_key",
+        "api_key",
+        "public",
+      ]
+    `)
+    expect(first).toBe(second)
+  })
+})

package/src/internal/Viem.ts

@@ -58,7 +58,7 @@ export type UrlResolver = (chainId: ChainId) => string | undefined
  * webhook poller). A missing `url` falls back to the built-in public host map
  * ({@link url}); a missing `basicAuth` means no Basic auth is sent.
  *
- * Memoization is keyed on the resolved output (see `App.create` and
+ * Memoization is keyed on the resolved output (see {@link createGetClient} and
  * {@link Tidx.createGetClient}), not the context, so a resolver may branch on
  * any principal field without unbounded client cardinality: callers that
  * resolve to the same upstream share a client. Pass the result to
@@ -130,6 +130,39 @@ export function getClient(options: getClient.Options): getClient.ReturnType {
     .extend(tempoActions())
 }
 
+/** Builds a memoized Tempo client resolver. */
+export function createGetClient(options: createGetClient.Options = {}): createGetClient.ReturnType {
+  const { defaultChainId: defaultChainId_option = defaultChainId, rpc } = options
+  const clients = new Map<string, getClient.ReturnType>()
+
+  return (chainId = defaultChainId_option, principal = null) => {
+    const { basicAuth, url } = resolve(rpc, { chainId, principal })
+    const cacheKey = JSON.stringify([url, basicAuth, chainId])
+    const existing = clients.get(cacheKey)
+    if (existing) return existing
+
+    const client = getClient({
+      chainId,
+      rpc: { basicAuth, url: () => url },
+    })
+    clients.set(cacheKey, client)
+    return client
+  }
+}
+
+export declare namespace createGetClient {
+  /** Options for building a memoized Tempo client resolver. */
+  type Options = {
+    /** Tempo chain id used when a caller omits one. */
+    defaultChainId?: ChainId | undefined
+    /** Tempo RPC options applied to every constructed client. */
+    rpc?: getClient.Rpc | undefined
+  }
+
+  /** Memoized Tempo client resolver. */
+  type ReturnType = (chainId?: ChainId, principal?: Auth.Principal | null) => getClient.ReturnType
+}
+
 export declare namespace getClient {
   /** Tempo viem client with public and Tempo action helpers. */
   type ReturnType = core_Client<