tapimo 0.12.0 → 0.13.0

package/src/db/tables/fundingCatalog.test.ts

@@ -71,8 +71,12 @@ describe('publish', () => {
       catalog: head,
       chainTokens: catalog.chainTokens,
       chains: catalog.chains,
-      // Absent `capabilities` persists as null (indicative-only).
-      routes: catalog.routes.map((route) => ({ ...route, capabilities: null })),
+      // Optional route JSON persists as null.
+      routes: catalog.routes.map((route) => ({
+        ...route,
+        capabilities: null,
+        configuration: null,
+      })),
       tokens: catalog.tokens,
     })
   })
@@ -87,6 +91,16 @@ describe('publish', () => {
     expect((await FundingCatalog.read(db)).routes[0]?.capabilities).toStrictEqual(capabilities)
   })
 
+  test('round-trips route configuration', async () => {
+    const db = TestApp.database()
+    const configuration = { poolAddress: `0x${'11'.repeat(20)}` }
+    await FundingCatalog.publish(db, {
+      ...catalog,
+      routes: [{ ...catalog.routes[0]!, configuration }],
+    })
+    expect((await FundingCatalog.read(db)).routes[0]?.configuration).toStrictEqual(configuration)
+  })
+
   test('replaces rows and advances the catalog version', async () => {
     const db = TestApp.database()
     const first = await FundingCatalog.publish(db, catalog)

package/src/db/tables/fundingCatalog.ts

@@ -28,10 +28,12 @@ export type ChainTokenTable = db_Schema.FundingChainToken
 /** Columns of the `funding_routes` table. */
 export type RouteTable = db_Schema.FundingRoute
 
-/** A route row whose `capabilities` may be absent (validated input, fixtures). */
-export type RouteRow = Omit<db_Schema.FundingRoute, 'capabilities'> & {
+/** A route row whose optional JSON fields may be absent in validated input. */
+export type RouteRow = Omit<db_Schema.FundingRoute, 'capabilities' | 'configuration'> & {
   /** Executable capability; absent and null both mean indicative-only. */
   capabilities?: db_Schema.FundingRoute['capabilities'] | undefined
+  /** Provider-specific route configuration; absent and null are equivalent. */
+  configuration?: db_Schema.FundingRoute['configuration'] | undefined
 }
 
 /** Stored funding catalog rows and version metadata. */
@@ -117,7 +119,11 @@ export function publish(db: Db.Db, input: publish.Input): Promise<db_Schema.Fund
       await tx.kysely
         .insertInto('funding_routes')
         .values(
-          input.routes.map((route) => ({ ...route, capabilities: route.capabilities ?? null })),
+          input.routes.map((route) => ({
+            ...route,
+            capabilities: route.capabilities ?? null,
+            configuration: route.configuration ?? null,
+          })),
         )
         .execute()
 

package/src/handlers/internal/utils.test.ts

@@ -0,0 +1,53 @@
+import { RpcRequest } from 'ox'
+
+import * as Utils from './utils.js'
+
+const request = RpcRequest.from({ id: 1, method: 'eth_sendRawTransaction', params: ['0x'] })
+
+describe('rpcErrorJson', () => {
+  test('maps upstream expired transactions to a transaction-rejected error', () => {
+    const error = {
+      cause: {
+        code: -32603,
+        message:
+          'Revm error: transaction expired: current block timestamp 1755616740 >= validBefore 1755616739',
+      },
+    }
+
+    expect(Utils.rpcErrorJson(request, error)).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": -32003,
+          "data": {
+            "code": "transaction_expired",
+          },
+          "message": "Transaction expired.",
+        },
+        "id": 1,
+        "jsonrpc": "2.0",
+      }
+    `)
+  })
+
+  test('preserves unrelated upstream internal errors', () => {
+    const error = {
+      code: -32603,
+      data: { reason: 'database unavailable' },
+      message: 'Revm error: database unavailable',
+    }
+
+    expect(Utils.rpcErrorJson(request, error)).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": -32603,
+          "data": {
+            "reason": "database unavailable",
+          },
+          "message": "Revm error: database unavailable",
+        },
+        "id": 1,
+        "jsonrpc": "2.0",
+      }
+    `)
+  })
+})

