tapimo 0.15.1 → 0.18.0

package/src/db/tables/sponsoredTransactions.ts

@@ -6,6 +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 ApiKeyOwnerTombstones from './apiKeyOwnerTombstones.js'
 import * as SponsorshipAttributions from './sponsorshipAttributions.js'
 
 /** Columns of the `sponsored_transactions` table, derived from `Schema.SponsoredTransaction`. */
@@ -29,6 +30,8 @@ export const failedIntentRecoveryTtlMs = 86_400_000
  * @returns The stored record.
  */
 export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
+  if (!db.kysely.isTransaction) return db.transaction((tx) => upsert(tx, input))
+  await lockOrganization(db, input.orgId)
   const record: Record = {
     apiKeyId: input.apiKeyId,
     sponsorshipAttributionId: input.sponsorshipAttributionId ?? null,
@@ -43,6 +46,8 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     finalizationAttemptedAt: null,
     finalizedAt: null,
     id: Id.generate('stx'),
+    meterEventFirstAttemptedAt: null,
+    meterReportAttemptedAt: null,
     meterReportedAt: null,
     orgId: input.orgId,
     projectId: input.projectId ?? null,
@@ -50,6 +55,7 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     status: 'pending',
     transaction: input.transaction,
     transactionHash: input.transactionHash ?? null,
+    transactionHashReconciled: false,
   }
   const stored = await db.kysely
     .insertInto('sponsored_transactions')
@@ -64,12 +70,9 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
             eb.ref('sponsored_transactions.feeMax'),
             eb.ref('excluded.feeMax'),
           ),
-          // A raw submission fills the intent's hash; a duplicate intent never
-          // clears an already-known hash.
-          transactionHash: eb.fn.coalesce(
-            eb.ref('excluded.transactionHash'),
-            eb.ref('sponsored_transactions.transactionHash'),
-          ),
+          // A raw submission fills an intent or refreshes a submitted hash,
+          // but never replaces a finalized or reconciled hash.
+          transactionHash: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'finalized' OR ${eb.ref('sponsored_transactions.transactionHashReconciled')} THEN ${eb.ref('sponsored_transactions.transactionHash')} ELSE coalesce(${eb.ref('excluded.transactionHash')}, ${eb.ref('sponsored_transactions.transactionHash')}) END`,
           createdAt: sql`CASE WHEN ${eb.ref('sponsored_transactions.status')} = 'failed' THEN ${eb.ref('excluded.createdAt')} ELSE ${eb.ref('sponsored_transactions.createdAt')} END`,
           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`,
@@ -227,30 +230,51 @@ export declare namespace claimPending {
 }
 
 /**
- * Lists active hash-less fill intents, oldest first, for reconciliation.
+ * Lists pending sponsorships, oldest first, for sign-payload reconciliation.
  *
  * @param db - The database.
  * @param options - Paging options.
- * @returns The fill intents.
+ * @returns The reconciliation candidates.
  */
