tapimo 0.7.2 → 0.9.0

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

@@ -77,6 +77,180 @@ describe('listByAddress', () => {
   })
 })
 
+describe('listByDepositAddress', () => {
+  const seedAddressDeposit = (address: Awaited<ReturnType<typeof seedAddress>>, index: number) => {
+    const sourceTransactionHash = `fe${index.toString(16).padStart(62, '0')}`
+    return Deposit.create(db, {
+      now: new Date(Date.UTC(2026, 1, 2, 0, 0, index)),
+      providerRequestId: `relay_deposit_address_request_${index}`,
+      snapshot: TestFunding.depositSnapshot(address.id, {
+        provider: address.snapshot.provider,
+        sourceTransactionHashes: [sourceTransactionHash],
+      }),
+      sourceTransactionHash,
+      sourceTransferIndex: 0,
+    })
+  }
+
+  test('pages one reusable address across provider records newest-first', async () => {
+    const depositAddress = 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE'
+    const firstAddress = await seedAddress({
+      snapshot: TestFunding.depositAddressSnapshot({
+        address: depositAddress,
+        provider: { id: 'relay_deposit_address_first', name: 'Relay' },
+      }),
+    })
+    const secondAddress = await seedAddress({
+      snapshot: TestFunding.depositAddressSnapshot({
+        address: depositAddress,
+        provider: { id: 'relay_deposit_address_second', name: 'Relay' },
+        subsidize: true,
+      }),
+    })
+    const first = await seedAddressDeposit(firstAddress, 1)
+    const second = await seedAddressDeposit(secondAddress, 2)
+    const third = await seedAddressDeposit(firstAddress, 3)
+    const unrelatedAddress = await seedAddress({
+      snapshot: TestFunding.depositAddressSnapshot({
+        address: 'TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3',
+        provider: { id: 'relay_deposit_address_unrelated', name: 'Relay' },
+        recipient: `0x${'fe'.repeat(20)}`,
+      }),
+    })
+    await seedAddressDeposit(unrelatedAddress, 4)
+
+    const page = await FundingDeposits.listByDepositAddress(db, {
+      depositAddress,
+      limit: 2,
+      owner,
+    })
+    expect(page.map((row) => row.id)).toEqual([third.id, second.id])
+    const rest = await FundingDeposits.listByDepositAddress(db, {
+      cursor: { createdAt: second.createdAt, id: second.id },
+      depositAddress,
+      limit: 2,
+      owner,
+    })
+    expect(rest.map((row) => row.id)).toEqual([first.id])
+  })
+
+  test('narrows project-attributed owners to their project', async () => {
+    const depositAddress = 'TWd4WrZ9wn84f5x1hZhL4DHvk738ns5jwb'
+    const address = await seedAddress({
+      projectId: 'prj_deposit',
+      snapshot: TestFunding.depositAddressSnapshot({
+        address: depositAddress,
+        provider: { id: 'relay_deposit_address_project', name: 'Relay' },
+      }),
+    })
+    await seedAddressDeposit(address, 5)
+
+    expect(
+      await FundingDeposits.listByDepositAddress(db, {
+        depositAddress,
+        limit: 10,
+        owner: { ...owner, projectId: 'prj_other' },
+      }),
+    ).toEqual([])
+  })
+
+  test('normalizes EVM address casing', async () => {
+    const depositAddress = `0x${'Ab'.repeat(20)}`
+    const source = TestFunding.transferSnapshot()
+    const address = await seedAddress({
+      snapshot: TestFunding.depositAddressSnapshot({
+        address: depositAddress,
+        provider: { id: 'relay_deposit_address_evm', name: 'Relay' },
+        recipient: `0x${'fd'.repeat(20)}`,
+        refundAddress: depositAddress,
+        sourceChain: source.sourceChain,
+        sourceToken: source.sourceToken,
+      }),
+    })
+    const record = await seedAddressDeposit(address, 6)
+
+    const rows = await FundingDeposits.listByDepositAddress(db, {
+      depositAddress,
+      limit: 10,
+      owner,
+    })
+    expect(rows.map((row) => row.id)).toEqual([record.id])
+  })
+})
+
+describe('listByRecipient', () => {
+  test('pages recipient deposits across addresses and hides foreign ownership', async () => {
+    const recipient = '0xABcdEFABcdEFabcdEfAbCdefabcdeFABcDEFabCD'
+    const firstAddress = await seedAddress({
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_first', name: 'Relay' },
+        recipient,
+      }),
+    })
+    const secondAddress = await seedAddress({
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_second', name: 'Relay' },
+        recipient,
+        subsidize: true,
+      }),
+    })
+    const first = await seedDeposit(firstAddress)
+    const second = await seedDeposit(secondAddress)
+    const third = await seedDeposit(firstAddress)
+    const unrelatedAddress = await seedAddress()
+    await seedDeposit(unrelatedAddress)
+    const foreignAddress = await seedAddress({
+      orgId: 'org_other',
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_foreign', name: 'Relay' },
+        recipient,
+      }),
+    })
+    await seedDeposit(foreignAddress)
+
+    const page = await FundingDeposits.listByRecipient(db, {
+      limit: 2,
+      owner,
+      recipient: recipient.toLowerCase(),
+    })
+    expect(page.map((row) => row.id)).toEqual([third.id, second.id])
+    const rest = await FundingDeposits.listByRecipient(db, {
+      cursor: { createdAt: second.createdAt, id: second.id },
+      limit: 2,
+      owner,
+      recipient: recipient.toLowerCase(),
+    })
+    expect(rest.map((row) => row.id)).toEqual([first.id])
+  })
+
+  test('narrows project-attributed owners to their project', async () => {
+    const recipient = `0x${'ab'.repeat(20)}`
+    const firstAddress = await seedAddress({
+      projectId: 'prj_deposit',
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_project', name: 'Relay' },
+        recipient,
+      }),
+    })
+    const secondAddress = await seedAddress({
+      projectId: 'prj_other',
+      snapshot: TestFunding.depositAddressSnapshot({
+        provider: { id: 'relay_recipient_other_project', name: 'Relay' },
+        recipient,
+      }),
+    })
+    const first = await seedDeposit(firstAddress)
+    await seedDeposit(secondAddress)
+
+    const rows = await FundingDeposits.listByRecipient(db, {
+      limit: 10,
+      owner: { ...owner, projectId: 'prj_deposit' },
+      recipient,
+    })
+    expect(rows.map((row) => row.id)).toEqual([first.id])
+  })
+})
+
 describe('getOwned', () => {
   test('returns owned deposits and hides foreign ownership', async () => {
     const address = await seedAddress()
@@ -227,6 +401,71 @@ describe('update', () => {
   })
 })
 
+describe('recordRequestObservation', () => {
+  test('attaches the first poll and webhook timestamps without changing material state', async () => {
+    const address = await seedAddress()
+    const record = await seedDeposit(address, { providerRequestId: 'relay_observed' })
+    await FundingDeposits.recordRequestObservation(db, {
+      depositAddressId: address.id,
+      pollObservedAt: '2026-01-02T00:00:02.000Z',
+      providerRequestId: 'relay_observed',
+      webhookReceivedAt: '2026-01-02T00:00:03.000Z',
+    })
+    await FundingDeposits.recordRequestObservation(db, {
+      depositAddressId: address.id,
+      pollObservedAt: '2026-01-02T00:00:01.000Z',
+      providerRequestId: 'relay_observed',
+      webhookReceivedAt: '2026-01-02T00:00:04.000Z',
+    })
+
+    expect(await FundingDeposits.get(db, record.id)).toMatchInlineSnapshot(
+      {
+        createdAt: expect.any(String),
+        depositAddressId: expect.any(String),
+        id: expect.any(String),
+        providerOutputToken: expect.any(Object),
+        snapshot: expect.any(Object),
+        updatedAt: expect.any(String),
+      },
+      `
+      {
+        "createdAt": Any<String>,
+        "depositAddressId": Any<String>,
+        "detectionTrigger": null,
+        "environment": "production",
+        "id": Any<String>,
+        "orgId": "org_deposits",
+        "pollObservedAt": "2026-01-02T00:00:01.000Z",
+        "projectId": null,
+        "providerOutputAmount": null,
+        "providerOutputToken": Any<Object>,
+        "providerRequestId": "relay_observed",
+        "providerRequestIds": [
+          "relay_observed",
+        ],
+        "providerState": null,
+        "providerTransactionHashes": [],
+        "providerTransferIndex": 0,
+        "retryState": null,
+        "settlementTransaction": null,
+        "settlementTransactionHash": null,
+        "snapshot": Any<Object>,
+        "sourceChainId": "tron:0x2b6653dc",
+        "sourceTransactionHash": "0000000000000000000000000000000000000000000000000000000000000011",
+        "sourceTransferIndex": 0,
+        "status": "detected",
+        "statusReason": null,
+        "subsidyAmount": null,
+        "tempoGasPaid": null,
+        "updatedAt": Any<String>,
+        "version": 1,
+        "webhookReceivedAt": "2026-01-02T00:00:03.000Z",
+      }
+    `,
+    )
+  })
+})
+
 describe('toPublic', () => {
   test('omits private reconciliation and settlement state', async () => {
     const address = await seedAddress()

package/src/db/tables/fundingDeposits.ts

@@ -1,4 +1,4 @@
-import type { JSONColumnType, Selectable } from 'kysely'
+import { sql, type JSONColumnType, type Selectable } from 'kysely'
 
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
@@ -40,6 +40,63 @@ export function insert(db: Db.Db, record: Record): Promise<Record> {
     .executeTakeFirstOrThrow()
 }
 
+/** Inserts a chain-observed source transfer or returns its existing deposit. */
+export async function insertOrGetSource(
+  db: Db.Db,
+  record: Record & { sourceTransferIndex: number },
+): Promise<insertOrGetSource.Result> {
+  const inserted = await db.kysely
+    .insertInto('funding_deposits')
+    .values({
+      ...record,
+      providerRequestIds: JSON.stringify(record.providerRequestIds),
+      providerTransactionHashes: JSON.stringify(record.providerTransactionHashes),
+    })
+    .onConflict((oc) =>
+      oc.columns(['depositAddressId', 'sourceTransactionHash', 'sourceTransferIndex']).doNothing(),
+    )
+    .returningAll()
+    .executeTakeFirst()
+  if (inserted) return { record: inserted, type: 'created' }
+  const existing = await db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('depositAddressId', '=', record.depositAddressId)
+    .where('sourceTransactionHash', '=', record.sourceTransactionHash)
+    .where('sourceTransferIndex', '=', record.sourceTransferIndex)
+    .executeTakeFirstOrThrow()
+  return { record: existing, type: 'existing' }
+}
+
+export declare namespace insertOrGetSource {
+  /** Result of idempotently persisting one verified source transfer. */
+  type Result = { record: Record; type: 'created' | 'existing' }
+}
+
+/** Serializes source attribution for one address and transaction. */
+export function withSourceTransaction<const result>(
+  db: Db.Db,
+  options: withSourceTransaction.Options<result>,
+): Promise<result> {
+  return db.transaction(async (tx) => {
+    const key = `${options.depositAddressId}:${options.sourceTransactionHash.toLowerCase()}`
+    await sql`SELECT pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(tx.kysely)
+    return options.fn(tx)
+  })
+}
+
+export declare namespace withSourceTransaction {
+  /** Source identity and transaction-scoped work protected by its advisory lock. */
+  type Options<result> = {
+    /** Funding deposit address that received the transfer. */
+    depositAddressId: string
+    /** Database work serialized for the source transaction. */
+    fn: (db: Db.Db) => Promise<result>
+    /** Source transaction whose deposit attribution must not race. */
+    sourceTransactionHash: string
+  }
+}
+
 /** Gets deposits created from one provider-observed source transaction. */
 export function listByProviderObservation(
   db: Db.Db,
@@ -67,6 +124,45 @@ export declare namespace listByProviderObservation {
   }
 }
 
+/** Attaches first-observation timestamps to every deposit from one provider request. */
+export function recordRequestObservation(
+  db: Db.Db,
+  options: recordRequestObservation.Options,
+): Promise<Record[]> {
+  return db.kysely
+    .updateTable('funding_deposits')
+    .set({
+      ...(options.pollObservedAt
+        ? {
+            pollObservedAt: sql<string>`LEAST(COALESCE(poll_observed_at, ${options.pollObservedAt}), ${options.pollObservedAt})`,
+          }
+        : {}),
+      ...(options.webhookReceivedAt
+        ? {
+            webhookReceivedAt: sql<string>`LEAST(COALESCE(webhook_received_at, ${options.webhookReceivedAt}), ${options.webhookReceivedAt})`,
+          }
+        : {}),
+    })
+    .where('depositAddressId', '=', options.depositAddressId)
+    .where('providerRequestId', '=', options.providerRequestId)
+    .returningAll()
+    .execute()
+}
+
+export declare namespace recordRequestObservation {
+  /** First observations associated with one provider request. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    depositAddressId: string
+    /** When polling first observed the provider request. */
+    pollObservedAt?: string | undefined
+    /** Provider request identifier. */
+    providerRequestId: string
+    /** When Tempo first received an authenticated provider webhook. */
+    webhookReceivedAt?: string | undefined
+  }
+}
+
 /** Gets deposits associated with one address and source transaction. */
 export function listBySourceTransaction(
   db: Db.Db,
@@ -91,6 +187,32 @@ export declare namespace listBySourceTransaction {
   }
 }
 
+/** Lists nonterminal source transfers that await provider attribution. */
+export function listUnattributed(db: Db.Db, depositAddressId: string): Promise<Record[]> {
+  return db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('depositAddressId', '=', depositAddressId)
+    .where('providerRequestId', 'is', null)
+    .where('status', 'not in', ['completed', 'refunded'])
+    .orderBy('createdAt', 'asc')
+    .orderBy('id', 'asc')
+    .execute()
+}
+
+/** Returns whether an address has a source transfer awaiting provider attribution. */
+export async function hasUnattributed(db: Db.Db, depositAddressId: string): Promise<boolean> {
+  return Boolean(
+    await db.kysely
+      .selectFrom('funding_deposits')
+      .select('id')
+      .where('depositAddressId', '=', depositAddressId)
+      .where('providerRequestId', 'is', null)
+      .limit(1)
+      .executeTakeFirst(),
+  )
+}
+
 /** Gets a funding deposit without ownership scoping. */
 export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely
@@ -155,6 +277,97 @@ export declare namespace listByAddress {
   }
 }
 
+/** Lists deposits for one reusable source-chain address newest-first. */
+export function listByDepositAddress(
+  db: Db.Db,
+  options: listByDepositAddress.Options,
+): Promise<Record[]> {
+  const { cursor, depositAddress, limit, owner } = options
+  const address = /^0x[0-9a-fA-F]{40}$/.test(depositAddress)
+    ? depositAddress.toLowerCase()
+    : depositAddress
+  let query = db.kysely
+    .selectFrom('funding_deposits')
+    .innerJoin(
+      'funding_deposit_addresses',
+      'funding_deposit_addresses.id',
+      'funding_deposits.depositAddressId',
+    )
+    .selectAll('funding_deposits')
+    .where('funding_deposit_addresses.address', '=', address)
+    .where('funding_deposit_addresses.environment', '=', owner.environment)
+    .where('funding_deposit_addresses.orgId', '=', owner.orgId)
+    .where('funding_deposits.environment', '=', owner.environment)
+    .where('funding_deposits.orgId', '=', owner.orgId)
+  if (owner.projectId !== undefined)
+    query = query
+      .where('funding_deposit_addresses.projectId', '=', owner.projectId)
+      .where('funding_deposits.projectId', '=', owner.projectId)
+  if (cursor)
+    query = query.where((eb) =>
+      eb.or([
+        eb('funding_deposits.createdAt', '<', cursor.createdAt),
+        eb.and([
+          eb('funding_deposits.createdAt', '=', cursor.createdAt),
+          eb('funding_deposits.id', '<', cursor.id),
+        ]),
+      ]),
+    )
+  return query
+    .orderBy('funding_deposits.createdAt', 'desc')
+    .orderBy('funding_deposits.id', 'desc')
+    .limit(limit)
+    .execute()
+}
+
+export declare namespace listByDepositAddress {
+  /** Deposit address filter, ownership, and paging options. */
+  type Options = {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: listByAddress.Cursor | undefined
+    /** Reusable source-chain address that received the funds. */
+    depositAddress: string
+    /** Maximum rows to return. */
+    limit: number
+    /** Ownership filter derived from the authenticated API key. */
+    owner: Owner
+  }
+}
+
+/** Lists one recipient's owner-visible deposits newest-first. */
+export function listByRecipient(db: Db.Db, options: listByRecipient.Options): Promise<Record[]> {
+  const { cursor, limit, owner, recipient } = options
+  let query = db.kysely
+    .selectFrom('funding_deposits')
+    .selectAll()
+    .where('environment', '=', owner.environment)
+    .where('orgId', '=', owner.orgId)
+    .where(sql<boolean>`lower(snapshot->>'recipient') = ${recipient.toLowerCase()}`)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  if (cursor)
+    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(limit).execute()
+}
+
+export declare namespace listByRecipient {
+  /** Recipient filter, ownership, and paging options. */
+  type Options = {
+    /** Exclusive lower bound from the previous page. */
+    cursor?: listByAddress.Cursor | undefined
+    /** Maximum rows to return. */
+    limit: number
+    /** Ownership filter derived from the authenticated API key. */
+    owner: Owner
+    /** Tempo account that receives completed deposits. */
+    recipient: string
+  }
+}
+
 /** Applies a version-guarded deposit update. */
 export function update(db: Db.Db, options: update.Options): Promise<Record | undefined> {
   return db.kysely