tapimo 0.14.0 → 0.15.0

package/src/db/tables/sponsoredTransactions.ts

@@ -1,4 +1,4 @@
-import type { ExpressionBuilder, Selectable } from 'kysely'
+import type { Selectable } from 'kysely'
 import { sql } from 'kysely'
 import { Value } from 'ox'
 
@@ -6,7 +6,7 @@ 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'
+import * as SponsorshipAttributions from './sponsorshipAttributions.js'
 
 /** Columns of the `sponsored_transactions` table, derived from `Schema.SponsoredTransaction`. */
 export type Table = db_Schema.SponsoredTransaction
@@ -31,6 +31,7 @@ export const failedIntentRecoveryTtlMs = 86_400_000
 export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
   const record: Record = {
     apiKeyId: input.apiKeyId,
+    sponsorshipAttributionId: input.sponsorshipAttributionId ?? null,
     billable: input.billable,
     chainId: input.chainId,
     createdAt: new Date().toISOString(),
@@ -39,6 +40,7 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     feeAmount: null,
     feeMax: input.feeMax ?? null,
     feeToken: input.feeToken ?? null,
+    finalizationAttemptedAt: null,
     finalizedAt: null,
     id: Id.generate('stx'),
     meterReportedAt: null,
@@ -74,6 +76,9 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
         }))
         // A shared envelope cannot transfer billing attribution between owners.
         .where('sponsored_transactions.orgId', '=', input.orgId)
+        .where(
+          sql<boolean>`sponsored_transactions.sponsorship_attribution_id IS NOT DISTINCT FROM ${record.sponsorshipAttributionId}`,
+        )
         .where(
           sql<boolean>`sponsored_transactions.project_id IS NOT DISTINCT FROM ${record.projectId}`,
         ),
