tapimo 0.13.0 → 0.15.0

package/src/db/tables/{fundingTransferEvents.ts → routesTransferEvents.ts}

@@ -3,15 +3,15 @@ import type { Selectable } from 'kysely'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
 
-/** Columns of the `funding_transfer_events` table. */
-export type Table = db_Schema.FundingTransferEvent
+/** Columns of the `routes_transfer_events` table. */
+export type Table = db_Schema.RoutesTransferEvent
 /** One immutable public snapshot at a material version. */
 export type Record = Selectable<Table>
 
 /** Inserts an event row. Callers commit it with its transfer row in one transaction. */
 export function insert(db: Db.Db, record: Record): Promise<Record> {
   return db.kysely
-    .insertInto('funding_transfer_events')
+    .insertInto('routes_transfer_events')
     .values(record)
     .returningAll()
     .executeTakeFirstOrThrow()
@@ -20,7 +20,7 @@ export function insert(db: Db.Db, record: Record): Promise<Record> {
 /** Lists a transfer's events, oldest version first. */
 export function listByTransfer(db: Db.Db, transferId: string): Promise<Record[]> {
   return db.kysely
-    .selectFrom('funding_transfer_events')
+    .selectFrom('routes_transfer_events')
     .selectAll()
     .where('transferId', '=', transferId)
     .orderBy('version', 'asc')

package/src/db/tables/routesTransferSubsidies.ts

@@ -0,0 +1,38 @@
+import { sql, type Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as Schema from '../Schema.js'
+
+/** Columns of the `routes_transfer_subsidies` table. */
+export type Table = Schema.RoutesTransferSubsidy
+/** A shared subsidy transaction and its billing owner. */
+export type Record = Selectable<Table>
+
+/** Serializes subsidy preparation for a source payment and returns its persisted settlement. */
+export async function getForUpdateIn(
+  db: Db.Db,
+  options: getForUpdateIn.Options,
+): Promise<Record | undefined> {
+  const key = JSON.stringify([
+    'routes-transfer-subsidy',
+    options.sourceChainId,
+    options.transactionRef,
+  ])
+  await sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(db.kysely)
+  return db.kysely
+    .selectFrom('routes_transfer_subsidies')
+    .selectAll()
+    .where('sourceChainId', '=', options.sourceChainId)
+    .where('transactionRef', '=', options.transactionRef)
+    .executeTakeFirst()
+}
+
+export declare namespace getForUpdateIn {
+  /** Verified source execution identity. */
+  type Options = {
+    /** Source CAIP-2 chain. */
+    sourceChainId: string
+    /** Canonical source transaction reference. */
+    transactionRef: string
+  }
+}

package/src/db/tables/routesTransferSubsidyNonces.ts

@@ -0,0 +1,124 @@
+import { sql, type Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `routes_transfer_subsidy_nonces` table. */
+export type Table = db_Schema.RoutesTransferSubsidyNonce
+/** One persisted destination signer nonce cursor. */
+export type Record = Selectable<Table>
+
+/** Serializes inventory and nonce operations for one signer and chain. */
+async function lock(db: Db.Db, options: Lane): Promise<void> {
+  const key = `${options.chainId}:${options.account.toLowerCase()}`
+  await sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(db.kysely)
+}
+
+type Lane = {
+  /** Destination subsidy signer address. */
+  account: string
+  /** Destination EVM chain CAIP-2 id. */
+  chainId: string
+}
+
+/** Locks a signer lane and rejects new work when its nonce cannot be recovered. */
+export async function lockAvailableIn(db: Db.Db, options: Lane): Promise<void> {
+  await lock(db, options)
+  const current = await db.kysely
+    .selectFrom('routes_transfer_subsidy_nonces')
+    .selectAll()
+    .where('account', '=', options.account.toLowerCase())
+    .where('chainId', '=', options.chainId)
+    .forUpdate()
+    .executeTakeFirst()
+  if (current?.blockedAt) throw new BlockedError()
+}
+
+/** Blocks a signer lane after a reserved nonce is permanently rejected. */
+export async function block(db: Db.Db, options: block.Options): Promise<void> {
+  return db.transaction((tx) => blockIn(tx, options))
+}
+
+/** Blocks a signer lane inside a caller-owned transaction. */
+export async function blockIn(db: Db.Db, options: block.Options): Promise<void> {
+  await lock(db, options)
+  const now = new Date().toISOString()
+  const updated = await db.kysely
+    .updateTable('routes_transfer_subsidy_nonces')
+    .set({
+      blockedAt: now,
+      blockedReason: options.reason,
+      blockedTransferId: options.transferId,
+      updatedAt: now,
+    })
+    .where('account', '=', options.account.toLowerCase())
+    .where('chainId', '=', options.chainId)
+    .executeTakeFirst()
+  if (updated.numUpdatedRows !== 1n) throw new MissingCursorError()
+}
+
+export declare namespace block {
+  /** Signer lane and permanent rejection evidence. */
+  type Options = Lane & {
+    /** Bounded reason for blocking the signer lane. */
+    reason: 'broadcast_rejected'
+    /** Transfer holding the rejected nonce. */
+    transferId: string
+  }
+}
+
+/** Reserves one nonce under a transaction-scoped signer and chain lock. */
+export async function reserve(db: Db.Db, options: reserve.Options): Promise<number> {
+  const account = options.account.toLowerCase()
+  await lock(db, options)
+  const current = await db.kysely
+    .selectFrom('routes_transfer_subsidy_nonces')
+    .selectAll()
+    .where('account', '=', account)
+    .where('chainId', '=', options.chainId)
+    .forUpdate()
+    .executeTakeFirst()
+  if (current?.blockedAt) throw new BlockedError()
+  const nonce = Math.max(current ? Number(current.nextNonce) : 0, options.pendingNonce)
+  await db.kysely
+    .insertInto('routes_transfer_subsidy_nonces')
+    .values({
+      account,
+      blockedAt: null,
+      blockedReason: null,
+      blockedTransferId: null,
+      chainId: options.chainId,
+      nextNonce: String(nonce + 1),
+      updatedAt: new Date().toISOString(),
+    })
+    .onConflict((conflict) =>
+      conflict.columns(['chainId', 'account']).doUpdateSet({
+        nextNonce: String(nonce + 1),
+        updatedAt: new Date().toISOString(),
+      }),
+    )
+    .execute()
+  return nonce
+}
+
+/** The signer lane is blocked by an unrecoverable reserved nonce. */
+export class BlockedError extends Error {
+  override name = 'Routes.TransferSubsidyNonce.BlockedError'
+}
+
+/** A rejected subsidy transaction had no persisted nonce cursor. */
+export class MissingCursorError extends Error {
+  override name = 'Routes.TransferSubsidyNonce.MissingCursorError'
+}
+
+export declare namespace reserve {
+  /** Signer and chain cursor used to reserve one nonce. */
+  type Options = {
+    /** Destination subsidy signer address. */
+    account: string
+    /** Destination EVM chain CAIP-2 id. */
+    chainId: string
+    /** Next nonce observed from the pending RPC state. */
+    pendingNonce: number
+  }
+}

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

@@ -0,0 +1,195 @@
+import * as TestApp from '../../../test/App.js'
+import * as TestRoutes from '../../../test/Routes.js'
+import * as Transfer from '../../internal/routes/Transfer.js'
+import * as RoutesTransferTransactions from './routesTransferTransactions.js'
+
+const db = TestApp.database()
+
+function createTransfer(id: string) {
+  return Transfer.create(db, {
+    apiKeyId: 'key_test',
+    environment: 'production',
+    id,
+    orgId: 'org_test',
+    snapshot: TestRoutes.transferSnapshot(),
+  })
+}
+
+describe('insert', () => {
+  test('canonicalizes EVM hashes before enforcing source uniqueness', async () => {
+    const first = await createTransfer('rtr_evm_first')
+    const second = await createTransfer('rtr_evm_second')
+    const transactionRef = `0x${'aB'.repeat(32)}`
+
+    const inserted = await RoutesTransferTransactions.insert(db, {
+      chainId: 'eip155:8453',
+      createdAt: '2026-01-01T00:00:01.000Z',
+      role: 'source',
+      transactionRef,
+      transferId: first.id,
+    })
+    expect(inserted?.transactionRef).toBe(transactionRef.toLowerCase())
+
+    await expect(
+      RoutesTransferTransactions.insert(db, {
+        chainId: 'eip155:8453',
+        createdAt: '2026-01-01T00:00:02.000Z',
+        role: 'source',
+        transactionRef: transactionRef.toUpperCase(),
+        transferId: second.id,
+      }),
+    ).rejects.toMatchObject({ constraint: 'routes_transfer_transactions_source_owner_unique' })
+  })
+
+  test('preserves case-sensitive non-EVM transaction references', async () => {
+    const first = await createTransfer('rtr_solana_first')
+    const second = await createTransfer('rtr_solana_second')
+    const transactionRef = 'A'.repeat(87)
+
+    const uppercase = await RoutesTransferTransactions.insert(db, {
+      chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      createdAt: '2026-01-01T00:00:01.000Z',
+      role: 'source',
+      transactionRef,
+      transferId: first.id,
+    })
+    const lowercase = await RoutesTransferTransactions.insert(db, {
+      chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+      createdAt: '2026-01-01T00:00:02.000Z',
+      role: 'source',
+      transactionRef: transactionRef.toLowerCase(),
+      transferId: second.id,
+    })
+
+    expect([uppercase?.transactionRef, lowercase?.transactionRef]).toEqual([
+      transactionRef,
+      transactionRef.toLowerCase(),
+    ])
+  })
+})
+
+describe('claimSource', () => {
+  test('returns claimed, replayed, and conflicting ownership outcomes', async () => {
+    const first = await createTransfer('rtr_claim_first')
+    const second = await createTransfer('rtr_claim_second')
+    const record = {
+      chainId: 'eip155:8453',
+      createdAt: '2026-01-01T00:00:01.000Z',
+      role: 'source' as const,
+      transactionRef: `0x${'cd'.repeat(32)}`,
+      transferId: first.id,
+    }
+    const claimed = await RoutesTransferTransactions.claimSource(db, record)
+    const replayed = await RoutesTransferTransactions.claimSource(db, record)
+    const conflict = await RoutesTransferTransactions.claimSource(db, {
+      ...record,
+      transferId: second.id,
+    })
+    expect([claimed.type, replayed.type, conflict.type]).toEqual([
+      'claimed',
+      'replayed',
+      'conflict',
+    ])
+  })
+})
+
+describe('getSource', () => {
+  test('selects the tenant owner when source references are shared', async () => {
+    const database = TestApp.database()
+    const owners = []
+    for (const orgId of ['org_first', 'org_second'])
+      owners.push(
+        await Transfer.create(database, {
+          apiKeyId: `key_${orgId}`,
+          environment: 'production',
+          orgId,
+          snapshot: TestRoutes.transferSnapshot(),
+        }),
+      )
+    const transactionRef = `0x${'ef'.repeat(32)}`
+    for (const owner of owners)
+      await RoutesTransferTransactions.insert(database, {
+        chainId: 'eip155:8453',
+        createdAt: owner.createdAt,
+        role: 'source',
+        transactionRef,
+        transferId: owner.id,
+      })
+    for (const owner of owners)
+      expect(
+        (
+          await RoutesTransferTransactions.getSource(database, {
+            chainId: 'eip155:8453',
+            transactionRef,
+            transferId: owner.id,
+          })
+        )?.transferId,
+      ).toBe(owner.id)
+  })
+
+  test('scopes ownership through transfer tenancy without depending on evidence columns', async () => {
+    const database = TestApp.database()
+    const owner = await Transfer.create(database, {
+      apiKeyId: 'key_original',
+      environment: 'production',
+      orgId: 'org_owner',
+      projectId: 'prj_owner',
+      snapshot: TestRoutes.transferSnapshot(),
+    })
+    const transactionRef = `0x${'de'.repeat(32)}`
+    await RoutesTransferTransactions.claimSource(database, {
+      chainId: 'eip155:8453',
+      createdAt: owner.createdAt,
+      role: 'source',
+      transactionRef,
+      transferId: owner.id,
+    })
+    const scopes = [
+      { environment: 'production', orgId: 'org_owner', projectId: 'prj_owner' },
+      { environment: 'production', orgId: 'org_foreign', projectId: 'prj_owner' },
+      { environment: 'sandbox', orgId: 'org_owner', projectId: 'prj_owner' },
+      { environment: 'production', orgId: 'org_owner', projectId: 'prj_foreign' },
+      { environment: 'production', orgId: 'org_owner' },
+    ] as const
+    const records = []
+    for (const scope of scopes) {
+      const transfer = await Transfer.create(database, {
+        ...scope,
+        apiKeyId: 'key_rotated',
+        snapshot: TestRoutes.transferSnapshot(),
+      })
+      const record = await RoutesTransferTransactions.getSource(database, {
+        chainId: 'eip155:8453',
+        transactionRef,
+        transferId: transfer.id,
+      })
+      records.push(record?.transferId === owner.id)
+    }
+    expect(records).toMatchInlineSnapshot(`
+      [
+        true,
+        false,
+        false,
+        false,
+        false,
+      ]
+    `)
+  })
+
+  test('resolves EVM hashes case-insensitively', async () => {
+    const transfer = await createTransfer('rtr_get_source')
+    await RoutesTransferTransactions.claimSource(db, {
+      chainId: 'eip155:8453',
+      createdAt: '2026-01-01T00:00:01.000Z',
+      role: 'source',
+      transactionRef: `0x${'ce'.repeat(32)}`,
+      transferId: transfer.id,
+    })
+    const record = await RoutesTransferTransactions.getSource(db, {
+      chainId: 'eip155:8453',
+      transactionRef: `0x${'CE'.repeat(32)}`,
+      transferId: transfer.id,
+    })
+    expect(record?.transferId).toBe(transfer.id)
+  })
+})

package/src/db/tables/routesTransferTransactions.ts

@@ -0,0 +1,158 @@
+import { type Generated, sql, type Selectable } from 'kysely'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `routes_transfer_transactions` table. */
+export type Table = Omit<
+  db_Schema.RoutesTransferTransaction,
+  'environment' | 'orgId' | 'projectId'
+> & {
+  /** Environment derived by the database. */
+  environment: Generated<string>
+  /** Organization derived by the database. */
+  orgId: Generated<string>
+  /** Project derived by the database. */
+  projectId: Generated<string | null>
+}
+/** One verified transaction reference on a transfer. */
+export type Record = Selectable<Table>
+
+/**
+ * Inserts a transaction reference, lowercasing EVM hashes while preserving
+ * other references. Repeats return `undefined`; conflicting source ownership throws.
+ */
+export function insert(db: Db.Db, record: insert.Record): Promise<Record | undefined> {
+  return db.kysely
+    .insertInto('routes_transfer_transactions')
+    .values({
+      ...record,
+      transactionRef: normalize(record.chainId, record.transactionRef),
+    })
+    .onConflict((oc) => oc.columns(['transferId', 'role', 'transactionRef']).doNothing())
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace insert {
+  /** Transaction evidence; the database derives tenancy from its transfer. */
+  type Record = Omit<Selectable<Table>, 'environment' | 'orgId' | 'projectId'>
+}
+
+/** Claims a source transaction once within its transfer's organization, environment, and project. */
+export async function claimSource(db: Db.Db, record: insert.Record): Promise<claimSource.Result> {
+  const transactionRef = normalize(record.chainId, record.transactionRef)
+  const inserted = await db.kysely
+    .insertInto('routes_transfer_transactions')
+    .values({ ...record, transactionRef })
+    .onConflict((oc) => oc.doNothing())
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return { record: inserted, type: 'claimed' }
+  const existing = await getSource(db, {
+    chainId: record.chainId,
+    transactionRef,
+    transferId: record.transferId,
+  })
+  if (existing?.transferId === record.transferId) return { record: existing, type: 'replayed' }
+  return { type: 'conflict' }
+}
+
+export declare namespace claimSource {
+  /** Source transaction ownership outcome. */
+  type Result =
+    | { record: Record; type: 'claimed' }
+    | { record: Record; type: 'replayed' }
+    | { type: 'conflict' }
+}
+
+/** Gets a source claim within the given transfer's organization, environment, and project. */
+export function getSource(db: Db.Db, options: getSource.Options): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('routes_transfer_transactions as transaction')
+    .innerJoin('routes_transfers as owner', 'owner.id', 'transaction.transferId')
+    .innerJoin('routes_transfers as tenant', (join) =>
+      join
+        .on('tenant.id', '=', options.transferId)
+        .onRef('owner.orgId', '=', 'tenant.orgId')
+        .onRef('owner.environment', '=', 'tenant.environment')
+        .on(sql<boolean>`owner.project_id IS NOT DISTINCT FROM tenant.project_id`),
+    )
+    .selectAll('transaction')
+    .where('transaction.chainId', '=', options.chainId)
+    .where('transaction.role', '=', 'source')
+    .where('transaction.transactionRef', '=', normalize(options.chainId, options.transactionRef))
+    .executeTakeFirst()
+}
+
+export declare namespace getSource {
+  /** Source transaction identity. */
+  type Options = {
+    /** CAIP-2 chain containing the transaction. */
+    chainId: string
+    /** EVM transaction hash or case-sensitive chain reference. */
+    transactionRef: string
+    /** Transfer whose tenant scope is searched. */
+    transferId: string
+  }
+}
+
+/** Removes one source transaction only when the transfer still owns it. */
+export function removeSource(
+  db: Db.Db,
+  options: removeSource.Options,
+): Promise<Record | undefined> {
+  return db.kysely
+    .deleteFrom('routes_transfer_transactions')
+    .where('chainId', '=', options.chainId)
+    .where('role', '=', 'source')
+    .where('transactionRef', '=', normalize(options.chainId, options.transactionHash))
+    .where('transferId', '=', options.transferId)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace removeSource {
+  /** Exact source evidence identity and owner. */
+  type Options = {
+    /** CAIP-2 chain containing the transaction. */
+    chainId: string
+    /** Source transaction reference. */
+    transactionHash: string
+    /** Owning transfer id (`rtr_…`). */
+    transferId: string
+  }
+}
+
+/** Removes every remaining source transaction owned by one transfer. */
+export function removeSources(db: Db.Db, options: removeSources.Options): Promise<Record[]> {
+  return db.kysely
+    .deleteFrom('routes_transfer_transactions')
+    .where('role', '=', 'source')
+    .where('transferId', '=', options.transferId)
+    .returningAll()
+    .execute()
+}
+
+export declare namespace removeSources {
+  /** Source transaction owner. */
+  type Options = {
+    /** Owning transfer id (`rtr_…`). */
+    transferId: string
+  }
+}
+
+/** Lists a transfer's transaction references, oldest first. */
+export function listByTransfer(db: Db.Db, transferId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('routes_transfer_transactions')
+    .selectAll()
+    .where('transferId', '=', transferId)
+    .orderBy('createdAt', 'asc')
+    .execute()
+}
+
+/** Canonicalizes a transaction reference for storage and comparison. */
+export function normalize(chainId: string, transactionRef: string): string {
+  return chainId.startsWith('eip155:') ? transactionRef.toLowerCase() : transactionRef
+}