tapimo 0.13.0 → 0.15.0

package/src/db/tables/sponsoredTransactions.test.ts

@@ -3,6 +3,8 @@ import { nanoid } from 'nanoid'
 import * as Runtime from '../../../test/runtime.js'
 import * as Db from '../Db.js'
 import * as Organizations from './organizations.js'
+import * as Projects from './projects.js'
+import * as SponsorshipAttributions from './sponsorshipAttributions.js'
 import * as SponsoredTransactions from './sponsoredTransactions.js'
 
 const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
@@ -47,12 +49,14 @@ describe('upsert', () => {
         "feeAmount": null,
         "feeMax": null,
         "feeToken": null,
+        "finalizationAttemptedAt": null,
         "finalizedAt": null,
         "id": "stx_<id>",
         "meterReportedAt": null,
         "orgId": "org_1",
         "projectId": "prj_1",
         "signPayload": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        "sponsorshipAttributionId": null,
         "status": "pending",
         "transaction": "0x76cccccccccccccccccccccccccccccccc",
         "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
@@ -124,6 +128,20 @@ describe('upsert', () => {
     await db.close()
   })
 
+  test('behavior: rejects a sign payload already attributed to another project', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    const first = await SponsoredTransactions.upsert(db, intent)
+
+    await expect(
+      SponsoredTransactions.upsert(db, { ...input, projectId: 'prj_2' }),
+    ).rejects.toBeInstanceOf(SponsoredTransactions.AttributionConflictError)
+
+    expect(await SponsoredTransactions.get(db, first.id)).toStrictEqual(first)
+    await db.close()
+  })
+
   test('behavior: a raw submission reopens a failed fill intent', async () => {
     const db = create()
     await db.migrate()
@@ -184,6 +202,130 @@ describe('listPending', () => {
   })
 })
 
+describe('claimPending', () => {
+  test('behavior: rotates through a bounded backlog before retrying rows', async () => {
+    const db = create()
+    await db.migrate()
+    for (let index = 1; index <= 5; index++)
+      await SponsoredTransactions.upsert(db, {
+        ...input,
+        signPayload: `0x${index.toString(16).padStart(64, '0')}`,
+        transactionHash: `0x${(index + 5).toString(16).padStart(64, '0')}`,
+      })
+    const pending = await SponsoredTransactions.listPending(db)
+
+    const first = await SponsoredTransactions.claimPending(db, {
+      attemptedAt: '2027-01-01T00:00:00.000Z',
+      limit: 2,
+    })
+    const second = await SponsoredTransactions.claimPending(db, {
+      attemptedAt: '2027-01-01T00:01:00.000Z',
+      limit: 2,
+    })
+    const third = await SponsoredTransactions.claimPending(db, {
+      attemptedAt: '2027-01-01T00:02:00.000Z',
+      limit: 2,
+    })
+
+    expect(first.map(({ id }) => id)).toEqual(pending.slice(0, 2).map(({ id }) => id))
+    expect(second.map(({ id }) => id)).toEqual(pending.slice(2, 4).map(({ id }) => id))
+    expect(third.map(({ id }) => id)).toEqual([pending[4]!.id, pending[0]!.id])
+    await db.close()
+  })
+})
+
+describe('listIntents', () => {
+  test('behavior: returns active hash-less intents without failed rows', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    const failed = await SponsoredTransactions.upsert(db, intent)
+    await SponsoredTransactions.fail(db, failed.id, new Date().toISOString())
+    const pending = await SponsoredTransactions.upsert(db, {
+      ...intent,
+      signPayload: `0x${'bc'.repeat(32)}`,
+    })
+
+    expect((await SponsoredTransactions.listIntents(db)).map((record) => record.id)).toStrictEqual([
+      pending.id,
+    ])
+    await db.close()
+  })
+})
+
+describe('listRecoveryWindows', () => {
+  test('behavior: returns each chain with its oldest eligible failed intent', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    vi.useFakeTimers({ now: new Date('2026-01-01T00:00:00.000Z') })
+    try {
+      const first = await SponsoredTransactions.upsert(db, intent)
+      await SponsoredTransactions.fail(db, first.id, '2026-01-02T00:00:00.000Z')
+      vi.setSystemTime(new Date('2026-01-01T01:00:00.000Z'))
+      const second = await SponsoredTransactions.upsert(db, {
+        ...intent,
+        chainId: 4217,
+        signPayload: `0x${'bc'.repeat(32)}`,
+      })
+      await SponsoredTransactions.fail(db, second.id, '2026-01-02T00:00:00.000Z')
+
+      expect(
+        (
+          await SponsoredTransactions.listRecoveryWindows(db, {
+            failedSince: '2026-01-01T12:00:00.000Z',
+          })
+        ).sort((left, right) => left.chainId - right.chainId),
+      ).toMatchInlineSnapshot(`
+        [
+          {
+            "chainId": 4217,
+            "createdAt": "2026-01-01T01:00:00.000Z",
+          },
+          {
+            "chainId": 42431,
+            "createdAt": "2026-01-01T00:00:00.000Z",
+          },
+        ]
+      `)
+    } finally {
+      vi.useRealTimers()
+      await db.close()
+    }
+  })
+})
+
+describe('listRecoverableIntents', () => {
+  test('behavior: returns pending and eligible failed intents matching candidate payloads', async () => {
+    const db = create()
+    await db.migrate()
+    const { transactionHash: _, ...intent } = input
+    const pending = await SponsoredTransactions.upsert(db, {
+      ...intent,
+      signPayload: `0x${'bd'.repeat(32)}`,
+    })
+    const eligible = await SponsoredTransactions.upsert(db, intent)
+    await SponsoredTransactions.fail(db, eligible.id, '2026-01-02T00:00:00.000Z')
+    const expired = await SponsoredTransactions.upsert(db, {
+      ...intent,
+      signPayload: `0x${'bc'.repeat(32)}`,
+    })
+    await SponsoredTransactions.fail(db, expired.id, '2026-01-01T00:00:00.000Z')
+
+    expect(
+      (
+        await SponsoredTransactions.listRecoverableIntents(db, {
+          failedSince: '2026-01-01T12:00:00.000Z',
+          signPayloads: [eligible.signPayload, expired.signPayload, pending.signPayload],
+        })
+      )
+        .map((record) => record.id)
+        .sort(),
+    ).toStrictEqual([eligible.id, pending.id].sort())
+    await db.close()
+  })
+})
+
 describe('assignTransactionHash', () => {
   test('behavior: reopens a failed intent when reconciliation finds its hash', async () => {
     const db = create()
@@ -270,8 +412,9 @@ describe('assignTransactionHash', () => {
       })
       expect(
         (
-          await SponsoredTransactions.listIntents(db, {
+          await SponsoredTransactions.listRecoverableIntents(db, {
             failedSince: '2026-02-01T00:00:00.000Z',
+            signPayloads: [failed.signPayload],
           })
         ).map((record) => record.id),
       ).toContain(failed.id)
@@ -393,6 +536,416 @@ describe('spend', () => {
     expect(await SponsoredTransactions.spend(db, { chainIds: [input.chainId], orgId: 'org_1', since: future })).toBe(0n) // prettier-ignore
     await db.close()
   })
+
+  test('behavior: promotional spend is isolated by project', async () => {
+    const db = create()
+    await db.migrate()
+    await SponsoredTransactions.upsert(db, {
+      ...input,
+      billable: false,
+      feeMax: '100',
+      projectId: 'prj_1',
+      signPayload: `0x${'09'.repeat(32)}`,
+    })
+    await SponsoredTransactions.upsert(db, {
+      ...input,
+      billable: false,
+      feeMax: '200',
+      projectId: 'prj_2',
+      signPayload: `0x${'0a'.repeat(32)}`,
+    })
+
+    expect(
+      await SponsoredTransactions.spend(db, {
+        billable: false,
+        chainIds: [input.chainId],
+        orgId: 'org_1',
+        projectId: 'prj_1',
+        since: '2000-01-01T00:00:00.000Z',
+      }),
+    ).toBe(100n)
+    await db.close()
+  })
+})
+
+describe('reserve', () => {
+  test('behavior: enforces promotional limits independently per project', async () => {
+    const db = create()
+    await db.migrate()
+    const limit = {
+      billable: false,
+      chainIds: [input.chainId],
+      max: 100n,
+      projectId: 'prj_1',
+      since: '2000-01-01T00:00:00.000Z',
+    } as const
+    await SponsoredTransactions.reserve(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '100',
+        signPayload: `0x${'0b'.repeat(32)}`,
+      },
+      limit,
+    )
+    await SponsoredTransactions.reserve(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '100',
+        projectId: 'prj_2',
+        signPayload: `0x${'0c'.repeat(32)}`,
+      },
+      { ...limit, projectId: 'prj_2' },
+    )
+
+    await expect(
+      SponsoredTransactions.reserve(
+        db,
+        {
+          ...input,
+          billable: false,
+          feeMax: '1',
+          signPayload: `0x${'0d'.repeat(32)}`,
+        },
+        limit,
+      ),
+    ).rejects.toBeInstanceOf(SponsoredTransactions.PeriodSpendLimitError)
+    await db.close()
+  })
+})
+
+describe('reservePromotion', () => {
+  async function configure(db: Db.Db, attributionSpendLimit: string | null) {
+    await Organizations.create(db, { id: 'org_1', name: 'Privy' })
+    await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      attributionSpendLimit,
+      durationDays: 90,
+    })
+  }
+
+  test('behavior: atomically records the first sponsorship and immutable window', async () => {
+    const db = create()
+    await db.migrate()
+    await configure(db, '0.000001')
+    const project = await Projects.create(db, { name: 'App', orgId: 'org_1' })
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: project.id,
+    })
+    const result = await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        projectId: project.id,
+        sponsorshipAttributionId: attribution.id,
+      },
+      {
+        at: '2026-01-01T00:00:00.000Z',
+        chainIds: [input.chainId],
+      },
+    )
+    const updated = await SponsorshipAttributions.get(db, {
+      id: attribution.id,
+      orgId: 'org_1',
+    })
+    expect({
+      endsAt: updated?.endsAt,
+      startsAt: updated?.startsAt,
+    }).toMatchInlineSnapshot(`
+      {
+        "endsAt": "2026-04-01T00:00:00.000Z",
+        "startsAt": "2026-01-01T00:00:00.000Z",
+      }
+    `)
+    if (result.status === 'ineligible') throw new Error('Expected a promotion reservation.')
+    expect(result.record.billable).toBe(false)
+    expect(updated?.spendLimit).toBe('1')
+    await db.close()
+  })
+
+  test('behavior: records an uncapped promotion', async () => {
+    const db = create()
+    await db.migrate()
+    await configure(db, null)
+    const project = await Projects.create(db, { name: 'App', orgId: 'org_1' })
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: project.id,
+    })
+    const result = await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '100',
+        projectId: project.id,
+        sponsorshipAttributionId: attribution.id,
+      },
+      {
+        at: '2026-01-01T00:00:00.000Z',
+        chainIds: [input.chainId],
+      },
+    )
+    if (result.status === 'ineligible') throw new Error('Expected a promotion reservation.')
+    expect(result.record.billable).toBe(false)
+    expect(
+      await SponsorshipAttributions.get(db, { id: attribution.id, orgId: 'org_1' }),
+    ).toMatchObject({
+      endsAt: '2026-04-01T00:00:00.000Z',
+      spendLimit: null,
+      startsAt: '2026-01-01T00:00:00.000Z',
+    })
+    await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '100',
+        sponsorshipAttributionId: attribution.id,
+        signPayload: `0x${'24'.repeat(32)}`,
+      },
+      {
+        at: '2026-01-02T00:00:00.000Z',
+        chainIds: [input.chainId],
+      },
+    )
+    expect(
+      (await SponsorshipAttributions.get(db, { id: attribution.id, orgId: 'org_1' }))?.spendLimit,
+    ).toBeNull()
+    await db.close()
+  })
+
+  test('behavior: reads the current organization policy when activating', async () => {
+    const db = create()
+    await db.migrate()
+    await configure(db, '0.000001')
+    const project = await Projects.create(db, { name: 'App', orgId: 'org_1' })
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: project.id,
+    })
+    await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      attributionSpendLimit: '0.000002',
+      durationDays: 90,
+    })
+
+    const result = await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '2',
+        projectId: project.id,
+        sponsorshipAttributionId: attribution.id,
+      },
+      {
+        at: '2026-01-01T00:00:00.000Z',
+        chainIds: [input.chainId],
+      },
+    )
+
+    expect(result.status).toBe('subsidized')
+    expect(
+      (await SponsorshipAttributions.get(db, { id: attribution.id, orgId: 'org_1' }))?.spendLimit,
+    ).toBe('2')
+    await db.close()
+  })
+
+  test('behavior: conflicting envelopes do not activate another project', async () => {
+    const db = create()
+    await db.migrate()
+    await configure(db, null)
+    const first = await Projects.create(db, { name: 'First', orgId: 'org_1' })
+    const second = await Projects.create(db, { name: 'Second', orgId: 'org_1' })
+    const secondAttribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: second.id,
+    })
+    await SponsoredTransactions.upsert(db, { ...input, projectId: first.id })
+
+    await expect(
+      SponsoredTransactions.reservePromotion(
+        db,
+        {
+          ...input,
+          billable: false,
+          projectId: second.id,
+          sponsorshipAttributionId: secondAttribution.id,
+        },
+        {
+          at: '2026-01-01T00:00:00.000Z',
+          chainIds: [input.chainId],
+        },
+      ),
+    ).rejects.toBeInstanceOf(SponsoredTransactions.AttributionConflictError)
+
+    expect(
+      await SponsorshipAttributions.get(db, { id: secondAttribution.id, orgId: 'org_1' }),
+    ).toMatchObject({ startsAt: null })
+    await db.close()
+  })
+
+  test('behavior: policy changes preserve unattributed retry snapshots', async () => {
+    const db = create()
+    await db.migrate()
+    await configure(db, null)
+    const existing = await SponsoredTransactions.upsert(db, { ...input, billable: true })
+    const attribution = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
+
+    const result = await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        sponsorshipAttributionId: attribution.id,
+        transactionHash: `0x${'33'.repeat(32)}`,
+      },
+      { at: '2026-01-01T00:00:00.000Z', chainIds: [input.chainId] },
+    )
+
+    expect(result).toMatchObject({
+      record: {
+        billable: true,
+        id: existing.id,
+        sponsorshipAttributionId: null,
+        transactionHash: `0x${'33'.repeat(32)}`,
+      },
+      status: 'billed',
+    })
+    expect(
+      await SponsorshipAttributions.get(db, { id: attribution.id, orgId: 'org_1' }),
+    ).toMatchObject({ startsAt: null })
+    await db.close()
+  })
+
+  test('behavior: later policy changes cannot raise an activated project cap', async () => {
+    const db = create()
+    await db.migrate()
+    await configure(db, '0.000001')
+    const project = await Projects.create(db, { name: 'App', orgId: 'org_1' })
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: project.id,
+    })
+    const promotion = {
+      at: '2026-01-01T00:00:00.000Z',
+      chainIds: [input.chainId],
+    } as const
+    await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '1',
+        sponsorshipAttributionId: attribution.id,
+      },
+      promotion,
+    )
+    await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      attributionSpendLimit: '0.000002',
+      durationDays: 90,
+    })
+
+    const result = await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '1',
+        sponsorshipAttributionId: attribution.id,
+        signPayload: `0x${'23'.repeat(32)}`,
+      },
+      promotion,
+    )
+    if (result.status === 'ineligible') throw new Error('Expected a promotion reservation.')
+    expect(result.record.billable).toBe(true)
+    expect(
+      (await SponsorshipAttributions.get(db, { id: attribution.id, orgId: 'org_1' }))?.spendLimit,
+    ).toBe('1')
+    await db.close()
+  })
+
+  test('behavior: preserves activation when the first sponsorship exceeds the cap', async () => {
+    const db = create()
+    await db.migrate()
+    await configure(db, '0')
+    const project = await Projects.create(db, { name: 'App', orgId: 'org_1' })
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: project.id,
+    })
+    const result = await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '1',
+        projectId: project.id,
+        sponsorshipAttributionId: attribution.id,
+      },
+      {
+        at: '2026-01-01T00:00:00.000Z',
+        chainIds: [input.chainId],
+      },
+    )
+    if (result.status === 'ineligible') throw new Error('Expected a promotion reservation.')
+    expect(result.record.billable).toBe(true)
+    expect(
+      await SponsorshipAttributions.get(db, { id: attribution.id, orgId: 'org_1' }),
+    ).toMatchObject({
+      endsAt: '2026-04-01T00:00:00.000Z',
+      startsAt: '2026-01-01T00:00:00.000Z',
+    })
+    expect(await SponsoredTransactions.listPending(db)).toMatchObject([{ billable: true }])
+    await db.close()
+  })
+
+  test('behavior: concurrent first sponsorships share one promotion window', async () => {
+    const schema = `t_${nanoid()}`
+    const firstDb = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    const secondDb = Db.postgres({ connectionString: Runtime.postgresUrl, schema })
+    await firstDb.migrate()
+    await configure(firstDb, '0.000002')
+    const project = await Projects.create(firstDb, { name: 'App', orgId: 'org_1' })
+    const attribution = await SponsorshipAttributions.resolveProject(firstDb, {
+      orgId: 'org_1',
+      projectId: project.id,
+    })
+    const reserve = (db: Db.Db, at: string, signPayload: string) =>
+      SponsoredTransactions.reservePromotion(
+        db,
+        {
+          ...input,
+          billable: false,
+          sponsorshipAttributionId: attribution.id,
+          signPayload,
+        },
+        {
+          at,
+          chainIds: [input.chainId],
+        },
+      )
+    const [first, second] = await Promise.all([
+      reserve(firstDb, '2026-01-01T00:00:00.000Z', `0x${'21'.repeat(32)}`),
+      reserve(secondDb, '2026-01-02T00:00:00.000Z', `0x${'22'.repeat(32)}`),
+    ])
+    expect(first.status).toBe('subsidized')
+    expect(second.status).toBe('subsidized')
+    const updated = await SponsorshipAttributions.get(firstDb, {
+      id: attribution.id,
+      orgId: 'org_1',
+    })
+    if (!updated?.endsAt || !updated.startsAt) throw new Error('Expected a promotion window.')
+    expect(Date.parse(updated.endsAt) - Date.parse(updated.startsAt)).toBe(90 * 86_400_000)
+    await Promise.all([firstDb.close(), secondDb.close()])
+  })
 })
 
 describe('listUnreported', () => {
@@ -407,6 +960,15 @@ describe('listUnreported', () => {
     // Pending, sandbox, and foreign-chain rows never report.
     await SponsoredTransactions.upsert(db, { ...input, signPayload: `0x${'13'.repeat(32)}` })
     await SponsoredTransactions.upsert(db, { ...input, billable: false, environment: 'sandbox', signPayload: `0x${'14'.repeat(32)}` }) // prettier-ignore
+    const promotion = await SponsoredTransactions.upsert(db, {
+      ...input,
+      billable: false,
+      signPayload: `0x${'16'.repeat(32)}`,
+    })
+    await SponsoredTransactions.finalize(db, promotion.id, {
+      feeAmount: '300',
+      finalizedAt: '2026-01-03T00:00:00.000Z',
+    })
 
     const rows = await SponsoredTransactions.listUnreported(db, { chainIds })
     expect(rows.map((row) => row.id)).toStrictEqual([first.id, second.id])