-export function listIntents(db: Db.Db, options: listIntents.Options = {}): Promise<Record[]> {
-  let query = db.kysely
+export async function listReconciliationCandidates(
+  db: Db.Db,
+  options: listReconciliationCandidates.Options = {},
+): Promise<Record[]> {
+  let intents = db.kysely
     .selectFrom('sponsored_transactions')
     .selectAll()
     .where('status', '=', 'pending')
     .where('transactionHash', 'is', null)
     .orderBy('createdAt', 'asc')
     .orderBy('id', 'asc')
-  if (options.limit !== undefined) query = query.limit(options.limit)
-  return query.execute()
+  let submitted = db.kysely
+    .selectFrom('sponsored_transactions')
+    .selectAll()
+    .where('status', '=', 'pending')
+    .where('transactionHash', 'is not', null)
+    .where('transactionHashReconciled', '=', false)
+    .orderBy('createdAt', 'asc')
+    .orderBy('id', 'asc')
+  if (options.limit !== undefined) {
+    intents = intents.limit(options.limit)
+    submitted = submitted.limit(options.limit)
+  }
+  const [records_intent, records_submitted] = await Promise.all([
+    intents.execute(),
+    submitted.execute(),
+  ])
+  return [...records_intent, ...records_submitted]
 }
 
-export declare namespace listIntents {
-  /** Options for {@link listIntents}. */
-  type Options = listPending.Options
+export declare namespace listReconciliationCandidates {
+  /** Options for {@link listReconciliationCandidates}. */
+  type Options = {
+    /** Maximum rows per transaction-hash state. */
+    limit?: number | undefined
+  }
 }
 
-/** Lists the oldest recoverable failed-intent timestamp for each chain. */
+/** Lists the oldest recoverable failed sponsorship timestamp for each chain. */
 export function listRecoveryWindows(
   db: Db.Db,
   options: listRecoveryWindows.Options,
@@ -261,7 +285,6 @@ export function listRecoveryWindows(
     .select((eb) => eb.fn.min<string>('createdAt').as('createdAt'))
     .where('finalizedAt', '>=', options.failedSince)
     .where('status', '=', 'failed')
-    .where('transactionHash', 'is', null)
     .groupBy('chainId')
     .execute()
 }
@@ -282,7 +305,7 @@ export declare namespace listRecoveryWindows {
   }
 }
 
-/** Lists pending and recoverable failed intents matching candidate sign payloads. */
+/** Lists pending intents and recoverable failed sponsorships matching candidate sign payloads. */
 export function listRecoverableIntents(
   db: Db.Db,
   options: listRecoverableIntents.Options,
@@ -294,11 +317,10 @@ export function listRecoverableIntents(
     .where('signPayload', 'in', [...options.signPayloads])
     .where((eb) =>
       eb.or([
-        eb('status', '=', 'pending'),
+        eb.and([eb('status', '=', 'pending'), eb('transactionHash', 'is', null)]),
         eb.and([eb('finalizedAt', '>=', options.failedSince), eb('status', '=', 'failed')]),
       ]),
     )
-    .where('transactionHash', 'is', null)
     .execute()
 }
 
@@ -313,12 +335,12 @@ export declare namespace listRecoverableIntents {
 }
 
 /**
- * Fills a reconciled intent's transaction hash and reopens failed intents.
- * A no-op once another pass already assigned the hash.
+ * Assigns a reconciled transaction hash and reopens failed sponsorships.
+ * A no-op once another pass resolved an active sponsorship.
  *
  * @param db - The database.
  * @param id - The sponsored-transaction id (`stx_…`).
- * @param transactionHash - The matched on-chain transaction hash.
+ * @param transactionHash - The matched on-chain transaction hash, which may replace an unmined hash.
  * @param limit - The active period spend limit, when enforced.
  */
 export async function assignTransactionHash(
@@ -330,12 +352,7 @@ export async function assignTransactionHash(
   try {
     await db.transaction(async (tx) => {
       const record = await get(tx, id)
-      if (
-        !record ||
-        record.transactionHash !== null ||
-        !['failed', 'pending'].includes(record.status)
-      )
-        return
+      if (!record || !['failed', 'pending'].includes(record.status)) return
       const failedSince = new Date(Date.now() - failedIntentRecoveryTtlMs).toISOString()
       if (
         record.status === 'failed' &&
@@ -360,10 +377,14 @@ export async function assignTransactionHash(
           finalizedAt: null,
           status: 'pending',
           transactionHash,
+          transactionHashReconciled: true,
         })
         .where('id', '=', id)
         .where('status', '=', record.status)
-        .where('transactionHash', 'is', null)
+      query =
+        record.transactionHash === null
+          ? query.where('transactionHash', 'is', null)
+          : query.where('transactionHash', '=', record.transactionHash)
       if (record.status === 'failed')
         query = query.where((eb) =>
           eb.exists(
@@ -397,7 +418,6 @@ export async function assignTransactionHash(
         .set({ finalizedAt: new Date().toISOString() })
         .where('id', '=', id)
         .where('status', '=', 'failed')
-        .where('transactionHash', 'is', null)
         .execute()
     throw error
   }
@@ -412,12 +432,19 @@ export async function assignTransactionHash(
  * @param input - The finalized fee facts.
  */
 export async function finalize(db: Db.Db, id: string, input: finalize.Input): Promise<void> {
-  await db.kysely
+  let query = db.kysely
     .updateTable('sponsored_transactions')
-    .set({ feeAmount: input.feeAmount, finalizedAt: input.finalizedAt, status: 'finalized' })
+    .set({
+      feeAmount: input.feeAmount,
+      finalizedAt: input.finalizedAt,
+      status: 'finalized',
+      ...(input.transactionHash === undefined ? {} : { transactionHashReconciled: true }),
+    })
     .where('id', '=', id)
     .where('status', '=', 'pending')
-    .execute()
+  if (input.transactionHash !== undefined)
+    query = query.where('transactionHash', '=', input.transactionHash)
+  await query.execute()
 }
 
 export declare namespace finalize {
@@ -427,6 +454,8 @@ export declare namespace finalize {
     feeAmount: string
     /** When the sponsorship finalized (ISO 8601). */
     finalizedAt: string
+    /** Transaction hash whose receipt produced the fee, when fencing concurrent reconciliation. */
+    transactionHash?: string | undefined
   }
 }
 
@@ -437,14 +466,33 @@ export declare namespace finalize {
  * @param db - The database.
  * @param id - The sponsored-transaction id (`stx_…`).
  * @param finalizedAt - When the sponsorship was marked failed (ISO 8601).
+ * @param options - Optional claimed-hash fence.
  */
-export async function fail(db: Db.Db, id: string, finalizedAt: string): Promise<void> {
-  await db.kysely
+export async function fail(
+  db: Db.Db,
+  id: string,
+  finalizedAt: string,
+  options: fail.Options = {},
+): Promise<void> {
+  let query = db.kysely
     .updateTable('sponsored_transactions')
     .set({ finalizedAt, status: 'failed' })
     .where('id', '=', id)
     .where('status', '=', 'pending')
-    .execute()
+  if (options.transactionHash !== undefined)
+    query =
+      options.transactionHash === null
+        ? query.where('transactionHash', 'is', null)
+        : query.where('transactionHash', '=', options.transactionHash)
+  await query.execute()
+}
+
+export declare namespace fail {
+  /** Optional compare-and-set fence for a claimed sponsorship. */
+  type Options = {
+    /** Transaction hash observed when finalization claimed the row. */
+    transactionHash?: string | null | undefined
+  }
 }
 
 /**
@@ -465,6 +513,7 @@ export async function reserve(
   limit: reserve.Limit,
 ): Promise<Record> {
   return db.transaction(async (tx) => {
+    await lockOrganization(tx, input.orgId)
     // `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.sponsorshipAttributionId
@@ -524,6 +573,7 @@ export function reservePromotion(
   options: reservePromotion.Options,
 ): Promise<reservePromotion.Result> {
   return db.transaction(async (tx) => {
+    await lockOrganization(tx, input.orgId)
     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
@@ -813,7 +863,7 @@ export declare namespace usage {
 
 /**
  * Lists finalized billable rows not yet reported to the billing meter, oldest
- * first, for the metering job.
+ * first, optionally scoped to chains.
  *
  * @param db - The database.
  * @param options - Reporting scope.
@@ -834,6 +884,89 @@ export function listUnreported(db: Db.Db, options: listUnreported.Options): Prom
   return query.execute()
 }
 
+/** Claims unreported sponsorships, reserving capacity for Stripe retries and unsent rows. */
+export function claimUnreported(db: Db.Db, options: claimUnreported.Options): Promise<Record[]> {
+  return db.transaction(async (tx) => {
+    const retries =
+      options.limit > 1
+        ? await tx.kysely
+            .selectFrom('sponsored_transactions')
+            .selectAll()
+            .where('status', '=', 'finalized')
+            .where('billable', '=', true)
+            .where('meterReportedAt', 'is', null)
+            .where('meterEventFirstAttemptedAt', 'is not', null)
+            .orderBy('meterReportAttemptedAt', 'asc')
+            .orderBy('finalizedAt', 'asc')
+            .orderBy('id', 'asc')
+            .limit(Math.floor(options.limit / 2))
+            .forUpdate()
+            .skipLocked()
+            .execute()
+        : []
+    const fresh = await tx.kysely
+      .selectFrom('sponsored_transactions')
+      .selectAll()
+      .where('status', '=', 'finalized')
+      .where('billable', '=', true)
+      .where('meterReportedAt', 'is', null)
+      .$if(options.limit > 1, (query) => query.where('meterEventFirstAttemptedAt', 'is', null))
+      .orderBy(sql`meter_report_attempted_at nulls first`)
+      .orderBy('finalizedAt', 'asc')
+      .orderBy('id', 'asc')
+      .limit(options.limit - retries.length)
+      .forUpdate()
+      .skipLocked()
+      .execute()
+    const rows = [...retries, ...fresh]
+    if (rows.length === 0) return []
+    await tx.kysely
+      .updateTable('sponsored_transactions')
+      .set({ meterReportAttemptedAt: options.attemptedAt })
+      .where(
+        'id',
+        'in',
+        rows.map((row) => row.id),
+      )
+      .execute()
+    return rows.map((row) => ({ ...row, meterReportAttemptedAt: options.attemptedAt }))
+  })
+}
+
+/** Persists the first possible Stripe submission before any network request. */
+export async function beginMeterEvent(db: Db.Db, id: string, at: string): Promise<string> {
+  const row = await db.kysely
+    .updateTable('sponsored_transactions')
+    .set({ meterEventFirstAttemptedAt: sql`coalesce(meter_event_first_attempted_at, ${at})` })
+    .where('id', '=', id)
+    .where('status', '=', 'finalized')
+    .where('meterReportedAt', 'is', null)
+    .returning('meterEventFirstAttemptedAt')
+    .executeTakeFirstOrThrow()
+  return row.meterEventFirstAttemptedAt!
+}
+
+/** Clears the retry clock only after Stripe explicitly rejected the event. */
+export async function clearRejectedMeterEventAttempt(db: Db.Db, id: string): Promise<void> {
+  await db.kysely
+    .updateTable('sponsored_transactions')
+    .set({ meterEventFirstAttemptedAt: null })
+    .where('id', '=', id)
+    .where('status', '=', 'finalized')
+    .where('meterReportedAt', 'is', null)
+    .execute()
+}
+
+export declare namespace claimUnreported {
+  /** One bounded reporting pass. */
+  type Options = {
+    /** Time recorded for each claimed row (ISO 8601). */
+    attemptedAt: string
+    /** Maximum sponsorships claimed by this pass. */
+    limit: number
+  }
+}
+
 export declare namespace listUnreported {
   /** Options for {@link listUnreported}. */
   type Options = {
@@ -857,10 +990,21 @@ export async function markReported(db: Db.Db, id: string, at: string): Promise<v
     .updateTable('sponsored_transactions')
     .set({ meterReportedAt: at })
     .where('id', '=', id)
+    .where('status', '=', 'finalized')
     .where('meterReportedAt', 'is', null)
     .execute()
 }
 
+/** Holds the deletion fence before any sponsorship row, budget, or policy locks. */
+async function lockOrganization(db: Db.Db, orgId: string): Promise<void> {
+  if (!(await ApiKeyOwnerTombstones.lockActive(db, { orgId }))) throw new OrganizationDeletedError()
+}
+
+/** A deleted organization cannot acquire or reopen sponsorship commitments. */
+export class OrganizationDeletedError extends Error {
+  override name = 'SponsoredTransactions.OrganizationDeletedError'
+}
+
 /** Thrown by {@link reserve} when recording would exceed the org's period spend limit. */
 export class PeriodSpendLimitError extends Error {
   override name = 'SponsoredTransactions.PeriodSpendLimitError'

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

@@ -10,6 +10,8 @@ describe('getByEmail', () => {
     try {
       const first = await Users.upsertByAddress(db, { address: `0x${'11'.repeat(20)}` })
       const second = await Users.upsertByAddress(db, { address: `0x${'22'.repeat(20)}` })
+      expect(first.termsSharedAt).toBeNull()
+      expect(second.termsSharedAt).toBeNull()
       await db.kysely
         .updateTable('users')
         .set({ createdAt: '2026-01-01T00:00:00.000Z' })
@@ -49,6 +51,7 @@ describe('auth field migration compatibility', () => {
       await expect(Users.get(db, 'usr_legacy_worker')).resolves.toMatchObject({
         emailVerified: false,
         name: '',
+        termsSharedAt: null,
       })
     } finally {
       await db.close()
@@ -56,6 +59,54 @@ describe('auth field migration compatibility', () => {
   })
 })
 
+describe('recordTermsShared', () => {
+  test('records an older user once after sign-in', async () => {
+    const db = TestApp.database()
+    try {
+      const now = new Date().toISOString()
+      await db.kysely
+        .insertInto('users')
+        .values([
+          {
+            address: null,
+            createdAt: now,
+            email: 'developer@example.com',
+            emailVerified: true,
+            id: 'usr_older_terms',
+            image: null,
+            name: 'Developer',
+            updatedAt: now,
+          },
+          {
+            address: null,
+            createdAt: now,
+            email: 'other@example.com',
+            emailVerified: true,
+            id: 'usr_other_terms',
+            image: null,
+            name: 'Other',
+            updatedAt: now,
+          },
+        ])
+        .execute()
+
+      await Users.recordTermsShared(db, 'usr_older_terms')
+      const first = await Users.get(db, 'usr_older_terms')
+      expect(first).toMatchObject({
+        termsSharedAt: expect.any(String),
+      })
+      expect(await Users.get(db, 'usr_other_terms')).toMatchObject({
+        termsSharedAt: null,
+      })
+
+      await Users.recordTermsShared(db, 'usr_older_terms')
+      expect((await Users.get(db, 'usr_older_terms'))?.termsSharedAt).toBe(first?.termsSharedAt)
+    } finally {
+      await db.close()
+    }
+  })
+})
+
 describe('email migration precondition', () => {
   test('rejects a blank email', async () => {
     const db = TestApp.database()

package/src/db/tables/users.ts

@@ -51,6 +51,7 @@ export function getByEmail(db: Db.Db, email: string): Promise<Record | undefined
     .where(sql<string>`lower(btrim(email))`, '=', email.trim().toLowerCase())
     .orderBy('createdAt', 'asc')
     .orderBy('id', 'asc')
+    .limit(1)
     .executeTakeFirst()
 }
 
@@ -119,6 +120,17 @@ export async function upsertByAddress(db: Db.Db, input: upsertByAddress.Input):
     .executeTakeFirstOrThrow()
 }
 
+/** Records the first successful sign-in response that includes terms links. */
+export async function recordTermsShared(db: Db.Db, id: string): Promise<void> {
+  const now = new Date().toISOString()
+  await db.kysely
+    .updateTable('users')
+    .set({ termsSharedAt: now, updatedAt: now })
+    .where('id', '=', id)
+    .where('termsSharedAt', 'is', null)
+    .execute()
+}
+
 export declare namespace upsertByAddress {
   /** Fields accepted when ensuring a user. */
   type Input = {

package/src/handlers/internal/multisig.store.test.ts

@@ -0,0 +1,120 @@
+import { Hex } from 'ox'
+import { createClient, http } from 'viem'
+import { tempoLocalnet } from 'viem/tempo/chains'
+
+import * as Handler from '../../Handler.js'
+import * as Log from '../../internal/Log.js'
+import * as StateStore from '../../internal/Store.js'
+import * as Multisig from './multisig.js'
+
+describe('fromStore', () => {
+  test('requires atomic state', () => {
+    const { swap: _, ...state } = StateStore.memory()
+    expect(() => Multisig.fromStore(state)).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Multisig coordination requires an atomic state store.]`,
+    )
+  })
+
+  test('preserves concurrent compare-and-set', async () => {
+    const state = StateStore.memory()
+    const a = Multisig.fromStore(state)
+    const results = await Promise.all([
+      a.compareAndSet('operation', null, 'a'),
+      a.compareAndSet('operation', null, 'b'),
+    ])
+    expect({ results }).toMatchInlineSnapshot(`
+      {
+        "results": [
+          true,
+          false,
+        ],
+      }
+    `)
+  })
+
+  test('honors absolute expiration', async () => {
+    vi.useFakeTimers()
+    try {
+      const store = Multisig.fromStore(StateStore.memory())
+      await store.compareAndSet('lease', null, 'a', { expiresAt: Date.now() + 100 })
+      await vi.advanceTimersByTimeAsync(101)
+      expect(await store.getItem('lease')).toBeNull()
+      expect(await store.compareAndSet('lease', null, 'b')).toBe(true)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+})
+
+describe('relay', () => {
+  const client = createClient({ chain: tempoLocalnet, transport: http() })
+
+  test('serves unknown operations without forwarding them to the node', async () => {
+    const handler = Handler.relay({
+      getClient: () => client,
+      multisig: { store: StateStore.memory() },
+    })
+    const response = await handler.fetch(
+      new Request('http://relay/', {
+        method: 'POST',
+        body: JSON.stringify({
+          id: 42,
+          jsonrpc: '2.0',
+          method: 'multisig_getOperation',
+          params: [Hex.random(32)],
+        }),
+      }),
+    )
+    expect(await response.json()).toMatchInlineSnapshot(`
+      {
+        "id": 42,
+        "jsonrpc": "2.0",
+        "result": null,
+      }
+    `)
+  })
+
+  test('rejects invalid parameters across the five methods', async () => {
+    const handler = Handler.relay({
+      getClient: () => client,
+      multisig: { store: StateStore.memory() },
+    })
+    for (const method of [
+      'multisig_approveRawTransaction',
+      'multisig_approveRawTransactionSync',
+      'multisig_approveKeyAuthorization',
+      'multisig_getConfig',
+      'multisig_getOperation',
+    ]) {
+      const response = await handler.fetch(
+        new Request('http://relay/', {
+          method: 'POST',
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method, params: [] }),
+        }),
+      )
+      expect(await response.json()).toMatchObject({ error: { code: -32602 } })
+    }
+  })
+
+  test('reports corrupt coordinator state through RPC server-error observability', async () => {
+    const state = StateStore.memory()
+    const hash = Hex.random(32)
+    // Operation lookup keys are part of the persisted Viem coordinator format.
+    await state.put(`multisig:v2:multisig:operation:${hash}`, 'invalid')
+    const handler = Handler.relay({ getClient: () => client, multisig: { store: state } })
+    const response = await handler.fetch(
+      new Request('http://relay/', {
+        method: 'POST',
+        body: JSON.stringify({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'multisig_getOperation',
+          params: [hash],
+        }),
+      }),
+    )
+    const body: unknown = await response.json()
+    expect(body).toMatchObject({ error: { code: -32603 } })
+    expect(Log.rpcErrors(body)).toMatchObject({ serverErrors: 1 })
+  })
+})