tapimo 0.5.3 → 0.7.0

package/src/internal/Log.ts

@@ -4,16 +4,21 @@ import type { RequestIdVariables } from 'hono/request-id'
 import * as ApiKey from '../ApiKey.js'
 import type * as Auth from './Auth.js'
 import type * as EdgeCache from './EdgeCache.js'
+import type * as FundingQuotes from './FundingQuotes.js'
 import type * as Timing from './Timing.js'
 
 /** Hono variables read by the request logger and written by other layers. */
 export type Variables = {
   /** Stable error code recorded by `Response.error` for the request log entry. */
   errorCode?: string | undefined
+  /** Bounded outcomes for funding providers attempted by the request. */
+  fundingProviderAttempts?: Entry['fundingProviderAttempts'] | 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
+  /** Bounded JSON-RPC failure metadata recorded by a composed RPC handler. */
+  rpcResponse?: Entry['rpc'] | undefined
 }
 
 /** Hono environment shape used by the request logger. */
@@ -35,7 +40,7 @@ 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'
+  failure: 'http' | 'network' | 'payload' | 'rate_limit' | 'timeout' | 'unknown'
   /** Provider identifier. */
   id: string
   /** Provider operation identifier. */
@@ -44,6 +49,20 @@ export type ProviderFailure = {
   status?: number | undefined
 }
 
