tapimo 0.12.0 → 0.14.0

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

@@ -3,6 +3,7 @@ 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 SponsoredTransactions from './sponsoredTransactions.js'
 
 const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
@@ -124,6 +125,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()
@@ -393,6 +408,320 @@ 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, projectSpendLimit: string | null) {
+    await Organizations.create(db, { id: 'org_1', name: 'Privy' })
+    await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      durationDays: 90,
+      projectSpendLimit,
+    })
+  }
+
+  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 result = await SponsoredTransactions.reservePromotion(
+      db,
+      { ...input, billable: false, projectId: project.id },
+      {
+        at: '2026-01-01T00:00:00.000Z',
+        chainIds: [input.chainId],
+        projectId: project.id,
+      },
+    )
+    const updated = await Projects.get(db, project.id)
+    expect({
+      endsAt: updated?.sponsorshipSubsidyEndsAt,
+      startsAt: updated?.sponsorshipSubsidyStartsAt,
+    }).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((await Projects.get(db, project.id))?.sponsorshipSpendLimit).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 result = await SponsoredTransactions.reservePromotion(
+      db,
+      { ...input, billable: false, feeMax: '100', projectId: project.id },
+      {
+        at: '2026-01-01T00:00:00.000Z',
+        chainIds: [input.chainId],
+        projectId: project.id,
+      },
+    )
+    if (result.status === 'ineligible') throw new Error('Expected a promotion reservation.')
+    expect(result.record.billable).toBe(false)
+    expect(await Projects.get(db, project.id)).toMatchObject({
+      sponsorshipSubsidyEndsAt: '2026-04-01T00:00:00.000Z',
+      sponsorshipSubsidyStartsAt: '2026-01-01T00:00:00.000Z',
+      sponsorshipSpendLimit: null,
+    })
+    await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '100',
+        projectId: project.id,
+        signPayload: `0x${'24'.repeat(32)}`,
+      },
+      {
+        at: '2026-01-02T00:00:00.000Z',
+        chainIds: [input.chainId],
+        projectId: project.id,
+      },
+    )
+    expect((await Projects.get(db, project.id))?.sponsorshipSpendLimit).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' })
+    await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      durationDays: 90,
+      projectSpendLimit: '0.000002',
+    })
+
+    const result = await SponsoredTransactions.reservePromotion(
+      db,
+      { ...input, billable: false, feeMax: '2', projectId: project.id },
+      {
+        at: '2026-01-01T00:00:00.000Z',
+        chainIds: [input.chainId],
+        projectId: project.id,
+      },
+    )
+
+    expect(result.status).toBe('subsidized')
+    expect((await Projects.get(db, project.id))?.sponsorshipSpendLimit).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' })
+    await SponsoredTransactions.upsert(db, { ...input, projectId: first.id })
+
+    await expect(
+      SponsoredTransactions.reservePromotion(
+        db,
+        { ...input, billable: false, projectId: second.id },
+        {
+          at: '2026-01-01T00:00:00.000Z',
+          chainIds: [input.chainId],
+          projectId: second.id,
+        },
+      ),
+    ).rejects.toBeInstanceOf(SponsoredTransactions.AttributionConflictError)
+
+    expect(await Projects.get(db, second.id)).toMatchObject({
+      sponsorshipSubsidyEndsAt: null,
+      sponsorshipSubsidyStartsAt: 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 promotion = {
+      at: '2026-01-01T00:00:00.000Z',
+      chainIds: [input.chainId],
+      projectId: project.id,
+    } as const
+    await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '1',
+        projectId: project.id,
+      },
+      promotion,
+    )
+    await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      durationDays: 90,
+      projectSpendLimit: '0.000002',
+    })
+
+    const result = await SponsoredTransactions.reservePromotion(
+      db,
+      {
+        ...input,
+        billable: false,
+        feeMax: '1',
+        projectId: project.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 Projects.get(db, project.id))?.sponsorshipSpendLimit).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 result = await SponsoredTransactions.reservePromotion(
+      db,
+      { ...input, billable: false, feeMax: '1', projectId: project.id },
+      {
+        at: '2026-01-01T00:00:00.000Z',
+        chainIds: [input.chainId],
+        projectId: project.id,
+      },
+    )
+    if (result.status === 'ineligible') throw new Error('Expected a promotion reservation.')
+    expect(result.record.billable).toBe(true)
+    expect(await Projects.get(db, project.id)).toMatchObject({
+      sponsorshipSubsidyEndsAt: '2026-04-01T00:00:00.000Z',
+      sponsorshipSubsidyStartsAt: '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 reserve = (db: Db.Db, at: string, signPayload: string) =>
+      SponsoredTransactions.reservePromotion(
+        db,
+        {
+          ...input,
+          billable: false,
+          projectId: project.id,
+          signPayload,
+        },
+        {
+          at,
+          chainIds: [input.chainId],
+          projectId: project.id,
+        },
+      )
+    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 Projects.get(firstDb, project.id)
+    if (!updated?.sponsorshipSubsidyEndsAt || !updated.sponsorshipSubsidyStartsAt)
+      throw new Error('Expected a promotion window.')
+    expect(
+      Date.parse(updated.sponsorshipSubsidyEndsAt) - Date.parse(updated.sponsorshipSubsidyStartsAt),
+    ).toBe(90 * 86_400_000)
+    await Promise.all([firstDb.close(), secondDb.close()])
+  })
 })
 
 describe('listUnreported', () => {
@@ -407,6 +736,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])

