tapimo 0.13.0 → 0.15.0

package/src/apps/relay/App.ts

@@ -7,22 +7,31 @@ import { Addresses, TokenId, Transaction } from 'viem/tempo'
 import type * as App from '../../App.js'
 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 SponsoredTransactions from '../../db/tables/sponsoredTransactions.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())
@@ -97,7 +106,11 @@ function middleware(options: middleware.Options) {
 
     const recordRejection = (options: middleware.Rejection) => {
       const id =
-        Number.isSafeInteger(options.chainId) && options.chainId >= 0 ? options.chainId : null
+        options.chainId !== undefined &&
+        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)
@@ -121,17 +134,18 @@ function middleware(options: middleware.Options) {
       throw new Error('Internal error', { cause: new Error(options.message) })
     }
 
-    const feePayer = (() => {
+    const feePayer = await (async () => {
       if (!options.feePayer) return undefined
-      const attribution =
-        principal?.type === 'api_key'
-          ? {
-              apiKeyId: principal.id,
-              environment: principal.environment,
-              orgId: principal.orgId,
-              ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
-            }
-          : 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(),
+      })
+      const attribution = resolved?.attribution
+      const attributionError = resolved?.error
       const sponsorable =
         attribution !== undefined &&
         principal?.type === 'api_key' &&
@@ -147,6 +161,12 @@ 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 (attributionError)
+            rejectSponsorship({
+              chainId: id,
+              message: 'Attribution rejected.',
+              reason: attributionError,
+            })
           if (!attribution) {
             if (sponsorshipRequired)
               rejectSponsorship({
@@ -173,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.
@@ -186,15 +206,9 @@ function middleware(options: middleware.Options) {
               })
             return false
           }
-
-          // Enforcement reads hit the primary, never the cached replica: a
-          // stale `past_due`, a lowered limit, or another isolate's pending
-          // spend must not keep the gate open.
           const db = Db.get(c.get('db'))
-          // Mainnet sponsorship requires an active billing source; deployments
-          // without billing configured have no rows, so mainnet stays closed.
-          // `past_due` gets its own reason: the caller must settle an invoice,
-          // not attach a card.
+          // Enforcement reads hit the primary, never the cached replica: a
+          // stale `past_due` or another isolate's state must not keep the gate open.
           const billing = await Billing.status(db, attribution.orgId)
           if (billing === 'past_due') {
             if (sponsorshipRequired)
@@ -214,7 +228,6 @@ function middleware(options: middleware.Options) {
               })
             return 'billing_required'
           }
-
           const feeToken = (() => {
             try {
               return TokenId.toAddress(transaction.feeToken ?? feeToken_sponsor)
@@ -273,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')
@@ -286,7 +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
@@ -303,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,
@@ -318,14 +347,58 @@ function middleware(options: middleware.Options) {
           // Re-read settings on the authoritative path: the limit may have
           // changed since `validate`, and only mainnet spend is limited.
           const settings = mainnet ? await BillingSettings.get(db, attribution.orgId) : undefined
-          if (settings?.spendLimit == null) return void (await SponsoredTransactions.upsert(db, input)) // prettier-ignore
+          const billingLimit =
+            settings?.spendLimit == null
+              ? undefined
+              : {
+                  chainIds: Zones.chainIds({
+                    sourceId: Viem.chainId.mainnet,
+                    zones: c.get('zones').values(),
+                  }),
+                  max: Billing.toBaseUnits(settings.spendLimit),
+                  since: Billing.periodStart(settings.period),
+                }
           try {
-            await SponsoredTransactions.reserve(db, input, {
-              chainIds: [Viem.chainId.mainnet],
-              max: Billing.toBaseUnits(settings.spendLimit),
-              since: Billing.periodStart(settings.period),
-            })
+            if (
+              mainnet &&
+              attribution.environment === 'production' &&
+              sponsorshipAttribution !== undefined
+            ) {
+              const promotion = await SponsoredTransactions.reservePromotion(
+                db,
+                {
+                  ...input,
+                  billable: false,
+                  sponsorshipAttributionId: sponsorshipAttribution.id,
+                },
+                {
+                  at: new Date().toISOString(),
+                  ...(billingLimit ? { billingLimit } : {}),
+                  chainIds: Zones.chainIds({
+                    sourceId: Viem.chainId.mainnet,
+                    zones: c.get('zones').values(),
+                  }),
+                },
+              )
+              if (promotion.status !== 'ineligible')
+                return { subsidized: !promotion.record.billable }
+            }
+            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,
@@ -397,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 }),
@@ -518,6 +620,100 @@ function sponsorshipMethod(value: unknown): Log.SponsorshipMethod | undefined {
   }
 }
 
+/** Resolves request attribution within the authenticated API key's organization. */
+async function resolveAttribution(
+  db: Db.Db,
+  options: resolveAttribution.Options,
+): Promise<resolveAttribution.Result | undefined> {
+  if (options.principal?.type !== 'api_key') return undefined
+  const { principal } = options
+  const attribution = {
+    apiKeyId: principal.id,
+    environment: principal.environment,
+    orgId: principal.orgId,
+    ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
+  }
+  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. */
+    projectId?: string | undefined
+  }
+
+  /** Resolved API-key attribution. */
+  type Attribution = {
+    /** API key id. */
+    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. */
+    projectId?: string | undefined
+  }
+
+  /** Attribution result with an optional policy error. */
+  type Result = {
+    /** Attribution retained for request diagnostics. */
+    attribution: Attribution
+    /** Attribution error detected before transaction validation. */
+    error?: 'attribution_id_invalid' | 'project_id_invalid' | undefined
+  }
+}
+
 declare namespace middleware {
   /** One invariant sponsorship failure. */
   type Failure = {
@@ -538,7 +734,7 @@ declare namespace middleware {
   /** One sponsorship rejection recorded for request logging. */
   type Rejection = {
     /** Candidate transaction chain, validated before it enters the log entry. */
-    chainId: number
+    chainId?: number | undefined
     /** Stable client error code. */
     reason: Log.SponsorshipReason
   }
@@ -546,7 +742,7 @@ declare namespace middleware {
   /** One client-visible sponsorship refusal. */
   type Refusal = {
     /** Candidate transaction chain. */
-    chainId: number
+    chainId?: number | undefined
     /** Client-safe error message. */
     message: string
     /** Stable client error code. */

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
+  }
+}