tapimo 0.14.0 → 0.15.0

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

@@ -19,10 +19,13 @@ import * as Fees from '../../internal/Fees.js'
 import type * as Log from '../../internal/Log.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 SponsorshipReconciliationCursors from '../../db/tables/sponsorshipReconciliationCursors.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
 import * as core_Billing from '../management/Billing.js'
 import * as RequestListener from '../../handlers/internal/requestListener.js'
+import * as Tidx from '../../internal/Tidx.js'
 import * as Viem from '../../internal/Viem.js'
 import * as Sponsorships from './Sponsorships.js'
 
@@ -34,7 +37,7 @@ const zone = runtime.zone.chainId
 const zoneScope = `zone:${zone}:read` as const
 const zoneOptions = TestApp.zone({
   chainId: zone,
-  rpcUrl: runtime.zone.publicZoneUrl,
+  rpcUrl: runtime.zone.internalRpcUrl,
 })
 
 /** Super admin secret configured on the end-to-end billing app. */
@@ -42,6 +45,14 @@ const superAdminSecret = 'tempo:sk:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a
 
 /** Keys covering the sponsorship policy matrix. */
 const keys = [
+  {
+    environment: 'sandbox',
+    id: 'key_relay_sponsor',
+    orgId: 'org_1',
+    projectId: 'prj_1',
+    scopes: ['rpc-relay:read', 'rpc-relay:sponsor'],
+    token: 'secret_relay_sponsor',
+  },
   {
     id: 'key_sponsor',
     orgId: 'org_1',
@@ -226,6 +237,139 @@ describe('behavior: Zone chain routing', () => {
     expect(body).toMatchObject({ result: `0x${zone.toString(16)}` })
   })
 
+  test.each(['relay', 'sponsor'] as const)(
+    'rejects a Zone token without a public RPC on %s',
+    async (mount) => {
+      const calls: string[] = []
+      const server = await Relay.createServer(
+        RequestListener.fromFetchHandler(async (request) => {
+          calls.push(await request.text())
+          return Response.json({ id: 1, jsonrpc: '2.0', result: Hex.fromNumber(zone) })
+        }),
+      )
+      try {
+        const api = TestApp.create({
+          auth: { keys },
+          rpc: { auth: 'internal:secret', url: server.url },
+          zones: [TestApp.zone({ chainId: zone, rpcUrl: server.url })],
+        })
+        const body = await request(api, {
+          body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
+          mount,
+          pathChainId: zone,
+          zoneToken: 'unvalidated-token',
+        })
+
+        expect(body).toMatchObject({ error: { code: -32_603 } })
+        expect(calls).toMatchInlineSnapshot(`[]`)
+      } finally {
+        await server.closeAsync()
+      }
+    },
+  )
+
+  test.each(['relay', 'sponsor'] as const)(
+    'blocks privileged Zone methods before %s dispatch',
+    async (mount) => {
+      const calls: string[] = []
+      const server = await Relay.createServer(
+        RequestListener.fromFetchHandler(async (request) => {
+          calls.push(await request.text())
+          return Response.json({ id: 1, jsonrpc: '2.0', result: null })
+        }),
+      )
+      try {
+        for (const selector of ['path', 'body', 'default'] as const) {
+          const api = TestApp.create({
+            auth: { keys },
+            ...(selector === 'default' ? { defaultChainId: zone } : {}),
+            rpc: { publicZoneUrl: server.url, url: 'http://internal.zone.test' },
+            zones: [TestApp.zone({ chainId: zone, rpcUrl: 'http://internal.zone.test' })],
+          })
+          for (const method of [
+            'admin_nodeInfo',
+            'debug_traceTransaction',
+            'eth_accounts',
+            'eth_sendTransaction',
+            'eth_sign',
+            'eth_signTransaction',
+            'tempo_fundAddress',
+          ]) {
+            const body = await request(api, {
+              body: {
+                id: 1,
+                jsonrpc: '2.0',
+                method,
+                params: selector === 'body' ? [{ chainId: zone }] : [],
+              },
+              mount,
+              ...(selector === 'path' ? { pathChainId: zone } : {}),
+              zoneToken: 'caller-token',
+            })
+            expect(body).toMatchObject({
+              error: { code: -32004, data: { code: 'api_key_forbidden' } },
+            })
+          }
+        }
+        expect(calls).toMatchInlineSnapshot(`[]`)
+      } finally {
+        await server.closeAsync()
+      }
+    },
+  )
+
+  test.each(['relay', 'sponsor'] as const)(
+    'filters mixed Zone batches on %s while preserving reads and signed broadcasts',
+    async (mount) => {
+      const methods: string[] = []
+      const server = await Relay.createServer(
+        RequestListener.fromFetchHandler(async (request) => {
+          type Body = { id: number; method: string }
+          const body = (await request.json()) as Body
+          methods.push(body.method)
+          return Response.json({ id: body.id, jsonrpc: '2.0', result: null })
+        }),
+      )
+      try {
+        const api = TestApp.create({
+          auth: { keys },
+          rpc: { publicZoneUrl: server.url, url: 'http://internal.zone.test' },
+          zones: [TestApp.zone({ chainId: zone, rpcUrl: 'http://internal.zone.test' })],
+        })
+        const body = await request(api, {
+          body: [
+            { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
+            { id: 2, jsonrpc: '2.0', method: 'admin_nodeInfo' },
+            { id: 3, jsonrpc: '2.0', method: 'zone_getAuthorizationTokenInfo' },
+            { id: 4, jsonrpc: '2.0', method: 'eth_sendRawTransaction', params: ['0x00'] },
+            { id: 5, jsonrpc: '2.0', method: 'eth_getBlockAccessList', params: ['latest'] },
+            { id: 6, jsonrpc: '2.0', method: 'eth_getStorageValues', params: [{}, 'latest'] },
+          ],
+          mount,
+          pathChainId: zone,
+          zoneToken: 'caller-token',
+        })
+        expect(body).toMatchObject([
+          { id: 1, result: null },
+          { id: 2, error: { code: -32004, data: { code: 'api_key_forbidden' } } },
+          { id: 3, result: null },
+          { id: 4, result: null },
+          { id: 5, result: null },
+          { id: 6, result: null },
+        ])
+        expect(methods.sort()).toEqual([
+          'eth_chainId',
+          'eth_getBlockAccessList',
+          'eth_getStorageValues',
+          'eth_sendRawTransaction',
+          'zone_getAuthorizationTokenInfo',
+        ])
+      } finally {
+        await server.closeAsync()
+      }
+    },
+  )
+
   test('allows a Zone token in a batch', async () => {
     const body = (await request(app(), {
       body: [
@@ -242,6 +386,54 @@ describe('behavior: Zone chain routing', () => {
     ])
   })
 
+  test.each([
+    ['relay', 307],
+    ['relay', 308],
+    ['sponsor', 307],
+    ['sponsor', 308],
+  ] as const)('rejects public Zone redirects on %s with status %s', async (mount, status) => {
+    const calls: string[] = []
+    const internal = await Relay.createServer(
+      RequestListener.fromFetchHandler(async (request) => {
+        calls.push(await request.text())
+        return Response.json({ id: 1, jsonrpc: '2.0', result: Hex.fromNumber(zone) })
+      }),
+    )
+    const publicRpc = await Relay.createServer(
+      RequestListener.fromFetchHandler(async (request) => {
+        await request.text()
+        return new Response(null, { headers: { location: internal.url }, status })
+      }),
+    )
+    try {
+      const api = TestApp.create({
+        auth: { keys },
+        rpc: {
+          auth: 'internal:secret',
+          publicZoneUrl: publicRpc.url,
+          url: internal.url,
+          zoneHeaders: {
+            'CF-Access-Client-Id': 'service-id',
+            'CF-Access-Client-Secret': 'service-secret',
+          },
+        },
+        zones: [TestApp.zone({ chainId: zone, rpcUrl: internal.url })],
+      })
+      const body = await request(api, {
+        body: { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
+        mount,
+        pathChainId: zone,
+        zoneToken: 'caller-token',
+      })
+
+      expect(body).toMatchObject({ error: { code: -32_603 } })
+      expect(calls).toMatchInlineSnapshot(`[]`)
+    } finally {
+      await publicRpc.closeAsync()
+      await internal.closeAsync()
+    }
+  })
+
   test.each([
     ['relay', 'secret_zone_relay'],
     ['sponsor', 'secret_zone_sponsor'],
@@ -377,6 +569,62 @@ describe('behavior: Zone chain routing', () => {
     expect(body).toMatchObject({ error: { data: { code: 'api_key_forbidden' } } })
   })
 
+  test.each(['relay', 'sponsor'] as const)(
+    'blocks Zone raw-sign requests without explicit sponsorship on %s',
+    async (mount) => {
+      const calls: string[] = []
+      const server = await Relay.createServer(
+        RequestListener.fromFetchHandler(async (request) => {
+          calls.push(await request.text())
+          return Response.json({ id: 1, jsonrpc: '2.0', result: '0x00' })
+        }),
+      )
+      try {
+        const serialized = await senderAccount.signTransaction({
+          chainId: zone,
+          gas: 100_000n,
+          maxFeePerGas: 1_000_000n,
+          maxPriorityFeePerGas: 0n,
+          nonce: 0,
+          to: Tempo.accounts[8]!.address,
+          value: 0n,
+        })
+        const api = TestApp.create({
+          auth: { keys },
+          relay: { feePayer: { account: feePayerAccount } },
+          rpc: { publicZoneUrl: server.url, url: 'http://internal.zone.test' },
+          zones: [TestApp.zone({ chainId: zone, rpcUrl: 'http://internal.zone.test' })],
+        })
+        for (const transaction of [
+          serialized,
+          '0x02c0',
+          '0x76',
+          'not-hex',
+          { from: senderAccount.address },
+        ]) {
+          const body = await request(api, {
+            apiKey: 'secret_relay_sponsor',
+            body: {
+              id: 1,
+              jsonrpc: '2.0',
+              method: 'eth_signRawTransaction',
+              params: [transaction],
+            },
+            mount,
+            pathChainId: zone,
+            zoneToken: 'caller-token',
+          })
+          expect(body).toMatchObject({
+            error: { code: -32004, data: { code: 'api_key_forbidden' } },
+          })
+        }
+        expect(calls).toMatchInlineSnapshot(`[]`)
+      } finally {
+        await server.closeAsync()
+      }
+    },
+  )
+
   test('requires Zone authorization for an embedded signed transaction', async () => {
     const entries: Log.Entry[] = []
     const api = TestApp.create({
@@ -410,6 +658,16 @@ describe('behavior: Zone chain routing', () => {
     expect(refused).toMatchObject({ error: { data: { code: 'api_key_forbidden' } } })
     expectSponsorshipCode({ code: 'api_key_forbidden', entry: entries[0] })
     expect(authorized).toMatchObject({ result: expect.stringMatching(/^0x/) })
+    for (const mount of ['relay', 'sponsor'] as const) {
+      const authorized = await request(api, {
+        ...rpc,
+        apiKey: 'secret_relay_sponsor',
+        mount,
+        pathChainId: zone,
+        zoneToken: token(),
+      })
+      expect(authorized).toMatchObject({ result: expect.stringMatching(/^0x/) })
+    }
   })
 })
 
@@ -428,6 +686,7 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
       token: 'secret_sponsor',
     })
     expect(body.error).toBeUndefined()
+    expect(body.sponsorship_details).toStrictEqual({ subsidized: true })
     // The relay returned the envelope counter-signed by the fee payer.
     const signed = Transaction.deserialize(body.result as `0x76${string}`)
     expect(signed.feePayerSignature).toBeDefined()
@@ -450,12 +709,14 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
           "feeAmount": null,
           "feeMax": "1",
           "feeToken": "0x20c0000000000000000000000000000000000000",
+          "finalizationAttemptedAt": null,
           "finalizedAt": null,
           "id": "<id>",
           "meterReportedAt": null,
           "orgId": "org_1",
           "projectId": "prj_1",
           "signPayload": "<hash>",
+          "sponsorshipAttributionId": null,
           "status": "pending",
           "transaction": "<hex>",
           "transactionHash": "<hash>",
@@ -982,8 +1243,8 @@ describe('behavior: mainnet billing gate', () => {
   async function configureSubsidy(db: ReturnType<typeof TestApp.database>) {
     await Organizations.create(db, { id: 'org_1', name: 'Privy' })
     await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      attributionSpendLimit: '100.00',
       durationDays: 90,
-      projectSpendLimit: '100.00',
     })
     const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
     await activate(db)
@@ -998,52 +1259,310 @@ describe('behavior: mainnet billing gate', () => {
   /** 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: active project promotions waive charges with active billing', async () => {
+  test('behavior: read-only relay requests do not create sponsorship attributions', async () => {
     const db = TestApp.database()
-    const project = await configureSubsidy(db)
+    await configureSubsidy(db)
+
+    const body = await relayRequest(createMainnetApp({ db }), {
+      externalId: 'privy-account-1',
+      method: 'eth_chainId',
+      mount: 'relay',
+      params: [],
+      token: 'secret_unscoped',
+    })
+
+    expect(body.error).toBeUndefined()
+    expect(
+      await db.kysely.selectFrom('sponsorship_attributions').select('id').execute(),
+    ).toHaveLength(0)
+  })
+
+  test('behavior: opaque attribution promotions waive charges with active billing', async () => {
+    const db = TestApp.database()
+    await configureSubsidy(db)
+    await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
     const body = await relayRequest(createMainnetApp({ db }), {
+      externalId: 'privy-account-1',
       method: 'eth_signRawTransaction',
       params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
-      projectId: project.id,
       token: 'secret_unattributed_prod',
     })
     expect(body.error).toBeUndefined()
 
     const [row] = await SponsoredTransactions.listPending(db)
     expect(row).toMatchObject({
+      sponsorshipAttributionId: expect.stringMatching(/^sat_/),
       billable: false,
       orgId: 'org_1',
-      projectId: project.id,
+      projectId: null,
+    })
+    const updated = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
     })
-    const updated = await Projects.get(db, project.id)
-    const startsAt = updated?.sponsorshipSubsidyStartsAt
-    const endsAt = updated?.sponsorshipSubsidyEndsAt
+    const startsAt = updated?.startsAt
+    const endsAt = updated?.endsAt
     expect({ endsAt, startsAt }).toMatchObject({ endsAt: expect.any(String), startsAt: expect.any(String) }) // prettier-ignore
     if (!endsAt || !startsAt) throw new Error('Expected an activated promotion window.')
     expect(Date.parse(endsAt) - Date.parse(startsAt)).toBe(90 * 86_400_000)
   })
 
-  test('behavior: exhausted project promotions return to customer billing', async () => {
+  test.each(['externalId', 'legacyExternalId'] as const)(
+    'behavior: rotating %s cannot create fresh promotional budgets',
+    async (header) => {
+      const db = TestApp.databaseFactory()
+      const seed = db()
+      await configureSubsidy(seed)
+      await Organizations.setSponsorshipSubsidy(seed, 'org_1', {
+        attributionSpendLimit: '0.000001',
+        durationDays: 90,
+      })
+      await BillingSettings.upsert(seed, { orgId: 'org_1', spendLimit: '0.000002' })
+      const entries: Log.Entry[] = []
+      const app = createMainnetApp({ db, logger: (entry) => void entries.push(entry) })
+      const results = await Promise.all(
+        [0, 1, 2, 3].map(async (nonce) =>
+          relayRequest(app, {
+            [header]: `rotating-account-${nonce}`,
+            method: 'eth_signRawTransaction',
+            params: [await signSponsorable({ chainId: Viem.chainId.mainnet, nonce })],
+            token: 'secret_unattributed_prod',
+          }),
+        ),
+      )
+
+      expect(results.filter((result) => !result.error)).toHaveLength(2)
+      expect(results.filter((result) => result.error?.data?.code === 'spend_limit_exceeded')).toHaveLength(2) // prettier-ignore
+      expect(entries.filter((entry) => entry.sponsorship?.reason === 'spend_limit_exceeded')).toHaveLength(2) // prettier-ignore
+      expect(await seed.kysely.selectFrom('sponsorship_attributions').selectAll().execute()).toStrictEqual([]) // prettier-ignore
+      expect(
+        await SponsoredTransactions.spend(seed, {
+          billable: false,
+          chainIds: [Viem.chainId.mainnet],
+          orgId: 'org_1',
+          since: '2000-01-01T00:00:00.000Z',
+        }),
+      ).toBe(0n)
+      expect(
+        await SponsoredTransactions.spend(seed, {
+          chainIds: [Viem.chainId.mainnet],
+          orgId: 'org_1',
+          since: '2000-01-01T00:00:00.000Z',
+        }),
+      ).toBe(2n)
+    },
+  )
+
+  test('behavior: Privy legacy attribution header resolves the same canonical record', async () => {
+    const db = TestApp.database()
+    await configureSubsidy(db)
+    await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
+    const body = await relayRequest(createMainnetApp({ db }), {
+      legacyExternalId: 'privy-account-1',
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      token: 'secret_unattributed_prod',
+    })
+
+    expect(body.error).toBeUndefined()
+    expect(
+      await SponsorshipAttributions.resolveExternal(db, {
+        externalId: 'privy-account-1',
+        orgId: 'org_1',
+      }),
+    ).toMatchObject({ startsAt: expect.any(String) })
+  })
+
+  test('behavior: external attribution ids are bounded to 128 characters', async () => {
+    const db = TestApp.database()
+    await configureSubsidy(db)
+    await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'a'.repeat(128),
+      orgId: 'org_1',
+    })
+    const app = createMainnetApp({ db })
+    const accepted = await relayRequest(app, {
+      externalId: 'a'.repeat(128),
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      token: 'secret_unattributed_prod',
+    })
+    const rejected = await relayRequest(app, {
+      externalId: 'a'.repeat(129),
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, nonce: 1 })],
+      token: 'secret_unattributed_prod',
+    })
+
+    expect(accepted.error).toBeUndefined()
+    expect(rejected.error).toStrictEqual({
+      code: -32602,
+      data: { code: 'attribution_id_invalid' },
+      message: 'Attribution rejected.',
+    })
+    expect(
+      await db.kysely.selectFrom('sponsorship_attributions').select('externalId').execute(),
+    ).toStrictEqual([{ externalId: 'a'.repeat(128) }])
+  })
+
+  test('behavior: the canonical header takes precedence over the legacy header', async () => {
+    const db = TestApp.database()
+    await configureSubsidy(db)
+    await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'canonical-account',
+      orgId: 'org_1',
+    })
+    const body = await relayRequest(createMainnetApp({ db }), {
+      externalId: 'canonical-account',
+      legacyExternalId: 'legacy-account',
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      token: 'secret_unattributed_prod',
+    })
+
+    expect(body.error).toBeUndefined()
+    expect(
+      await db.kysely.selectFrom('sponsorship_attributions').select('externalId').execute(),
+    ).toStrictEqual([{ externalId: 'canonical-account' }])
+  })
+
+  test.each(['privy-account-2', 'unknown-account'])(
+    'behavior: retrying an envelope with attribution %s is rejected',
+    async (externalId) => {
+      const db = TestApp.database()
+      await configureSubsidy(db)
+      await SponsorshipAttributions.resolveExternal(db, {
+        externalId: 'privy-account-1',
+        orgId: 'org_1',
+      })
+      await SponsorshipAttributions.resolveExternal(db, {
+        externalId: 'privy-account-2',
+        orgId: 'org_1',
+      })
+      const app = createMainnetApp({ db })
+      const transaction = await signSponsorable({ chainId: Viem.chainId.mainnet })
+      const accepted = await relayRequest(app, {
+        externalId: 'privy-account-1',
+        method: 'eth_signRawTransaction',
+        params: [transaction],
+        token: 'secret_unattributed_prod',
+      })
+      const rejected = await relayRequest(app, {
+        externalId,
+        method: 'eth_signRawTransaction',
+        params: [transaction],
+        token: 'secret_unattributed_prod',
+      })
+
+      expect(accepted.error).toBeUndefined()
+      expect(rejected.error).toStrictEqual({
+        code: -32602,
+        data: { code: 'attribution_id_invalid' },
+        message: 'Attribution rejected.',
+      })
+    },
+  )
+
+  test('behavior: foreign external ids cannot select a legacy or project promotion', async () => {
+    const db = TestApp.database()
+    const project = await configureSubsidy(db)
+    const foreign = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'foreign-account',
+      orgId: 'org_2',
+    })
+    const legacy = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'legacy-account',
+      orgId: 'org_1',
+    })
+    const body = await relayRequest(createMainnetApp({ db }), {
+      externalId: 'foreign-account',
+      legacyExternalId: 'legacy-account',
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      projectId: project.id,
+      token: 'secret_unattributed_prod',
+    })
+
+    expect(body.error).toBeUndefined()
+    expect(await SponsoredTransactions.listPending(db)).toMatchObject([
+      { billable: true, projectId: project.id, sponsorshipAttributionId: null },
+    ])
+    expect(
+      await db.kysely.selectFrom('sponsorship_attributions').selectAll().orderBy('orgId').execute(),
+    ).toStrictEqual([legacy, foreign])
+  })
+
+  test('behavior: Tempo Project attribution uses the canonical promotion path', async () => {
+    const db = TestApp.database()
+    const project = await configureSubsidy(db)
+    const body = await relayRequest(createMainnetApp({ db }), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      projectId: project.id,
+      token: 'secret_unattributed_prod',
+    })
+
+    expect(body.error).toBeUndefined()
+    expect(await SponsoredTransactions.listPending(db)).toMatchObject([
+      {
+        billable: false,
+        projectId: project.id,
+        sponsorshipAttributionId: expect.stringMatching(/^sat_/),
+      },
+    ])
+  })
+
+  test('behavior: sponsor fills return their sponsorship details', async () => {
+    const db = TestApp.database()
+    const project = await configureSubsidy(db)
+    const body = await relayRequest(createMainnetApp({ db }), {
+      method: 'eth_fillTransaction',
+      params: [fill],
+      projectId: project.id,
+      token: 'secret_unattributed_prod',
+    })
+
+    expect(body.error).toBeUndefined()
+    expect(body.sponsorship_details).toStrictEqual({ subsidized: true })
+  })
+
+  test('behavior: exhausted attribution promotions return to customer billing', async () => {
     const db = TestApp.database()
     await Organizations.create(db, { id: 'org_1', name: 'Privy' })
     await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      attributionSpendLimit: '0.000001',
       durationDays: 90,
-      projectSpendLimit: '0.000001',
     })
-    const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
     await activate(db)
+    await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
     const app = createMainnetApp({ db })
+    const transaction = await signSponsorable({ chainId: Viem.chainId.mainnet })
 
     const subsidized = await relayRequest(app, {
+      externalId: 'privy-account-1',
       method: 'eth_signRawTransaction',
-      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
-      projectId: project.id,
+      params: [transaction],
       token: 'secret_unattributed_prod',
     })
     const billed = await relayRequest(app, {
+      externalId: 'privy-account-1',
       method: 'eth_signRawTransaction',
       params: [await signSponsorable({ chainId: Viem.chainId.mainnet, nonce: 1 })],
-      projectId: project.id,
+      token: 'secret_unattributed_prod',
+    })
+    const retried = await relayRequest(app, {
+      externalId: 'privy-account-1',
+      method: 'eth_signRawTransaction',
+      params: [transaction],
       token: 'secret_unattributed_prod',
     })
 
@@ -1051,49 +1570,123 @@ describe('behavior: mainnet billing gate', () => {
       billed: undefined,
       subsidized: undefined,
     })
+    expect({
+      billed: billed.sponsorship_details,
+      subsidized: subsidized.sponsorship_details,
+    }).toStrictEqual({ billed: { subsidized: false }, subsidized: { subsidized: true } })
+    expect(retried.sponsorship_details).toStrictEqual({ subsidized: true })
     expect(await SponsoredTransactions.listPending(db)).toMatchObject([
-      { billable: false, projectId: project.id },
-      { billable: true, projectId: project.id },
+      {
+        sponsorshipAttributionId: expect.stringMatching(/^sat_/),
+        billable: false,
+        projectId: null,
+      },
+      { sponsorshipAttributionId: expect.stringMatching(/^sat_/), billable: true, projectId: null },
     ])
   })
 
-  test('behavior: uncapped project promotions waive charges with active billing', async () => {
+  test('behavior: uncapped attribution promotions waive charges with active billing', async () => {
     const db = TestApp.database()
     await Organizations.create(db, { id: 'org_1', name: 'Privy' })
     await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      attributionSpendLimit: null,
       durationDays: 90,
-      projectSpendLimit: null,
     })
-    const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
     await activate(db)
+    await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
     const body = await relayRequest(createMainnetApp({ db }), {
+      externalId: 'privy-account-1',
       method: 'eth_signRawTransaction',
       params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
-      projectId: project.id,
       token: 'secret_unattributed_prod',
     })
     expect(body.error).toBeUndefined()
     expect(await SponsoredTransactions.listPending(db)).toMatchObject([
-      { billable: false, projectId: project.id },
+      {
+        sponsorshipAttributionId: expect.stringMatching(/^sat_/),
+        billable: false,
+        projectId: null,
+      },
     ])
   })
 
-  test('behavior: project promotions still require active billing', async () => {
+  test('behavior: registered attribution bursts share promotion and fallback billing limits', async () => {
+    const db = TestApp.databaseFactory()
+    const seed = db()
+    await configureSubsidy(seed)
+    await Organizations.setSponsorshipSubsidy(seed, 'org_1', {
+      attributionSpendLimit: '0.000002',
+      durationDays: 90,
+    })
+    await BillingSettings.upsert(seed, { orgId: 'org_1', spendLimit: '0.000001' })
+    const attribution = await SponsorshipAttributions.resolveExternal(seed, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
+    const entries: Log.Entry[] = []
+    const app = createMainnetApp({ db, logger: (entry) => void entries.push(entry) })
+    const results = await Promise.all(
+      Array.from({ length: 6 }, async (_, nonce) =>
+        relayRequest(app, {
+          ...(nonce % 2 === 0
+            ? { externalId: 'privy-account-1' }
+            : { legacyExternalId: 'privy-account-1' }),
+          method: 'eth_signRawTransaction',
+          params: [await signSponsorable({ chainId: Viem.chainId.mainnet, nonce })],
+          token: 'secret_unattributed_prod',
+        }),
+      ),
+    )
+
+    expect(results.filter((result) => !result.error)).toHaveLength(3)
+    expect(
+      results.filter((result) => result.error?.data?.code === 'spend_limit_exceeded'),
+    ).toHaveLength(3)
+    expect(
+      entries.filter((entry) => entry.sponsorship?.reason === 'spend_limit_exceeded'),
+    ).toHaveLength(3)
+    const rows = await SponsoredTransactions.listPending(seed)
+    expect(rows.filter((row) => !row.billable)).toHaveLength(2)
+    expect(rows.filter((row) => row.billable)).toHaveLength(1)
+    expect(rows.every((row) => row.sponsorshipAttributionId === attribution.id)).toBe(true)
+    for (const row of rows)
+      await SponsoredTransactions.finalize(seed, row.id, {
+        feeAmount: '1',
+        finalizedAt: new Date().toISOString(),
+      })
+    const scope = {
+      chainIds: [Viem.chainId.mainnet],
+      orgId: 'org_1',
+      since: '2000-01-01T00:00:00.000Z',
+    }
+    expect(await SponsoredTransactions.spend(seed, { ...scope, billable: false })).toBe(2n)
+    expect(await SponsoredTransactions.spend(seed, scope)).toBe(1n)
+    expect(
+      await SponsoredTransactions.listUnreported(seed, { chainIds: scope.chainIds }),
+    ).toMatchObject([{ billable: true, feeAmount: '1', sponsorshipAttributionId: attribution.id }])
+  })
+
+  test('behavior: attribution promotions still require active billing', async () => {
     const db = TestApp.database()
     await Organizations.create(db, { id: 'org_1', name: 'Privy' })
     await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      attributionSpendLimit: null,
       durationDays: 90,
-      projectSpendLimit: null,
     })
     const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
     await TestApp.verifiedSeed(db, Viem.chainId.mainnet)
     const body = await relayRequest(createMainnetApp({ db }), {
+      externalId: 'privy-account-1',
       method: 'eth_signRawTransaction',
       params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
       projectId: project.id,
       token: 'secret_unattributed_prod',
     })
     expect(body.error?.data).toStrictEqual({ code: 'billing_required' })
+    expect(body.sponsorship_details).toBeUndefined()
     expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
     expect(await Projects.get(db, project.id)).toMatchObject({
       sponsorshipSubsidyEndsAt: null,
@@ -1118,12 +1711,16 @@ describe('behavior: mainnet billing gate', () => {
   test('behavior: expired project promotions return to customer billing', async () => {
     const db = TestApp.database()
     const project = await configureSubsidy(db)
-    await Projects.activateSponsorship(db, {
-      at: new Date(Date.now() - 91 * 86_400_000).toISOString(),
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: project.id,
+    })
+    await SponsorshipAttributions.activate(db, {
       endsAt: new Date(Date.now() - 86_400_000).toISOString(),
-      id: project.id,
+      id: attribution.id,
       orgId: 'org_1',
       spendLimit: '100000000',
+      startsAt: new Date(Date.now() - 91 * 86_400_000).toISOString(),
     })
     const body = await relayRequest(createMainnetApp({ db }), {
       method: 'eth_signRawTransaction',
@@ -1147,7 +1744,7 @@ describe('behavior: mainnet billing gate', () => {
     expect(body.error).toStrictEqual({
       code: -32602,
       data: { code: 'project_id_invalid' },
-      message: 'Project attribution rejected.',
+      message: 'Attribution rejected.',
     })
   })
 
@@ -1164,6 +1761,23 @@ describe('behavior: mainnet billing gate', () => {
     expect(body.error?.data).toStrictEqual({ code: 'project_id_invalid' })
   })
 
+  test('behavior: rejects cached project attribution after project deletion', async () => {
+    const db = TestApp.database()
+    await configureSubsidy(db)
+    const body = await relayRequest(createMainnetApp({ db }), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      token: 'secret_sponsor_prod',
+    })
+
+    expect(body.error).toStrictEqual({
+      code: -32602,
+      data: { code: 'project_id_invalid' },
+      message: 'Attribution rejected.',
+    })
+    expect(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+  })
+
   test('behavior: refuses mainnet sponsorship without a billing source', async () => {
     const entries: Log.Entry[] = []
     const body = await relayRequest(
@@ -1515,44 +2129,57 @@ describe('behavior: mainnet billing gate', () => {
     expect(row?.currency).toBe('usd')
   })
 
-  test('behavior: refuses sponsorship over the period spend limit; raising restores', async () => {
-    const db = TestApp.database()
-    const entries: Log.Entry[] = []
-    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 = createMainnetApp({ db, logger: (entry) => void entries.push(entry) })
-    const request = async () =>
-      await relayRequest(app, {
-        method: 'eth_signRawTransaction',
-        params: [await signSponsorable({ chainId: Viem.chainId.mainnet, ...halfDollarFees })],
-        token: 'secret_sponsor_prod',
+  test.each([Viem.chainId.mainnet, 8001])(
+    'behavior: counts chain %i toward the period spend limit; raising restores',
+    async (chainId) => {
+      const db = TestApp.database()
+      const entries: Log.Entry[] = []
+      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,
+        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 refused = await request()
-    expect(refused.error?.message).toBe('Spend limit exceeded.')
-    expect(refused.error?.data).toStrictEqual({ code: 'spend_limit_exceeded' })
-    expectSponsorshipCode({ code: 'spend_limit_exceeded', entry: entries[0] })
 
-    await BillingSettings.upsert(db, { orgId: 'org_1', spendLimit: '10' })
-    const restored = await request()
-    expect(restored.error).toBeUndefined()
-  })
+      const app = createMainnetApp({
+        db,
+        logger: (entry) => void entries.push(entry),
+        zones: [
+          TestApp.zone({
+            chainId: 8001,
+            rpcUrl: 'https://zone.example',
+            sourceChainId: Viem.chainId.mainnet,
+          }),
+        ],
+      })
+      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' })
+      expectSponsorshipCode({ code: 'spend_limit_exceeded', entry: entries[0] })
+
+      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()
@@ -1698,6 +2325,142 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship (viem)', ()
     )
   }, 60_000)
 
+  test('behavior: old failed intents do not hide active transactions or pin recovery', async () => {
+    const receipts: Transaction.TransactionReceipt[] = []
+    const intents: SponsoredTransactions.Record[] = []
+    for (const amount of [3n, 4n, 5n]) {
+      const before = new Set((await SponsoredTransactions.listPending(db)).map((row) => row.id))
+      const { receipt } = await Actions.token.transferSync(getClient(), {
+        amount,
+        feePayer: true,
+        to: Tempo.accounts[8]!.address,
+        token: alphaUsd,
+      })
+      receipts.push(receipt)
+      const intent = (await SponsoredTransactions.listPending(db)).find(
+        (row) => row.transactionHash === null && !before.has(row.id),
+      )
+      expect(intent).toBeDefined()
+      intents.push(intent!)
+      // Separate the active intent's search window from the older transactions.
+      await new Promise((resolve) => setTimeout(resolve, 1_100))
+    }
+    await Organizations.create(db, { id: 'org_1', name: 'One' })
+    for (const intent of intents.slice(0, 2))
+      await SponsoredTransactions.fail(db, intent.id, new Date().toISOString())
+
+    const tidx = Tidx.getClient({
+      chainId: runtime.chainId,
+      tidx: { baseUrl: runtime.tidxUrl },
+    })
+    await expect
+      .poll(
+        async () => {
+          const { rows } = await tidx.fetch({
+            // Runtime hashes bound this query to the three submitted transactions.
+            query:
+              `SELECT hash FROM txs WHERE hash IN (${receipts.map((receipt) => `'${receipt.transactionHash}'`).join(', ')})` as string,
+          })
+          return rows.length
+        },
+        { timeout: 30_000 },
+      )
+      .toBe(3)
+
+    const options = {
+      candidateCap: 1,
+      feePayer: feePayer.address,
+      getClient: () => relayClient,
+      getTidx: () => tidx,
+      skewMs: 0,
+    }
+    // The real API health route rejects RPC calls, exercising a misconfigured upstream.
+    const unavailable = createClient({
+      chain: Tempo.chain,
+      transport: http(`${server.url}/health`, { retryCount: 0 }),
+    })
+    const failed = await Sponsorships.reconcile(db, {
+      ...options,
+      getClient: () => unavailable,
+    })
+    expect(failed.errors).toBeGreaterThan(0)
+    expect(
+      await SponsorshipReconciliationCursors.load(db, {
+        chainId: runtime.chainId,
+        feePayer: feePayer.address.toLowerCase() as Hex.Hex,
+      }),
+    ).toMatchObject({ complete: true, retryCount: 1 })
+    expect((await SponsoredTransactions.get(db, intents[2]!.id))?.transactionHash).toBeNull()
+    for (let attempt = 0; attempt < 2; attempt++)
+      expect(
+        (
+          await Sponsorships.reconcile(db, {
+            ...options,
+            getClient: () => unavailable,
+          })
+        ).errors,
+      ).toBeGreaterThan(0)
+    expect(
+      await SponsorshipReconciliationCursors.load(db, {
+        chainId: runtime.chainId,
+        feePayer: feePayer.address.toLowerCase() as Hex.Hex,
+      }),
+    ).toMatchObject({
+      blockNumber: receipts[2]!.blockNumber.toString(),
+      complete: false,
+      retryCount: 0,
+      transactionIndex: receipts[2]!.transactionIndex,
+    })
+
+    expect((await Sponsorships.reconcile(db, options)).errors).toBe(0)
+    expect((await SponsoredTransactions.get(db, intents[2]!.id))?.transactionHash).toBe(
+      receipts[2]!.transactionHash,
+    )
+    // Each pass must advance beyond already processed on-chain candidates.
+    await Sponsorships.reconcile(db, options)
+    expect(
+      await SponsorshipReconciliationCursors.load(db, {
+        chainId: runtime.chainId,
+        feePayer: feePayer.address.toLowerCase() as Hex.Hex,
+      }),
+    ).toMatchObject({ complete: true, retryCount: 0, retryKey: null })
+    for (const [index, intent] of intents.entries())
+      expect((await SponsoredTransactions.get(db, intent.id))?.transactionHash).toBe(
+        receipts[index]!.transactionHash,
+      )
+    await Sponsorships.finalize(db, { getClient: () => relayClient })
+    for (const intent of intents)
+      expect((await SponsoredTransactions.get(db, intent.id))?.status).toBe('finalized')
+
+    const { receipt } = await Actions.token.transferSync(getClient(), {
+      amount: 6n,
+      feePayer: true,
+      to: Tempo.accounts[8]!.address,
+      token: alphaUsd,
+    })
+    const later = (await SponsoredTransactions.listPending(db)).find(
+      (row) => row.transactionHash === null,
+    )!
+    await SponsoredTransactions.fail(db, later.id, new Date().toISOString())
+    await expect
+      .poll(
+        async () => {
+          const { rows } = await tidx.fetch({
+            // Runtime hash restricts the query to the new recovery candidate.
+            query: `SELECT hash FROM txs WHERE hash = '${receipt.transactionHash}'` as string,
+          })
+          return rows.length
+        },
+        { timeout: 30_000 },
+      )
+      .toBe(1)
+    // A new failed intent must start at the head, even after a full final page.
+    await Sponsorships.reconcile(db, options)
+    expect((await SponsoredTransactions.get(db, later.id))?.transactionHash).toBe(
+      receipt.transactionHash,
+    )
+  }, 90_000)
+
   test('behavior: sign-only sends record and finalize from the real receipt', async () => {
     const request = await prepareTransactionRequest(relayClient, {
       account: sender,
@@ -1792,6 +2555,10 @@ async function relayRequest(app: ReturnType<typeof TestApp.create>, options: rel
       body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: options.method, params: options.params }), // prettier-ignore
       headers: {
         'content-type': 'application/json',
+        ...(options.externalId ? { 'tempo-attribution-id': options.externalId } : {}),
+        ...(options.legacyExternalId
+          ? { 'x-tempo-attribution-key': options.legacyExternalId }
+          : {}),
         ...(options.projectId ? { 'tempo-project-id': options.projectId } : {}),
         ...(options.token ? { 'tempo-api-key': options.token } : {}),
       },
@@ -1801,12 +2568,17 @@ async function relayRequest(app: ReturnType<typeof TestApp.create>, options: rel
   return (await response.json()) as {
     error?: { code: number; data?: { code: string } | undefined; message: string } | undefined
     result?: `0x${string}` | undefined
+    sponsorship_details?: { subsidized: boolean } | undefined
   }
 }
 
 declare namespace relayRequest {
   /** Options for one composed relay request. */
   type Options = {
+    /** Opaque provider account attribution. */
+    externalId?: string | undefined
+    /** Legacy Privy external attribution id. */
+    legacyExternalId?: string | undefined
     /** JSON-RPC method. */
     method: string
     /** Relay mount to call. */
@@ -1954,6 +2726,7 @@ function createMainnetApp(options: createMainnetApp.Options = {}) {
     ...(options.logger ? { logger: options.logger } : {}),
     relay: { feePayer: { account: feePayerAccount } },
     supportedChainIds: [Viem.chainId.mainnet],
+    zones: options.zones,
   })
 }
 
@@ -1964,6 +2737,8 @@ declare namespace createMainnetApp {
     db?: Db.Source | undefined
     /** Structured request log sink. */
     logger?: Log.Emit | undefined
+    /** Configured Zone chains. */
+    zones?: TestApp.create.Options['zones'] | undefined
   }
 }