tapimo 0.1.0 → 0.3.0

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

@@ -0,0 +1,933 @@
+import { nanoid } from 'nanoid'
+import { Hash, Secp256k1 } from 'ox'
+import { createClient, http } from 'viem'
+import { prepareTransactionRequest, sendRawTransactionSync, signTransaction } from 'viem/actions'
+import { Account as TempoAccount, Actions, Transaction, withRelay } from 'viem/tempo'
+
+import * as TestApp from '../../../test/App.js'
+import { startTempo } from '../../../test/containers.js'
+import * as Relay from '../../../test/Relay.js'
+import * as Runtime from '../../../test/runtime.js'
+import * as Tempo from '../../../test/Tempo.js'
+import * as TestStripe from '../../../test/Stripe.js'
+import * as BillingSettings from '../../db/tables/billingSettings.js'
+import type * as Db from '../../db/Db.js'
+import * as Fees from '../../internal/Fees.js'
+import * as Organizations from '../../db/tables/organizations.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
+import * as core_Billing from '../platform/Billing.js'
+import * as RequestListener from '../../handlers/internal/requestListener.js'
+import * as Viem from '../../internal/Viem.js'
+import * as Sponsorships from './Sponsorships.js'
+
+const runtime = Runtime.get()
+
+const feePayerAccount = Tempo.accounts[10]!
+const senderAccount = Tempo.accounts[9]!
+
+/** Super admin secret configured on the end-to-end billing app. */
+const superAdminSecret = 'tempo:sk:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1'
+
+/** Keys covering the sponsorship policy matrix; all hold the base relay scope. */
+const keys = [
+  {
+    id: 'key_sponsor',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    environment: 'sandbox',
+    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    token: 'secret_sponsor',
+  },
+  {
+    id: 'key_sponsor_prod',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    environment: 'production',
+    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    token: 'secret_sponsor_prod',
+  },
+  {
+    id: 'key_wildcard',
+    orgId: 'org_2',
+    projectId: 'prj_2',
+    environment: 'sandbox',
+    scopes: ['*'],
+    token: 'secret_wildcard',
+  },
+  {
+    id: 'key_wildcard_prod',
+    orgId: 'org_2',
+    projectId: 'prj_2',
+    environment: 'production',
+    scopes: ['*'],
+    token: 'secret_wildcard_prod',
+  },
+  {
+    id: 'key_unscoped',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    environment: 'sandbox',
+    scopes: ['rpc-relay:read'],
+    token: 'secret_unscoped',
+  },
+  {
+    id: 'key_unattributed',
+    orgId: 'org_1',
+    environment: 'sandbox',
+    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    token: 'secret_unattributed',
+  },
+] as const satisfies readonly TestApp.kvStore.Key[]
+
+describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
+  test('behavior: scoped keys sponsor, recorded with attribution', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_sponsor',
+    })
+    expect(body.error).toBeUndefined()
+    // The relay returned the envelope counter-signed by the fee payer.
+    const signed = Transaction.deserialize(body.result as `0x76${string}`)
+    expect(signed.feePayerSignature).toBeDefined()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.transactionHash).toBe(Hash.keccak256(body.result!))
+    expect(row?.signPayload).toMatch(/^0x/)
+    expect(row?.chainId).toBe(runtime.chainId)
+    // The stored envelope is exactly the counter-signed transaction returned.
+    expect(row?.transaction).toBe(body.result)
+    expect({ ...row, chainId: '<chainId>', createdAt: '<timestamp>', id: '<id>', signPayload: '<hash>', transaction: '<hex>', transactionHash: '<hash>' }) // prettier-ignore
+      .toMatchInlineSnapshot(`
+        {
+          "apiKeyId": "key_sponsor",
+          "billable": false,
+          "chainId": "<chainId>",
+          "createdAt": "<timestamp>",
+          "currency": null,
+          "environment": "sandbox",
+          "feeAmount": null,
+          "feeMax": "1",
+          "feeToken": "0x20c0000000000000000000000000000000000000",
+          "finalizedAt": null,
+          "id": "<id>",
+          "meterReportedAt": null,
+          "orgId": "org_1",
+          "projectId": "prj_1",
+          "signPayload": "<hash>",
+          "status": "pending",
+          "transaction": "<hex>",
+          "transactionHash": "<hash>",
+        }
+      `)
+  })
+
+  test('behavior: production keys record billable rows', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error).toBeUndefined()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.billable).toBe(true)
+    expect(row?.environment).toMatchInlineSnapshot(`"production"`)
+  })
+
+  test('behavior: the wildcard scope grants sponsorship', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_wildcard',
+    })
+    expect(body.error).toBeUndefined()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.orgId).toMatchInlineSnapshot(`"org_2"`)
+  })
+
+  test('behavior: keys without the sponsor scope are refused', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_unscoped',
+    })
+    // "Sponsorship rejected." surfaces as invalid params (-32602).
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: keys without project attribution are refused', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_unattributed',
+    })
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: super admin principals are refused', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys, superAdmin: { secret: 'super-admin-secret' } },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'super-admin-secret',
+    })
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: sponsorship stays closed without a fee payer', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({ auth: { keys }, db })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      token: 'secret_sponsor',
+    })
+    expect(body.error?.code).toBe(-32601)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: mainnet sponsorship is refused until billing ships', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [
+        await senderAccount.signTransaction({
+          chainId: 4217,
+          feePayer: true,
+          gas: 100_000n,
+          maxFeePerGas: 1_000_000n,
+          maxPriorityFeePerGas: 0n,
+          nonce: 0,
+          to: Tempo.accounts[8]!.address,
+          value: 0n,
+        }),
+      ],
+      token: 'secret_sponsor',
+    })
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: an app-provided fee payer URL cannot trigger the managed fee payer', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_fillTransaction',
+      params: [
+        {
+          calls: [{ to: Tempo.accounts[8]!.address, value: '0x0' }],
+          chainId: `0x${runtime.chainId.toString(16)}`,
+          feePayer: 'https://example.com',
+          from: senderAccount.address,
+          gas: '0x186a0',
+          maxFeePerGas: '0xf4240',
+          maxPriorityFeePerGas: '0x0',
+          nonce: '0x0',
+        },
+      ],
+      token: 'secret_unscoped',
+    })
+    const result = body.result as unknown as
+      | { capabilities?: { sponsored?: boolean }; tx?: { feePayerSignature?: string | null } }
+      | undefined
+    expect(result?.tx?.feePayerSignature ?? null).toBeNull()
+    expect(result?.capabilities?.sponsored).toBe(false)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: sponsorship is refused for chains this deployment does not serve', async () => {
+    const db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [
+        await senderAccount.signTransaction({
+          chainId: 999_999,
+          feePayer: true,
+          gas: 100_000n,
+          maxFeePerGas: 1_000_000n,
+          maxPriorityFeePerGas: 0n,
+          nonce: 0,
+          to: Tempo.accounts[8]!.address,
+          value: 0n,
+        }),
+      ],
+      token: 'secret_sponsor',
+    })
+    expect(body.result).toBeUndefined()
+    expect(body.error?.code).toBe(-32602)
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+})
+
+// Chain-free (`eth_signRawTransaction` signs locally; the sponsor fee token
+// short-circuits resolution), so the gate matrix runs in every mode.
+describe('behavior: mainnet billing gate', () => {
+  function createApp(db: Db.Source = TestApp.database()) {
+    return TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+      supportedChainIds: [Viem.chainId.mainnet],
+    })
+  }
+
+  /** Activates billing for the org so the gate reaches the limit checks. */
+  async function activate(db: ReturnType<typeof TestApp.database>, orgId = 'org_1') {
+    await StripeCustomers.create(db, { orgId, stripeCustomerId: `cus_gate_${orgId}` })
+    await StripeCustomers.setStatus(db, orgId, 'active')
+    // The fee-token gate reads the verified list; seed mainnet's curated tokens.
+    await TestApp.verifiedSeed(db, Viem.chainId.mainnet)
+  }
+
+  // Gas prices are attodollars (1e-18 USD) per gas; the signed cap in
+  // fee-token units is ceil(gas × maxFeePerGas / 1e12). The helper's default
+  // envelope (100k gas × 1e6 atto) caps at 1 microdollar — negligible.
+  /** A $0.50 signed cap: 1M gas × 5e11 attodollars. */
+  const halfDollarFees = { gas: 1_000_000n, maxFeePerGas: 500_000_000_000n } as const
+  /** A $2 signed cap, over the `'1.00'` platform default. */
+  const overCapFees = { gas: 1_000_000n, maxFeePerGas: 2_000_000_000_000n } as const
+
+  test('behavior: refuses mainnet sponsorship without a billing source', async () => {
+    const body = await relayRequest(createApp(), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error?.code).toBe(-32602)
+    expect(body.error?.message).toBe('Billing required.')
+    expect(body.error?.data).toStrictEqual({ code: 'billing_required' })
+  })
+
+  test('behavior: refuses mainnet sponsorship while billing is inactive', async () => {
+    const db = TestApp.database()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_gate' })
+    const body = await relayRequest(createApp(db), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error?.code).toBe(-32602)
+    expect(body.error?.message).toBe('Billing required.')
+  })
+
+  test('behavior: past-due billing refuses with its own reason', async () => {
+    const db = TestApp.database()
+    await activate(db)
+    // An unpaid invoice parked the org; the caller must settle it, not attach a card.
+    await StripeCustomers.setStatus(db, 'org_1', 'past_due')
+    const body = await relayRequest(createApp(db), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error?.code).toBe(-32602)
+    expect(body.error?.message).toBe('Billing past due.')
+    expect(body.error?.data).toStrictEqual({ code: 'billing_past_due' })
+  })
+
+  test('behavior: active billing opens mainnet sponsorship and records it', async () => {
+    const db = TestApp.database()
+    await activate(db)
+
+    const body = await relayRequest(createApp(db), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error).toBeUndefined()
+    const signed = Transaction.deserialize(body.result as `0x76${string}`)
+    expect(signed.feePayerSignature).toBeDefined()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.chainId).toBe(Viem.chainId.mainnet)
+    expect(row?.billable).toBe(true)
+    expect(row?.orgId).toBe('org_1')
+    // The signed liability cap in fee-token units, for spend-limit accounting.
+    expect(row?.feeMax).toBe('500000')
+  })
+
+  test('behavior: a sandbox key never sponsors mainnet, even with active billing', async () => {
+    const db = TestApp.database()
+    await activate(db) // org_1 is active…
+    const body = await relayRequest(createApp(db), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
+      token: 'secret_sponsor', // …but this key is sandbox.
+    })
+    // Refused for the environment, before the billing check reveals a reason.
+    expect(body.error?.code).toBe(-32602)
+    expect(body.error?.message).toBe('Sponsorship rejected.')
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: other orgs stay gated by their own billing', async () => {
+    const db = TestApp.database()
+    // org_1 is active; the production wildcard key belongs to org_2, which has nothing.
+    await activate(db)
+    const body = await relayRequest(createApp(db), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
+      token: 'secret_wildcard_prod',
+    })
+    expect(body.error?.code).toBe(-32602)
+    expect(body.error?.message).toBe('Billing required.')
+  })
+
+  test('behavior: refuses a transaction over the platform fee cap', async () => {
+    const db = TestApp.database()
+    await activate(db)
+    const body = await relayRequest(createApp(db), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...overCapFees })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error?.code).toBe(-32602)
+    expect(body.error?.message).toBe('Transaction fee limit exceeded.')
+    expect(body.error?.data).toStrictEqual({ code: 'tx_fee_limit_exceeded' })
+  })
+
+  test('behavior: the org fee limit tightens the platform cap but never loosens it', async () => {
+    const db = TestApp.database()
+    await activate(db)
+    // Tighter than the platform default: $0.50 envelopes now refuse.
+    await BillingSettings.upsert(db, { orgId: 'org_1', txFeeLimit: '0.10' })
+    const app = createApp(db)
+    const tightened = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(tightened.error?.data).toStrictEqual({ code: 'tx_fee_limit_exceeded' })
+
+    // Looser than the platform default: the $2 envelope still refuses.
+    await BillingSettings.upsert(db, { orgId: 'org_1', txFeeLimit: '999999' })
+    const loosened = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...overCapFees })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(loosened.error?.data).toStrictEqual({ code: 'tx_fee_limit_exceeded' })
+  })
+
+  test('behavior: refuses fee tokens the verified list does not resolve to USD', async () => {
+    const db = TestApp.database()
+    await activate(db)
+    // EURC is verified yet non-USD; fee math reads micro-USD, so it refuses.
+    const eurc = `0x${'e0'.repeat(20)}` as const
+    await TestApp.verifiedSeed(db, Viem.chainId.mainnet, {
+      tokens: [{ address: eurc, currency: 'EUR', decimals: 6, name: 'Euro Coin', symbol: 'EURC' }],
+    })
+
+    const app = createApp(db)
+    const request = async (feeToken: `0x${string}`) =>
+      await relayRequest(app, {
+        method: 'eth_signRawTransaction',
+        params: [await signSponsorable({ chainId: Viem.chainId.mainnet, feeToken })],
+        token: 'secret_sponsor_prod',
+      })
+    const nonUsd = await request(eurc)
+    expect(nonUsd.error?.message).toBe('Fee token unsupported.')
+    expect(nonUsd.error?.data).toStrictEqual({ code: 'fee_token_unsupported' })
+    // Tokens absent from the verified list refuse the same way.
+    const unverified = await request(`0x${'ab'.repeat(20)}`)
+    expect(unverified.error?.data).toStrictEqual({ code: 'fee_token_unsupported' })
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
+  test('behavior: sponsored rows snapshot the fee currency', async () => {
+    const db = TestApp.database()
+    await activate(db)
+
+    const body = await relayRequest(createApp(db), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error).toBeUndefined()
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.currency).toBe('usd')
+  })
+
+  test('behavior: refuses sponsorship over the period spend limit; raising restores', async () => {
+    const db = TestApp.database()
+    await activate(db)
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '1' })
+    // $0.90 already finalized this window; a $0.50 cap would overshoot $1.
+    const seeded = await SponsoredTransactions.upsert(db, {
+      apiKeyId: 'key_sponsor_prod',
+      billable: true,
+      chainId: Viem.chainId.mainnet,
+      environment: 'production',
+      orgId: 'org_1',
+      projectId: 'prj_1',
+      signPayload: `0x${'31'.repeat(32)}`,
+      transaction: `0x76${'cc'.repeat(16)}`,
+      transactionHash: `0x${'32'.repeat(32)}`,
+    })
+    await SponsoredTransactions.finalize(db, seeded.id, {
+      feeAmount: '900000',
+      finalizedAt: new Date().toISOString(),
+    })
+
+    const app = createApp(db)
+    const request = async () =>
+      await relayRequest(app, {
+        method: 'eth_signRawTransaction',
+        params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
+        token: 'secret_sponsor_prod',
+      })
+    const refused = await request()
+    expect(refused.error?.message).toBe('Spend limit exceeded.')
+    expect(refused.error?.data).toStrictEqual({ code: 'spend_limit_exceeded' })
+
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '10' })
+    const restored = await request()
+    expect(restored.error).toBeUndefined()
+  })
+
+  test('behavior: pending signed caps consume spend-limit budget', async () => {
+    const db = TestApp.database()
+    await activate(db)
+    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '1' })
+    // A pending $0.90 cap, fee unknown until its receipt lands.
+    await SponsoredTransactions.upsert(db, {
+      apiKeyId: 'key_sponsor_prod',
+      billable: true,
+      chainId: Viem.chainId.mainnet,
+      environment: 'production',
+      feeMax: '900000',
+      orgId: 'org_1',
+      projectId: 'prj_1',
+      signPayload: `0x${'33'.repeat(32)}`,
+      transaction: `0x76${'cc'.repeat(16)}`,
+      transactionHash: `0x${'34'.repeat(32)}`,
+    })
+
+    const body = await relayRequest(createApp(db), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error?.data).toStrictEqual({ code: 'spend_limit_exceeded' })
+  })
+
+  test('behavior: concurrent bursts cannot overshoot the spend limit', async () => {
+    // A per-request factory (like production) over a multi-connection pool, so
+    // the reserve transactions run concurrently and the advisory lock — not the
+    // pool — is what serializes them.
+    const db = TestApp.databaseFactory()
+    const seed = db()
+    await activate(seed)
+    // Limit fits exactly two $0.50 sponsorships.
+    await BillingSettings.upsert(seed, { orgId: 'org_1', spendLimit: '1' })
+    const app = createApp(db)
+    // Distinct nonces → distinct envelopes → distinct rows, fired together.
+    const results = await Promise.all(
+      Array.from({ length: 6 }, async (_, nonce) =>
+        relayRequest(app, {
+          method: 'eth_signRawTransaction',
+          params: [await signSponsorable({ chainId: Viem.chainId.mainnet, nonce, ...halfDollarFees })], // prettier-ignore
+          token: 'secret_sponsor_prod',
+        }),
+      ),
+    )
+    const sponsored = results.filter((r) => !r.error)
+    const refused = results.filter((r) => r.error?.data?.code === 'spend_limit_exceeded')
+    expect(sponsored).toHaveLength(2)
+    expect(refused).toHaveLength(4)
+    // Recorded spend never exceeds the limit ($1 = 1e6 base units).
+    const spend = await SponsoredTransactions.spend(seed, {
+      chainIds: [Viem.chainId.mainnet],
+      orgId: 'org_1',
+      since: '2000-01-01T00:00:00.000Z',
+    })
+    expect(spend).toBe(1_000_000n)
+  })
+})
+
+describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship (viem)', () => {
+  const alphaUsd = '0x20c0000000000000000000000000000000000001'
+  const feePayer = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey())
+  const sender = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey())
+  const relayClient = Relay.getClient()
+
+  let db: ReturnType<typeof TestApp.database>
+  let server: Relay.Server
+
+  function getClient(policy?: 'sign-and-broadcast' | 'sign-only') {
+    return createClient({
+      account: sender,
+      chain: Tempo.chain,
+      transport: withRelay(
+        Relay.http(),
+        http(`${server.url}/rpc/relay`, {
+          fetchOptions: { headers: { 'tempo-api-key': 'secret_sponsor' } },
+        }),
+        policy ? { policy } : {},
+      ),
+    })
+  }
+
+  beforeAll(async () => {
+    await Promise.all(
+      [feePayer, sender].map((account) =>
+        Actions.faucet.fundSync(relayClient, { account, timeout: 60_000 }),
+      ),
+    )
+    db = TestApp.database()
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      // Explicit fee token: exercises the consumer override of the pathUSD default.
+      relay: { feePayer: { account: feePayer, feeToken: alphaUsd } },
+    })
+    server = await Relay.createServer(RequestListener.fromFetchHandler((req) => app.fetch(req)))
+  }, 120_000)
+
+  afterAll(async () => {
+    await server.closeAsync()
+  })
+
+  test('behavior: transferSync sponsors end-to-end, recording a fill intent', async () => {
+    const { receipt } = await Actions.token.transferSync(getClient(), {
+      amount: 1n,
+      feePayer: true,
+      to: Tempo.accounts[8]!.address,
+      token: alphaUsd,
+    })
+
+    // Sponsored on-chain: the fee payer paid, the sender's transfer landed.
+    expect(receipt.status).toBe('success')
+    expect(receipt.feePayer?.toLowerCase()).toBe(feePayer.address.toLowerCase())
+
+    const intent = (await SponsoredTransactions.listPending(db)).find(
+      (row) => row.transactionHash === null,
+    )
+    expect(intent?.apiKeyId).toBe('key_sponsor')
+    expect(intent?.orgId).toBe('org_1')
+    expect(intent?.billable).toBe(false)
+    expect(intent?.feeToken?.toLowerCase()).toBe(alphaUsd)
+
+    const finalizer = Sponsorships.createFinalizer({
+      db,
+      defaultChainId: runtime.chainId,
+      feePayer: feePayer.address,
+      rpc: TestApp.rpc,
+      tidx: { baseUrl: runtime.tidxUrl! },
+    })
+    let finalized: Awaited<ReturnType<typeof SponsoredTransactions.get>>
+    for (let attempt = 0; attempt < 30; attempt++) {
+      await finalizer.tick()
+      finalized = await SponsoredTransactions.get(db, intent!.id)
+      if (finalized?.status === 'finalized') break
+      await new Promise((resolve) => setTimeout(resolve, 1_000))
+    }
+    expect(finalized?.status).toBe('finalized')
+    expect(finalized?.transactionHash).toBe(receipt.transactionHash)
+    expect(finalized?.feeAmount).toBe(
+      Fees.fromGas(receipt.gasUsed, receipt.effectiveGasPrice).toString(),
+    )
+  }, 60_000)
+
+  test('behavior: sign-only sends record and finalize from the real receipt', async () => {
+    const request = await prepareTransactionRequest(relayClient, {
+      account: sender,
+      calls: [
+        Actions.token.transfer.call(relayClient, {
+          amount: 1n,
+          to: Tempo.accounts[8]!.address,
+          token: alphaUsd,
+        }),
+      ],
+      feePayer: true,
+    })
+    const signed = await signTransaction(relayClient, request)
+
+    const receipt = await sendRawTransactionSync(getClient(), {
+      serializedTransaction: signed,
+    })
+
+    const row = (await SponsoredTransactions.listPending(db)).find(
+      (row) => row.transactionHash === receipt.transactionHash,
+    )
+    expect(row?.apiKeyId).toBe('key_sponsor')
+    expect(row?.orgId).toBe('org_1')
+    expect(row?.transaction.startsWith('0x76')).toBe(true)
+
+    // The finalizer resolves the row against the real localnet receipt.
+    const result = await Sponsorships.finalize(db, { getClient: () => relayClient })
+    expect(result.failed).toBe(0)
+    expect(result.finalized).toBeGreaterThanOrEqual(1)
+    const finalized = await SponsoredTransactions.get(db, row!.id)
+    expect(finalized?.status).toBe('finalized')
+    expect(finalized?.feeAmount).toBe(
+      Fees.fromGas(receipt.gasUsed, receipt.effectiveGasPrice).toString(),
+    )
+  }, 30_000)
+
+  test('behavior: sign-and-broadcast sends record through the relay', async () => {
+    const request = await prepareTransactionRequest(relayClient, {
+      account: sender,
+      calls: [
+        Actions.token.transfer.call(relayClient, {
+          amount: 2n,
+          to: Tempo.accounts[8]!.address,
+          token: alphaUsd,
+        }),
+      ],
+      feePayer: true,
+    })
+    const signed = await signTransaction(relayClient, request)
+
+    const receipt = await sendRawTransactionSync(getClient('sign-and-broadcast'), {
+      serializedTransaction: signed,
+    })
+
+    const rows = await SponsoredTransactions.listPending(db)
+    expect(rows.find((row) => row.transactionHash === receipt.transactionHash)).toBeDefined()
+  }, 30_000)
+})
+
+/**
+ * Signs a sponsorship-requesting Tempo transaction (fee-payer slot present but
+ * empty; the serializer strips `feeToken`, the sponsor picks it) entirely
+ * offline: `eth_signRawTransaction` never touches the chain, so the suite
+ * runs without a node.
+ */
+async function signSponsorable(
+  overrides: {
+    chainId?: number
+    feeToken?: `0x${string}`
+    gas?: bigint
+    maxFeePerGas?: bigint
+    nonce?: number
+  } = {},
+) {
+  return await senderAccount.signTransaction({
+    chainId: overrides.chainId ?? runtime.chainId,
+    feePayer: true,
+    gas: overrides.gas ?? 100_000n,
+    maxFeePerGas: overrides.maxFeePerGas ?? 1_000_000n,
+    maxPriorityFeePerGas: 0n,
+    nonce: overrides.nonce ?? 0,
+    to: Tempo.accounts[8]!.address,
+    value: 0n,
+    ...(overrides.feeToken ? { feeToken: overrides.feeToken } : {}),
+  })
+}
+
+/** Posts one JSON-RPC request to the composed app's relay mount. */
+async function relayRequest(
+  app: ReturnType<typeof TestApp.create>,
+  options: { method: string; params: readonly unknown[]; token?: string | undefined },
+) {
+  const response = await app.fetch(
+    new Request('http://tempo-api.test/rpc/relay', {
+      body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: options.method, params: options.params }), // prettier-ignore
+      headers: {
+        'content-type': 'application/json',
+        ...(options.token ? { 'tempo-api-key': options.token } : {}),
+      },
+      method: 'POST',
+    }),
+  )
+  return (await response.json()) as {
+    error?: { code: number; data?: { code: string } | undefined; message: string } | undefined
+    result?: `0x${string}` | undefined
+  }
+}
+
+// The full billing-to-invoice flow with nothing synthetic: a disposable node
+// runs under mainnet's chain id (dev consensus, funded dev alloc), so a real
+// card attach opens the real gate, a real sponsored transaction mines with a
+// real receipt, the real finalizer prices it, and real meter events land on a
+// real Stripe invoice.
+describe.runIf(TestStripe.secretKey)(
+  'behavior: sponsored spend reaches the invoice (stripe sandbox)',
+  () => {
+    // prettier-ignore
+    const webhookSecret = `whsec_${'c'.repeat(32)}`
+    let node: Awaited<ReturnType<typeof startTempo>> | undefined
+
+    beforeAll(async () => {
+      node = await startTempo({ chainId: Viem.chainId.mainnet })
+    }, 240_000)
+
+    afterAll(async () => {
+      await TestStripe.sweep()
+      await node?.container.stop()
+    })
+
+    test(
+      'a sponsored transaction meters real usage onto the invoice',
+      { retry: 0, timeout: 300_000 },
+      async () => {
+        // prettier-ignore
+        const { url } = node!
+        const stripe = TestStripe.client()
+        const db = TestApp.database()
+        // The key attributes to org_1; the row must exist for the usage read.
+        await Organizations.create(db, { id: 'org_1', name: 'Sponsored Spend Org' })
+        // Mainnet sponsorship refuses fee tokens the verified list cannot
+        // resolve to USD; seed it like the gate tests do.
+        await TestApp.verifiedSeed(db, Viem.chainId.mainnet)
+        const app = TestApp.create({
+          auth: { keys, superAdmin: { secret: superAdminSecret } },
+          billing: { stripe: { client: stripe, webhookSecret } },
+          db,
+          relay: { feePayer: { account: feePayerAccount } },
+          rpc: { url: () => url },
+          supportedChainIds: [Viem.chainId.mainnet],
+        })
+        const chainClient = Viem.getClient({
+          chainId: Viem.chainId.mainnet,
+          rpc: { url: () => url },
+        })
+        // Both signers pay real fee-token balances on the node.
+        await Actions.faucet.fundSync(chainClient, { account: senderAccount.address, timeout: 60_000 }) // prettier-ignore
+        await Actions.faucet.fundSync(chainClient, { account: feePayerAccount.address, timeout: 60_000 }) // prettier-ignore
+
+        // Closed until a real card attach flips the derived status.
+        const refused = await relayRequest(app, {
+          method: 'eth_signRawTransaction',
+          params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+          token: 'secret_sponsor_prod',
+        })
+        expect(refused.error?.data).toStrictEqual({ code: 'billing_required' })
+
+        const customer = await stripe.customers.create({
+          metadata: { orgId: 'org_1' },
+          name: `Test Org ${nanoid(10)}`,
+        })
+        TestStripe.track(customer.id)
+        await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: customer.id })
+        await TestStripe.completeCheckout(app, { customer: customer.id, webhookSecret })
+        expect((await StripeCustomers.get(db, 'org_1'))?.status).toBe('active')
+
+        // Broadcast a sponsored transaction through the relay; it mines locally.
+        const sent = await relayRequest(app, {
+          method: 'eth_sendRawTransactionSync',
+          params: [
+            await signSponsorable({
+              chainId: Viem.chainId.mainnet,
+              gas: 1_000_000n,
+              maxFeePerGas: 500_000_000_000n,
+            }),
+          ],
+          token: 'secret_sponsor_prod',
+        })
+        expect(sent.error).toBeUndefined()
+
+        // The real receipt finalizes the row with the actual charged fee.
+        const finalizer = Sponsorships.createFinalizer({ db, rpc: { url: () => url } })
+        await finalizer.tick()
+        const [row] = await SponsoredTransactions.listUnreported(db, { chainIds: [Viem.chainId.mainnet] }) // prettier-ignore
+        expect(row?.status).toBe('finalized')
+        expect(row?.feeMax).toBe('500000')
+        const feeAmount = BigInt(row!.feeAmount!)
+        expect(feeAmount).toBeGreaterThan(0n)
+        expect(feeAmount).toBeLessThanOrEqual(500_000n)
+
+        // Usage surfaces through the API exactly as enforced.
+        const usage = await app.request('/v1/orgs/org_1/billing', {
+          headers: { 'tempo-api-key': superAdminSecret },
+        })
+        expect(usage.status).toBe(200)
+        const body = (await usage.json()) as { spend: { amount: string } }
+        expect(body.spend.amount).toBe(core_Billing.fromBaseUnits(feeAmount))
+
+        // The reporter meters the spend; Stripe aggregates it onto the upcoming
+        // invoice (asynchronously, so poll).
+        expect(await core_Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
+          failed: 0,
+          reported: 1,
+          skipped: 0,
+        })
+        const { priceId } = await core_Billing.ensureFixtures(stripe)
+        const [subscription] = (await stripe.subscriptions.list({ customer: customer.id, limit: 1, price: priceId })).data // prettier-ignore
+        expect(subscription).toBeDefined()
+        const deadline = Date.now() + 180_000
+        let quantity: number | null | undefined
+        while (Date.now() < deadline) {
+          const preview = await stripe.invoices.createPreview({
+            customer: customer.id,
+            subscription: subscription!.id,
+          })
+          quantity = preview.lines.data.find((l) => l.pricing?.price_details?.price === priceId)?.quantity // prettier-ignore
+          if (quantity === Number(feeAmount)) break
+          await new Promise((resolve) => setTimeout(resolve, 5_000))
+        }
+        expect(quantity).toBe(Number(feeAmount))
+      },
+    )
+  },
+)