package/src/db/tables/sponsoredTransactions.ts

@@ -1,9 +1,12 @@
 import type { ExpressionBuilder, Selectable } from 'kysely'
 import { sql } from 'kysely'
+import { Value } from 'ox'
 
+import * as Fees from '../../internal/Fees.js'
 import * as Id from '../../internal/Id.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
+import * as Projects from './projects.js'
 
 /** Columns of the `sponsored_transactions` table, derived from `Schema.SponsoredTransaction`. */
 export type Table = db_Schema.SponsoredTransaction
@@ -46,7 +49,7 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     transaction: input.transaction,
     transactionHash: input.transactionHash ?? null,
   }
-  return await db.kysely
+  const stored = await db.kysely
     .insertInto('sponsored_transactions')
     .values(record)
     .onConflict((oc) =>
@@ -69,11 +72,16 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
           finalizedAt: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN NULL ELSE ${eb.ref('sponsored_transactions.finalizedAt')} END`,
           status: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN 'pending' ELSE ${eb.ref('sponsored_transactions.status')} END`,
         }))
-        // A shared envelope cannot transfer billing attribution across tenants.
-        .where('sponsored_transactions.orgId', '=', input.orgId),
+        // A shared envelope cannot transfer billing attribution between owners.
+        .where('sponsored_transactions.orgId', '=', input.orgId)
+        .where(
+          sql<boolean>`sponsored_transactions.project_id IS NOT DISTINCT FROM ${record.projectId}`,
+        ),
     )
     .returningAll()
