tapimo 0.7.1 → 0.7.2

package/src/db/tables/fundingDepositAddresses.ts

@@ -0,0 +1,376 @@
+import { sql, type JSONColumnType, type Selectable } from 'kysely'
+import * as pg from 'pg'
+
+import type * as Db from '../Db.js'
+import type * as db_Schema from '../Schema.js'
+
+/** Columns of the `funding_deposit_addresses` table. */
+export type Table = Omit<db_Schema.FundingDepositAddress, 'providerRequestIds'> & {
+  /** Private provider request identifiers stored as JSON. */
+  providerRequestIds: JSONColumnType<readonly string[], string, string>
+}
+
+/** A stored funding deposit address. */
+export type Record = Selectable<Table>
+
+/** Ownership filter derived from the authenticated API key. */
+export type Owner = {
+  /** Key environment. */
+  environment: Record['environment']
+  /** Owning organization id (`org_…`). */
+  orgId: string
+  /** Attributed project id for project-scoped API keys. */
+  projectId?: string | undefined
+}
+
+/** Identity fields that make one reusable address match a caller request. */
+export type Match = Owner & {
+  /** Customer destination token key. */
+  destinationTokenKey: string
+  /** Tempo account that receives completed deposits. */
+  recipient: string
+  /** Source-chain account that receives refunds. */
+  refundAddress: string
+  /** Source chain CAIP-2 id. */
+  sourceChainId: string
+  /** Source token key. */
+  sourceTokenKey: string
+  /** Whether Tempo guarantees normalized 1:1 delivery. */
+  subsidize: boolean
+}
+
+/** Inserts a provisioned funding deposit address. */
+export function insert(db: Db.Db, record: Record): Promise<Record> {
+  return db.kysely
+    .insertInto('funding_deposit_addresses')
+    .values({
+      ...record,
+      providerRequestIds: JSON.stringify(record.providerRequestIds),
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+}
+
+/** Inserts an address or returns the concurrently-created matching resource. */
+export async function insertOrGet(db: Db.Db, options: insertOrGet.Options): Promise<Record> {
+  const record = await db.kysely
+    .insertInto('funding_deposit_addresses')
+    .values({
+      ...options.record,
+      providerRequestIds: JSON.stringify(options.record.providerRequestIds),
+    })
+    .onConflict((oc) =>
+      oc
+        .columns([
+          'orgId',
+          'environment',
+          'projectId',
+          'sourceChainId',
+          'sourceTokenKey',
+          'destinationTokenKey',
+          'recipient',
+          'refundAddress',
+          'subsidize',
+        ])
+        .doNothing(),
+    )
+    .returningAll()
+    .executeTakeFirst()
+    .catch((cause) => {
+      if (
+        cause instanceof pg.DatabaseError &&
+        cause.code === '23505' &&
+        cause.constraint === 'funding_deposit_addresses_provider_address_key'
+      )
+        throw new ConflictError()
+      throw cause
+    })
+  if (record) return record
+  const existing = await getMatching(db, options.match)
+  if (existing) return existing
+  throw new ConflictError()
+}
+
+export declare namespace insertOrGet {
+  /** Record and stable identity used by create-or-get. */
+  type Options = {
+    /** Stable customer-visible address identity. */
+    match: Match
+    /** Provisioned address record to insert. */
+    record: Record
+  }
+}
+
+/** Gets a funding deposit address without ownership scoping. */
+export function get(db: Db.Db, id: string): Promise<Record | undefined> {
+  return db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst()
+}
+
+/** Gets a funding deposit address by its provider-owned address. */
+export function getByProviderAddress(
+  db: Db.Db,
+  options: getByProviderAddress.Options,
+): Promise<Record | undefined> {
+  const address = /^0x[0-9a-fA-F]{40}$/.test(options.address)
+    ? options.address.toLowerCase()
+    : options.address
+  return db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('address', '=', address)
+    .where('providerId', '=', options.providerId)
+    .executeTakeFirst()
+}
+
+export declare namespace getByProviderAddress {
+  /** Provider address identity received from a reconciliation trigger. */
+  type Options = {
+    /** Provider-owned reusable deposit address. */
+    address: string
+    /** Funding provider id. */
+    providerId: string
+  }
+}
+
+/** Gets an owner-visible funding deposit address. */
+export function getOwned(db: Db.Db, owner: Owner, id: string): Promise<Record | undefined> {
+  let query = db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('environment', '=', owner.environment)
+    .where('id', '=', id)
+    .where('orgId', '=', owner.orgId)
+  if (owner.projectId !== undefined) query = query.where('projectId', '=', owner.projectId)
+  return query.executeTakeFirst()
+}
+
+/** Gets the reusable address that matches one owner and route identity. */
+export function getMatching(db: Db.Db, match: Match): Promise<Record | undefined> {
+  let query = db.kysely
+    .selectFrom('funding_deposit_addresses')
+    .selectAll()
+    .where('destinationTokenKey', '=', match.destinationTokenKey)
+    .where('environment', '=', match.environment)
+    .where('orgId', '=', match.orgId)
+    .where('recipient', '=', match.recipient)
+    .where('refundAddress', '=', match.refundAddress)
+    .where('sourceChainId', '=', match.sourceChainId)
+    .where('sourceTokenKey', '=', match.sourceTokenKey)
+    .where('subsidize', '=', match.subsidize)
+  query =
+    match.projectId === undefined
+      ? query.where('projectId', 'is', null)
+      : query.where('projectId', '=', match.projectId)
+  return query.executeTakeFirst()
+}
+
+/** Claims a bounded batch of active addresses due for provider reconciliation. */
+export function claimDue(db: Db.Db, options: claimDue.Options): Promise<readonly Record[]> {
+  return db.transaction(async (tx) => {
+    const due = await tx.kysely
+      .selectFrom('funding_deposit_addresses')
+      .select('id')
+      .where('nextPollAt', '<=', options.now)
+      .where('providerId', '=', options.providerId)
+      .where('status', '=', 'active')
+      .where((eb) =>
+        eb.or([eb('pollLeaseUntil', 'is', null), eb('pollLeaseUntil', '<=', options.now)]),
+      )
+      .orderBy('nextPollAt', 'asc')
+      .orderBy('id', 'asc')
+      .limit(options.limit)
+      .forUpdate()
+      .skipLocked()
+      .execute()
+    if (due.length === 0) return []
+    return tx.kysely
+      .updateTable('funding_deposit_addresses')
+      .set({
+        pollLeaseUntil: options.leaseUntil,
+        pollLeaseVersion: sql<number>`poll_lease_version + 1`,
+      })
+      .where(
+        'id',
+        'in',
+        due.map((record) => record.id),
+      )
+      .returningAll()
+      .execute()
+  })
+}
+
+export declare namespace claimDue {
+  /** Provider and lease bounds for one reconciliation claim. */
+  type Options = {
+    /** Exclusive upper bound on rows claimed in one tick. */
+    limit: number
+    /** Expiry time assigned to each claimed lease. */
+    leaseUntil: string
+    /** Current time used for due and expired-lease comparisons. */
+    now: string
+    /** Funding provider whose addresses should be claimed. */
+    providerId: string
+  }
+}
+
+/** Claims one active address unless another reconciliation owns its lease. */
+export function claim(db: Db.Db, options: claim.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposit_addresses')
+    .set({
+      pollLeaseUntil: options.leaseUntil,
+      pollLeaseVersion: sql<number>`poll_lease_version + 1`,
+    })
+    .where('id', '=', options.id)
+    .where('status', '=', 'active')
+    .where((eb) =>
+      eb.or([eb('pollLeaseUntil', 'is', null), eb('pollLeaseUntil', '<=', options.now)]),
+    )
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace claim {
+  /** Identity and lease bounds for one reconciliation claim. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Expiry time assigned to the claimed lease. */
+    leaseUntil: string
+    /** Current time used for expired-lease comparison. */
+    now: string
+  }
+}
+
+/** Extends an active reconciliation lease without changing its fence. */
+export async function renewPoll(db: Db.Db, options: renewPoll.Options): Promise<boolean> {
+  return Boolean(
+    await db.kysely
+      .updateTable('funding_deposit_addresses')
+      .set({ pollLeaseUntil: options.leaseUntil })
+      .where('id', '=', options.id)
+      .where('pollLeaseUntil', 'is not', null)
+      .where('pollLeaseVersion', '=', options.pollLeaseVersion)
+      .where('status', '=', 'active')
+      .returning('id')
+      .executeTakeFirst(),
+  )
+}
+
+export declare namespace renewPoll {
+  /** Lease identity and renewed expiry guarded by the current fence. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Replacement reconciliation lease expiry. */
+    leaseUntil: string
+    /** Fencing token returned by the claim operation. */
+    pollLeaseVersion: number
+  }
+}
+
+/** Completes an owned reconciliation lease and schedules the address again. */
+export function completePoll(
+  db: Db.Db,
+  options: completePoll.Options,
+): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposit_addresses')
+    .set({
+      lastPolledAt: options.lastPolledAt,
+      nextPollAt: options.nextPollAt,
+      pollFailureCount: 0,
+      pollLeaseUntil: null,
+      providerRequestIds: JSON.stringify(options.providerRequestIds),
+      providerState: options.providerState,
+    })
+    .where('id', '=', options.id)
+    .where('pollLeaseVersion', '=', options.pollLeaseVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace completePoll {
+  /** Successful reconciliation result guarded by the claimed lease version. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Time when provider reconciliation completed. */
+    lastPolledAt: string
+    /** Time when this address becomes due again. */
+    nextPollAt: string
+    /** Fencing token returned by {@link claimDue}. */
+    pollLeaseVersion: number
+    /** Provider request identifiers retained from address provisioning. */
+    providerRequestIds: readonly string[]
+    /** Bounded provider reconciliation state. */
+    providerState: Record['providerState']
+  }
+}
+
+/** Releases an owned reconciliation lease after failure and schedules a retry. */
+export function failPoll(db: Db.Db, options: failPoll.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposit_addresses')
+    .set({
+      nextPollAt: options.nextPollAt,
+      pollFailureCount: sql<number>`poll_failure_count + 1`,
+      pollLeaseUntil: null,
+    })
+    .where('id', '=', options.id)
+    .where('pollLeaseVersion', '=', options.pollLeaseVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace failPoll {
+  /** Failed reconciliation result guarded by the claimed lease version. */
+  type Options = {
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Time when this address becomes eligible for retry. */
+    nextPollAt: string
+    /** Fencing token returned by {@link claimDue}. */
+    pollLeaseVersion: number
+  }
+}
+
+/** Applies a version-guarded deposit address status update. */
+export function update(db: Db.Db, options: update.Options): Promise<Record | undefined> {
+  return db.kysely
+    .updateTable('funding_deposit_addresses')
+    .set({
+      status: options.status,
+      updatedAt: options.updatedAt,
+      version: options.version,
+    })
+    .where('id', '=', options.id)
+    .where('version', '=', options.expectedVersion)
+    .returningAll()
+    .executeTakeFirst()
+}
+
+export declare namespace update {
+  /** Guarded address update fields. */
+  type Options = {
+    /** Stored version required for the update. */
+    expectedVersion: number
+    /** Funding deposit address id (`fda_…`). */
+    id: string
+    /** Replacement lifecycle status. */
+    status: Record['status']
+    /** New material update time. */
+    updatedAt: string
+    /** New material version. */
+    version: number
+  }
+}
+
+/** Provider address conflicted with a different customer-visible identity. */
+export class ConflictError extends Error {
+  override name = 'FundingDepositAddresses.ConflictError'
+}

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

@@ -0,0 +1,261 @@
+import * as Deposit from '../../internal/funding/Deposit.js'
+import * as DepositAddress from '../../internal/funding/DepositAddress.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as FundingDeposits from './fundingDeposits.js'
+
+const db = TestApp.database()
+const owner = { environment: 'production', orgId: 'org_deposits' } as const
+
+let addressCounter = 0
+async function seedAddress(input: Partial<DepositAddress.create.Input> = {}) {
+  const index = addressCounter++
+  const now = new Date(Date.UTC(2026, 0, 1, 0, 0, index))
+  return DepositAddress.create(db, {
+    apiKeyId: 'key_test',
+    deliveryStrategy: 'provider',
+    environment: owner.environment,
+    id: DepositAddress.generateId(now),
+    now,
+    orgId: owner.orgId,
+    providerOutputToken: TestFunding.providerOutputToken(),
+    snapshot: TestFunding.depositAddressSnapshot({
+      provider: { id: `relay_${index}`, name: 'Relay' },
+      recipient: `0x${index.toString(16).padStart(40, '0')}`,
+    }),
+    ...input,
+  })
+}
+
+let depositCounter = 0
+function seedDeposit(
+  address: Awaited<ReturnType<typeof seedAddress>>,
+  input: Partial<Deposit.create.Input> = {},
+) {
+  const index = depositCounter++
+  const now = new Date(Date.UTC(2026, 0, 2, 0, 0, index))
+  const sourceTransactionHash = index.toString(16).padStart(64, '0')
+  return Deposit.create(db, {
+    now,
+    providerRequestId: `relay_request_${index}`,
+    snapshot: TestFunding.depositSnapshot(address.id, {
+      provider: address.snapshot.provider,
+      sourceTransactionHashes: [sourceTransactionHash],
+    }),
+    sourceTransactionHash,
+    sourceTransferIndex: 0,
+    ...input,
+  })
+}
+
+describe('listByAddress', () => {
+  test('pages one owner-visible address newest-first', async () => {
+    const address = await seedAddress()
+    const first = await seedDeposit(address)
+    const second = await seedDeposit(address)
+    const third = await seedDeposit(address)
+    const foreign = await seedAddress({ orgId: 'org_other' })
+    await seedDeposit(foreign)
+
+    const page = await FundingDeposits.listByAddress(db, owner, address.id, { limit: 2 })
+    expect(page.map((row) => row.id)).toEqual([third.id, second.id])
+    const rest = await FundingDeposits.listByAddress(db, owner, address.id, {
+      cursor: { createdAt: second.createdAt, id: second.id },
+      limit: 2,
+    })
+    expect(rest.map((row) => row.id)).toEqual([first.id])
+  })
+
+  test('narrows project-attributed owners to their project', async () => {
+    const address = await seedAddress({ projectId: 'prj_deposit' })
+    await seedDeposit(address)
+    expect(
+      await FundingDeposits.listByAddress(db, { ...owner, projectId: 'prj_other' }, address.id, {
+        limit: 10,
+      }),
+    ).toEqual([])
+  })
+})
+
+describe('getOwned', () => {
+  test('returns owned deposits and hides foreign ownership', async () => {
+    const address = await seedAddress()
+    const record = await seedDeposit(address)
+    expect((await FundingDeposits.getOwned(db, owner, record.id))?.id).toBe(record.id)
+    expect(
+      await FundingDeposits.getOwned(db, { ...owner, orgId: 'org_other' }, record.id),
+    ).toBeUndefined()
+  })
+})
+
+describe('insert', () => {
+  test('derives identity, ownership, and route from the deposit address', async () => {
+    const address = await seedAddress({ projectId: 'prj_deposit' })
+    const foreign = await seedAddress({ orgId: 'org_other' })
+    const sourceTransactionHash = 'bb'.repeat(32)
+    const record = await Deposit.create(db, {
+      providerRequestId: 'relay_request_insert',
+      snapshot: TestFunding.depositSnapshot(address.id, {
+        destinationChain: foreign.snapshot.destinationChain,
+        destinationToken: foreign.snapshot.destinationToken,
+        provider: foreign.snapshot.provider,
+        recipient: foreign.snapshot.recipient,
+        refundAddress: foreign.snapshot.refundAddress,
+        sourceChain: { addressFormat: 'hex', id: 'eip155:1', kind: 'evm', name: 'Ethereum' },
+        sourceToken: foreign.snapshot.sourceToken,
+      }),
+      sourceTransactionHash,
+      sourceTransferIndex: 7,
+    })
+
+    expect(record).toMatchObject({
+      depositAddressId: address.id,
+      environment: address.environment,
+      id: expect.stringMatching(/^fdp_/),
+      orgId: address.orgId,
+      projectId: address.projectId,
+      providerOutputToken: address.providerOutputToken,
+      snapshot: {
+        destinationChain: address.snapshot.destinationChain,
+        destinationToken: address.snapshot.destinationToken,
+        provider: address.snapshot.provider,
+        recipient: address.snapshot.recipient,
+        refundAddress: address.snapshot.refundAddress,
+        sourceChain: address.snapshot.sourceChain,
+        sourceToken: address.snapshot.sourceToken,
+        sourceTransactionHashes: [sourceTransactionHash],
+      },
+    })
+  })
+
+  test('deduplicates one source transfer across deposit addresses', async () => {
+    const firstAddress = await seedAddress()
+    const secondAddress = await seedAddress()
+    const sourceTransactionHash = 'aa'.repeat(32)
+    await seedDeposit(firstAddress, { sourceTransactionHash, sourceTransferIndex: 7 })
+    await expect(
+      seedDeposit(secondAddress, { sourceTransactionHash, sourceTransferIndex: 7 }),
+    ).rejects.toMatchObject({ code: '23505' })
+  })
+})
+
+describe('update', () => {
+  test('applies allowed transitions and rejects terminal exits', async () => {
+    const address = await seedAddress()
+    const record = await seedDeposit(address)
+    const bridging = await Deposit.transition(db, {
+      expectedVersion: 1,
+      id: record.id,
+      status: 'bridging',
+    })
+    expect(bridging.type).toBe('applied')
+    const completed = await Deposit.transition(db, {
+      expectedVersion: 2,
+      id: record.id,
+      status: 'completed',
+    })
+    expect(completed.type).toBe('applied')
+    expect(
+      await Deposit.transition(db, {
+        expectedVersion: 3,
+        id: record.id,
+        status: 'refunding',
+      }),
+    ).toMatchObject({ type: 'invalid' })
+  })
+
+  test('persists reconciliation state without changing source identity', async () => {
+    const address = await seedAddress()
+    const foreign = await seedAddress({ orgId: 'org_other' })
+    const record = await seedDeposit(address)
+    const destinationTransactionHash = `0x${'cc'.repeat(32)}`
+    const providerTransactionHash = `0x${'dd'.repeat(32)}`
+    const result = await Deposit.transition(db, {
+      expectedVersion: 1,
+      id: record.id,
+      providerOutputAmount: {
+        baseUnits: '98889820',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '98.88982',
+      },
+      providerRequestIds: ['relay-request'],
+      providerState: { request: 'provider-state' },
+      providerTransactionHashes: [providerTransactionHash],
+      retryState: { attempts: 1 },
+      settlementTransaction: `0x${'ab'.repeat(32)}`,
+      settlementTransactionHash: `0x${'ee'.repeat(32)}`,
+      snapshot: {
+        ...record.snapshot,
+        depositAddressId: foreign.id,
+        destinationTransactionHashes: [destinationTransactionHash],
+        sourceChain: { addressFormat: 'hex', id: 'eip155:1', kind: 'evm', name: 'Ethereum' },
+        sourceTransactionHashes: ['changed-source-transaction'],
+      },
+      status: 'bridging',
+      subsidyAmount: {
+        baseUnits: '1110180',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '1.11018',
+      },
+      tempoGasPaid: '21000',
+    })
+
+    expect(result).toMatchObject({
+      record: {
+        depositAddressId: record.depositAddressId,
+        providerOutputAmount: { baseUnits: '98889820' },
+        providerRequestIds: ['relay-request'],
+        providerState: { request: 'provider-state' },
+        providerTransactionHashes: [providerTransactionHash],
+        retryState: { attempts: 1 },
+        settlementTransaction: `0x${'ab'.repeat(32)}`,
+        settlementTransactionHash: `0x${'ee'.repeat(32)}`,
+        snapshot: {
+          depositAddressId: record.snapshot.depositAddressId,
+          destinationTransactionHashes: [destinationTransactionHash],
+          sourceChain: record.snapshot.sourceChain,
+          sourceTransactionHashes: record.snapshot.sourceTransactionHashes,
+        },
+        status: 'bridging',
+        subsidyAmount: { baseUnits: '1110180' },
+        tempoGasPaid: '21000',
+      },
+      type: 'applied',
+    })
+  })
+})
+
+describe('toPublic', () => {
+  test('omits private reconciliation and settlement state', async () => {
+    const address = await seedAddress()
+    const record = await seedDeposit(address, {
+      providerOutputAmount: {
+        baseUnits: '98889820',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '98.88982',
+      },
+      providerRequestIds: ['relay-request'],
+      providerState: { correlation: 'private' },
+      settlementTransaction: `0x${'ab'.repeat(32)}`,
+      subsidyAmount: {
+        baseUnits: '1110180',
+        currency: 'USD',
+        decimals: 6,
+        formatted: '1.11018',
+      },
+    })
+    const public_ = Deposit.toPublic(record)
+    expect(public_.sourceTransferIndex).toBe(record.sourceTransferIndex)
+    expect(public_).not.toMatchObject({
+      providerOutputAmount: expect.anything(),
+      providerOutputToken: expect.anything(),
+      providerRequestIds: expect.anything(),
+      providerState: expect.anything(),
+      settlementTransaction: expect.anything(),
+      subsidyAmount: expect.anything(),
+    })
+  })
+})