tapimo 0.13.0 → 0.14.0

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

@@ -18,6 +18,7 @@ import type * as Db from '../../db/Db.js'
 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 SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
 import * as core_Billing from '../management/Billing.js'
@@ -104,6 +105,13 @@ const keys = [
     scopes: ['rpc-relay:sponsor'],
     token: 'secret_unattributed',
   },
+  {
+    id: 'key_unattributed_prod',
+    orgId: 'org_1',
+    environment: 'production',
+    scopes: ['rpc-relay:sponsor'],
+    token: 'secret_unattributed_prod',
+  },
 ] as const satisfies readonly TestApp.kvStore.Key[]
 
 describe('behavior: Zone chain routing', () => {
@@ -525,7 +533,7 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
     const body = await relayRequest(app, {
       method: 'eth_signRawTransaction',
       params: [await signSponsorable()],
-      token: 'secret_unattributed',
+      token: 'secret_unattributed_prod',
     })
     expect(body.error).toBeUndefined()
     expect(Transaction.deserialize(body.result as `0x76${string}`).feePayerSignature).toBeDefined()
@@ -535,6 +543,28 @@ describe.skipIf(runtime.mode !== 'localnet')('behavior: sponsorship', () => {
     expect(row?.projectId).toBeNull()
   })
 
+  test('behavior: organization-attributed keys use a validated request project', async () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: 'org_1', name: 'One' })
+    const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
+    const app = TestApp.create({
+      auth: { keys },
+      db,
+      relay: { feePayer: { account: feePayerAccount } },
+    })
+
+    const body = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable()],
+      projectId: project.id,
+      token: 'secret_unattributed_prod',
+    })
+    expect(body.error).toBeUndefined()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row?.projectId).toBe(project.id)
+  })
+
   test('behavior: batches aggregate sponsorship rejections without retaining payloads', async () => {
     const db = TestApp.database()
     const entries: Log.Entry[] = []
@@ -948,6 +978,18 @@ describe('behavior: mainnet billing gate', () => {
     await TestApp.verifiedSeed(db, Viem.chainId.mainnet)
   }
 
+  /** Configures one attributed project for Tempo-funded sponsorship. */
+  async function configureSubsidy(db: ReturnType<typeof TestApp.database>) {
+    await Organizations.create(db, { id: 'org_1', name: 'Privy' })
+    await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      durationDays: 90,
+      projectSpendLimit: '100.00',
+    })
+    const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
+    await activate(db)
+    return project
+  }
+
   // Gas prices are attodollars (1e-18 USD) per gas; the signed cap in
   // fee-token units is ceil(gas × maxFeePerGas / 1e12). The helper's default
   // envelope (100k gas × 1e6 atto) caps at 1 microdollar — negligible.
@@ -956,6 +998,172 @@ 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 () => {
+    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()
+
+    const [row] = await SponsoredTransactions.listPending(db)
+    expect(row).toMatchObject({
+      billable: false,
+      orgId: 'org_1',
+      projectId: project.id,
+    })
+    const updated = await Projects.get(db, project.id)
+    const startsAt = updated?.sponsorshipSubsidyStartsAt
+    const endsAt = updated?.sponsorshipSubsidyEndsAt
+    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 () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: 'org_1', name: 'Privy' })
+    await Organizations.setSponsorshipSubsidy(db, 'org_1', {
+      durationDays: 90,
+      projectSpendLimit: '0.000001',
+    })
+    const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
+    await activate(db)
+    const app = createMainnetApp({ db })
+
+    const subsidized = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      projectId: project.id,
+      token: 'secret_unattributed_prod',
+    })
+    const billed = await relayRequest(app, {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet, nonce: 1 })],
+      projectId: project.id,
+      token: 'secret_unattributed_prod',
+    })
+
+    expect({ billed: billed.error, subsidized: subsidized.error }).toStrictEqual({
+      billed: undefined,
+      subsidized: undefined,
+    })
+    expect(await SponsoredTransactions.listPending(db)).toMatchObject([
+      { billable: false, projectId: project.id },
+      { billable: true, projectId: project.id },
+    ])
+  })
+
+  test('behavior: uncapped project 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', {
+      durationDays: 90,
+      projectSpendLimit: null,
+    })
+    const project = await Projects.create(db, { name: 'Privy app', orgId: 'org_1' })
+    await activate(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 },
+    ])
+  })
+
+  test('behavior: project 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', {
+      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 }), {
+      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(await SponsoredTransactions.listPending(db)).toHaveLength(0)
+    expect(await Projects.get(db, project.id)).toMatchObject({
+      sponsorshipSubsidyEndsAt: null,
+      sponsorshipSubsidyStartsAt: null,
+    })
+  })
+
+  test('behavior: subsidized organization keys without project attribution use customer billing', 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_unattributed_prod',
+    })
+    expect(body.error).toBeUndefined()
+    expect(await SponsoredTransactions.listPending(db)).toMatchObject([
+      { billable: true, orgId: 'org_1', projectId: null },
+    ])
+  })
+
+  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(),
+      endsAt: new Date(Date.now() - 86_400_000).toISOString(),
+      id: project.id,
+      orgId: 'org_1',
+      spendLimit: '100000000',
+    })
+    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: true, projectId: project.id },
+    ])
+  })
+
+  test('behavior: rejects request attribution from project-scoped keys', async () => {
+    const body = await relayRequest(createMainnetApp(), {
+      method: 'eth_signRawTransaction',
+      params: [await signSponsorable({ chainId: Viem.chainId.mainnet })],
+      projectId: 'prj_1',
+      token: 'secret_sponsor_prod',
+    })
+    expect(body.error).toStrictEqual({
+      code: -32602,
+      data: { code: 'project_id_invalid' },
+      message: 'Project attribution rejected.',
+    })
+  })
+
+  test('behavior: rejects request attribution outside the key organization', async () => {
+    const db = TestApp.database()
+    await Organizations.create(db, { id: 'org_2', name: 'Two' })
+    const project = await Projects.create(db, { name: 'Other app', orgId: 'org_2' })
+    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?.data).toStrictEqual({ code: 'project_id_invalid' })
+  })
+
   test('behavior: refuses mainnet sponsorship without a billing source', async () => {
     const entries: Log.Entry[] = []
     const body = await relayRequest(
@@ -1584,6 +1792,7 @@ 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.projectId ? { 'tempo-project-id': options.projectId } : {}),
         ...(options.token ? { 'tempo-api-key': options.token } : {}),
       },
       method: 'POST',
@@ -1604,6 +1813,8 @@ declare namespace relayRequest {
     mount?: 'relay' | 'sponsor' | undefined
     /** JSON-RPC parameters. */
     params: readonly unknown[]
+    /** Request-level project attribution. */
+    projectId?: string | undefined
     /** API-key credential. */
     token?: string | undefined
   }

package/src/apps/relay/App.ts

@@ -7,9 +7,11 @@ import { Addresses, TokenId, Transaction } from 'viem/tempo'
 import type * as App from '../../App.js'
 import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
+import * as Organizations from '../../db/tables/organizations.js'
+import * as Projects from '../../db/tables/projects.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Fees from '../../internal/Fees.js'
 import * as Log from '../../internal/Log.js'
-import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Billing from '../management/Billing.js'
 import * as Handler from '../../Handler.js'
 import * as Auth from '../../internal/Auth.js'
@@ -85,6 +87,7 @@ function middleware(options: middleware.Options) {
     : 0n
   return createMiddleware<App.Environment>(async (c) => {
     const principal = Auth.getPrincipal(c)
+    const requestedAt = new Date().toISOString()
     const verifiedTokens = c.get('verifiedTokens')
     const zoneToken_header = c.req.header(ZoneRpcAuthentication.headerName)
     const zoneToken = zoneToken_header?.trim() ? zoneToken_header : undefined
@@ -97,7 +100,11 @@ function middleware(options: middleware.Options) {
 
     const recordRejection = (options: middleware.Rejection) => {
       const id =
-        Number.isSafeInteger(options.chainId) && options.chainId >= 0 ? options.chainId : null
+        options.chainId !== undefined &&
+        Number.isSafeInteger(options.chainId) &&
+        options.chainId >= 0
+          ? options.chainId
+          : null
       if (chainId !== null) chainId = chainId === undefined || chainId === id ? id : null
       if (options.reason === 'internal_error') internalErrors = Math.min(internalErrors + 1, 65_535)
       if (reason !== null)
@@ -121,22 +128,49 @@ function middleware(options: middleware.Options) {
       throw new Error('Internal error', { cause: new Error(options.message) })
     }
 
-    const feePayer = (() => {
+    const feePayer = await (async () => {
       if (!options.feePayer) return undefined
-      const attribution =
-        principal?.type === 'api_key'
-          ? {
-              apiKeyId: principal.id,
-              environment: principal.environment,
-              orgId: principal.orgId,
-              ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
-            }
-          : undefined
+      const resolved = await resolveAttribution(Db.get(c.get('db')), {
+        principal,
+        projectId: c.req.header('tempo-project-id')?.trim(),
+      })
+      const attribution = resolved?.attribution
+      const attributionError = resolved?.error
       const sponsorable =
         attribution !== undefined &&
         principal?.type === 'api_key' &&
         (principal.apiKey.scopes.includes('rpc-relay:sponsor') ||
           principal.apiKey.scopes.includes(Scope.wildcard))
+      let promotionState_promise: Promise<middleware.PromotionState>
+      const promotionState = () =>
+        (promotionState_promise ??= (async () => {
+          if (!attribution) return { status: 'inactive' }
+          const db = Db.get(c.get('db'))
+          const organization = await Organizations.get(db, attribution.orgId)
+          if (!organization || organization.sponsorshipSubsidyDurationDays === null)
+            return { status: 'inactive' }
+          // Missing project attribution opts out of the subsidy but must not interrupt sponsorship.
+          if (!attribution.projectId) return { status: 'inactive' }
+          const project = await Projects.get(db, attribution.projectId)
+          if (!project) return { message: 'Attributed project disappeared.', status: 'error' }
+          if (project.orgId !== attribution.orgId)
+            return { message: 'Attributed project changed ownership.', status: 'error' }
+          if (
+            (project.sponsorshipSubsidyStartsAt === null) !==
+            (project.sponsorshipSubsidyEndsAt === null)
+          )
+            return { message: 'Project promotion window is inconsistent.', status: 'error' }
+          if (
+            project.sponsorshipSubsidyEndsAt !== null &&
+            Date.parse(requestedAt) >= Date.parse(project.sponsorshipSubsidyEndsAt)
+          )
+            return { status: 'inactive' }
+          return { status: 'active' }
+        })())
+      const validatePromotion = async (chainId: number) => {
+        const state = await promotionState()
+        if (state.status === 'error') failSponsorship({ chainId, message: state.message })
+      }
       // Lifted so validation and the sponsored-token default read one value.
       const feeToken_sponsor = options.feePayer.feeToken ?? Addresses.pathUsd
       return {
@@ -147,6 +181,12 @@ function middleware(options: middleware.Options) {
           // only mainnet: the relay resolves chainId from the request body, so
           // the query-string chain guard never sees it.
           const id = Number(transaction.chainId)
+          if (attributionError)
+            rejectSponsorship({
+              chainId: id,
+              message: 'Project attribution rejected.',
+              reason: attributionError,
+            })
           if (!attribution) {
             if (sponsorshipRequired)
               rejectSponsorship({
@@ -186,15 +226,9 @@ function middleware(options: middleware.Options) {
               })
             return false
           }
-
-          // Enforcement reads hit the primary, never the cached replica: a
-          // stale `past_due`, a lowered limit, or another isolate's pending
-          // spend must not keep the gate open.
           const db = Db.get(c.get('db'))
-          // Mainnet sponsorship requires an active billing source; deployments
-          // without billing configured have no rows, so mainnet stays closed.
-          // `past_due` gets its own reason: the caller must settle an invoice,
-          // not attach a card.
+          // Enforcement reads hit the primary, never the cached replica: a
+          // stale `past_due` or another isolate's state must not keep the gate open.
           const billing = await Billing.status(db, attribution.orgId)
           if (billing === 'past_due') {
             if (sponsorshipRequired)
@@ -214,6 +248,7 @@ function middleware(options: middleware.Options) {
               })
             return 'billing_required'
           }
+          await validatePromotion(id)
 
           const feeToken = (() => {
             try {
@@ -286,7 +321,6 @@ function middleware(options: middleware.Options) {
           // reconciliation convention; pending rows charge it to spend limits.
           const feeMax = Fees.maxOf(Transaction.deserialize(event.transaction as `0x76${string}`))
           const db = Db.get(c.get('db'))
-
           const feeToken = (() => {
             try {
               return event.feeToken !== undefined ? TokenId.toAddress(event.feeToken) : undefined
@@ -318,13 +352,54 @@ function middleware(options: middleware.Options) {
           // Re-read settings on the authoritative path: the limit may have
           // changed since `validate`, and only mainnet spend is limited.
           const settings = mainnet ? await BillingSettings.get(db, attribution.orgId) : undefined
-          if (settings?.spendLimit == null) return void (await SponsoredTransactions.upsert(db, input)) // prettier-ignore
+          const billingLimit =
+            settings?.spendLimit == null
+              ? undefined
+              : {
+                  chainIds: [Viem.chainId.mainnet],
+                  max: Billing.toBaseUnits(settings.spendLimit),
+                  since: Billing.periodStart(settings.period),
+                }
+          if (
+            mainnet &&
+            attribution.environment === 'production' &&
+            attribution.projectId !== undefined
+          )
+            try {
+              const promotion = await SponsoredTransactions.reservePromotion(
+                db,
+                { ...input, billable: false },
+                {
+                  at: new Date().toISOString(),
+                  ...(billingLimit ? { billingLimit } : {}),
+                  chainIds: [Viem.chainId.mainnet],
+                  projectId: attribution.projectId,
+                },
+              )
+              if (promotion.status !== 'ineligible') return
+            } catch (error) {
+              if (error instanceof SponsoredTransactions.AttributionConflictError)
+                rejectSponsorship({
+                  chainId: event.chainId,
+                  message: 'Project attribution rejected.',
+                  reason: 'project_id_invalid',
+                })
+              if (error instanceof SponsoredTransactions.PromotionActivationError)
+                failSponsorship({
+                  chainId: event.chainId,
+                  message: 'Project promotion activation failed.',
+                })
+              if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
+                rejectSponsorship({
+                  chainId: event.chainId,
+                  message: 'Spend limit exceeded.',
+                  reason: 'spend_limit_exceeded',
+                })
+              throw error
+            }
+          if (!billingLimit) return void (await SponsoredTransactions.upsert(db, input))
           try {
-            await SponsoredTransactions.reserve(db, input, {
-              chainIds: [Viem.chainId.mainnet],
-              max: Billing.toBaseUnits(settings.spendLimit),
-              since: Billing.periodStart(settings.period),
-            })
+            await SponsoredTransactions.reserve(db, input, billingLimit)
           } catch (error) {
             if (error instanceof SponsoredTransactions.PeriodSpendLimitError)
               rejectSponsorship({
@@ -518,6 +593,57 @@ function sponsorshipMethod(value: unknown): Log.SponsorshipMethod | undefined {
   }
 }
 
+/** Resolves optional request-level project attribution within the API key's organization. */
+async function resolveAttribution(
+  db: Db.Db,
+  options: resolveAttribution.Options,
+): Promise<resolveAttribution.Result | undefined> {
+  if (options.principal?.type !== 'api_key') return undefined
+  const { principal } = options
+  const attribution = {
+    apiKeyId: principal.id,
+    environment: principal.environment,
+    orgId: principal.orgId,
+    ...(principal.projectId === undefined ? {} : { projectId: principal.projectId }),
+  }
+  if (!options.projectId) return { attribution }
+  if (principal.projectId !== undefined) return { attribution, error: 'project_id_invalid' }
+  const project = await Projects.get(db, options.projectId)
+  if (!project || project.orgId !== principal.orgId)
+    return { attribution, error: 'project_id_invalid' }
+  return { attribution: { ...attribution, projectId: project.id } }
+}
+
+declare namespace resolveAttribution {
+  /** Inputs for resolving API-key project attribution. */
+  type Options = {
+    /** Authenticated request principal. */
+    principal: Auth.Principal | null
+    /** Optional project id supplied by the caller. */
+    projectId?: string | undefined
+  }
+
+  /** Resolved API-key attribution. */
+  type Attribution = {
+    /** API key id. */
+    apiKeyId: string
+    /** API key environment. */
+    environment: 'production' | 'sandbox'
+    /** API key organization id. */
+    orgId: string
+    /** Attributed project id. */
+    projectId?: string | undefined
+  }
+
+  /** Attribution result with an optional policy error. */
+  type Result = {
+    /** Attribution retained for request diagnostics. */
+    attribution: Attribution
+    /** Project attribution error detected before transaction validation. */
+    error?: 'project_id_invalid' | undefined
+  }
+}
+
 declare namespace middleware {
   /** One invariant sponsorship failure. */
   type Failure = {
@@ -535,10 +661,13 @@ declare namespace middleware {
     path: 'rpc/relay' | 'rpc/sponsor'
   }
 
+  /** Cached promotion validation state; request accounting is applied per batch item. */
+  type PromotionState = { status: 'active' | 'inactive' } | { message: string; status: 'error' }
+
   /** One sponsorship rejection recorded for request logging. */
   type Rejection = {
     /** Candidate transaction chain, validated before it enters the log entry. */
-    chainId: number
+    chainId?: number | undefined
     /** Stable client error code. */
     reason: Log.SponsorshipReason
   }
@@ -546,7 +675,7 @@ declare namespace middleware {
   /** One client-visible sponsorship refusal. */
   type Refusal = {
     /** Candidate transaction chain. */
-    chainId: number
+    chainId?: number | undefined
     /** Client-safe error message. */
     message: string
     /** Stable client error code. */

package/src/apps/relay/Sponsorships.ts

@@ -11,6 +11,7 @@ import { getTransactionReceipt } from 'viem/actions'
 
 import * as Db from '../../db/Db.js'
 import * as BillingSettings from '../../db/tables/billingSettings.js'
+import * as Projects from '../../db/tables/projects.js'
 import * as Fees from '../../internal/Fees.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as Tidx from '../../internal/Tidx.js'
@@ -292,7 +293,29 @@ export function createFinalizer(options: createFinalizer.Options): createFinaliz
               getClient,
               getTidx: (chainId) => getTidx(chainId as Viem.ChainId),
               limitFor: async (intent) => {
-                if (!intent.billable || !Viem.isMainnet(intent.chainId)) return undefined
+                if (!Viem.isMainnet(intent.chainId)) return undefined
+                if (!intent.billable) {
+                  if (!intent.projectId) return undefined
+                  const project = await Projects.get(db, intent.projectId)
+                  // Missing promotion state cannot prove the intent remains within Tempo's budget.
+                  if (!project || project.sponsorshipSubsidyStartsAt === null)
+                    return {
+                      billable: false,
+                      chainIds: [Viem.chainId.mainnet],
+                      max: -1n,
+                      projectId: intent.projectId,
+                      since: intent.createdAt,
+                    }
+                  if (project.sponsorshipSpendLimit === null) return undefined
+                  return {
+                    billable: false,
+                    chainIds: [Viem.chainId.mainnet],
+                    max: BigInt(project.sponsorshipSpendLimit),
+                    projectId: intent.projectId,
+                    since: project.sponsorshipSubsidyStartsAt,
+                  }
+                }
+                if (!intent.billable) return undefined
                 const settings = await BillingSettings.get(db, intent.orgId)
                 if (settings?.spendLimit == null) return undefined
                 return {

package/src/db/Db.ts

@@ -1488,6 +1488,41 @@ export const migrations: readonly Migration[] = [
     up: (db) =>
       raw(db, sql`ALTER TABLE funding_routes ADD COLUMN IF NOT EXISTS configuration jsonb`),
   },
+  {
+    name: '0138_organizations_sponsorship_subsidy',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE organizations
+          ADD COLUMN IF NOT EXISTS sponsorship_subsidy_duration_days integer,
+          ADD COLUMN IF NOT EXISTS sponsorship_subsidy_project_spend_limit text`,
+      ),
+  },
+  {
+    name: '0139_projects_sponsorship_activation',
+    up: (db) =>
+      raw(
+        db,
+        sql`ALTER TABLE projects
+          ADD COLUMN IF NOT EXISTS sponsorship_subsidy_starts_at text,
+          ADD COLUMN IF NOT EXISTS sponsorship_subsidy_ends_at text,
+          DROP CONSTRAINT IF EXISTS projects_sponsorship_subsidy_window_consistent,
+          ADD CONSTRAINT projects_sponsorship_subsidy_window_consistent CHECK ((sponsorship_subsidy_starts_at IS NULL) = (sponsorship_subsidy_ends_at IS NULL))`,
+      ),
+  },
+  {
+    name: '0140_projects_sponsorship_spend_limit',
+    up: (db) =>
+      raw(db, sql`ALTER TABLE projects ADD COLUMN IF NOT EXISTS sponsorship_spend_limit text`),
+  },
+  {
+    name: '0141_sponsored_transactions_promotion_spend_index',
+    up: (db) =>
+      raw(
+        db,
+        sql`CREATE INDEX IF NOT EXISTS sponsored_transactions_promotion_spend_idx ON sponsored_transactions (org_id, project_id, status, created_at) WHERE NOT billable`,
+      ),
+  },
 ]
 
 /**

package/src/db/Schema.ts

@@ -219,6 +219,12 @@ export const Organization = z.object({
   name: z
     .string()
     .check(z.describe('Human-readable organization name.'), z.meta({ examples: ['Acme, Inc.'] })),
+  sponsorshipSubsidyDurationDays: z
+    .nullable(z.number().check(z.int(), z.positive()))
+    .check(z.describe('Promotional sponsorship duration in days, or null when disabled.')),
+  sponsorshipSubsidyProjectSpendLimit: z
+    .nullable(z.string())
+    .check(z.describe('Per-project promotional spend cap in decimal USD, or null when disabled.')),
   updatedAt: z.string().check(z.describe('When the organization was last updated (ISO 8601).')),
   userId: z
     .nullable(z.string())
@@ -243,6 +249,15 @@ export const Project = z.object({
     .string()
     .check(z.describe('Human-readable project name.'), z.meta({ examples: ['Checkout'] })),
   orgId: z.string().check(z.describe('Owning organization id (`org_…`).')),
+  sponsorshipSubsidyStartsAt: z
+    .nullable(z.string())
+    .check(z.describe('When the project first activated promotional sponsorship, or null.')),
+  sponsorshipSubsidyEndsAt: z
+    .nullable(z.string())
+    .check(z.describe('When the project promotional sponsorship ends, or null.')),
+  sponsorshipSpendLimit: z
+    .nullable(z.string())
+    .check(z.describe('Promotional spend cap in fee-token base units, or null.')),
   updatedAt: z.string().check(z.describe('When the project was last updated (ISO 8601).')),
 })
 
@@ -640,8 +655,8 @@ export const FundingTransfer = z.object({
     .check(z.describe('Attributed project id (`prj_…`), or null for organization-attributed keys.')), // prettier-ignore
   providerId: z.string().check(z.describe('Selected funding provider id.')),
   providerState: z
-    .nullable(z.custom<funding_Provider.prepareTransfer.Correlation>())
-    .check(z.describe('Private provider correlation (`jsonb`), or null. Never serialized publicly.')), // prettier-ignore
+    .nullable(z.custom<funding_Transfer.ProviderState>())
+    .check(z.describe('Private provider state (`jsonb`), or null. Never serialized publicly.')), // prettier-ignore
   quoteExpiresAt: z
     .string()
     .check(z.describe('When the quoted terms stop being executable (ISO 8601).')),