+/** Bounded operational result for one funding quote provider attempt. */
+export type FundingProviderAttempt = {
+  /** Wall-clock duration of the provider attempt in milliseconds. */
+  durationMs: number
+  /** Failure class, present only when the provider attempt failed. */
+  failure?: ProviderFailure['failure'] | undefined
+  /** Provider identifier. */
+  id: FundingQuotes.ProviderId
+  /** Stable upstream operation identifier. */
+  operation: string
+  /** Provider attempt outcome. */
+  outcome: 'available' | 'failed' | 'thin' | 'unavailable'
+}
+
 /** One canonical request log entry. */
 export type Entry = {
   /** `'hit'` when the edge response cache served the request without reaching the origin handlers. */
@@ -52,7 +71,9 @@ export type Entry = {
   duration: number
   /** Stable error code when the response is a JSON error envelope (e.g. `not_found`, `api_key_invalid`). */
   errorCode?: string | undefined
-  /** Log level derived from the response status: 5xx `error`, 4xx `warn`, else `info`. */
+  /** Bounded funding provider attempts made while serving the request. */
+  fundingProviderAttempts?: readonly FundingProviderAttempt[] | undefined
+  /** Log level: 5xx `error`; 4xx or JSON-RPC failure `warn`; otherwise `info`. */
   level: Level
   /** Request method. */
   method: string
@@ -102,7 +123,16 @@ export type Entry = {
   requestId: string
   /** Matched handler path (bounded cardinality), e.g. `/v1/tokens/:address`; `/*` when a middleware (e.g. an edge-cache hit) short-circuited routing. */
   route: string
-  /** Response status code. */
+  /** JSON-RPC failures returned in an otherwise successful HTTP response. */
+  rpc?: {
+    /** Numeric JSON-RPC error code when every failed response shares one code. */
+    code?: number | undefined
+    /** Stable application error code from `error.data.code`, when shared by every failed response. */
+    dataCode?: string | undefined
+    /** Number of failed responses in the single or batch JSON-RPC response. */
+    errors: number
+  }
+  /** HTTP response status code. JSON-RPC failures retain their protocol-native `200`. */
   status: number
   /** Upstream operation durations in milliseconds, from the request's Server-Timing metrics (e.g. RPC and TIDX calls). */
   timings?: Record<string, number> | undefined
@@ -119,8 +149,9 @@ export type Emit = (entry: Entry) => Promise<void> | void
  *
  * The entry derives everything from state other layers already produce —
  * `requestId`, the auth principal, `RateLimit-*` headers, Server-Timing
- * metrics, the `errorCode` recorded by `Response.error`, and the edge-cache
- * hit marker — so handlers never log per-request lines themselves.
+ * metrics, the `errorCode` recorded by `Response.error`, JSON-RPC response
+ * errors, and the edge-cache hit marker, so handlers never log per-request
+ * lines themselves.
  */
 export function middleware<environment extends Environment = Environment>(
   options: middleware.Options = {},
@@ -140,8 +171,12 @@ export function middleware<environment extends Environment = Environment>(
     // (the same pattern EdgeCache uses for its cross-layer reads).
     const principal = c.get('principal' as never) as Auth.Principal | undefined
     const errorCode = c.get('errorCode' as never) as string | undefined
+    const fundingProviderAttempts = c.get('fundingProviderAttempts' as never) as
+      | Entry['fundingProviderAttempts']
+      | undefined
     const provider = c.get('providerFailure' as never) as Entry['provider']
     const providerFailures = c.get('providerFailures' as never) as Entry['providerFailures']
+    const rpc = c.get('rpcResponse' as never) as Entry['rpc']
 
     // The `request` total metric duplicates `duration` (measured here, one
     // layer further out), so only operation timings are kept.
@@ -170,7 +205,13 @@ export function middleware<environment extends Environment = Environment>(
       ...(c.get('edgeCacheStatus' as never) === 'hit' ? { cache: 'hit' as const } : {}),
       duration: round(duration),
       ...(errorCode === undefined ? {} : { errorCode }),
-      level: status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info',
+      ...(fundingProviderAttempts === undefined ? {} : { fundingProviderAttempts }),
+      level:
+        status >= 500 || rpcServerError(rpc?.code)
+          ? 'error'
+          : status >= 400 || rpc
+            ? 'warn'
+            : 'info',
       method: c.req.method,
       path: url.pathname,
       ...(principal?.payment === undefined ? {} : { payment: principal.payment.reason }),
@@ -197,6 +238,7 @@ export function middleware<environment extends Environment = Environment>(
       ...(rateLimit === undefined ? {} : { rateLimit }),
       requestId: c.get('requestId' as never) as string,
       route: c.req.routePath,
+      ...(rpc === undefined ? {} : { rpc }),
       status,
       ...(timings === undefined ? {} : { timings }),
     })
@@ -215,6 +257,51 @@ export function middleware<environment extends Environment = Environment>(
   }
 }
 
+const rpcDataCode = /^[a-z][a-z0-9_]{0,63}$/
+
+/** Extracts bounded error metadata from an already-parsed JSON-RPC response. */
+export function rpcErrors(body: unknown): Entry['rpc'] {
+  const values = Array.isArray(body) ? body : [body]
+  const errors = values.flatMap((value) => {
+    if (!value || typeof value !== 'object') return []
+    const record = value as Record<string, unknown>
+    if (record['jsonrpc'] !== '2.0' || !record['error'] || typeof record['error'] !== 'object')
+      return []
+    const error = record['error'] as Record<string, unknown>
+    if (
+      !Number.isInteger(error['code']) ||
+      Number(error['code']) < -2_147_483_648 ||
+      Number(error['code']) > 2_147_483_647
+    )
+      return []
+    const data = error['data']
+    const dataCode_value =
+      data && typeof data === 'object' ? (data as Record<string, unknown>)['code'] : undefined
+    const dataCode = typeof dataCode_value === 'string' ? dataCode_value : undefined
+    return [
+      {
+        code: error['code'] as number,
+        ...(dataCode && rpcDataCode.test(dataCode) ? { dataCode } : {}),
+      },
+    ]
+  })
+  if (errors.length === 0) return undefined
+
+  const codes = new Set(errors.map((error) => error.code))
+  const dataCodes = new Set(errors.map((error) => error.dataCode).filter(Boolean))
+  return {
+    ...(codes.size === 1 ? { code: errors[0]!.code } : {}),
+    ...(dataCodes.size === 1 && errors.every((error) => error.dataCode !== undefined)
+      ? { dataCode: errors[0]!.dataCode }
+      : {}),
+    errors: Math.min(errors.length, 65_535),
+  }
+}
+
+function rpcServerError(code: number | undefined) {
+  return code === -32603 || (code !== undefined && code >= -32099 && code <= -32000)
+}
+
 export declare namespace middleware {
   /** Options for the request logger middleware. */
   type Options = {

package/src/internal/MetricSink.test.ts

@@ -0,0 +1,215 @@
+import * as Metrics from '../Metrics.js'
+import type * as Log from './Log.js'
+import * as MetricSink from './MetricSink.js'
+
+type MetricEvent = {
+  name: string
+  tags: Metrics.Tags | undefined
+  type: 'count' | 'gauge' | 'histogram'
+  value: number
+}
+
+describe('requests', () => {
+  test('records JSON-RPC errors with bounded code tags', () => {
+    const events: MetricEvent[] = []
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {},
+      gauge() {},
+      histogram() {},
+    })
+    const record = MetricSink.requests(metrics)
+
+    record({
+      duration: 10,
+      level: 'warn',
+      method: 'POST',
+      path: '/rpc/relay',
+      requestId: 'request_private',
+      route: '/rpc/relay',
+      rpc: { code: -32602, dataCode: 'billing_required', errors: 2 },
+      status: 200,
+    })
+
+    expect(events).toMatchInlineSnapshot(`
+      [
+        {
+          "name": "http_response_count",
+          "tags": {
+            "cache": "miss",
+            "method": "POST",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "route": "/rpc/relay",
+            "status": 200,
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "rpc_response_error_count",
+          "tags": {
+            "cache": "miss",
+            "method": "POST",
+            "principal_environment": "none",
+            "principal_type": "unknown",
+            "route": "/rpc/relay",
+            "rpc_error_code": "-32602",
+          },
+          "type": "count",
+          "value": 2,
+        },
+      ]
+    `)
+  })
+
+  test('records bounded funding provider attempts without caller data', () => {
+    const events: MetricEvent[] = []
+    let flushes = 0
+    const metrics = Metrics.from({
+      count(name, value, tags) {
+        events.push({ name, tags, type: 'count', value })
+      },
+      flush() {
+        flushes += 1
+      },
+      gauge(name, value, tags) {
+        events.push({ name, tags, type: 'gauge', value })
+      },
+      histogram(name, value, tags) {
+        events.push({ name, tags, type: 'histogram', value })
+      },
+    })
+    const record = MetricSink.requests(metrics)
+
+    record({
+      duration: 100,
+      fundingProviderAttempts: [
+        {
+          durationMs: 10,
+          id: 'relay',
+          operation: 'quote/v2',
+          outcome: 'available',
+        },
+        {
+          durationMs: 20,
+          id: 'rhino',
+          operation: 'quote/bridge-swap/public',
+          outcome: 'thin',
+        },
+        {
+          durationMs: 30,
+          id: 'squid',
+          operation: 'v2/route',
+          outcome: 'unavailable',
+        },
+        {
+          durationMs: 40,
+          failure: 'timeout',
+          id: 'across',
+          operation: 'swap/approval',
+          outcome: 'failed',
+        },
+      ],
+      level: 'info',
+      method: 'GET',
+      path: '/v1/funding/quotes',
+      principal: {
+        id: 'key_private',
+        orgId: 'org_private',
+        projectId: 'project_private',
+        type: 'api_key',
+      },
+      query: 'sourceAmount=secret',
+      requestId: 'request_private',
+      route: '/v1/funding/quotes',
+      status: 200,
+    } satisfies Log.Entry)
+
+    const funding = events.filter((event) => event.name.startsWith('funding_quote_provider_'))
+    expect(funding).toMatchInlineSnapshot(`
+      [
+        {
+          "name": "funding_quote_provider_attempt_count",
+          "tags": {
+            "outcome": "available",
+            "provider": "relay",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "funding_quote_provider_duration_ms",
+          "tags": {
+            "outcome": "available",
+            "provider": "relay",
+          },
+          "type": "histogram",
+          "value": 10,
+        },
+        {
+          "name": "funding_quote_provider_attempt_count",
+          "tags": {
+            "outcome": "thin",
+            "provider": "rhino",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "funding_quote_provider_duration_ms",
+          "tags": {
+            "outcome": "thin",
+            "provider": "rhino",
+          },
+          "type": "histogram",
+          "value": 20,
+        },
+        {
+          "name": "funding_quote_provider_attempt_count",
+          "tags": {
+            "outcome": "unavailable",
+            "provider": "squid",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "funding_quote_provider_duration_ms",
+          "tags": {
+            "outcome": "unavailable",
+            "provider": "squid",
+          },
+          "type": "histogram",
+          "value": 30,
+        },
+        {
+          "name": "funding_quote_provider_attempt_count",
+          "tags": {
+            "failure": "timeout",
+            "outcome": "failed",
+            "provider": "across",
+          },
+          "type": "count",
+          "value": 1,
+        },
+        {
+          "name": "funding_quote_provider_duration_ms",
+          "tags": {
+            "failure": "timeout",
+            "outcome": "failed",
+            "provider": "across",
+          },
+          "type": "histogram",
+          "value": 40,
+        },
+      ]
+    `)
+    expect(JSON.stringify(funding)).not.toMatch(
+      /key_private|org_private|project_private|request_private|secret/,
+    )
+    expect(flushes).toBe(1)
+  })
+})

package/src/internal/MetricSink.ts

@@ -85,6 +85,12 @@ export function requests(backend: Metrics): RequestSink {
     })
     backend.histogram('http_response_duration_ms', entry.duration, tags)
 
+    if (entry.rpc)
+      backend.count('rpc_response_error_count', entry.rpc.errors, {
+        ...tags,
+        rpc_error_code: rpcErrorCode(entry.rpc.code),
+      })
+
     if (entry.status === 429 || entry.errorCode === 'rate_limit_exceeded')
       backend.count('http_rate_limit_count', 1, {
         ...tags,
@@ -95,10 +101,28 @@ export function requests(backend: Metrics): RequestSink {
     for (const [operation, duration] of Object.entries(entry.timings ?? {}))
       backend.histogram('upstream_duration_ms', duration, { ...tags, operation })
 
+    for (const attempt of entry.fundingProviderAttempts ?? []) {
+      const tags_attempt = {
+        ...(attempt.failure === undefined ? {} : { failure: attempt.failure }),
+        outcome: attempt.outcome,
+        provider: attempt.id,
+      }
+      backend.count('funding_quote_provider_attempt_count', 1, tags_attempt)
+      backend.histogram('funding_quote_provider_duration_ms', attempt.durationMs, tags_attempt)
+    }
+
     backend.flush()
   }
 }
 
+/** Maps arbitrary upstream JSON-RPC codes into bounded metric tags. */
+function rpcErrorCode(code: number | undefined) {
+  if (code === undefined) return 'mixed'
+  if ([-32700, -32600, -32601, -32602, -32603].includes(code)) return String(code)
+  if (code >= -32099 && code <= -32000) return 'server'
+  return 'other'
+}
+
 function routeTags(entry: Log.Entry): RouteTags {
   return {
     cache: entry.cache ?? 'miss',

package/src/internal/OpenApi.ts

@@ -64,6 +64,7 @@ export const errorCodes = {
     'address_invalid',
     'token_invalid',
     'symbol_invalid',
+    'quote_amount_out_of_range',
     'pair_invalid',
     'pair_id_invalid',
     'transaction_invalid',
@@ -71,6 +72,7 @@ export const errorCodes = {
     'block_invalid',
     'chain_id_invalid',
     'chain_id_unsupported',
+    'destination_transition_invalid',
     'url_invalid',
     'api_key_malformed',
   ],
@@ -85,6 +87,7 @@ export const errorCodes = {
     'receipt_not_found',
     'order_not_found',
     'pair_not_found',
+    'quote_not_available',
     'verified_token_not_found',
     'webhook_not_found',
     'delivery_not_found',

package/src/internal/Response.test.ts

@@ -0,0 +1,28 @@
+import { Hono } from 'hono'
+
+import * as Response from './Response.js'
+
+describe('upstream', () => {
+  test('returns a stable message and preserves the cause on context', async () => {
+    const app = new Hono()
+    const cause = new Error('provider URL contains secret credentials')
+    let captured: Error | undefined
+
+    app.use(async (c, next) => {
+      await next()
+      captured = c.error
+    })
+    app.get('/', (c) => Response.upstream(c, cause))
+
+    const response = await app.request('/')
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "upstream_error",
+          "message": "Upstream service could not complete the request",
+        },
+      }
+    `)
+    expect(captured).toBe(cause)
+  })
+})

package/src/internal/Response.ts

@@ -39,12 +39,20 @@ export function unsupportedChainId(c: Context, chainId: number, supported: Itera
 }
 
 /**
- * Maps an unexpected upstream failure to a 502 JSON error envelope. Rethrows
- * non-`Error` causes so the global handler can convert them.
+ * Maps an unexpected upstream failure to a stable 502 JSON error envelope.
+ * Preserves `Error` causes for reporting and rethrows non-`Error` causes.
  */
 export function upstream(c: Context, cause: unknown) {
-  if (cause instanceof Error)
-    return error(c, { code: 'upstream_error', message: cause.message, status: 502 })
+  if (cause instanceof Error) {
+    // Preserve the original error for error-reporting middleware without
+    // exposing provider URLs, payloads, or credentials in the response.
+    c.error = cause
+    return error(c, {
+      code: 'upstream_error',
+      message: 'Upstream service could not complete the request',
+      status: 502,
+    })
+  }
   throw cause
 }
 

package/src/internal/Schema.ts

@@ -290,6 +290,35 @@ export const DecimalString = z
     z.meta({ examples: ['1000000'] }),
   )
 
+/** A self-contained token quantity in base units and human-readable form. */
+export const TokenAmount = describe(
+  z.object({
+    baseUnits: DecimalString.check(z.describe("The quantity in the token's smallest unit.")),
+    currency: z
+      .string()
+      .check(
+        z.describe('The monetary denomination of this quantity.'),
+        z.meta({ examples: ['USD'] }),
+      ),
+    decimals: z
+      .number()
+      .check(
+        z.int(),
+        z.nonnegative(),
+        z.describe('Decimal places used to convert `baseUnits` into `formatted`.'),
+        z.meta({ examples: [6] }),
+      ),
+    formatted: z
+      .string()
+      .check(
+        z.regex(/^\d+(\.\d+)?$/),
+        z.describe('The quantity rendered in whole token units.'),
+        z.meta({ examples: ['1'] }),
+      ),
+  }),
+  'A token quantity with its denomination and decimal representation.',
+)
+
 /**
  * Minimum page size accepted across list endpoints. Floored at 5 because the
  * indexer rejects signature-decoded `Transfer` queries with `LIMIT < 5`
@@ -306,6 +335,22 @@ export const Limit = z
     z.meta({ examples: [10] }),
   )
 
+/** Valuation denomination query parameter shared across valuation-bearing endpoints. */
+export const Denomination = z
+  .optional(
+    z.pipe(
+      z.string().check(z.regex(/^[a-zA-Z]{3}$/)),
+      z.transform((value) => value.toUpperCase()),
+    ),
+  )
+  .check(
+    z.describe(
+      'Currency to denominate values in (case-insensitive, e.g. `AUD`). ' +
+        'Must be priced by the configured FX oracle. Defaults to `USD`.',
+    ),
+    z.meta({ examples: ['AUD'] }),
+  )
+
 /** Opaque keyset-pagination cursor query parameter shared across list endpoints. */
 export const Cursor = z
   .optional(z.string())
@@ -464,17 +509,17 @@ export function timestampBound(noun: string, bound: 'from' | 'to') {
 
 /**
  * Builds the schema for a comma-separated opt-in query parameter (e.g.
- * `?include=token,feeToken`), parsed into a validated array of the given enum's
+ * `?include=token,totalCount`), parsed into a validated array of the given enum's
  * members. Absent or empty values yield `[]`. Centralizes the splitting,
  * trimming, and OpenAPI array-enum metadata that every list endpoint otherwise
  * repeats.
  *
- * A repeated parameter (`?include=token&include=feeToken`) arrives from the
+ * A repeated parameter (`?include=token&include=totalCount`) arrives from the
  * validator as a `string[]`, so the input accepts both forms and each entry is
- * still comma-split — the two styles compose freely.
+ * still comma-split, so the two styles compose freely.
  *
- * Pass the endpoint's `Include` enum — kept local so its members drive both the
- * parsed type and the docs — plus the param description.
+ * Pass the endpoint's local `Include` enum so its members drive the parsed type
+ * and documentation, plus the parameter description.
  */
 export function includeQuery<const T extends Readonly<Record<string, string>>>(
   member: z.ZodMiniEnum<T>,

package/src/internal/Value.test.ts

@@ -0,0 +1,20 @@
+import * as Value from './Value.js'
+
+describe('tokenAmount', () => {
+  test('renders a self-contained token quantity', () => {
+    expect(
+      Value.tokenAmount({
+        baseUnits: '1234567',
+        currency: 'USD',
+        decimals: 6,
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "baseUnits": "1234567",
+        "currency": "USD",
+        "decimals": 6,
+        "formatted": "1.234567",
+      }
+    `)
+  })
+})

package/src/internal/Value.ts

@@ -1,4 +1,4 @@
-import { Hex } from 'ox'
+import { Hex, Value as core_Value } from 'ox'
 
 /** Coerce a TIDX numeric column (bigint / number / string) to a JS number. */
 export function toNumber(value: unknown) {
@@ -39,6 +39,29 @@ export function toIntegerString(value: unknown) {
   return undefined
 }
 
+/** Builds a token amount from its base-unit quantity and immutable token metadata. */
+export function tokenAmount(options: tokenAmount.Options) {
+  const baseUnits = options.baseUnits.toString()
+  return {
+    baseUnits,
+    currency: options.currency,
+    decimals: options.decimals,
+    formatted: core_Value.format(BigInt(baseUnits), options.decimals),
+  }
+}
+
+export declare namespace tokenAmount {
+  /** Inputs needed to render a self-contained token amount. */
+  type Options = {
+    /** Quantity in the token's smallest unit. */
+    baseUnits: bigint | string
+    /** Monetary denomination reported by the token. */
+    currency: string
+    /** Decimal places used by the token. */
+    decimals: number
+  }
+}
+
 /**
  * Coerce a TIDX numeric column (bigint / number / decimal string) to a minimal
  * `0x`-prefixed hex quantity (`0x0` for zero), matching the JSON-RPC wire

package/src/internal/VerifiedTokens.ts

@@ -535,7 +535,15 @@ export async function snapshot(c: Context<App.Environment>, chainId: ChainId): P
 
     // Soft-stale: serve immediately, refresh in the background. Never blocks.
     if (cell) {
-      void refresh(c, Db.get(c.get('dbCached')), chainId, cell)
+      const inflight = refresh(c, Db.get(c.get('dbCached')), chainId, cell)
+      // Workers cancel post-response I/O unless kept alive via `waitUntil`;
+      // without it the refresh dies mid-query and publishes never propagate.
+      // Node has no execution context, and fire-and-forget survives there.
+      try {
+        c.executionCtx.waitUntil(inflight)
+      } catch {
+        void inflight
+      }
       return cell.snapshot
     }