package/src/handlers/internal/utils.ts

@@ -127,6 +127,21 @@ export function rpcErrorJson(request: RpcRequest.RpcRequest, error: unknown) {
       { request },
     )
 
+  if (
+    inner.code === RpcResponse.InternalError.code &&
+    /^Revm error: transaction expired(?:\.|: .+)?$/.test(inner.message)
+  )
+    return RpcResponse.from(
+      {
+        error: {
+          code: RpcResponse.TransactionRejectedError.code,
+          data: { code: 'transaction_expired' },
+          message: 'Transaction expired.',
+        },
+      },
+      { request },
+    )
+
   const { code, data, message } = inner
   return RpcResponse.from(
     {

package/src/internal/Auth.ts

@@ -676,7 +676,10 @@ export declare namespace middleware {
   }
 
   /** MPP payment options used by auth middleware. */
-  type MppOptions = Omit<NonNullable<Parameters<typeof Mppx.create>[0]>, 'methods'> & {
+  type MppOptions = Omit<
+    Parameters<typeof Mppx.create<readonly [ReturnType<typeof tempo.session>]>>[0],
+    'methods'
+  > & {
     /** Paid-request quota per access principal. Defaults to 100 per minute. */
     rateLimit?: RateLimit.Limit | undefined
     /** Global Tempo Session options passed to the MPP method instantiator. */
@@ -1451,8 +1454,8 @@ export function require<environment extends Environment = Environment>(
         return proceed()
       }
 
-      const apiKey = await auth.apiKey?.resolve(c, credential.token)
-      if (!apiKey) {
+      const apiKey_resolved = await auth.apiKey?.resolve(c, credential.token)
+      if (!apiKey_resolved) {
         // A bearer session token is indistinguishable from an API key at the
         // header, so a failed key lookup falls through to the session lane
         // before rejecting.
@@ -1470,6 +1473,10 @@ export function require<environment extends Environment = Environment>(
         })
       }
 
+      const scopes = Scope.expandAliases(apiKey_resolved.scopes)
+      const apiKey =
+        scopes === apiKey_resolved.scopes ? apiKey_resolved : { ...apiKey_resolved, scopes }
+
       // Sandbox keys are testnet-only. A sandbox key that explicitly targets
       // mainnet (`?chainId`) is rejected with a clear message rather than
       // steered or downgraded to anonymous, so the caller learns their key does
@@ -1847,7 +1854,8 @@ function getRequestId(c: hono_Context) {
   return typeof variables['requestId'] === 'string' ? variables['requestId'] : undefined
 }
 
-function hasPaymentCredential(c: hono_Context) {
+/** True when the request carries an `Authorization: Payment` MPP credential. */
+export function hasPaymentCredential(c: hono_Context) {
   const authorization = c.req.header('authorization')
   if (!authorization) return false
   return !!Credential.extractPaymentScheme(authorization)

package/src/internal/EarnVaults.capabilities.test.ts

@@ -21,8 +21,8 @@ describe('deriveZoneId', () => {
   test('derives IDs from mainnet and testnet Zone chain schemes', () => {
     expect([
       EarnVaults.deriveZoneId(421_700_006),
-      EarnVaults.deriveZoneId(1_424_310_001),
-    ]).toStrictEqual([6, 1])
+      EarnVaults.deriveZoneId(1_424_310_003),
+    ]).toStrictEqual([6, 3])
   })
 
   test('rejects a source chain ID', () => {

package/src/internal/EarnVaults.test.ts

@@ -245,7 +245,7 @@ describe('resolveZoneRoutes', () => {
           zones: [TestEarn.zone],
         }),
       ).rejects.toThrowErrorMatchingInlineSnapshot(
-        `[EarnVaults.InvalidRegistryError: Zone 1424310001 is configured more than once.]`,
+        `[EarnVaults.InvalidRegistryError: Zone 1424310003 is configured more than once.]`,
       )
       await expect(
         EarnVaults.resolveZoneRoutes({

package/src/internal/EarnVaults.ts

@@ -167,7 +167,7 @@ export namespace schema {
     .strictObject({
       chainId: Schema.ChainId.check(
         z.describe('Private Zone chain id.'),
-        z.meta({ examples: [1424310001] }),
+        z.meta({ examples: [1424310003] }),
       ),
       deploymentBlock: z
         .number()
@@ -175,11 +175,11 @@ export namespace schema {
           z.int(),
           z.nonnegative(),
           z.describe('Parent-chain block that deployed the Earn router.'),
-          z.meta({ examples: [31039238] }),
+          z.meta({ examples: [31730087] }),
         ),
       earnRouter: Schema.Address.check(
         z.describe('Parent-chain router for this Zone and Earn vault.'),
-        z.meta({ examples: ['0x9144086a79dea966d8bf1b52125ebed8919fc45c'] }),
+        z.meta({ examples: ['0xebedc74ffeead186acc6cac05eb82fb9e093a7c7'] }),
       ),
     })
     .check(z.describe('Curated Earn route through one private Zone.'))

package/src/internal/Fetch.test.ts

@@ -0,0 +1,46 @@
+import * as http from 'node:http'
+
+import * as Fetch from './Fetch.js'
+
+describe('withTimeout', () => {
+  test('aborts a fetch after the configured duration', async () => {
+    const server = http.createServer(() => {})
+    const url = await listen(server)
+
+    try {
+      const fetch = Fetch.withTimeout(globalThis.fetch, { timeout: 10 })
+      await expect(fetch(url)).rejects.toMatchObject({ name: 'TimeoutError' })
+    } finally {
+      server.closeAllConnections()
+      await close(server)
+    }
+  })
+})
+
+describe('resolveSignal', () => {
+  test('preserves caller and Request signals', () => {
+    const signal = AbortSignal.timeout(1_000)
+    const request = new Request('https://api.tempo.xyz', { signal })
+
+    expect(Fetch.resolveSignal('https://api.tempo.xyz', { init: { signal }, timeout: 10 })).toBe(
+      signal,
+    )
+    expect(Fetch.resolveSignal(request, { timeout: 10 })).toBe(request.signal)
+  })
+})
+
+function close(server: http.Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()))
+  })
+}
+
+function listen(server: http.Server): Promise<string> {
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address()
+      if (!address || typeof address === 'string') throw new Error('Expected a TCP server address.')
+      resolve(`http://127.0.0.1:${address.port}`)
+    })
+  })
+}

package/src/internal/Fetch.ts

@@ -0,0 +1,56 @@
+import * as Timeout from './Timeout.js'
+
+/** Installs the default outbound fetch timeout once for this runtime. */
+export function install(): void {
+  if (isInstalled(globalThis.fetch)) return
+
+  const fetch = withTimeout(globalThis.fetch.bind(globalThis), { timeout: Timeout.duration })
+  Object.defineProperty(fetch, timeoutMarker, { value: true })
+  globalThis.fetch = fetch
+}
+
+/** Adds a default maximum duration to fetch calls that do not carry a signal. */
+export function withTimeout(
+  fetch: typeof globalThis.fetch,
+  options: withTimeout.Options,
+): typeof globalThis.fetch {
+  return ((input, init) => {
+    const signal = resolveSignal(input, { init, timeout: options.timeout })
+    return fetch(input, { ...init, signal })
+  }) as typeof globalThis.fetch
+}
+
+/** Resolves a caller signal or creates the default fetch deadline signal. */
+export function resolveSignal(
+  input: Parameters<typeof globalThis.fetch>[0],
+  options: resolveSignal.Options,
+): AbortSignal {
+  return (
+    options.init?.signal ??
+    (input instanceof Request ? input.signal : Timeout.signal({ timeout: options.timeout }))
+  )
+}
+
+export declare namespace resolveSignal {
+  /** Options for {@link resolveSignal}. */
+  type Options = {
+    /** Optional fetch initialization carrying a caller signal. */
+    init?: Parameters<typeof globalThis.fetch>[1]
+    /** Default maximum duration in milliseconds. */
+    timeout: number
+  }
+}
+
+export declare namespace withTimeout {
+  /** Options for {@link withTimeout}. */
+  type Options = {
+    /** Maximum fetch duration in milliseconds. */
+    timeout: number
+  }
+}
+
+const timeoutMarker = Symbol.for('tempo.api.fetch.timeout')
+
+function isInstalled(fetch: typeof globalThis.fetch): boolean {
+  return timeoutMarker in fetch
+}

package/src/internal/Log.test.ts

@@ -457,6 +457,27 @@ describe('middleware', () => {
     `)
   })
 
+  test('preserves the request error and unfinished stages', async () => {
+    const entries: Log.Entry[] = []
+    const causes: Error[] = []
+    const api = app({
+      emit: (entry, cause) => {
+        entries.push(entry)
+        if (cause) causes.push(cause)
+      },
+    })
+    const cause = new Error('Memoized cache-miss flight timed out after 15000ms.')
+    api.get('/activities', (c) => {
+      void Timing.time(c, 'transaction_activity_mpp', () => new Promise(() => {}))
+      return Response.upstream(c, cause)
+    })
+
+    await api.request('/activities')
+
+    expect(causes[0]).toBe(cause)
+    expect(entries[0]?.pendingTimings?.['transaction_activity_mpp']).toBeGreaterThanOrEqual(0)
+  })
+
   test('includes bounded funding provider attempts', async () => {
     const entries: Log.Entry[] = []
     const api = app({ emit: (entry) => void entries.push(entry) })

package/src/internal/Log.ts

@@ -151,6 +151,8 @@ export type Entry = {
   path: string
   /** MPP payment reason when the request was paid per call. */
   payment?: Auth.Payment['reason'] | undefined
+  /** Operations still running when the response completed, with elapsed milliseconds. */
+  pendingTimings?: Record<string, number> | undefined
   /** Bounded outcome for an MPP relay operation. */
   mpp?: {
     /** Resolved Tempo chain selected by the credential. */
@@ -228,7 +230,7 @@ export type Entry = {
 }
 
 /** Sink receiving one {@link Entry} per request. */
-export type Emit = (entry: Entry) => Promise<void> | void
+export type Emit = (entry: Entry, cause?: Error) => Promise<void> | void
 
 /**
  * Emits one canonical structured log entry per request, after the response is
@@ -258,7 +260,8 @@ export function middleware<environment extends Environment = Environment>(
     // Hono cannot resolve variable types through the generic `environment`,
     // so shared-variable reads are cast from the environment contract above
     // (the same pattern EdgeCache uses for its cross-layer reads).
-    const error = c.error as ErrorMetadata | undefined
+    const cause = c.error
+    const error = cause as (Error & ErrorMetadata) | undefined
     const principal = c.get('principal' as never) as Auth.Principal | undefined
     const errorCaptured = c.get('errorCaptured' as never) as boolean | undefined
     const chainId = c.get('chainId' as never) as number | undefined
@@ -279,7 +282,6 @@ export function middleware<environment extends Environment = Environment>(
       error?.providerFailures ?? (c.get('providerFailures' as never) as Entry['providerFailures'])
     const rpc = c.get('rpcResponse' as never) as Entry['rpc']
     const sponsorship = c.get('sponsorship' as never) as Entry['sponsorship']
-
     // The `request` total metric duplicates `duration` (measured here, one
     // layer further out), so only operation timings are kept.
     const metrics = (c.get('serverTiming' as never) as Timing.Metric[] | undefined)?.filter(
@@ -295,6 +297,17 @@ export function middleware<environment extends Environment = Environment>(
           }, new Map<string, number>()),
         )
       : undefined
+    const activeTimings = c.get('activeTimings' as never) as Timing.Active[] | undefined
+    const pendingTimings = activeTimings?.length
+      ? Object.fromEntries(
+          activeTimings.reduce((result, timing) => {
+            const duration = round(performance.now() - timing.start)
+            const existing = result.get(timing.name)
+            if (existing === undefined || duration > existing) result.set(timing.name, duration)
+            return result
+          }, new Map<string, number>()),
+        )
+      : undefined
 
     const rateLimit = (() => {
       const limit = c.res.headers.get('RateLimit-Limit')
@@ -310,7 +323,7 @@ export function middleware<environment extends Environment = Environment>(
       }
     })()
 
-    const result = fn({
+    const entry = {
       ...(c.get('edgeCacheStatus' as never) === 'hit' ? { cache: 'hit' as const } : {}),
       ...(chainId === undefined ? {} : { chainId }),
       duration: round(duration),
@@ -333,6 +346,7 @@ export function middleware<environment extends Environment = Environment>(
       ...(mpp === undefined ? {} : { mpp }),
       path: url.pathname,
       ...(principal?.payment === undefined ? {} : { payment: principal.payment.reason }),
+      ...(pendingTimings === undefined ? {} : { pendingTimings }),
       ...(principal === undefined
         ? {}
         : {
@@ -360,7 +374,8 @@ export function middleware<environment extends Environment = Environment>(
       ...(sponsorship === undefined ? {} : { sponsorship }),
       status,
       ...(timings === undefined ? {} : { timings }),
-    })
+    } satisfies Entry
+    const result = fn(entry, cause)
 
     if (result instanceof Promise) {
       const promise = result.catch((error) => console.error('request log sink failed', error))

package/src/internal/OpenApi.ts

@@ -148,6 +148,7 @@ export const errorCodes = {
   500: ['internal_error'],
   501: ['billing_unconfigured'],
   502: ['upstream_error'],
+  504: ['request_timeout'],
 } as const satisfies Record<number, readonly [string, ...string[]]>
 
 /**
@@ -220,6 +221,7 @@ const standardErrorNames = {
   500: 'InternalError',
   501: 'NotImplementedError',
   502: 'UpstreamError',
+  504: 'RequestTimeoutError',
 } as const satisfies Record<keyof typeof errorCodes, string>
 
 const reservedErrorNames = new Set<string>(Object.values(standardErrorNames))
@@ -300,12 +302,12 @@ export const paymentChallenge = {
   headers: { 'WWW-Authenticate': headerRef('WwwAuthenticate') },
 } as const
 
-type ResponseComponentName = 'InternalError' | 'PaymentRequired' | 'RateLimited'
+type ResponseComponentName = 'InternalError' | 'PaymentRequired' | 'RateLimited' | 'RequestTimeout'
 
 /**
  * Reusable responses registered under `components.responses` (see `App.create`)
- * and `$ref`-erenced from operations, so the uniform `402`/`429`/`500` responses
- * are defined once instead of inlined on every operation.
+ * and `$ref`-erenced from operations, so the uniform `402`/`429`/`500`/`504`
+ * responses are defined once instead of inlined on every operation.
  */
 export function responseComponents(): ResponsesWithResolver {
   return {
@@ -320,6 +322,11 @@ export function responseComponents(): ResponsesWithResolver {
         'Rate limit exceeded. On endpoints that accept MPP, over-quota unpaid requests return `402 Payment Required` instead.',
       headers: { ...rateLimitHeaders },
     },
+    RequestTimeout: {
+      content: errorContent(504, errorCodes[504], 'Request timed out'),
+      description:
+        'Request timed out. The request did not complete within the 60-second deadline; retry it.',
+    },
   }
 }
 
@@ -344,6 +351,7 @@ export function standardError(
 ): ResponsesWithResolver[string] {
   if (status === 429) return responseRef('RateLimited')
   if (status === 500) return responseRef('InternalError')
+  if (status === 504) return responseRef('RequestTimeout')
   return { content: errorContent(status, mergeErrorCodes(status, codes), description), description }
 }
 
@@ -352,7 +360,8 @@ export function standardError(
  * pre-filled, plus the success response (with rate-limit headers):
  *
  * - `400` invalid request, `401` missing/invalid key, `403` forbidden, `429`
- *   rate limited, `500` internal error, and `502` upstream failure on every operation;
+ *   rate limited, `500` internal error, `502` upstream failure, and `504`
+ *   request timeout on every operation;
  * - `404`/`409`/`412`/`413`/`415` only when an `errors` entry is set.
  *
  * `error.code` is enumerated per status from {@link errorCodes}. Operation-level
@@ -404,6 +413,7 @@ export function responses<schema extends z.ZodMiniType>(
     500: responseRef('InternalError'),
     ...(errors?.[501] && { 501: error(501, 'Not implemented.') }),
     502: error(502, 'Upstream data failure.'),
+    504: responseRef('RequestTimeout'),
   }
 }
 

package/src/internal/Response.ts

@@ -142,7 +142,7 @@ export declare namespace error {
   }
 
   /** HTTP status code accepted by the public error helper. */
-  type Status = 400 | 401 | 403 | 404 | 409 | 412 | 413 | 415 | 429 | 500 | 501 | 502 | 503
+  type Status = 400 | 401 | 403 | 404 | 409 | 412 | 413 | 415 | 429 | 500 | 501 | 502 | 503 | 504
 
   /** Options for creating a JSON error response. */
   type Options<status extends Status = Status, code extends string = string> = {

package/src/internal/Schema.test.ts

@@ -6,6 +6,8 @@ describe('ChainId', () => {
   test('resolves aliases to their chain id', () => {
     expect(Schema.ChainId.parse('mainnet')).toMatchInlineSnapshot(`4217`)
     expect(Schema.ChainId.parse('testnet')).toMatchInlineSnapshot(`42431`)
+    expect(Schema.ChainId.parse('1424310001')).toMatchInlineSnapshot(`1424310003`)
+    expect(Schema.ChainId.parse(1_424_310_001)).toMatchInlineSnapshot(`1424310003`)
   })
 
   test('accepts numeric chain ids as numbers or strings', () => {

package/src/internal/Schema.ts

@@ -90,12 +90,19 @@ export function tokenAddress(example: core_Hex.Hex) {
     )
 }
 
-/** Maps human-readable chain aliases to their Tempo chain id. */
+/** Maps caller-facing chain aliases to their current Tempo chain id. */
 export const chainIdAlias = {
+  // TODO: Remove this alias after clients migrate to chain 1424310003.
+  1_424_310_001: 1_424_310_003,
   mainnet: 4217,
   testnet: 42431,
 } as const
 
+/** Resolves a numeric chain id through the caller-facing alias map. */
+export function resolveChainId(chainId: number): number {
+  return chainIdAlias[chainId as keyof typeof chainIdAlias] ?? chainId
+}
+
 /**
  * Tempo chain id. Accepts a chain alias (`mainnet`/`testnet`) or any positive
  * integer chain id (a number or numeric string), normalizing all forms to a
@@ -110,7 +117,10 @@ export const ChainId = z
         z.enum(['mainnet', 'testnet']),
         z.transform((alias) => chainIdAlias[alias]),
       ),
-      z.coerce.number(),
+      z.pipe(
+        z.coerce.number(),
+        z.transform((chainId) => resolveChainId(chainId)),
+      ),
     ]),
     z.number().check(z.int(), z.positive()),
   )