@@ -89,6 +94,8 @@ export declare namespace upsert {
   type Input = {
     /** API key id (`key_…`) that requested sponsorship. */
     apiKeyId: string
+    /** Canonical sponsorship attribution id snapshotted at sponsorship time. */
+    sponsorshipAttributionId?: string | undefined
     /** Whether the sponsorship accrues billable spend; false for sandbox. */
     billable: boolean
     /** Chain the sponsored transaction targets. */
@@ -129,19 +136,44 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
     .executeTakeFirst()
 }
 
-/**
- * Lists pending sponsorships, oldest first, for the finalization job.
- *
- * @param db - The database.
- * @param options - Paging options.
- * @returns The pending records.
- */
+/** Lists sponsored transactions newest-first for administrative inspection. */
+export function list(db: Db.Db, options: list.Options): Promise<Record[]> {
+  let query = db.kysely.selectFrom('sponsored_transactions').selectAll()
+  const cursor = options.cursor
+  if (cursor !== undefined)
+    query = query.where((eb) =>
+      eb.or([
+        eb('createdAt', '<', cursor.createdAt),
+        eb.and([eb('createdAt', '=', cursor.createdAt), eb('id', '<', cursor.id)]),
+      ]),
+    )
+  return query.orderBy('createdAt', 'desc').orderBy('id', 'desc').limit(options.limit).execute()
+}
+
+export declare namespace list {
+  /** Pagination options for sponsored transactions. */
+  type Options = {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: Cursor | undefined
+    /** Maximum rows returned. */
+    limit: number
+  }
+
+  /** Cursor fields for the last transaction on the previous page. */
+  type Cursor = {
+    /** Sponsorship creation time. */
+    createdAt: string
+    /** Sponsored transaction id, used as a deterministic tie-breaker. */
+    id: string
+  }
+}
+
+/** Lists pending sponsorships, oldest first. */
 export function listPending(db: Db.Db, options: listPending.Options = {}): Promise<Record[]> {
   let query = db.kysely
     .selectFrom('sponsored_transactions')
     .selectAll()
     .where('status', '=', 'pending')
-    // `id` breaks same-millisecond `createdAt` ties for a deterministic scan.
     .orderBy('createdAt', 'asc')
     .orderBy('id', 'asc')
   if (options.limit !== undefined) query = query.limit(options.limit)
@@ -156,22 +188,57 @@ export declare namespace listPending {
   }
 }
 
+/** Claims the least-recently attempted pending sponsorships for one finalization pass. */
+export function claimPending(db: Db.Db, options: claimPending.Options): Promise<Record[]> {
+  return db.transaction(async (db) => {
+    const rows = await db.kysely
+      .selectFrom('sponsored_transactions')
+      .selectAll()
+      .where('status', '=', 'pending')
+      .orderBy(sql`finalization_attempted_at nulls first`)
+      .orderBy('createdAt', 'asc')
+      .orderBy('id', 'asc')
+      .limit(options.limit)
+      .forUpdate()
+      .skipLocked()
+      .execute()
+    if (rows.length === 0) return []
+    await db.kysely
+      .updateTable('sponsored_transactions')
+      .set({ finalizationAttemptedAt: options.attemptedAt })
+      .where(
+        'id',
+        'in',
+        rows.map((row) => row.id),
+      )
+      .execute()
+    return rows.map((row) => ({ ...row, finalizationAttemptedAt: options.attemptedAt }))
+  })
+}
+
+export declare namespace claimPending {
+  /** Claim timestamp and batch bound. */
+  type Options = {
+    /** Timestamp recorded before receipt lookups begin. */
+    attemptedAt: string
+    /** Maximum rows claimed by this pass. */
+    limit: number
+  }
+}
+
 /**
- * Lists hash-less fill intents, oldest first, for the reconciliation pass.
- * Failed intents are included only when the caller supplies a recovery floor.
+ * Lists active hash-less fill intents, oldest first, for reconciliation.
  *
  * @param db - The database.
  * @param options - Paging options.
- * @returns The pending intents.
+ * @returns The fill intents.
  */
 export function listIntents(db: Db.Db, options: listIntents.Options = {}): Promise<Record[]> {
   let query = db.kysely
     .selectFrom('sponsored_transactions')
     .selectAll()
-    .where(intentStatus(options.failedSince))
+    .where('status', '=', 'pending')
     .where('transactionHash', 'is', null)
-    // `pending` sorts after `failed`; descending keeps active intents first.
-    .orderBy('status', 'desc')
     .orderBy('createdAt', 'asc')
     .orderBy('id', 'asc')
   if (options.limit !== undefined) query = query.limit(options.limit)
@@ -180,9 +247,68 @@ export function listIntents(db: Db.Db, options: listIntents.Options = {}): Promi
 
 export declare namespace listIntents {
   /** Options for {@link listIntents}. */
-  type Options = listPending.Options & {
-    /** Include failed intents whose terminal timestamp is at or after this ISO timestamp. */
-    failedSince?: string | undefined
+  type Options = listPending.Options
+}
+
+/** Lists the oldest recoverable failed-intent timestamp for each chain. */
+export function listRecoveryWindows(
+  db: Db.Db,
+  options: listRecoveryWindows.Options,
+): Promise<listRecoveryWindows.Window[]> {
+  return db.kysely
+    .selectFrom('sponsored_transactions')
+    .select('chainId')
+    .select((eb) => eb.fn.min<string>('createdAt').as('createdAt'))
+    .where('finalizedAt', '>=', options.failedSince)
+    .where('status', '=', 'failed')
+    .where('transactionHash', 'is', null)
+    .groupBy('chainId')
+    .execute()
+}
+
+export declare namespace listRecoveryWindows {
+  /** Failed-intent recovery window options. */
+  type Options = {
+    /** Earliest terminal timestamp eligible for recovery. */
+    failedSince: string
+  }
+
+  /** One chain's failed-intent recovery window. */
+  type Window = {
+    /** Chain containing recoverable failed intents. */
+    chainId: number
+    /** Oldest eligible intent creation timestamp. */
+    createdAt: string
+  }
+}
+
+/** Lists pending and recoverable failed intents matching candidate sign payloads. */
+export function listRecoverableIntents(
+  db: Db.Db,
+  options: listRecoverableIntents.Options,
+): Promise<Record[]> {
+  if (options.signPayloads.length === 0) return Promise.resolve([])
+  return db.kysely
+    .selectFrom('sponsored_transactions')
+    .selectAll()
+    .where('signPayload', 'in', [...options.signPayloads])
+    .where((eb) =>
+      eb.or([
+        eb('status', '=', 'pending'),
+        eb.and([eb('finalizedAt', '>=', options.failedSince), eb('status', '=', 'failed')]),
+      ]),
+    )
+    .where('transactionHash', 'is', null)
+    .execute()
+}
+
+export declare namespace listRecoverableIntents {
+  /** Reconciliation candidate lookup options. */
+  type Options = {
+    /** Earliest terminal timestamp eligible for recovery. */
+    failedSince: string
+    /** Candidate fee-payer sign payloads. */
+    signPayloads: readonly string[]
   }
 }
 
@@ -220,7 +346,11 @@ export async function assignTransactionHash(
         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
+        const scope = limit.sponsorshipAttributionId
+          ? `${record.orgId}:${limit.sponsorshipAttributionId}`
+          : 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
@@ -248,6 +378,9 @@ export async function assignTransactionHash(
       if (record.status === 'failed' && limited) {
         const committed = await spend(tx, {
           ...(limit.billable === undefined ? {} : { billable: limit.billable }),
+          ...(limit.sponsorshipAttributionId === undefined
+            ? {}
+            : { sponsorshipAttributionId: limit.sponsorshipAttributionId }),
           chainIds: limit.chainIds,
           orgId: record.orgId,
           ...(limit.projectId === undefined ? {} : { projectId: limit.projectId }),
@@ -334,7 +467,11 @@ 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.
-    const scope = limit.projectId ? `${input.orgId}:${limit.projectId}` : input.orgId
+    const scope = limit.sponsorshipAttributionId
+      ? `${input.orgId}:${limit.sponsorshipAttributionId}`
+      : 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)
     const limited =
@@ -342,6 +479,9 @@ export async function reserve(
     if (limited) {
       const committed = await spend(tx, {
         ...(limit.billable === undefined ? {} : { billable: limit.billable }),
+        ...(limit.sponsorshipAttributionId === undefined
+          ? {}
+          : { sponsorshipAttributionId: limit.sponsorshipAttributionId }),
         chainIds: limit.chainIds,
         orgId: input.orgId,
         ...(limit.projectId === undefined ? {} : { projectId: limit.projectId }),
@@ -359,6 +499,8 @@ const billingLockClass = 1112294220
 export declare namespace reserve {
   /** The period spend limit enforced by {@link reserve}. */
   type Limit = {
+    /** Canonical attribution scope for independent limits. */
+    sponsorshipAttributionId?: string | undefined
     /** Billing snapshot whose rows consume this limit; omit for customer-billable spend. */
     billable?: boolean | undefined
     /** Chains whose spend counts (mainnet chain ids). */
@@ -378,11 +520,11 @@ export declare namespace reserve {
  */
 export function reservePromotion(
   db: Db.Db,
-  input: upsert.Input,
+  input: reservePromotion.Input,
   options: reservePromotion.Options,
 ): Promise<reservePromotion.Result> {
   return db.transaction(async (tx) => {
-    const scope = `${input.orgId}:${options.projectId}`
+    const scope = `${input.orgId}:${input.sponsorshipAttributionId}`
     await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${scope}))`.execute(tx.kysely) // prettier-ignore
     const existing = await tx.kysely
       .selectFrom('sponsored_transactions')
@@ -391,9 +533,21 @@ export function reservePromotion(
       .forUpdate()
       .executeTakeFirst()
     if (existing) {
-      if (existing.orgId !== input.orgId || existing.projectId !== options.projectId)
+      if (
+        existing.orgId !== input.orgId ||
+        (existing.sponsorshipAttributionId !== null &&
+          existing.sponsorshipAttributionId !== input.sponsorshipAttributionId) ||
+        existing.projectId !== (input.projectId ?? null)
+      )
         throw new AttributionConflictError()
-      const stored = await upsert(tx, input)
+      // A pre-promotion row keeps its null attribution and billable snapshot
+      // when policy changes before an idempotent retry.
+      const stored = await upsert(
+        tx,
+        existing.sponsorshipAttributionId === null
+          ? { ...input, billable: existing.billable, sponsorshipAttributionId: undefined }
+          : 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, {
@@ -403,18 +557,21 @@ export function reservePromotion(
         })
         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) {
+      if (!stored.billable && stored.sponsorshipAttributionId !== null) {
+        const attribution = await SponsorshipAttributions.get(tx, {
+          id: input.sponsorshipAttributionId,
+          orgId: input.orgId,
+        })
+        if (!attribution?.startsAt) throw new PromotionActivationError()
+        if (attribution.spendLimit !== null) {
           const committed = await spend(tx, {
+            sponsorshipAttributionId: input.sponsorshipAttributionId,
             billable: false,
             chainIds: options.chainIds,
             orgId: input.orgId,
-            projectId: options.projectId,
-            since: project.sponsorshipSubsidyStartsAt,
+            since: attribution.startsAt,
           })
-          if (committed > BigInt(project.sponsorshipSpendLimit)) throw new PeriodSpendLimitError()
+          if (committed > BigInt(attribution.spendLimit)) throw new PeriodSpendLimitError()
         }
       }
       return { record: stored, status: stored.billable ? 'billed' : 'subsidized' }
@@ -429,21 +586,19 @@ export function reservePromotion(
     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)
-    )
+    const current = await SponsorshipAttributions.get(tx, {
+      id: input.sponsorshipAttributionId,
+      orgId: input.orgId,
+    })
+    if (current?.endsAt && Date.parse(options.at) >= Date.parse(current.endsAt))
       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,
+    const attribution = await SponsorshipAttributions.activate(tx, {
+      id: input.sponsorshipAttributionId,
       endsAt,
-      id: options.projectId,
       orgId: input.orgId,
       spendLimit:
         organization.sponsorshipSubsidyProjectSpendLimit === null
@@ -452,19 +607,19 @@ export function reservePromotion(
               organization.sponsorshipSubsidyProjectSpendLimit,
               Fees.tokenDecimals,
             ).toString(),
+      startsAt: options.at,
     })
-    if (!project?.sponsorshipSubsidyStartsAt || !project.sponsorshipSubsidyEndsAt)
-      throw new PromotionActivationError()
     let record = await upsert(tx, input)
-    if (project.sponsorshipSpendLimit !== null) {
+    if (!attribution.startsAt) throw new PromotionActivationError()
+    if (attribution.spendLimit !== null) {
       const committed = await spend(tx, {
+        sponsorshipAttributionId: input.sponsorshipAttributionId,
         billable: false,
         chainIds: options.chainIds,
         orgId: input.orgId,
-        projectId: options.projectId,
-        since: project.sponsorshipSubsidyStartsAt,
+        since: attribution.startsAt,
       })
-      if (committed > BigInt(project.sponsorshipSpendLimit)) {
+      if (committed > BigInt(attribution.spendLimit)) {
         record = await tx.kysely
           .updateTable('sponsored_transactions')
           .set({ billable: true })
@@ -487,16 +642,20 @@ export function reservePromotion(
 }
 
 export declare namespace reservePromotion {
-  /** Project promotion window and cap. */
+  /** Sponsored transaction with its canonical attribution snapshot. */
+  type Input = upsert.Input & {
+    /** Canonical sponsorship attribution id. */
+    sponsorshipAttributionId: string
+  }
+
+  /** Attribution 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. */
+    /** Customer billing limit used when the attribution 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. */
@@ -508,7 +667,7 @@ export declare namespace reservePromotion {
         status: 'billed' | 'subsidized'
       }
     | {
-        /** The current organization or project policy does not grant a promotion. */
+        /** The current organization or attribution policy does not grant a promotion. */
         status: 'ineligible'
       }
 }
@@ -523,7 +682,15 @@ export declare namespace reservePromotion {
  * @returns The committed spend in base units.
  */
 export async function spend(db: Db.Db, options: spend.Options): Promise<bigint> {
-  const { billable, chainIds, environment = 'production', orgId, projectId, since } = options
+  const {
+    sponsorshipAttributionId,
+    billable,
+    chainIds,
+    environment = 'production',
+    orgId,
+    projectId,
+    since,
+  } = options
   let query = db.kysely
     .selectFrom('sponsored_transactions')
     .select([
@@ -538,6 +705,8 @@ export async function spend(db: Db.Db, options: spend.Options): Promise<bigint>
     .where('chainId', 'in', [...chainIds])
     .where('createdAt', '>=', since)
   if (billable !== undefined) query = query.where('billable', '=', billable)
+  if (sponsorshipAttributionId !== undefined)
+    query = query.where('sponsorshipAttributionId', '=', sponsorshipAttributionId)
   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.
@@ -552,6 +721,8 @@ export async function spend(db: Db.Db, options: spend.Options): Promise<bigint>
 export declare namespace spend {
   /** Options for {@link spend}. */
   type Options = {
+    /** Canonical sponsorship attribution id whose spend counts. */
+    sponsorshipAttributionId?: string | undefined
     /** Billing snapshot to count; omit for the existing production-billable behavior. */
     billable?: boolean | undefined
     /** Chains whose spend counts (mainnet chain ids). */
@@ -690,17 +861,6 @@ export async function markReported(db: Db.Db, id: string, at: string): Promise<v
     .execute()
 }
 
-/** Intent status predicate; failed rows are recovery candidates only briefly. */
-function intentStatus(failedSince: string | undefined) {
-  return (eb: ExpressionBuilder<Db.Database, 'sponsored_transactions'>) => {
-    if (failedSince === undefined) return eb('status', '=', 'pending')
-    return eb.or([
-      eb('status', '=', 'pending'),
-      eb.and([eb('status', '=', 'failed'), eb('finalizedAt', '>=', failedSince)]),
-    ])
-  }
-}
-
 /** Thrown by {@link reserve} when recording would exceed the org's period spend limit. */
 export class PeriodSpendLimitError extends Error {
   override name = 'SponsoredTransactions.PeriodSpendLimitError'
@@ -711,7 +871,7 @@ export class PromotionActivationError extends Error {
   override name = 'SponsoredTransactions.PromotionActivationError'
 }
 
-/** Thrown when one signed envelope is presented with conflicting project attribution. */
+/** Thrown when one signed envelope is presented with conflicting attribution. */
 export class AttributionConflictError extends Error {
   override name = 'SponsoredTransactions.AttributionConflictError'
 }

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

@@ -0,0 +1,160 @@
+import { nanoid } from 'nanoid'
+
+import * as Runtime from '../../../test/runtime.js'
+import * as Db from '../Db.js'
+import * as SponsoredTransactions from './sponsoredTransactions.js'
+import * as SponsorshipAttributions from './sponsorshipAttributions.js'
+
+const create = () => Db.postgres({ connectionString: Runtime.postgresUrl, schema: `t_${nanoid()}` })
+
+describe('getExternal', () => {
+  test('behavior: reads only existing attributions in the owning organization', async () => {
+    const db = create()
+    await db.migrate()
+    const attribution = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'partner-app',
+      orgId: 'org_1',
+    })
+
+    expect(
+      await SponsorshipAttributions.getExternal(db, { externalId: 'partner-app', orgId: 'org_1' }),
+    ).toStrictEqual(attribution)
+    expect(
+      await SponsorshipAttributions.getExternal(db, { externalId: 'partner-app', orgId: 'org_2' }),
+    ).toBeUndefined()
+    expect(
+      await SponsorshipAttributions.getExternal(db, { externalId: 'unknown-app', orgId: 'org_1' }),
+    ).toBeUndefined()
+    expect(await db.kysely.selectFrom('sponsorship_attributions').selectAll().execute()).toStrictEqual([attribution]) // prettier-ignore
+    await db.close()
+  })
+})
+
+describe('resolveExternal', () => {
+  test('behavior: resolves one canonical id per organization and external id', async () => {
+    const db = create()
+    await db.migrate()
+    const options = { externalId: 'privy-account-1', orgId: 'org_1' }
+
+    const [first, retried, otherOrganization] = await Promise.all([
+      SponsorshipAttributions.resolveExternal(db, options),
+      SponsorshipAttributions.resolveExternal(db, options),
+      SponsorshipAttributions.resolveExternal(db, { ...options, orgId: 'org_2' }),
+    ])
+
+    expect(retried.id).toBe(first.id)
+    expect(otherOrganization.id).not.toBe(first.id)
+    await db.close()
+  })
+})
+
+describe('resolveProject', () => {
+  test('behavior: resolves Tempo Projects through the canonical attribution table', async () => {
+    const db = create()
+    await db.migrate()
+
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: 'prj_1',
+    })
+
+    expect(attribution).toMatchObject({ externalId: null, orgId: 'org_1', projectId: 'prj_1' })
+    await db.close()
+  })
+
+  test('migration: preserves legacy project promotion state and spend attribution', async () => {
+    const db = create()
+    await db.migrate()
+    await db.kysely
+      .insertInto('projects')
+      .values({
+        createdAt: '2026-01-01T00:00:00.000Z',
+        id: 'prj_1',
+        name: 'App',
+        orgId: 'org_1',
+        sponsorshipSubsidyEndsAt: '2026-04-01T00:00:00.000Z',
+        sponsorshipSubsidyStartsAt: '2026-01-01T00:00:00.000Z',
+        sponsorshipSpendLimit: '1000000',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      })
+      .execute()
+    await SponsoredTransactions.upsert(db, {
+      apiKeyId: 'key_1',
+      billable: false,
+      chainId: 4217,
+      environment: 'production',
+      feeMax: '500000',
+      orgId: 'org_1',
+      projectId: 'prj_1',
+      signPayload: `0x${'11'.repeat(32)}`,
+      transaction: `0x${'22'.repeat(32)}`,
+    })
+    for (const name of [
+      '0156_project_sponsorship_attributions',
+      '0157_project_sponsored_transaction_attributions',
+    ]) {
+      const migration = Db.migrations.find((candidate) => candidate.name === name)
+      if (!migration) throw new Error(`Expected ${name}.`)
+      await migration.up(db.kysely).execute()
+    }
+
+    const attribution = await SponsorshipAttributions.resolveProject(db, {
+      orgId: 'org_1',
+      projectId: 'prj_1',
+    })
+    expect(attribution).toMatchObject({
+      endsAt: '2026-04-01T00:00:00.000Z',
+      spendLimit: '1000000',
+      startsAt: '2026-01-01T00:00:00.000Z',
+    })
+    expect(await SponsoredTransactions.listPending(db)).toMatchObject([
+      { sponsorshipAttributionId: attribution.id },
+    ])
+    await db.close()
+  })
+})
+
+describe('activate', () => {
+  test('behavior: preserves the first promotion snapshot', async () => {
+    const db = create()
+    await db.migrate()
+    const attribution = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
+    const options = {
+      endsAt: '2026-04-01T00:00:00.000Z',
+      id: attribution.id,
+      orgId: 'org_1',
+      spendLimit: '1000000',
+      startsAt: '2026-01-01T00:00:00.000Z',
+    }
+
+    const first = await SponsorshipAttributions.activate(db, options)
+    const retried = await SponsorshipAttributions.activate(db, {
+      ...options,
+      endsAt: '2027-04-01T00:00:00.000Z',
+      spendLimit: '2000000',
+      startsAt: '2027-01-01T00:00:00.000Z',
+    })
+
+    expect(retried).toStrictEqual(first)
+    await db.close()
+  })
+})
+
+describe('get', () => {
+  test('behavior: does not cross organization boundaries', async () => {
+    const db = create()
+    await db.migrate()
+    const attribution = await SponsorshipAttributions.resolveExternal(db, {
+      externalId: 'privy-account-1',
+      orgId: 'org_1',
+    })
+
+    expect(
+      await SponsorshipAttributions.get(db, { id: attribution.id, orgId: 'org_2' }),
+    ).toBeUndefined()
+    await db.close()
+  })
+})