-    .executeTakeFirstOrThrow()
+    .executeTakeFirst()
+  if (!stored) throw new AttributionConflictError()
+  return stored
 }
 
 export declare namespace upsert {
@@ -208,8 +216,13 @@ export async function assignTransactionHash(
         (record.finalizedAt === null || record.finalizedAt < failedSince)
       )
         return
-      if (record.status === 'failed' && record.billable && limit)
-        await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${record.orgId}))`.execute(tx.kysely) // prettier-ignore
+      const limited =
+        limit !== undefined &&
+        (limit.billable === undefined ? record.billable : record.billable === limit.billable)
+      if (record.status === 'failed' && limited) {
+        const scope = limit.projectId ? `${record.orgId}:${limit.projectId}` : record.orgId
+        await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${scope}))`.execute(tx.kysely) // prettier-ignore
+      }
       let query = tx.kysely
         .updateTable('sponsored_transactions')
         .set({
@@ -232,10 +245,12 @@ export async function assignTransactionHash(
         )
       const updated = await query.executeTakeFirst()
       if (updated.numUpdatedRows === 0n) return
-      if (record.status === 'failed' && record.billable && limit) {
+      if (record.status === 'failed' && limited) {
         const committed = await spend(tx, {
+          ...(limit.billable === undefined ? {} : { billable: limit.billable }),
           chainIds: limit.chainIds,
           orgId: record.orgId,
+          ...(limit.projectId === undefined ? {} : { projectId: limit.projectId }),
           since: limit.since,
         })
         if (committed > limit.max) throw new PeriodSpendLimitError()
@@ -319,12 +334,17 @@ export async function reserve(
   return db.transaction(async (tx) => {
     // `hashtext` maps the org id into the advisory-lock keyspace; the class
     // namespaces it against other advisory-lock users. Released at tx end.
-    await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${input.orgId}))`.execute(tx.kysely) // prettier-ignore
+    const scope = limit.projectId ? `${input.orgId}:${limit.projectId}` : input.orgId
+    await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${scope}))`.execute(tx.kysely) // prettier-ignore
     const record = await upsert(tx, input)
-    if (record.billable) {
+    const limited =
+      limit.billable === undefined ? record.billable : record.billable === limit.billable
+    if (limited) {
       const committed = await spend(tx, {
+        ...(limit.billable === undefined ? {} : { billable: limit.billable }),
         chainIds: limit.chainIds,
         orgId: input.orgId,
+        ...(limit.projectId === undefined ? {} : { projectId: limit.projectId }),
         since: limit.since,
       })
       if (committed > limit.max) throw new PeriodSpendLimitError()
@@ -339,15 +359,160 @@ const billingLockClass = 1112294220
 export declare namespace reserve {
   /** The period spend limit enforced by {@link reserve}. */
   type Limit = {
+    /** Billing snapshot whose rows consume this limit; omit for customer-billable spend. */
+    billable?: boolean | undefined
     /** Chains whose spend counts (mainnet chain ids). */
     chainIds: readonly number[]
     /** Limit in fee-token base units. */
     max: bigint
+    /** Project scope for independent limits; omit for the organization-wide budget. */
+    projectId?: string | undefined
     /** Window start (ISO 8601). */
     since: string
   }
 }
 
+/**
+ * Applies the current promotion policy and records the sponsorship atomically.
+ * Exhausted promotions retain their window and fall back to customer billing.
+ */
+export function reservePromotion(
+  db: Db.Db,
+  input: upsert.Input,
+  options: reservePromotion.Options,
+): Promise<reservePromotion.Result> {
+  return db.transaction(async (tx) => {
+    const scope = `${input.orgId}:${options.projectId}`
+    await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${scope}))`.execute(tx.kysely) // prettier-ignore
+    const existing = await tx.kysely
+      .selectFrom('sponsored_transactions')
+      .selectAll()
+      .where('signPayload', '=', input.signPayload)
+      .forUpdate()
+      .executeTakeFirst()
+    if (existing) {
+      if (existing.orgId !== input.orgId || existing.projectId !== options.projectId)
+        throw new AttributionConflictError()
+      const stored = await upsert(tx, input)
+      if (stored.billable && options.billingLimit) {
+        await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${input.orgId}))`.execute(tx.kysely) // prettier-ignore
+        const billed = await spend(tx, {
+          chainIds: options.billingLimit.chainIds,
+          orgId: input.orgId,
+          since: options.billingLimit.since,
+        })
+        if (billed > options.billingLimit.max) throw new PeriodSpendLimitError()
+      }
+      if (!stored.billable) {
+        const project = await Projects.get(tx, options.projectId)
+        if (!project?.sponsorshipSubsidyStartsAt) throw new PromotionActivationError()
+        if (project.sponsorshipSpendLimit !== null) {
+          const committed = await spend(tx, {
+            billable: false,
+            chainIds: options.chainIds,
+            orgId: input.orgId,
+            projectId: options.projectId,
+            since: project.sponsorshipSubsidyStartsAt,
+          })
+          if (committed > BigInt(project.sponsorshipSpendLimit)) throw new PeriodSpendLimitError()
+        }
+      }
+      return { record: stored, status: stored.billable ? 'billed' : 'subsidized' }
+    }
+
+    const organization = await tx.kysely
+      .selectFrom('organizations')
+      .select(['sponsorshipSubsidyDurationDays', 'sponsorshipSubsidyProjectSpendLimit'])
+      .where('id', '=', input.orgId)
+      .forShare()
+      .executeTakeFirst()
+    if (!organization || organization.sponsorshipSubsidyDurationDays === null)
+      return { status: 'ineligible' }
+
+    const current = await Projects.get(tx, options.projectId)
+    if (!current || current.orgId !== input.orgId) throw new PromotionActivationError()
+    if (
+      current.sponsorshipSubsidyEndsAt !== null &&
+      Date.parse(options.at) >= Date.parse(current.sponsorshipSubsidyEndsAt)
+    )
+      return { status: 'ineligible' }
+
+    const endsAt = new Date(
+      Date.parse(options.at) + organization.sponsorshipSubsidyDurationDays * 86_400_000,
+    ).toISOString()
+    const project = await Projects.activateSponsorship(tx, {
+      at: options.at,
+      endsAt,
+      id: options.projectId,
+      orgId: input.orgId,
+      spendLimit:
+        organization.sponsorshipSubsidyProjectSpendLimit === null
+          ? null
+          : Value.from(
+              organization.sponsorshipSubsidyProjectSpendLimit,
+              Fees.tokenDecimals,
+            ).toString(),
+    })
+    if (!project?.sponsorshipSubsidyStartsAt || !project.sponsorshipSubsidyEndsAt)
+      throw new PromotionActivationError()
+    let record = await upsert(tx, input)
+    if (project.sponsorshipSpendLimit !== null) {
+      const committed = await spend(tx, {
+        billable: false,
+        chainIds: options.chainIds,
+        orgId: input.orgId,
+        projectId: options.projectId,
+        since: project.sponsorshipSubsidyStartsAt,
+      })
+      if (committed > BigInt(project.sponsorshipSpendLimit)) {
+        record = await tx.kysely
+          .updateTable('sponsored_transactions')
+          .set({ billable: true })
+          .where('id', '=', record.id)
+          .returningAll()
+          .executeTakeFirstOrThrow()
+        if (options.billingLimit) {
+          await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${input.orgId}))`.execute(tx.kysely) // prettier-ignore
+          const billed = await spend(tx, {
+            chainIds: options.billingLimit.chainIds,
+            orgId: input.orgId,
+            since: options.billingLimit.since,
+          })
+          if (billed > options.billingLimit.max) throw new PeriodSpendLimitError()
+        }
+      }
+    }
+    return { record, status: record.billable ? 'billed' : 'subsidized' }
+  })
+}
+
+export declare namespace reservePromotion {
+  /** Project promotion window and cap. */
+  type Options = {
+    /** Timestamp of the recorded sponsorship that may activate the window. */
+    at: string
+    /** Customer billing limit used when the project promotion is exhausted. */
+    billingLimit?: reserve.Limit | undefined
+    /** Mainnet chains whose promotional spend counts. */
+    chainIds: readonly number[]
+    /** Project receiving the independent promotion. */
+    projectId: string
+  }
+
+  /** Promotion reservation outcome. */
+  type Result =
+    | {
+        /** Stored sponsorship. */
+        record: Record
+        /** Whether Tempo or the customer pays for the stored sponsorship. */
+        status: 'billed' | 'subsidized'
+      }
+    | {
+        /** The current organization or project policy does not grant a promotion. */
+        status: 'ineligible'
+      }
+}
+
 /**
  * Billable spend committed since a cutoff, in fee-token base units: finalized
  * rows at their actual fee plus pending rows at their signed fee cap, so
@@ -358,8 +523,8 @@ export declare namespace reserve {
  * @returns The committed spend in base units.
  */
 export async function spend(db: Db.Db, options: spend.Options): Promise<bigint> {
-  const { chainIds, environment = 'production', orgId, since } = options
-  const query = db.kysely
+  const { billable, chainIds, environment = 'production', orgId, projectId, since } = options
+  let query = db.kysely
     .selectFrom('sponsored_transactions')
     .select([
       sql<string>`coalesce(sum(case when status = 'finalized' then fee_amount::numeric else 0 end), 0)`.as('finalized'), // prettier-ignore
@@ -372,22 +537,31 @@ export async function spend(db: Db.Db, options: spend.Options): Promise<bigint>
     .where('status', 'in', ['finalized', 'pending'])
     .where('chainId', 'in', [...chainIds])
     .where('createdAt', '>=', since)
+  if (billable !== undefined) query = query.where('billable', '=', billable)
+  if (projectId !== undefined) query = query.where('projectId', '=', projectId)
   // Production mirrors the sponsorship gate — only billable rows count. Sandbox
   // rows are non-billable by construction, so the figure is display-only.
-  const row = await (environment === 'production' ? query.where('billable', '=', true) : query) //
-    .executeTakeFirstOrThrow()
+  const row = await (
+    environment === 'production' && billable === undefined
+      ? query.where('billable', '=', true)
+      : query
+  ).executeTakeFirstOrThrow()
   return BigInt(row.finalized) + BigInt(row.pending)
 }
 
 export declare namespace spend {
   /** Options for {@link spend}. */
   type Options = {
+    /** Billing snapshot to count; omit for the existing production-billable behavior. */
+    billable?: boolean | undefined
     /** Chains whose spend counts (mainnet chain ids). */
     chainIds: readonly number[]
     /** Environment whose spend counts; production mirrors the billing gate, sandbox is display-only. Defaults to `production`. */
     environment?: Table['environment'] | undefined
     /** Organization id (`org_…`) the spend attributes to. */
     orgId: string
+    /** Project whose spend counts; omit for organization-wide spend. */
+    projectId?: string | undefined
     /** Window start (ISO 8601); rows created earlier are out of scope. */
     since: string
   }
@@ -531,3 +705,13 @@ function intentStatus(failedSince: string | undefined) {
 export class PeriodSpendLimitError extends Error {
   override name = 'SponsoredTransactions.PeriodSpendLimitError'
 }
+
+/** Thrown when a promotional window cannot be activated consistently. */
+export class PromotionActivationError extends Error {
+  override name = 'SponsoredTransactions.PromotionActivationError'
+}
+
+/** Thrown when one signed envelope is presented with conflicting project attribution. */
+export class AttributionConflictError extends Error {
+  override name = 'SponsoredTransactions.AttributionConflictError'
+}