tapimo 0.7.0 → 0.7.2

package/src/apps/relay/App.ts

@@ -1,6 +1,6 @@
 import { Hono } from 'hono'
 import { createMiddleware } from 'hono/factory'
-import { RpcResponse } from 'ox'
+import { Hash, Hex, RpcResponse } from 'ox'
 import { ZoneRpcAuthentication } from 'ox/tempo'
 import { Addresses, TokenId, Transaction } from 'viem/tempo'
 
@@ -88,16 +88,48 @@ function middleware(options: middleware.Options) {
     const verifiedTokens = c.get('verifiedTokens')
     const zoneToken_header = c.req.header(ZoneRpcAuthentication.headerName)
     const zoneToken = zoneToken_header?.trim() ? zoneToken_header : undefined
+    let chainId: number | null | undefined
+    let internalErrors = 0
+    let reason: Log.SponsorshipReason | null | undefined
+    let rejections = 0
+    const reasons = new Set<Log.SponsorshipReason>()
+    const requests: rejectionDiagnostics.Request[] = []
+
+    const recordRejection = (options: middleware.Rejection) => {
+      const id =
+        Number.isSafeInteger(options.chainId) && options.chainId >= 0 ? options.chainId : null
+      if (chainId !== null) chainId = chainId === undefined || chainId === id ? id : null
+      if (options.reason === 'internal_error') internalErrors = Math.min(internalErrors + 1, 65_535)
+      if (reason !== null)
+        reason = reason === undefined || reason === options.reason ? options.reason : null
+      reasons.add(options.reason)
+      rejections = Math.min(rejections + 1, 65_535)
+    }
+
+    const rejectSponsorship = (options: middleware.Refusal): never => {
+      recordRejection({ chainId: options.chainId, reason: options.reason })
+      throw new RpcResponse.InvalidParamsError({
+        data: { code: options.reason },
+        message: options.message,
+      })
+    }
+
+    const failSponsorship = (options: middleware.Failure): never => {
+      recordRejection({ chainId: options.chainId, reason: 'internal_error' })
+      // Capability-form fills serialize `Error.message`, so retain the
+      // internal detail only as a cause.
+      throw new Error('Internal error', { cause: new Error(options.message) })
+    }
 
     const feePayer = (() => {
       if (!options.feePayer) return undefined
       const attribution =
-        principal?.type === 'api_key' && principal.projectId !== undefined
+        principal?.type === 'api_key'
           ? {
               apiKeyId: principal.id,
               environment: principal.environment,
               orgId: principal.orgId,
-              projectId: principal.projectId,
+              ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
             }
           : undefined
       const sponsorable =
@@ -115,9 +147,30 @@ function middleware(options: middleware.Options) {
           // only mainnet: the relay resolves chainId from the request body, so
           // the query-string chain guard never sees it.
           const id = Number(transaction.chainId)
-          if (!attribution || !sponsorable || !c.get('supportedChainIds').has(id)) {
+          if (!attribution) {
+            if (sponsorshipRequired)
+              rejectSponsorship({
+                chainId: id,
+                message: 'Sponsorship rejected.',
+                reason: 'api_key_required',
+              })
+            return false
+          }
+          if (!sponsorable) {
             if (sponsorshipRequired)
-              throw new RpcResponse.InvalidParamsError({ message: 'Sponsorship rejected.' })
+              failSponsorship({
+                chainId: id,
+                message: 'Sponsor route accepted an ineligible API key.',
+              })
+            return false
+          }
+          if (!c.get('supportedChainIds').has(id)) {
+            if (sponsorshipRequired)
+              rejectSponsorship({
+                chainId: id,
+                message: 'Sponsorship rejected.',
+                reason: 'chain_id_unsupported',
+              })
             return false
           }
           if (!Viem.isMainnet(id)) return true
@@ -126,7 +179,11 @@ function middleware(options: middleware.Options) {
           // it. Refuse here, or sandbox spend would sponsor mainnet unbilled.
           if (attribution.environment !== 'production') {
             if (sponsorshipRequired)
-              throw new RpcResponse.InvalidParamsError({ message: 'Sponsorship rejected.' })
+              rejectSponsorship({
+                chainId: id,
+                message: 'Sponsorship rejected.',
+                reason: 'production_api_key_required',
+              })
             return false
           }
 
@@ -141,17 +198,19 @@ function middleware(options: middleware.Options) {
           const billing = await Billing.status(db, attribution.orgId)
           if (billing === 'past_due') {
             if (sponsorshipRequired)
-              throw new RpcResponse.InvalidParamsError({
-                data: { code: 'billing_past_due' },
+              rejectSponsorship({
+                chainId: id,
                 message: 'Billing past due.',
+                reason: 'billing_past_due',
               })
             return 'billing_past_due'
           }
           if (billing !== 'active') {
             if (sponsorshipRequired)
-              throw new RpcResponse.InvalidParamsError({
-                data: { code: 'billing_required' },
+              rejectSponsorship({
+                chainId: id,
                 message: 'Billing required.',
+                reason: 'billing_required',
               })
             return 'billing_required'
           }
@@ -172,9 +231,10 @@ function middleware(options: middleware.Options) {
             verified.decimals !== Fees.tokenDecimals
           ) {
             if (sponsorshipRequired)
-              throw new RpcResponse.InvalidParamsError({
-                data: { code: 'fee_token_unsupported' },
+              rejectSponsorship({
+                chainId: id,
                 message: 'Fee token unsupported.',
+                reason: 'fee_token_unsupported',
               })
             return 'fee_token_unsupported'
           }
@@ -184,9 +244,10 @@ function middleware(options: middleware.Options) {
           const feeMax = Fees.maxOf(transaction)
           if (feeMax === undefined) {
             if (sponsorshipRequired)
-              throw new RpcResponse.InvalidParamsError({
-                data: { code: 'tx_fee_limit_exceeded' },
+              rejectSponsorship({
+                chainId: id,
                 message: 'Transaction fee limit exceeded.',
+                reason: 'tx_fee_limit_exceeded',
               })
             return 'tx_fee_limit_exceeded'
           }
@@ -198,9 +259,10 @@ function middleware(options: middleware.Options) {
           })()
           if (feeMax > cap) {
             if (sponsorshipRequired)
-              throw new RpcResponse.InvalidParamsError({
-                data: { code: 'tx_fee_limit_exceeded' },
+              rejectSponsorship({
+                chainId: id,
                 message: 'Transaction fee limit exceeded.',
+                reason: 'tx_fee_limit_exceeded',
               })
             return 'tx_fee_limit_exceeded'
           }
@@ -215,7 +277,10 @@ function middleware(options: middleware.Options) {
           // Defense in depth: `validate` already refuses non-production
           // mainnet, so reaching here with that pair is a wiring bug.
           if (mainnet && attribution.environment !== 'production')
-            throw new RpcResponse.InvalidParamsError({ message: 'Sponsorship rejected.' })
+            failSponsorship({
+              chainId: event.chainId,
+              message: 'Non-production key reached mainnet sponsorship recording.',
+            })
 
           // The cap recomputes from canonical envelope bytes, mirroring the
           // reconciliation convention; pending rows charge it to spend limits.
@@ -238,11 +303,11 @@ function middleware(options: middleware.Options) {
 
           const input = {
             apiKeyId: attribution.apiKeyId,
-            billable: attribution.environment === 'production',
+            billable: mainnet && attribution.environment === 'production',
             chainId: event.chainId,
             environment: attribution.environment,
             orgId: attribution.orgId,
-            projectId: attribution.projectId,
+            ...(attribution.projectId === undefined ? {} : { projectId: attribution.projectId }),
             signPayload: event.signPayload,
             transaction: event.transaction,
             ...(currency ? { currency } : {}),
@@ -262,9 +327,10 @@ function middleware(options: middleware.Options) {
             })
           } catch (error) {
             if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
-              throw new RpcResponse.InvalidParamsError({
-                data: { code: 'spend_limit_exceeded' },
+              rejectSponsorship({
+                chainId: event.chainId,
                 message: 'Spend limit exceeded.',
+                reason: 'spend_limit_exceeded',
               })
             throw error
           }
@@ -274,8 +340,15 @@ function middleware(options: middleware.Options) {
 
     const authorizeChainId = (chainId: number | undefined) => {
       const resolved = chainId ?? c.get('chainId')
-      if (!c.get('supportedChainIds').has(resolved))
+      if (!c.get('supportedChainIds').has(resolved)) {
+        if (sponsorshipRequired)
+          rejectSponsorship({
+            chainId: resolved,
+            message: 'Unsupported chain id.',
+            reason: 'chain_id_unsupported',
+          })
         throw new RpcResponse.InvalidParamsError({ message: 'Unsupported chain id.' })
+      }
       if (c.get('zones').has(resolved)) {
         const scopes = principal?.type === 'api_key' ? principal.apiKey.scopes : undefined
         const allowed =
@@ -283,9 +356,16 @@ function middleware(options: middleware.Options) {
           scopes?.includes(`zone:${resolved}:read`) ||
           zoneToken !== undefined
         if (allowed) return resolved
+        const message = `Chain id ${resolved} is a zone. Use an API key granting \`zone:${resolved}:read\`, or pass a Zone token via \`X-Authorization-Token\`.`
+        if (sponsorshipRequired)
+          rejectSponsorship({
+            chainId: resolved,
+            message,
+            reason: 'api_key_forbidden',
+          })
         throw new RpcResponse.InvalidParamsError({
           data: { code: 'api_key_forbidden' },
-          message: `Chain id ${resolved} is a zone. Use an API key granting \`zone:${resolved}:read\`, or pass a Zone token via \`X-Authorization-Token\`.`,
+          message,
         })
       }
       return resolved
@@ -300,7 +380,8 @@ function middleware(options: middleware.Options) {
       const client = Viem.getClient({
         chainId: resolved,
         principal,
-        rpc: { url: () => zone.forwardRpcUrl },
+        rpc: c.get('rpc'),
+        zone,
         zoneToken,
       })
       zoneClients.set(resolved, client)
@@ -312,6 +393,21 @@ function middleware(options: middleware.Options) {
       cache: c.get('store'),
       ...(options.features ? { features: options.features } : {}),
       getClient,
+      onRequest: async (request) => {
+        const method = sponsorshipMethod(request.method)
+        const params = 'params' in request && Array.isArray(request.params) ? request.params : []
+        const transaction = params[0]
+        requests.push({
+          id: rpcId('id' in request ? request.id : undefined),
+          ...(method === undefined ? {} : { method }),
+          ...(method !== undefined &&
+          requests.length === 0 &&
+          method !== 'eth_fillTransaction' &&
+          Hex.validate(transaction, { strict: true })
+            ? { payloadHash: Hash.keccak256(transaction) }
+            : {}),
+        })
+      },
       path: Path.join(c.get('basePath'), options.path),
       ...(feePayer ? { feePayer } : {}),
       ...(verifiedTokens
@@ -330,11 +426,107 @@ function middleware(options: middleware.Options) {
       .catch(() => undefined)
     const rpc = Log.rpcErrors(body)
     if (rpc) c.set('rpcResponse', rpc)
+    if (rejections > 0) {
+      const matched = rejectionDiagnostics({
+        body,
+        reasons,
+        requests,
+      })
+      // Capability-form fill refusals are successful JSON-RPC responses, so
+      // only a non-batch request can be attributed without error matching.
+      const rejected =
+        matched.length === 0 && !Array.isArray(body) && requests.length === 1 ? requests : matched
+      const methods = new Set(rejected.map((request) => request.method))
+      const method = methods.size === 1 ? rejected[0]?.method : undefined
+      const payloadHash =
+        !Array.isArray(body) && rejected.length === 1 ? rejected[0]?.payloadHash : undefined
+      c.set('sponsorship', {
+        ...(chainId === null || chainId === undefined ? {} : { chainId }),
+        ...(internalErrors === 0 ? {} : { internalErrors }),
+        ...(method === undefined ? {} : { method }),
+        outcome: 'rejected',
+        ...(payloadHash === undefined ? {} : { payloadHash }),
+        ...(reason === null || reason === undefined ? {} : { reason }),
+        rejections,
+      })
+    }
     return response
   })
 }
 
+function rejectionDiagnostics(options: rejectionDiagnostics.Options) {
+  const requests = new Map<rejectionDiagnostics.Id, rejectionDiagnostics.Request | null>()
+  for (const request of options.requests) {
+    if (requests.has(request.id)) requests.set(request.id, null)
+    else requests.set(request.id, request)
+  }
+  const responses = Array.isArray(options.body) ? options.body : [options.body]
+  return responses.flatMap((response) => {
+    if (!response || typeof response !== 'object' || Array.isArray(response)) return []
+    const record = response as Record<string, unknown>
+    if (record['jsonrpc'] !== '2.0') return []
+    const error = record['error']
+    if (!error || typeof error !== 'object' || Array.isArray(error)) return []
+    const data = (error as Record<string, unknown>)['data']
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return []
+    const code = (data as Record<string, unknown>)['code']
+    if (typeof code !== 'string' || !options.reasons.has(code as Log.SponsorshipReason)) return []
+    const request = requests.get(rpcId(record['id']))
+    return request?.method === undefined ? [] : [request]
+  })
+}
+
+declare namespace rejectionDiagnostics {
+  /** JSON-RPC request id used only for request-response matching. */
+  type Id = number | string | null | undefined
+
+  /** Inputs for matching request metadata to sponsorship rejection responses. */
+  type Options = {
+    /** Parsed single or batch JSON-RPC response. */
+    body: unknown
+    /** Sponsorship codes recorded while handling the request. */
+    reasons: ReadonlySet<Log.SponsorshipReason>
+    /** Bounded request metadata in request order. */
+    requests: readonly Request[]
+  }
+
+  /** Bounded metadata for one valid JSON-RPC request. */
+  type Request = {
+    /** JSON-RPC request id, retained only for response matching. */
+    id: Id
+    /** Sponsorship-capable JSON-RPC method. */
+    method?: Log.SponsorshipMethod | undefined
+    /** Raw transaction hash, captured only for the first valid request. */
+    payloadHash?: Hex.Hex | undefined
+  }
+}
+
+function rpcId(value: unknown): rejectionDiagnostics.Id {
+  if (typeof value === 'number' || typeof value === 'string' || value === null) return value
+  return undefined
+}
+
+function sponsorshipMethod(value: unknown): Log.SponsorshipMethod | undefined {
+  switch (value) {
+    case 'eth_fillTransaction':
+    case 'eth_sendRawTransaction':
+    case 'eth_sendRawTransactionSync':
+    case 'eth_signRawTransaction':
+      return value
+    default:
+      return undefined
+  }
+}
+
 declare namespace middleware {
+  /** One invariant sponsorship failure. */
+  type Failure = {
+    /** Candidate transaction chain. */
+    chainId: number
+    /** Internal error message hidden from the client. */
+    message: string
+  }
+
   /** Internal relay mount configuration. */
   type Options = relay.Options & {
     /** Optional wallet feature bundle. */
@@ -342,4 +534,22 @@ declare namespace middleware {
     /** RPC mount path. */
     path: 'rpc/relay' | 'rpc/sponsor'
   }
+
+  /** One sponsorship rejection recorded for request logging. */
+  type Rejection = {
+    /** Candidate transaction chain, validated before it enters the log entry. */
+    chainId: number
+    /** Stable client error code. */
+    reason: Log.SponsorshipReason
+  }
+
+  /** One client-visible sponsorship refusal. */
+  type Refusal = {
+    /** Candidate transaction chain. */
+    chainId: number
+    /** Client-safe error message. */
+    message: string
+    /** Stable client error code. */
+    reason: Exclude<Log.SponsorshipReason, 'internal_error'>
+  }
 }

package/src/apps/relay/Sponsorships.test.ts

@@ -4,6 +4,7 @@ import type { Client } from 'viem'
 
 import * as Runtime from '../../../test/runtime.js'
 import * as Db from '../../db/Db.js'
+import * as Organizations from '../../db/tables/organizations.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Sponsorships from './Sponsorships.js'
 
@@ -41,6 +42,7 @@ describe('finalize', () => {
     })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "failed": 0,
         "finalized": 1,
         "pending": 0,
@@ -62,6 +64,7 @@ describe('finalize', () => {
     const result = await Sponsorships.finalize(db, { getClient: () => client({}) })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "failed": 0,
         "finalized": 0,
         "pending": 1,
@@ -87,6 +90,7 @@ describe('finalize', () => {
     })
     expect(young).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "failed": 0,
         "finalized": 0,
         "pending": 1,
@@ -102,6 +106,7 @@ describe('finalize', () => {
     })
     expect(settled).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "failed": 1,
         "finalized": 0,
         "pending": 0,
@@ -124,6 +129,7 @@ describe('finalize', () => {
     })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "failed": 1,
         "finalized": 0,
         "pending": 0,
@@ -151,6 +157,7 @@ describe('finalize', () => {
     })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 1,
         "failed": 0,
         "finalized": 0,
         "pending": 1,
@@ -178,6 +185,7 @@ describe('finalize', () => {
     })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 1,
         "failed": 1,
         "finalized": 0,
         "pending": 0,
@@ -206,6 +214,7 @@ describe('finalize', () => {
     })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "failed": 0,
         "finalized": 1,
         "pending": 0,
@@ -256,6 +265,7 @@ describe('reconcile', () => {
     })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "matched": 1,
         "scanned": 1,
       }
@@ -269,6 +279,7 @@ describe('reconcile', () => {
   test('behavior: recovers recently failed intents by sign payload', async () => {
     const db = create()
     await db.migrate()
+    await Organizations.create(db, { id: 'org_1', name: 'One' })
     const { transactionHash: _, ...rest } = input
     const intent = await SponsoredTransactions.upsert(db, { ...rest, signPayload })
     await SponsoredTransactions.fail(db, intent.id, '2026-01-01T00:00:00.000Z')
@@ -287,6 +298,7 @@ describe('reconcile', () => {
     })()
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "matched": 1,
         "scanned": 1,
       }
@@ -298,6 +310,43 @@ describe('reconcile', () => {
     await db.close()
   })
 
+  test('behavior: spend-limit refusals are not operational errors', async () => {
+    const db = create()
+    await db.migrate()
+    await Organizations.create(db, { id: 'org_1', name: 'One' })
+    const { transactionHash: _, ...rest } = input
+    const intent = await SponsoredTransactions.upsert(db, { ...rest, signPayload })
+    await SponsoredTransactions.fail(db, intent.id, '2026-01-01T00:00:00.000Z')
+
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:01:00.000Z') })
+    const result = await (async () => {
+      try {
+        return await Sponsorships.reconcile(db, {
+          feePayer: '0xFee0000000000000000000000000000000000000',
+          getClient: () => rpc,
+          getTidx: () => tidx([{ from: sender, hash: minedHash }]),
+          limitFor: async () => ({
+            chainIds: [42431],
+            max: -1n,
+            since: '2025-01-01T00:00:00.000Z',
+          }),
+        })
+      } finally {
+        vi.useRealTimers()
+      }
+    })()
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "errors": 0,
+        "matched": 0,
+        "scanned": 1,
+      }
+    `)
+    expect((await SponsoredTransactions.get(db, intent.id))?.transactionHash).toBeNull()
+    await db.close()
+  })
+
   test('behavior: unmatched candidates leave intents pending', async () => {
     const db = create()
     await db.migrate()
@@ -311,6 +360,7 @@ describe('reconcile', () => {
     })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 0,
         "matched": 0,
         "scanned": 1,
       }
@@ -365,6 +415,7 @@ describe('reconcile', () => {
     })
     expect(result).toMatchInlineSnapshot(`
       {
+        "errors": 1,
         "matched": 0,
         "scanned": 0,
       }

package/src/apps/relay/Sponsorships.ts

@@ -38,7 +38,7 @@ export async function finalize(db: Db.Db, options: finalize.Options): Promise<fi
   } = options
 
   const rows = await SponsoredTransactions.listPending(db, { limit: batchSize })
-  const result = { failed: 0, finalized: 0, pending: 0 }
+  const result = { errors: 0, failed: 0, finalized: 0, pending: 0 }
 
   for (const row of rows) {
     // Fill intents carry no hash until reconciliation matches them on-chain;
@@ -60,6 +60,7 @@ export async function finalize(db: Db.Db, options: finalize.Options): Promise<fi
       // Unmined transactions surface as a typed not-found; let the TTL decide.
       if (error instanceof TransactionReceiptNotFoundError) receipt = null
       else {
+        result.errors++
         if (Date.parse(row.createdAt) + receiptErrorTtlMs <= now().getTime()) {
           await SponsoredTransactions.fail(db, row.id, now().toISOString())
           result.failed++
@@ -102,6 +103,8 @@ export declare namespace finalize {
 
   /** Counters returned by one finalization pass. */
   type Result = {
+    /** Receipt lookup errors that prevented finalization work. */
+    errors: number
     /** Rows marked failed (unmined past the pending TTL). */
     failed: number
     /** Rows finalized with an actual fee. */
@@ -126,7 +129,7 @@ export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<
   const {
     batchSize = 100,
     candidateCap = 500,
-    failedIntentTtlMs = 86_400_000,
+    failedIntentTtlMs = SponsoredTransactions.failedIntentRecoveryTtlMs,
     feePayer,
     getClient,
     getTidx,
@@ -137,7 +140,7 @@ export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<
     failedSince: new Date(Date.now() - failedIntentTtlMs).toISOString(),
     limit: batchSize,
   })
-  const result = { matched: 0, scanned: 0 }
+  const result = { errors: 0, matched: 0, scanned: 0 }
   if (intents.length === 0) return result
 
   const chains = new Map<number, SponsoredTransactions.Record[]>()
@@ -161,6 +164,7 @@ export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<
       candidates = fetched.rows
     } catch {
       // Indexer outage must not fail intents; retry on the next pass.
+      result.errors++
       continue
     }
 
@@ -187,8 +191,10 @@ export async function reconcile(db: Db.Db, options: reconcile.Options): Promise<
         )
         bySignPayload.delete(signPayload)
         result.matched++
-      } catch {
-        // Unresolvable candidate (lookup error, malformed envelope): skip it.
+      } catch (error) {
+        // Spend-limit enforcement is an expected policy refusal; dependency,
+        // lookup, and malformed-envelope failures remain operational errors.
+        if (!(error instanceof SponsoredTransactions.PeriodSpendLimitError)) result.errors++
       }
     }
   }
@@ -223,6 +229,8 @@ export declare namespace reconcile {
 
   /** Counters returned by one reconciliation pass. */
   type Result = {
+    /** Dependency or candidate errors that prevented reconciliation work. */
+    errors: number
     /** Intents matched to an on-chain transaction. */
     matched: number
     /** On-chain candidates inspected. */
@@ -294,14 +302,18 @@ export function createFinalizer(options: createFinalizer.Options): createFinaliz
                 }
               },
             })
-          : { matched: 0, scanned: 0 }
+          : { errors: 0, matched: 0, scanned: 0 }
       const finalized = await finalize(db, {
         batchSize: options.batchSize,
         getClient,
         now: options.now,
         pendingTtlMs: options.pendingTtlMs,
       })
-      return { ...finalized, ...reconciled }
+      return {
+        ...finalized,
+        ...reconciled,
+        errors: finalized.errors + reconciled.errors,
+      }
     },
   }
 }