tapimo 0.14.0 → 0.15.0

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

@@ -0,0 +1,1048 @@
+import { sql } from 'kysely'
+
+import * as Deposit from '../../internal/routes/Deposit.js'
+import * as DepositAddress from '../../internal/routes/DepositAddress.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestRoutes from '../../../test/Routes.js'
+import * as Db from '../Db.js'
+import * as Organizations from './organizations.js'
+import * as RoutesDepositAddresses from './routesDepositAddresses.js'
+import * as RoutesIdempotency from './routesIdempotency.js'
+
+const db = TestApp.database()
+const owner = { environment: 'production', orgId: 'org_deposit_addresses' } as const
+
+let counter = 0
+function seed(input: Partial<DepositAddress.create.Input> = {}) {
+  const index = counter++
+  const now = new Date(Date.UTC(2026, 0, 1, 0, 0, index))
+  const { snapshot, ...rest } = input
+  return DepositAddress.create(db, {
+    deliveryStrategy: 'provider',
+    environment: owner.environment,
+    id: DepositAddress.generateId(now),
+    now,
+    orgId: owner.orgId,
+    providerOutputToken: TestRoutes.providerOutputToken(),
+    snapshot: TestRoutes.depositAddressSnapshot({
+      provider: { id: `relay_${index}`, name: 'Relay' },
+      recipient: `0x${index.toString(16).padStart(40, '0')}`,
+      ...snapshot,
+    }),
+    ...rest,
+  })
+}
+
+describe('getOwned', () => {
+  test('returns owned addresses and hides foreign ownership', async () => {
+    const record = await seed()
+    expect((await RoutesDepositAddresses.getOwned(db, owner, record.id))?.id).toBe(record.id)
+    expect(
+      await RoutesDepositAddresses.getOwned(db, { ...owner, orgId: 'org_other' }, record.id),
+    ).toBeUndefined()
+    expect(
+      await RoutesDepositAddresses.getOwned(db, { ...owner, projectId: 'prj_other' }, record.id),
+    ).toBeUndefined()
+    await DepositAddress.transition(db, {
+      expectedVersion: record.version,
+      id: record.id,
+      status: 'deactivated',
+    })
+    expect(await RoutesDepositAddresses.getOwned(db, owner, record.id)).toBeUndefined()
+  })
+})
+
+describe('getByProviderAddress', () => {
+  test('excludes deactivated addresses from provider-triggered work', async () => {
+    const record = await seed()
+    expect(
+      await RoutesDepositAddresses.getByProviderAddress(db, {
+        address: record.address,
+        providerId: record.providerId,
+      }),
+    ).toMatchObject({ id: record.id })
+    await DepositAddress.transition(db, {
+      expectedVersion: record.version,
+      id: record.id,
+      status: 'deactivated',
+    })
+    expect(
+      await RoutesDepositAddresses.getByProviderAddress(db, {
+        address: record.address,
+        providerId: record.providerId,
+      }),
+    ).toBeUndefined()
+  })
+})
+
+describe('routes migration', () => {
+  test('backfills canonical creator attribution for retained addresses', async () => {
+    const orgId = 'org_deposit_address_creator_backfill'
+    const userId = 'usr_deposit_address_creator_backfill'
+    await Organizations.create(db, { id: orgId, name: 'Creator backfill', userId })
+    const record = await seed({ orgId })
+    await db.kysely
+      .updateTable('routes_deposit_addresses')
+      .set({ creatorUserId: null })
+      .where('id', '=', record.id)
+      .execute()
+    const migration = Db.migrations.find(
+      (candidate) => candidate.name === '0265_routes_deposit_address_creator',
+    )
+    if (!migration) throw new Error('Expected the creator-attribution migration.')
+
+    for (let run = 0; run < 2; run++) await migration.up(db.kysely).execute()
+
+    await expect(RoutesDepositAddresses.get(db, record.id)).resolves.toMatchObject({
+      creatorUserId: userId,
+    })
+  })
+
+  test('backfills legacy snapshots and remains safe to rerun', async () => {
+    const record = await seed({
+      snapshot: TestRoutes.depositAddressSnapshot({ subsidize: true }),
+    })
+    await sql`UPDATE routes_deposit_addresses SET snapshot = snapshot - 'subsidize' WHERE id = ${record.id}`.execute(
+      db.kysely,
+    )
+    const migration = Db.migrations.find((candidate) => candidate.name === '0190_routes_tables')
+    if (!migration) throw new Error('Expected the routes migration.')
+
+    const legacy = await RoutesDepositAddresses.get(db, record.id)
+    if (!legacy) throw new Error('Expected a legacy route deposit address.')
+    for (let run = 0; run < 2; run++) await migration.up(db.kysely).execute()
+    const migrated = await RoutesDepositAddresses.get(db, record.id)
+    if (!migrated) throw new Error('Expected a migrated route deposit address.')
+
+    expect({
+      legacyPublic: DepositAddress.toPublic(legacy),
+      migratedSnapshot: migrated.snapshot,
+    }).toMatchInlineSnapshot(
+      {
+        legacyPublic: {
+          createdAt: expect.any(String),
+          id: expect.any(String),
+          updatedAt: expect.any(String),
+        },
+      },
+      `
+      {
+        "legacyPublic": {
+          "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+          "createdAt": Any<String>,
+          "destinationChain": {
+            "addressFormat": "hex",
+            "id": "eip155:4217",
+            "kind": "evm",
+            "name": "Tempo",
+          },
+          "destinationToken": {
+            "address": "0x20c00000000000000000000014f22ca97301eb73",
+            "currency": "USD",
+            "decimals": 6,
+            "name": "USDT0",
+            "standard": "TIP-20",
+            "symbol": "USDT0",
+            "tokenKey": "eip155:4217/erc20:0x20c00000000000000000000014f22ca97301eb73",
+            "verified": true,
+          },
+          "id": Any<String>,
+          "provider": {
+            "id": "relay",
+            "name": "Relay",
+          },
+          "recipient": "0x1111111111111111111111111111111111111111",
+          "refundAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+          "sourceChain": {
+            "addressFormat": "base58check",
+            "id": "tron:0x2b6653dc",
+            "kind": "tron",
+            "name": "Tron",
+          },
+          "sourceToken": {
+            "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+            "currency": "USD",
+            "decimals": 6,
+            "name": "Tether USD",
+            "standard": "TRC-20",
+            "symbol": "USDT",
+            "tokenKey": "tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+            "verified": true,
+          },
+          "status": "active",
+          "subsidize": true,
+          "updatedAt": Any<String>,
+        },
+        "migratedSnapshot": {
+          "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+          "destinationChain": {
+            "addressFormat": "hex",
+            "id": "eip155:4217",
+            "kind": "evm",
+            "name": "Tempo",
+          },
+          "destinationToken": {
+            "address": "0x20c00000000000000000000014f22ca97301eb73",
+            "currency": "USD",
+            "decimals": 6,
+            "name": "USDT0",
+            "standard": "TIP-20",
+            "symbol": "USDT0",
+            "tokenKey": "eip155:4217/erc20:0x20c00000000000000000000014f22ca97301eb73",
+            "verified": true,
+          },
+          "provider": {
+            "id": "relay",
+            "name": "Relay",
+          },
+          "recipient": "0x1111111111111111111111111111111111111111",
+          "refundAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+          "sourceChain": {
+            "addressFormat": "base58check",
+            "id": "tron:0x2b6653dc",
+            "kind": "tron",
+            "name": "Tron",
+          },
+          "sourceToken": {
+            "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+            "currency": "USD",
+            "decimals": 6,
+            "name": "Tether USD",
+            "standard": "TRC-20",
+            "symbol": "USDT",
+            "tokenKey": "tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+            "verified": true,
+          },
+          "subsidize": true,
+        },
+      }
+    `,
+    )
+  })
+})
+
+describe('getMatching', () => {
+  test('matches the owner, route, recipient, and refund address', async () => {
+    const record = await seed()
+    const match: RoutesDepositAddresses.Match = {
+      destinationTokenKey: record.destinationTokenKey,
+      environment: record.environment,
+      orgId: record.orgId,
+      recipient: record.recipient,
+      refundAddress: record.refundAddress,
+      sourceChainId: record.sourceChainId,
+      sourceTokenKey: record.sourceTokenKey,
+      subsidize: record.subsidize,
+    }
+
+    expect((await RoutesDepositAddresses.getMatching(db, match))?.id).toBe(record.id)
+    expect(
+      await RoutesDepositAddresses.getMatching(db, { ...match, refundAddress: 'TWrong' }),
+    ).toBeUndefined()
+  })
+})
+
+describe('validateCreationCapacity', () => {
+  afterEach(async () => {
+    await db.kysely.deleteFrom('routes_idempotency_requests').execute()
+  })
+
+  test('blocks fresh provisioning during the unattributed rollout drain', async () => {
+    await Organizations.upsert(db, { id: owner.orgId, name: 'Deposit addresses' })
+    const existing = await seed()
+    const legacy = await RoutesIdempotency.claim(db, {
+      apiKeyId: 'key_legacy_worker',
+      irrevocable: false,
+      keyHash: 'hash_legacy_worker',
+      operation: RoutesIdempotency.operations.depositAddress,
+      orgId: owner.orgId,
+      requestHash: 'request_legacy_worker',
+      ttlMs: 60_000,
+    })
+    if (legacy.type !== 'claimed') throw new Error('Expected a fresh legacy claim.')
+    await RoutesIdempotency.checkpoint(db, {
+      apiKeyId: 'key_legacy_worker',
+      createdAt: legacy.createdAt,
+      keyHash: 'hash_legacy_worker',
+      replayTtlMs: 86_400_000,
+      response: '{"requestId":"relay_legacy"}',
+    })
+    await db.kysely
+      .updateTable('routes_idempotency_requests')
+      .set({ matchHash: null, operation: null, orgId: null })
+      .where('apiKeyId', '=', 'key_legacy_worker')
+      .where('keyHash', '=', 'hash_legacy_worker')
+      .execute()
+    const claim = async (apiKeyId: string, keyHash: string) => {
+      const result = await RoutesDepositAddresses.claimCreation(db, {
+        claim: {
+          apiKeyId,
+          irrevocable: false,
+          keyHash,
+          requestHash: `request_${keyHash}`,
+          ttlMs: 60_000,
+        },
+        orgId: owner.orgId,
+      })
+      if (result.type !== 'claimed') throw new Error('Expected a fresh claim.')
+      return { apiKeyId, createdAt: result.createdAt, keyHash }
+    }
+    const match: RoutesDepositAddresses.Match = {
+      destinationTokenKey: existing.destinationTokenKey,
+      environment: existing.environment,
+      orgId: existing.orgId,
+      recipient: existing.recipient,
+      refundAddress: existing.refundAddress,
+      sourceChainId: existing.sourceChainId,
+      sourceTokenKey: existing.sourceTokenKey,
+      subsidize: existing.subsidize,
+    }
+    const reusable = await RoutesDepositAddresses.validateCreationCapacity(db, {
+      claim: await claim('key_reusable', 'hash_reusable'),
+      match,
+      matchHash: 'match_reusable',
+      maxPerCreator: 100,
+      orgId: owner.orgId,
+      pendingTtlMs: 60_000,
+      replayTtlMs: 86_400_000,
+      serializeMatchingResponse: (record) => JSON.stringify({ id: record.id }),
+    })
+
+    expect(reusable).toMatchObject({ record: { id: existing.id }, type: 'existing' })
+    await expect(
+      RoutesDepositAddresses.validateCreationCapacity(db, {
+        claim: await claim('key_fresh', 'hash_fresh'),
+        match: { ...match, recipient: `0x${'ab'.repeat(20)}` },
+        matchHash: 'match_fresh',
+        maxPerCreator: 100,
+        orgId: owner.orgId,
+        pendingTtlMs: 60_000,
+        replayTtlMs: 86_400_000,
+        serializeMatchingResponse: (record) => JSON.stringify({ id: record.id }),
+      }),
+    ).rejects.toThrow(RoutesDepositAddresses.MatchInProgressError)
+  })
+
+  test('does not charge a matching pending claim against the final slot', async () => {
+    await Organizations.upsert(db, { id: owner.orgId, name: 'Deposit addresses' })
+    const existing = await seed()
+    const maxPerCreator = (await RoutesDepositAddresses.countByOrganization(db, owner.orgId)) + 1
+    const match: RoutesDepositAddresses.Match = {
+      destinationTokenKey: existing.destinationTokenKey,
+      environment: existing.environment,
+      orgId: existing.orgId,
+      recipient: existing.recipient,
+      refundAddress: existing.refundAddress,
+      sourceChainId: existing.sourceChainId,
+      sourceTokenKey: existing.sourceTokenKey,
+      subsidize: existing.subsidize,
+    }
+    const claim = async (apiKeyId: string, keyHash: string, requestHash: string) => {
+      const result = await RoutesDepositAddresses.claimCreation(db, {
+        claim: { apiKeyId, irrevocable: false, keyHash, requestHash, ttlMs: 60_000 },
+        orgId: owner.orgId,
+      })
+      if (result.type !== 'claimed') throw new Error('Expected a fresh claim.')
+      return { apiKeyId, createdAt: result.createdAt, keyHash }
+    }
+    const matching = await claim('key_matching', 'hash_matching', 'request_matching')
+    const finalSlot = await claim('key_final_slot', 'hash_final_slot', 'request_final_slot')
+
+    await RoutesDepositAddresses.validateCreationCapacity(db, {
+      claim: matching,
+      match,
+      matchHash: 'match_existing',
+      maxPerCreator,
+      orgId: owner.orgId,
+      pendingTtlMs: 60_000,
+      replayTtlMs: 86_400_000,
+      serializeMatchingResponse: (record) => JSON.stringify({ id: record.id }),
+    })
+    await RoutesDepositAddresses.validateCreationCapacity(db, {
+      claim: finalSlot,
+      match: { ...match, recipient: `0x${'ab'.repeat(20)}` },
+      matchHash: 'match_final_slot',
+      maxPerCreator,
+      orgId: owner.orgId,
+      pendingTtlMs: 60_000,
+      replayTtlMs: 86_400_000,
+      serializeMatchingResponse: (record) => JSON.stringify({ id: record.id }),
+    })
+
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['apiKeyId', 'status'])
+        .where('apiKeyId', 'in', [matching.apiKeyId, finalSlot.apiKeyId])
+        .orderBy('apiKeyId')
+        .execute(),
+    ).resolves.toEqual([
+      { apiKeyId: 'key_final_slot', status: 'pending' },
+      { apiKeyId: 'key_matching', status: 'completed' },
+    ])
+    await expect(
+      RoutesIdempotency.countInFlightDepositAddresses(db, {
+        orgId: owner.orgId,
+        userId: null,
+      }),
+    ).resolves.toBe(1)
+  })
+
+  test('completes a recovered checkpoint when its durable match already exists', async () => {
+    await Organizations.upsert(db, { id: owner.orgId, name: 'Deposit addresses' })
+    const existing = await seed()
+    const match: RoutesDepositAddresses.Match = {
+      destinationTokenKey: existing.destinationTokenKey,
+      environment: existing.environment,
+      orgId: existing.orgId,
+      recipient: existing.recipient,
+      refundAddress: existing.refundAddress,
+      sourceChainId: existing.sourceChainId,
+      sourceTokenKey: existing.sourceTokenKey,
+      subsidize: existing.subsidize,
+    }
+    const claim = async (apiKeyId: string, keyHash: string) => {
+      const result = await RoutesDepositAddresses.claimCreation(db, {
+        claim: { apiKeyId, irrevocable: false, keyHash, requestHash: keyHash, ttlMs: 60_000 },
+        orgId: owner.orgId,
+      })
+      if (result.type !== 'claimed') throw new Error('Expected a fresh claim.')
+      return { apiKeyId, createdAt: result.createdAt, keyHash }
+    }
+    const recoveredClaim = await claim('key_recovered_existing', 'hash_recovered_existing')
+    await RoutesIdempotency.checkpoint(db, {
+      ...recoveredClaim,
+      replayTtlMs: 86_400_000,
+      response: '{"requestId":"relay_recovered"}',
+    })
+    const current = await claim('key_current_existing', 'hash_current_existing')
+
+    await RoutesDepositAddresses.validateCreationCapacity(db, {
+      claim: current,
+      match,
+      matchHash: 'match_recovered_existing',
+      maxPerCreator: 100,
+      orgId: owner.orgId,
+      pendingTtlMs: 60_000,
+      recoveredClaim,
+      replayTtlMs: 86_400_000,
+      serializeMatchingResponse: (record) => JSON.stringify({ id: record.id }),
+    })
+
+    await expect(
+      db.kysely
+        .selectFrom('routes_idempotency_requests')
+        .select(['apiKeyId', 'status'])
+        .where('apiKeyId', 'in', [current.apiKeyId, recoveredClaim.apiKeyId])
+        .orderBy('apiKeyId')
+        .execute(),
+    ).resolves.toEqual([
+      { apiKeyId: current.apiKeyId, status: 'completed' },
+      { apiKeyId: recoveredClaim.apiKeyId, status: 'completed' },
+    ])
+  })
+})
+
+describe('claimDue', () => {
+  test('claims due addresses once and reclaims an expired lease with a new fence', async () => {
+    const record = await seed()
+    const now = '2027-01-01T00:00:00.000Z'
+    const first = await RoutesDepositAddresses.claimDue(db, {
+      leaseUntil: '2027-01-01T00:01:00.000Z',
+      limit: 10,
+      now,
+      providerId: record.providerId,
+    })
+    const blocked = await RoutesDepositAddresses.claimDue(db, {
+      leaseUntil: '2027-01-01T00:02:00.000Z',
+      limit: 10,
+      now,
+      providerId: record.providerId,
+    })
+    const reclaimed = await RoutesDepositAddresses.claimDue(db, {
+      leaseUntil: '2027-01-01T00:03:00.000Z',
+      limit: 10,
+      now: '2027-01-01T00:01:00.000Z',
+      providerId: record.providerId,
+    })
+
+    expect({ blocked, first, reclaimed }).toMatchInlineSnapshot(
+      {
+        first: [
+          {
+            createdAt: expect.any(String),
+            id: expect.any(String),
+            nextPollAt: expect.any(String),
+            providerId: expect.any(String),
+            providerOutputToken: expect.any(Object),
+            recipient: expect.any(String),
+            snapshot: expect.any(Object),
+            statusUpdatedAt: expect.any(String),
+            updatedAt: expect.any(String),
+          },
+        ],
+        reclaimed: [
+          {
+            createdAt: expect.any(String),
+            id: expect.any(String),
+            nextPollAt: expect.any(String),
+            providerId: expect.any(String),
+            providerOutputToken: expect.any(Object),
+            recipient: expect.any(String),
+            snapshot: expect.any(Object),
+            statusUpdatedAt: expect.any(String),
+            updatedAt: expect.any(String),
+          },
+        ],
+      },
+      `
+      {
+        "blocked": [],
+        "first": [
+          {
+            "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+            "createdAt": Any<String>,
+            "creatorUserId": null,
+            "deliveryStrategy": "provider",
+            "destinationTokenKey": "eip155:4217/erc20:0x20c00000000000000000000014f22ca97301eb73",
+            "environment": "production",
+            "id": Any<String>,
+            "lastPolledAt": null,
+            "nextPollAt": Any<String>,
+            "orgId": "org_deposit_addresses",
+            "pollFailureCount": 0,
+            "pollLeaseUntil": "2027-01-01T00:01:00.000Z",
+            "pollLeaseVersion": 1,
+            "projectId": null,
+            "providerId": Any<String>,
+            "providerOutputToken": Any<Object>,
+            "providerRequestIds": [],
+            "providerState": null,
+            "recipient": Any<String>,
+            "refundAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+            "snapshot": Any<Object>,
+            "sourceChainId": "tron:0x2b6653dc",
+            "sourceTokenKey": "tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+            "status": "active",
+            "statusUpdatedAt": Any<String>,
+            "subsidize": false,
+            "updatedAt": Any<String>,
+            "version": 1,
+          },
+        ],
+        "reclaimed": [
+          {
+            "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+            "createdAt": Any<String>,
+            "creatorUserId": null,
+            "deliveryStrategy": "provider",
+            "destinationTokenKey": "eip155:4217/erc20:0x20c00000000000000000000014f22ca97301eb73",
+            "environment": "production",
+            "id": Any<String>,
+            "lastPolledAt": null,
+            "nextPollAt": Any<String>,
+            "orgId": "org_deposit_addresses",
+            "pollFailureCount": 0,
+            "pollLeaseUntil": "2027-01-01T00:03:00.000Z",
+            "pollLeaseVersion": 2,
+            "projectId": null,
+            "providerId": Any<String>,
+            "providerOutputToken": Any<Object>,
+            "providerRequestIds": [],
+            "providerState": null,
+            "recipient": Any<String>,
+            "refundAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+            "snapshot": Any<Object>,
+            "sourceChainId": "tron:0x2b6653dc",
+            "sourceTokenKey": "tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+            "status": "active",
+            "statusUpdatedAt": Any<String>,
+            "subsidize": false,
+            "updatedAt": Any<String>,
+            "version": 1,
+          },
+        ],
+      }
+    `,
+    )
+  })
+})
+
+describe('completePoll', () => {
+  test('persists reconciliation state only for the current lease', async () => {
+    const record = await seed()
+    const [claim] = await RoutesDepositAddresses.claimDue(db, {
+      leaseUntil: '2027-01-01T00:01:00.000Z',
+      limit: 1,
+      now: '2027-01-01T00:00:00.000Z',
+      providerId: record.providerId,
+    })
+    if (!claim) throw new Error('Expected a claimed address.')
+    const completed = await RoutesDepositAddresses.completePoll(db, {
+      id: record.id,
+      lastPolledAt: '2027-01-01T00:00:10.000Z',
+      nextPollAt: '2027-01-01T00:01:10.000Z',
+      pollLeaseVersion: claim.pollLeaseVersion,
+      providerRequestIds: ['relay-request', 'relay-child'],
+      providerState: { highWater: '2027-01-01T00:00:05.000Z' },
+    })
+    const stale = await RoutesDepositAddresses.completePoll(db, {
+      id: record.id,
+      lastPolledAt: '2027-01-01T00:00:20.000Z',
+      nextPollAt: '2027-01-01T00:01:20.000Z',
+      pollLeaseVersion: claim.pollLeaseVersion - 1,
+      providerRequestIds: [],
+      providerState: null,
+    })
+
+    expect({ completed, stale }).toMatchInlineSnapshot(
+      {
+        completed: {
+          createdAt: expect.any(String),
+          id: expect.any(String),
+          providerId: expect.any(String),
+          providerOutputToken: expect.any(Object),
+          recipient: expect.any(String),
+          snapshot: expect.any(Object),
+          statusUpdatedAt: expect.any(String),
+          updatedAt: expect.any(String),
+        },
+      },
+      `
+      {
+        "completed": {
+          "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+          "createdAt": Any<String>,
+          "creatorUserId": null,
+          "deliveryStrategy": "provider",
+          "destinationTokenKey": "eip155:4217/erc20:0x20c00000000000000000000014f22ca97301eb73",
+          "environment": "production",
+          "id": Any<String>,
+          "lastPolledAt": "2027-01-01T00:00:10.000Z",
+          "nextPollAt": "2027-01-01T00:01:10.000Z",
+          "orgId": "org_deposit_addresses",
+          "pollFailureCount": 0,
+          "pollLeaseUntil": null,
+          "pollLeaseVersion": 1,
+          "projectId": null,
+          "providerId": Any<String>,
+          "providerOutputToken": Any<Object>,
+          "providerRequestIds": [
+            "relay-request",
+            "relay-child",
+          ],
+          "providerState": {
+            "highWater": "2027-01-01T00:00:05.000Z",
+          },
+          "recipient": Any<String>,
+          "refundAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+          "snapshot": Any<Object>,
+          "sourceChainId": "tron:0x2b6653dc",
+          "sourceTokenKey": "tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+          "status": "active",
+          "statusUpdatedAt": Any<String>,
+          "subsidize": false,
+          "updatedAt": Any<String>,
+          "version": 1,
+        },
+        "stale": undefined,
+      }
+    `,
+    )
+  })
+})
+
+describe('failPoll', () => {
+  test('increments failures and releases only the current lease', async () => {
+    const record = await seed()
+    const [claim] = await RoutesDepositAddresses.claimDue(db, {
+      leaseUntil: '2027-01-01T00:01:00.000Z',
+      limit: 1,
+      now: '2027-01-01T00:00:00.000Z',
+      providerId: record.providerId,
+    })
+    if (!claim) throw new Error('Expected a claimed address.')
+    const failed = await RoutesDepositAddresses.failPoll(db, {
+      id: record.id,
+      nextPollAt: '2027-01-01T00:00:30.000Z',
+      pollLeaseVersion: claim.pollLeaseVersion,
+    })
+    const stale = await RoutesDepositAddresses.failPoll(db, {
+      id: record.id,
+      nextPollAt: '2027-01-01T00:00:40.000Z',
+      pollLeaseVersion: claim.pollLeaseVersion - 1,
+    })
+
+    expect({ failed, stale }).toMatchInlineSnapshot(
+      {
+        failed: {
+          createdAt: expect.any(String),
+          id: expect.any(String),
+          providerId: expect.any(String),
+          providerOutputToken: expect.any(Object),
+          recipient: expect.any(String),
+          snapshot: expect.any(Object),
+          statusUpdatedAt: expect.any(String),
+          updatedAt: expect.any(String),
+        },
+      },
+      `
+      {
+        "failed": {
+          "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+          "createdAt": Any<String>,
+          "creatorUserId": null,
+          "deliveryStrategy": "provider",
+          "destinationTokenKey": "eip155:4217/erc20:0x20c00000000000000000000014f22ca97301eb73",
+          "environment": "production",
+          "id": Any<String>,
+          "lastPolledAt": null,
+          "nextPollAt": "2027-01-01T00:00:30.000Z",
+          "orgId": "org_deposit_addresses",
+          "pollFailureCount": 1,
+          "pollLeaseUntil": null,
+          "pollLeaseVersion": 1,
+          "projectId": null,
+          "providerId": Any<String>,
+          "providerOutputToken": Any<Object>,
+          "providerRequestIds": [],
+          "providerState": null,
+          "recipient": Any<String>,
+          "refundAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
+          "snapshot": Any<Object>,
+          "sourceChainId": "tron:0x2b6653dc",
+          "sourceTokenKey": "tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+          "status": "active",
+          "statusUpdatedAt": Any<String>,
+          "subsidize": false,
+          "updatedAt": Any<String>,
+          "version": 1,
+        },
+        "stale": undefined,
+      }
+    `,
+    )
+  })
+})
+
+describe('insertOrGet', () => {
+  test('returns the existing address for an identical reusable identity', async () => {
+    const record = await seed()
+    const match: RoutesDepositAddresses.Match = {
+      destinationTokenKey: record.destinationTokenKey,
+      environment: record.environment,
+      orgId: record.orgId,
+      recipient: record.recipient,
+      refundAddress: record.refundAddress,
+      sourceChainId: record.sourceChainId,
+      sourceTokenKey: record.sourceTokenKey,
+      subsidize: record.subsidize,
+    }
+    const duplicate = { ...record, id: DepositAddress.generateId(new Date('2027-01-01')) }
+
+    await expect(
+      RoutesDepositAddresses.insertOrGet(db, { match, record: duplicate }),
+    ).resolves.toMatchObject({
+      id: record.id,
+    })
+  })
+
+  test('rejects a provider address assigned to another reusable identity', async () => {
+    const provider = { id: `relay_collision_${counter}`, name: 'Relay' }
+    const first = await seed({
+      snapshot: TestRoutes.depositAddressSnapshot({
+        provider,
+        recipient: `0x${'cd'.repeat(20)}`,
+      }),
+    })
+    const recipient = `0x${'ab'.repeat(20)}`
+    const record: RoutesDepositAddresses.Record = {
+      ...first,
+      id: DepositAddress.generateId(new Date('2027-01-01')),
+      orgId: 'org_other',
+      recipient,
+      snapshot: { ...first.snapshot, recipient },
+    }
+    const match: RoutesDepositAddresses.Match = {
+      destinationTokenKey: record.destinationTokenKey,
+      environment: record.environment,
+      orgId: record.orgId,
+      recipient: record.recipient,
+      refundAddress: record.refundAddress,
+      sourceChainId: record.sourceChainId,
+      sourceTokenKey: record.sourceTokenKey,
+      subsidize: record.subsidize,
+    }
+
+    await expect(
+      RoutesDepositAddresses.insertOrGet(db, { match, record }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[RoutesDepositAddresses.ConflictError]`)
+    expect((await RoutesDepositAddresses.get(db, first.id))?.id).toBe(first.id)
+  })
+})
+
+describe('insertOrGetWithinLimit', () => {
+  test('serializes concurrent inserts at the organization cap', async () => {
+    await Organizations.upsert(db, { id: owner.orgId, name: 'Deposit addresses' })
+    const template = await seed()
+    const current = await RoutesDepositAddresses.countByOrganization(db, owner.orgId)
+    const create = (index: number) => {
+      const recipient = `0x${(index + 100).toString(16).padStart(40, '0')}`
+      const record: RoutesDepositAddresses.Record = {
+        ...template,
+        address: `concurrent-address-${index}`,
+        id: DepositAddress.generateId(new Date(Date.UTC(2027, 0, 1, 0, 0, index))),
+        providerId: `relay_concurrent_${index}`,
+        recipient,
+        snapshot: {
+          ...template.snapshot,
+          address: `concurrent-address-${index}`,
+          provider: { id: `relay_concurrent_${index}`, name: 'Relay' },
+          recipient,
+        },
+      }
+      return db.transaction((tx) =>
+        RoutesDepositAddresses.insertOrGetWithinLimit(tx, {
+          match: {
+            destinationTokenKey: record.destinationTokenKey,
+            environment: record.environment,
+            orgId: record.orgId,
+            recipient: record.recipient,
+            refundAddress: record.refundAddress,
+            sourceChainId: record.sourceChainId,
+            sourceTokenKey: record.sourceTokenKey,
+            subsidize: record.subsidize,
+          },
+          maxPerCreator: current + 1,
+          record,
+        }),
+      )
+    }
+
+    const results = await Promise.allSettled([create(1), create(2)])
+
+    expect({
+      count: await RoutesDepositAddresses.countByOrganization(db, owner.orgId),
+      fulfilled: results.filter((result) => result.status === 'fulfilled').length,
+      rejected: results
+        .filter((result) => result.status === 'rejected')
+        .map((result) => result.reason),
+    }).toMatchObject({
+      count: current + 1,
+      fulfilled: 1,
+      rejected: [expect.any(RoutesDepositAddresses.LimitExceededError)],
+    })
+  })
+})
+
+describe('insert', () => {
+  test('prevents one provider address from belonging to two resources', async () => {
+    const provider = { id: `relay_unique_${counter}`, name: 'Relay' }
+    const first = await seed({ snapshot: TestRoutes.depositAddressSnapshot({ provider }) })
+    await expect(
+      seed({ snapshot: TestRoutes.depositAddressSnapshot({ provider }), orgId: 'org_other' }),
+    ).rejects.toMatchObject({ code: '23505' })
+    expect((await RoutesDepositAddresses.get(db, first.id))?.id).toBe(first.id)
+  })
+})
+
+describe('update', () => {
+  test('applies allowed transitions once against the expected version', async () => {
+    const record = await seed()
+    const applied = await DepositAddress.transition(db, {
+      expectedVersion: 1,
+      id: record.id,
+      status: 'action-required',
+    })
+    expect(applied.type).toBe('applied')
+    expect(
+      await DepositAddress.transition(db, {
+        expectedVersion: 1,
+        id: record.id,
+        status: 'action-required',
+      }),
+    ).toMatchObject({ type: 'stale' })
+  })
+})
+
+describe('toPublic', () => {
+  test('omits private provider and ownership state', async () => {
+    const record = await seed({
+      providerRequestIds: ['relay-request'],
+      providerState: { correlation: 'private' },
+    })
+    expect(DepositAddress.toPublic(record)).not.toMatchObject({
+      deliveryStrategy: expect.anything(),
+      providerOutputToken: expect.anything(),
+      providerRequestIds: expect.anything(),
+      providerState: expect.anything(),
+    })
+  })
+})
+
+describe('renewPoll', () => {
+  test('extends only the current active lease', async () => {
+    const record = await seed()
+    const [claim] = await RoutesDepositAddresses.claimDue(db, {
+      leaseUntil: '2027-01-01T00:01:00.000Z',
+      limit: 1,
+      now: '2027-01-01T00:00:00.000Z',
+      providerId: record.providerId,
+    })
+    if (!claim) throw new Error('Expected a claimed address.')
+    const renewed = await RoutesDepositAddresses.renewPoll(db, {
+      id: claim.id,
+      leaseUntil: '2027-01-01T00:02:00.000Z',
+      pollLeaseVersion: claim.pollLeaseVersion,
+    })
+    const stale = await RoutesDepositAddresses.renewPoll(db, {
+      id: claim.id,
+      leaseUntil: '2027-01-01T00:03:00.000Z',
+      pollLeaseVersion: claim.pollLeaseVersion - 1,
+    })
+
+    expect({ renewed, stale }).toMatchInlineSnapshot(`
+      {
+        "renewed": true,
+        "stale": false,
+      }
+    `)
+  })
+})
+
+describe('listByOwner', () => {
+  test('pages organization addresses and narrows project-attributed owners', async () => {
+    const listOwner = { environment: owner.environment, orgId: 'org_address_list' } as const
+    const first = await seed({ orgId: listOwner.orgId })
+    const project = await seed({ orgId: listOwner.orgId, projectId: 'prj_address_list' })
+    const sibling = await seed({ orgId: listOwner.orgId, projectId: 'prj_address_sibling' })
+    await seed({ orgId: 'org_address_list_foreign' })
+    await seed({ environment: 'sandbox', orgId: listOwner.orgId })
+
+    const page = await RoutesDepositAddresses.listByOwner(db, { limit: 2, owner: listOwner })
+    expect(page.map((record) => record.id)).toEqual([sibling.id, project.id])
+    const rest = await RoutesDepositAddresses.listByOwner(db, {
+      cursor: { createdAt: project.createdAt, id: project.id },
+      limit: 2,
+      owner: listOwner,
+    })
+    expect(rest.map((record) => record.id)).toEqual([first.id])
+    expect(
+      (
+        await RoutesDepositAddresses.listByOwner(db, {
+          limit: 10,
+          owner: { ...listOwner, projectId: 'prj_address_list' },
+        })
+      ).map((record) => record.id),
+    ).toEqual([project.id])
+    await DepositAddress.transition(db, {
+      expectedVersion: sibling.version,
+      id: sibling.id,
+      status: 'deactivated',
+    })
+    expect(
+      (await RoutesDepositAddresses.listByOwner(db, { limit: 10, owner: listOwner })).map(
+        (record) => record.id,
+      ),
+    ).not.toContain(sibling.id)
+  })
+})
+
+describe('list', () => {
+  test('filters across owners and searches addresses and transaction references', async () => {
+    const record = await seed({
+      orgId: 'org_admin_address',
+      snapshot: TestRoutes.depositAddressSnapshot({
+        address: 'TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj',
+        provider: { id: 'relay_admin_address', name: 'Relay' },
+      }),
+    })
+    const transactionRef = 'cd'.repeat(32)
+    await Deposit.create(db, {
+      now: new Date('2026-01-02T00:00:00.000Z'),
+      providerRequestId: 'relay_admin_address_deposit',
+      snapshot: TestRoutes.depositSnapshot(record.id, {
+        provider: record.snapshot.provider,
+        sourceTransactionHashes: [transactionRef],
+      }),
+      sourceTransactionHash: transactionRef,
+      sourceTransferIndex: 0,
+    })
+
+    const byAddress = await RoutesDepositAddresses.list(db, {
+      limit: 10,
+      providerId: 'relay_admin_address',
+      query: record.address,
+    })
+    const byTransaction = await RoutesDepositAddresses.list(db, {
+      limit: 10,
+      providerId: 'relay_admin_address',
+      query: transactionRef.toUpperCase(),
+    })
+
+    expect([byAddress, byTransaction].map((rows) => rows.map(({ id }) => id))).toEqual([
+      [record.id],
+      [record.id],
+    ])
+  })
+})
+
+describe('summarize', () => {
+  test('counts action-required addresses but not active addresses', async () => {
+    const active = await seed({
+      orgId: 'org_admin_address_summary',
+      snapshot: TestRoutes.depositAddressSnapshot({
+        address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
+        provider: { id: 'relay_admin_address_summary', name: 'Relay' },
+      }),
+    })
+    const actionRequired = await seed({
+      orgId: 'org_admin_address_summary',
+      snapshot: TestRoutes.depositAddressSnapshot({
+        address: 'TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3',
+        provider: { id: 'relay_admin_address_summary', name: 'Relay' },
+        recipient: `0x${'ab'.repeat(20)}`,
+      }),
+    })
+    await DepositAddress.transition(db, {
+      expectedVersion: actionRequired.version,
+      id: actionRequired.id,
+      status: 'action-required',
+    })
+
+    expect(active.status).toBe('active')
+    expect(
+      await RoutesDepositAddresses.summarize(db, {
+        providerId: 'relay_admin_address_summary',
+      }),
+    ).toMatchObject({ actionRequired: 1, inProgress: 0 })
+  })
+})
+
+describe('checkpointPoll', () => {
+  test('retains the lease while saving progress and rejects a stale fence', async () => {
+    const record = await seed()
+    const [claim] = await RoutesDepositAddresses.claimDue(db, {
+      leaseUntil: '2027-01-01T00:01:00.000Z',
+      limit: 1,
+      now: '2027-01-01T00:00:00.000Z',
+      providerId: record.providerId,
+    })
+    if (!claim) throw new Error('Expected a claimed address.')
+    const providerState = { unattributed: { before: '2027-01-01T00:00:00.000Z' } }
+    const checkpoint = await RoutesDepositAddresses.checkpointPoll(db, {
+      id: record.id,
+      pollLeaseVersion: claim.pollLeaseVersion,
+      providerState,
+    })
+    expect(checkpoint).toEqual({ ...claim, providerState })
+    expect(
+      await RoutesDepositAddresses.checkpointPoll(db, {
+        id: record.id,
+        pollLeaseVersion: claim.pollLeaseVersion - 1,
+        providerState: null,
+      }),
+    ).toBeUndefined()
+    expect(await RoutesDepositAddresses.get(db, record.id)).toEqual(checkpoint)
+  })
+})