tapimo 0.14.0 → 0.15.0

package/src/apps/relay/App.ts

@@ -9,22 +9,29 @@ import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
 import * as Organizations from '../../db/tables/organizations.js'
 import * as Projects from '../../db/tables/projects.js'
+import * as SponsorshipAttributions from '../../db/tables/sponsorshipAttributions.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Fees from '../../internal/Fees.js'
 import * as Log from '../../internal/Log.js'
 import * as Billing from '../management/Billing.js'
+import * as Zones from '../Zones.js'
 import * as Handler from '../../Handler.js'
 import * as Auth from '../../internal/Auth.js'
 import * as OpenApi from '../../internal/OpenApi.js'
 import * as Path from '../../internal/Path.js'
 import * as VerifiedTokens from '../../internal/VerifiedTokens.js'
 import * as Viem from '../../internal/Viem.js'
+import * as ZoneRpc from '../../internal/ZoneRpc.js'
+import * as Utils from '../../handlers/internal/utils.js'
+import * as Sponsorship from '../../handlers/internal/sponsorship.js'
 import * as Scope from '../../Scope.js'
 
 /**
  * The relay route group exposes wallet features at `/rpc/relay` and fee
  * sponsorship at `/rpc/sponsor`. Mount it after `data()`, which publishes the
  * verified-token and zone context used by relay handlers.
+ * Successful managed sponsorships include the transaction's immutable
+ * `sponsorship_details.subsidized` value.
  *
  * ```ts
  * App.create(options).route('/', data()).route('/', relay())
@@ -87,7 +94,6 @@ function middleware(options: middleware.Options) {
     : 0n
   return createMiddleware<App.Environment>(async (c) => {
     const principal = Auth.getPrincipal(c)
-    const requestedAt = new Date().toISOString()
     const verifiedTokens = c.get('verifiedTokens')
     const zoneToken_header = c.req.header(ZoneRpcAuthentication.headerName)
     const zoneToken = zoneToken_header?.trim() ? zoneToken_header : undefined
@@ -131,6 +137,10 @@ function middleware(options: middleware.Options) {
     const feePayer = await (async () => {
       if (!options.feePayer) return undefined
       const resolved = await resolveAttribution(Db.get(c.get('db')), {
+        // The canonical header wins when Privy also sends its legacy header.
+        externalId:
+          c.req.header('tempo-attribution-id')?.trim() ||
+          c.req.header('x-tempo-attribution-key')?.trim(),
         principal,
         projectId: c.req.header('tempo-project-id')?.trim(),
       })
@@ -141,36 +151,6 @@ function middleware(options: middleware.Options) {
         principal?.type === 'api_key' &&
         (principal.apiKey.scopes.includes('rpc-relay:sponsor') ||
           principal.apiKey.scopes.includes(Scope.wildcard))
-      let promotionState_promise: Promise<middleware.PromotionState>
-      const promotionState = () =>
-        (promotionState_promise ??= (async () => {
-          if (!attribution) return { status: 'inactive' }
-          const db = Db.get(c.get('db'))
-          const organization = await Organizations.get(db, attribution.orgId)
-          if (!organization || organization.sponsorshipSubsidyDurationDays === null)
-            return { status: 'inactive' }
-          // Missing project attribution opts out of the subsidy but must not interrupt sponsorship.
-          if (!attribution.projectId) return { status: 'inactive' }
-          const project = await Projects.get(db, attribution.projectId)
-          if (!project) return { message: 'Attributed project disappeared.', status: 'error' }
-          if (project.orgId !== attribution.orgId)
-            return { message: 'Attributed project changed ownership.', status: 'error' }
-          if (
-            (project.sponsorshipSubsidyStartsAt === null) !==
-            (project.sponsorshipSubsidyEndsAt === null)
-          )
-            return { message: 'Project promotion window is inconsistent.', status: 'error' }
-          if (
-            project.sponsorshipSubsidyEndsAt !== null &&
-            Date.parse(requestedAt) >= Date.parse(project.sponsorshipSubsidyEndsAt)
-          )
-            return { status: 'inactive' }
-          return { status: 'active' }
-        })())
-      const validatePromotion = async (chainId: number) => {
-        const state = await promotionState()
-        if (state.status === 'error') failSponsorship({ chainId, message: state.message })
-      }
       // Lifted so validation and the sponsored-token default read one value.
       const feeToken_sponsor = options.feePayer.feeToken ?? Addresses.pathUsd
       return {
@@ -184,7 +164,7 @@ function middleware(options: middleware.Options) {
           if (attributionError)
             rejectSponsorship({
               chainId: id,
-              message: 'Project attribution rejected.',
+              message: 'Attribution rejected.',
               reason: attributionError,
             })
           if (!attribution) {
@@ -213,7 +193,7 @@ function middleware(options: middleware.Options) {
               })
             return false
           }
-          if (!Viem.isMainnet(id)) return true
+          if (!Viem.isMainnet(c.get('zones').get(id)?.sourceId ?? id)) return true
           // Mainnet is production-only: a sandbox key resolves chainId from the
           // request body, so the auth-layer sandbox/mainnet guard never sees
           // it. Refuse here, or sandbox spend would sponsor mainnet unbilled.
@@ -248,8 +228,6 @@ function middleware(options: middleware.Options) {
               })
             return 'billing_required'
           }
-          await validatePromotion(id)
-
           const feeToken = (() => {
             try {
               return TokenId.toAddress(transaction.feeToken ?? feeToken_sponsor)
@@ -308,7 +286,9 @@ function middleware(options: middleware.Options) {
         },
         onSponsored: async (event) => {
           if (!attribution) return
-          const mainnet = Viem.isMainnet(event.chainId)
+          const mainnet = Viem.isMainnet(
+            c.get('zones').get(event.chainId)?.sourceId ?? event.chainId,
+          )
           // Defense in depth: `validate` already refuses non-production
           // mainnet, so reaching here with that pair is a wiring bug.
           if (mainnet && attribution.environment !== 'production')
@@ -321,6 +301,18 @@ function middleware(options: middleware.Options) {
           // reconciliation convention; pending rows charge it to spend limits.
           const feeMax = Fees.maxOf(Transaction.deserialize(event.transaction as `0x76${string}`))
           const db = Db.get(c.get('db'))
+          const resolvedAttribution =
+            mainnet && attribution.environment === 'production'
+              ? await resolveSponsorshipAttribution(db, attribution)
+              : undefined
+          const sponsorshipAttribution = (() => {
+            if (resolvedAttribution !== 'project_id_invalid') return resolvedAttribution
+            return rejectSponsorship({
+              chainId: event.chainId,
+              message: 'Attribution rejected.',
+              reason: 'project_id_invalid',
+            })
+          })()
           const feeToken = (() => {
             try {
               return event.feeToken !== undefined ? TokenId.toAddress(event.feeToken) : undefined
@@ -337,6 +329,9 @@ function middleware(options: middleware.Options) {
 
           const input = {
             apiKeyId: attribution.apiKeyId,
+            ...(sponsorshipAttribution === undefined
+              ? {}
+              : { sponsorshipAttributionId: sponsorshipAttribution.id }),
             billable: mainnet && attribution.environment === 'production',
             chainId: event.chainId,
             environment: attribution.environment,
@@ -356,51 +351,54 @@ function middleware(options: middleware.Options) {
             settings?.spendLimit == null
               ? undefined
               : {
-                  chainIds: [Viem.chainId.mainnet],
+                  chainIds: Zones.chainIds({
+                    sourceId: Viem.chainId.mainnet,
+                    zones: c.get('zones').values(),
+                  }),
                   max: Billing.toBaseUnits(settings.spendLimit),
                   since: Billing.periodStart(settings.period),
                 }
-          if (
-            mainnet &&
-            attribution.environment === 'production' &&
-            attribution.projectId !== undefined
-          )
-            try {
+          try {
+            if (
+              mainnet &&
+              attribution.environment === 'production' &&
+              sponsorshipAttribution !== undefined
+            ) {
               const promotion = await SponsoredTransactions.reservePromotion(
                 db,
-                { ...input, billable: false },
+                {
+                  ...input,
+                  billable: false,
+                  sponsorshipAttributionId: sponsorshipAttribution.id,
+                },
                 {
                   at: new Date().toISOString(),
                   ...(billingLimit ? { billingLimit } : {}),
-                  chainIds: [Viem.chainId.mainnet],
-                  projectId: attribution.projectId,
+                  chainIds: Zones.chainIds({
+                    sourceId: Viem.chainId.mainnet,
+                    zones: c.get('zones').values(),
+                  }),
                 },
               )
-              if (promotion.status !== 'ineligible') return
-            } catch (error) {
-              if (error instanceof SponsoredTransactions.AttributionConflictError)
-                rejectSponsorship({
-                  chainId: event.chainId,
-                  message: 'Project attribution rejected.',
-                  reason: 'project_id_invalid',
-                })
-              if (error instanceof SponsoredTransactions.PromotionActivationError)
-                failSponsorship({
-                  chainId: event.chainId,
-                  message: 'Project promotion activation failed.',
-                })
-              if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
-                rejectSponsorship({
-                  chainId: event.chainId,
-                  message: 'Spend limit exceeded.',
-                  reason: 'spend_limit_exceeded',
-                })
-              throw error
+              if (promotion.status !== 'ineligible')
+                return { subsidized: !promotion.record.billable }
             }
-          if (!billingLimit) return void (await SponsoredTransactions.upsert(db, input))
-          try {
-            await SponsoredTransactions.reserve(db, input, billingLimit)
+            const record = !billingLimit
+              ? await SponsoredTransactions.upsert(db, input)
+              : await SponsoredTransactions.reserve(db, input, billingLimit)
+            return { subsidized: !record.billable }
           } catch (error) {
+            if (error instanceof SponsoredTransactions.AttributionConflictError)
+              rejectSponsorship({
+                chainId: event.chainId,
+                message: 'Attribution rejected.',
+                reason: attribution.externalId ? 'attribution_id_invalid' : 'project_id_invalid',
+              })
+            if (error instanceof SponsoredTransactions.PromotionActivationError)
+              failSponsorship({
+                chainId: event.chainId,
+                message: 'Attribution promotion activation failed.',
+              })
             if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
               rejectSponsorship({
                 chainId: event.chainId,
@@ -472,6 +470,35 @@ function middleware(options: middleware.Options) {
         const method = sponsorshipMethod(request.method)
         const params = 'params' in request && Array.isArray(request.params) ? request.params : []
         const transaction = params[0]
+        const chainId_body =
+          transaction && typeof transaction === 'object' && 'chainId' in transaction
+            ? Utils.resolveChainId(transaction.chainId)
+            : undefined
+        const chainId =
+          Utils.resolveChainId(c.req.param('chainId')) ?? chainId_body ?? c.get('chainId')
+        // Only explicit fee-payer requests stay local; other raw-sign payloads would reach node-managed signing.
+        const rawSponsorship =
+          request.method === 'eth_signRawTransaction' &&
+          Hex.validate(transaction, { strict: true }) &&
+          (() => {
+            try {
+              return Sponsorship.requestsRawSponsorship(transaction)
+            } catch {
+              return false
+            }
+          })()
+        if (
+          zoneToken &&
+          c.get('zones').has(chainId) &&
+          !ZoneRpc.readMethods.has(request.method) &&
+          !ZoneRpc.writeMethods.has(request.method) &&
+          !ZoneRpc.tokenMethods.has(request.method) &&
+          !rawSponsorship
+        )
+          throw new RpcResponse.MethodNotSupportedError({
+            data: { code: 'api_key_forbidden' },
+            message: 'Method is not permitted for Zone RPC.',
+          })
         requests.push({
           id: rpcId('id' in request ? request.id : undefined),
           ...(method === undefined ? {} : { method }),
@@ -593,7 +620,7 @@ function sponsorshipMethod(value: unknown): Log.SponsorshipMethod | undefined {
   }
 }
 
-/** Resolves optional request-level project attribution within the API key's organization. */
+/** Resolves request attribution within the authenticated API key's organization. */
 async function resolveAttribution(
   db: Db.Db,
   options: resolveAttribution.Options,
@@ -606,17 +633,58 @@ async function resolveAttribution(
     orgId: principal.orgId,
     ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
   }
-  if (!options.projectId) return { attribution }
-  if (principal.projectId !== undefined) return { attribution, error: 'project_id_invalid' }
-  const project = await Projects.get(db, options.projectId)
-  if (!project || project.orgId !== principal.orgId)
-    return { attribution, error: 'project_id_invalid' }
-  return { attribution: { ...attribution, projectId: project.id } }
+  if (options.externalId && options.externalId.length > 128)
+    return { attribution, error: 'attribution_id_invalid' }
+  const projectId = await (async () => {
+    if (!options.projectId) return principal.projectId
+    if (principal.projectId !== undefined) return undefined
+    const project = await Projects.get(db, options.projectId)
+    if (!project || project.orgId !== principal.orgId) return undefined
+    return project.id
+  })()
+  if (options.projectId && !projectId) return { attribution, error: 'project_id_invalid' }
+  return {
+    attribution: {
+      ...attribution,
+      ...(options.externalId ? { externalId: options.externalId } : {}),
+      ...(projectId ? { projectId } : {}),
+    },
+  }
+}
+
+/** Resolves promotion attribution only for an authorized sponsored transaction. */
+async function resolveSponsorshipAttribution(
+  db: Db.Db,
+  attribution: resolveAttribution.Attribution,
+): Promise<SponsorshipAttributions.Record | 'project_id_invalid' | undefined> {
+  const projectId = attribution.projectId
+  if (!attribution.externalId && !projectId) return undefined
+  const [billing, organization] = await Promise.all([
+    Billing.status(db, attribution.orgId),
+    Organizations.get(db, attribution.orgId),
+  ])
+  if (!organization || billing !== 'active' || organization.sponsorshipSubsidyDurationDays === null)
+    return undefined
+  // Caller-selected headers may select existing promotions, but must never create fresh budgets.
+  if (attribution.externalId)
+    return SponsorshipAttributions.getExternal(db, {
+      externalId: attribution.externalId,
+      orgId: attribution.orgId,
+    })
+  if (!projectId) return undefined
+  const project = await Projects.get(db, projectId)
+  if (!project || project.orgId !== attribution.orgId) return 'project_id_invalid'
+  return SponsorshipAttributions.resolveProject(db, {
+    orgId: attribution.orgId,
+    projectId,
+  })
 }
 
 declare namespace resolveAttribution {
   /** Inputs for resolving API-key project attribution. */
   type Options = {
+    /** Optional external partner attribution id supplied by the caller. */
+    externalId?: string | undefined
     /** Authenticated request principal. */
     principal: Auth.Principal | null
     /** Optional project id supplied by the caller. */
@@ -629,6 +697,8 @@ declare namespace resolveAttribution {
     apiKeyId: string
     /** API key environment. */
     environment: 'production' | 'sandbox'
+    /** External partner attribution id supplied by the caller. */
+    externalId?: string | undefined
     /** API key organization id. */
     orgId: string
     /** Attributed project id. */
@@ -639,8 +709,8 @@ declare namespace resolveAttribution {
   type Result = {
     /** Attribution retained for request diagnostics. */
     attribution: Attribution
-    /** Project attribution error detected before transaction validation. */
-    error?: 'project_id_invalid' | undefined
+    /** Attribution error detected before transaction validation. */
+    error?: 'attribution_id_invalid' | 'project_id_invalid' | undefined
   }
 }
 
@@ -661,9 +731,6 @@ declare namespace middleware {
     path: 'rpc/relay' | 'rpc/sponsor'
   }
 
-  /** Cached promotion validation state; request accounting is applied per batch item. */
-  type PromotionState = { status: 'active' | 'inactive' } | { message: string; status: 'error' }
-
   /** One sponsorship rejection recorded for request logging. */
   type Rejection = {
     /** Candidate transaction chain, validated before it enters the log entry. */

package/src/apps/relay/App.zone-billing.test.ts

@@ -0,0 +1,257 @@
+import { Transaction } from 'viem/tempo'
+
+import * as TestApp from '../../../test/App.js'
+import * as Tempo from '../../../test/Tempo.js'
+import * as BillingSettings from '../../db/tables/billingSettings.js'
+import * as Organizations from '../../db/tables/organizations.js'
+import * as SponsorshipAttributions from '../../db/tables/sponsorshipAttributions.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
+import type * as Log from '../../internal/Log.js'
+import * as VerifiedTokens from '../../internal/VerifiedTokens.js'
+import * as Viem from '../../internal/Viem.js'
+
+const chainId = 8001
+const siblingChainId = 8002
+const feeToken = '0x20c0000000000000000000000000000000000000'
+const token = {
+  address: feeToken,
+  currency: 'USD',
+  decimals: 6,
+  name: 'Path USD',
+  symbol: 'pathUSD',
+} satisfies VerifiedTokens.Token
+
+describe('Zone sponsorship billing', () => {
+  test.each(['sandbox', 'sandbox_wildcard'])('confines the %s key to testnet', async (apiKey) => {
+    const { app, db, entries } = await setup()
+    await StripeCustomers.setStatus(db, 'org_zone', 'active')
+    const body = await sponsor(app, { apiKey })
+    expect(body.error).toMatchInlineSnapshot(`
+      {
+        "code": -32602,
+        "data": {
+          "code": "production_api_key_required",
+        },
+        "message": "Sponsorship rejected.",
+      }
+    `)
+    expect(entries[0]?.sponsorship?.reason).toBe('production_api_key_required')
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test.each(['none', 'past_due'] as const)(
+    'requires active billing when status is %s',
+    async (status) => {
+      const { app, db, entries } = await setup()
+      await StripeCustomers.setStatus(db, 'org_zone', status)
+      const body = await sponsor(app)
+      const code = status === 'past_due' ? 'billing_past_due' : 'billing_required'
+      expect(body.error?.data).toEqual({ code })
+      expect(entries[0]?.sponsorship?.reason).toBe(code)
+      expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+    },
+  )
+
+  test('records the Zone id and billable USD spend with active billing', async () => {
+    const { app, db } = await setup()
+    await StripeCustomers.setStatus(db, 'org_zone', 'active')
+    const body = await sponsor(app)
+    expect(body.error).toBeUndefined()
+    expect(Transaction.deserialize(body.result!).feePayerSignature).toBeDefined()
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row).toMatchObject({
+      billable: true,
+      chainId,
+      currency: 'usd',
+      environment: 'production',
+      feeMax: '500000',
+      feeToken,
+      orgId: 'org_zone',
+    })
+  })
+
+  test.each([undefined, { ...token, currency: 'EUR' }, { ...token, decimals: 18 }])(
+    'rejects an unsupported Zone fee token %j',
+    async (verified) => {
+      const { app, db, entries } = await setup()
+      await StripeCustomers.setStatus(db, 'org_zone', 'active')
+      await VerifiedTokens.replace(db, chainId, verified ? [verified] : [])
+      const body = await sponsor(app)
+      expect(body.error?.data).toEqual({ code: 'fee_token_unsupported' })
+      expect(entries[0]?.sponsorship?.reason).toBe('fee_token_unsupported')
+      expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+    },
+  )
+
+  test.each([
+    { maxFeePerGas: 500_000_000_000n, txFeeLimit: '0.10' },
+    { maxFeePerGas: 2_000_000_000_000n, txFeeLimit: '999999' },
+  ])('enforces the lower fee cap for $txFeeLimit', async ({ maxFeePerGas, txFeeLimit }) => {
+    const { app, db, entries } = await setup()
+    await StripeCustomers.setStatus(db, 'org_zone', 'active')
+    await BillingSettings.upsert(db, { orgId: 'org_zone', txFeeLimit })
+    const body = await sponsor(app, { maxFeePerGas })
+    expect(body.error?.data).toEqual({ code: 'tx_fee_limit_exceeded' })
+    expect(entries[0]?.sponsorship?.reason).toBe('tx_fee_limit_exceeded')
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test.each([Viem.chainId.mainnet, chainId, siblingChainId])(
+    'counts existing chain %i spend before sponsoring the Zone',
+    async (existingChainId) => {
+      const { app, db, entries } = await setup()
+      await StripeCustomers.setStatus(db, 'org_zone', 'active')
+      await BillingSettings.upsert(db, { orgId: 'org_zone', spendLimit: '1' })
+      await SponsoredTransactions.upsert(db, {
+        apiKeyId: 'key_existing',
+        billable: true,
+        chainId: existingChainId,
+        environment: 'production',
+        feeMax: '900000',
+        orgId: 'org_zone',
+        signPayload: `0x${'ab'.repeat(32)}`,
+        transaction: `0x${'cd'.repeat(32)}`,
+      })
+      const body = await sponsor(app)
+      expect(body.error?.data).toEqual({ code: 'spend_limit_exceeded' })
+      expect(entries[0]?.sponsorship?.reason).toBe('spend_limit_exceeded')
+      expect(await SponsoredTransactions.listPending(db)).toHaveLength(1)
+
+      await BillingSettings.upsert(db, { orgId: 'org_zone', spendLimit: '2' })
+      expect((await sponsor(app)).error).toBeUndefined()
+      expect(await SponsoredTransactions.listPending(db)).toHaveLength(2)
+    },
+  )
+
+  test('counts Zone spend against the shared attribution promotion', async () => {
+    const { app, db } = await setup()
+    await StripeCustomers.setStatus(db, 'org_zone', 'active')
+    await Organizations.create(db, { id: 'org_zone', name: 'Zone' })
+    await Organizations.setSponsorshipSubsidy(db, 'org_zone', {
+      attributionSpendLimit: '0.75',
+      durationDays: 90,
+    })
+    await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'account',
+      orgId: 'org_zone',
+    })
+    expect((await sponsor(app, { externalId: 'account', nonce: 0 })).error).toBeUndefined()
+    expect(
+      (await sponsor(app, { chainId: siblingChainId, externalId: 'account', nonce: 1 })).error,
+    ).toBeUndefined()
+    const rows = await SponsoredTransactions.listPending(db)
+    expect(rows.find((row) => row.chainId === chainId)?.billable).toBe(false)
+    expect(rows.find((row) => row.chainId === siblingChainId)?.billable).toBe(true)
+  })
+
+  test('keeps sandbox sponsorship on a testnet-backed Zone non-billable', async () => {
+    const { app, db } = await setup({ sourceId: Viem.chainId.testnet })
+    const body = await sponsor(app, { apiKey: 'sandbox' })
+    expect(body.error).toBeUndefined()
+    expect(await SponsoredTransactions.listPending(db)).toMatchObject([
+      { billable: false, chainId, environment: 'sandbox' },
+    ])
+  })
+})
+
+async function setup(options: setup.Options = {}) {
+  const db = TestApp.database()
+  const entries: Log.Entry[] = []
+  const zones = [chainId, siblingChainId].map((id) =>
+    TestApp.zone({
+      chainId: id,
+      rpcUrl: 'https://zone.example',
+      sourceChainId: options.sourceId ?? Viem.chainId.mainnet,
+    }),
+  )
+  for (const id of [chainId, siblingChainId]) await VerifiedTokens.replace(db, id, [token])
+  await StripeCustomers.create(db, { orgId: 'org_zone', stripeCustomerId: 'cus_zone' })
+  const app = TestApp.create({
+    auth: {
+      keys: [
+        {
+          environment: 'production',
+          id: 'key_production',
+          orgId: 'org_zone',
+          scopes: ['rpc-relay:sponsor', `zone:${chainId}:read`, `zone:${siblingChainId}:read`],
+          token: 'production',
+        },
+        {
+          environment: 'sandbox',
+          id: 'key_sandbox',
+          orgId: 'org_zone',
+          scopes: ['rpc-relay:sponsor', `zone:${chainId}:read`],
+          token: 'sandbox',
+        },
+        {
+          environment: 'sandbox',
+          id: 'key_sandbox_wildcard',
+          orgId: 'org_zone',
+          scopes: ['*'],
+          token: 'sandbox_wildcard',
+        },
+      ],
+    },
+    db,
+    logger: (entry) => void entries.push(entry),
+    relay: { feePayer: { account: Tempo.accounts[10]!, feeToken } },
+    zones,
+  })
+  return { app, db, entries }
+}
+
+declare namespace setup {
+  /** Configured parent chain for the Zone fixtures. */
+  type Options = {
+    /** Parent Tempo chain id. */
+    sourceId?: Viem.ChainId | undefined
+  }
+}
+
+async function sponsor(app: ReturnType<typeof TestApp.create>, options: sponsor.Options = {}) {
+  const transaction = await Tempo.accounts[9]!.signTransaction({
+    chainId: options.chainId ?? chainId,
+    feePayer: true,
+    gas: 1_000_000n,
+    maxFeePerGas: options.maxFeePerGas ?? 500_000_000_000n,
+    maxPriorityFeePerGas: 0n,
+    nonce: options.nonce ?? 0,
+    to: Tempo.accounts[8]!.address,
+    value: 0n,
+  })
+  const response = await app.request('/rpc/sponsor', {
+    body: JSON.stringify({
+      id: 1,
+      jsonrpc: '2.0',
+      method: 'eth_signRawTransaction',
+      params: [transaction],
+    }),
+    headers: {
+      'content-type': 'application/json',
+      'tempo-api-key': options.apiKey ?? 'production',
+      ...(options.externalId ? { 'tempo-attribution-id': options.externalId } : {}),
+    },
+    method: 'POST',
+  })
+  return (await response.json()) as {
+    error?: { code: number; data?: { code: string }; message: string } | undefined
+    result?: `0x76${string}` | undefined
+  }
+}
+
+declare namespace sponsor {
+  /** Inputs for one locally signed sponsorship request. */
+  type Options = {
+    /** Credential selecting the key environment and scopes. */
+    apiKey?: string | undefined
+    /** Transaction chain id. */
+    chainId?: number | undefined
+    /** Account attribution shared across chains. */
+    externalId?: string | undefined
+    /** Signed gas price cap in attodollars. */
+    maxFeePerGas?: bigint | undefined
+    /** Sender nonce, distinguishing signed envelopes. */
+    nonce?: number | undefined
+  }
+}