tapimo 0.13.0 → 0.15.0

package/src/admin/apps/routes-support.ts

@@ -0,0 +1,201 @@
+import { Hono } from 'hono'
+import * as z from 'zod/mini'
+import { base, mainnet } from 'viem/chains'
+import { tempo } from 'viem/tempo/chains'
+
+import * as Db from '../../db/Db.js'
+import * as OpenApi from '../../internal/OpenApi.js'
+import * as RoutesCatalog from '../../internal/routes/Catalog.js'
+import type * as App from '../App.js'
+
+/** Zod schemas owned by the admin route support matrix. */
+export namespace schema {
+  /** Schemas for the getAdminRoutesSupport operation. */
+  export namespace getRoutesSupport {
+    const Chain = z
+      .object({
+        id: z
+          .string()
+          .check(z.describe('CAIP-2 chain identifier.'), z.meta({ examples: ['eip155:1'] })),
+        name: z
+          .string()
+          .check(z.describe('Human-readable chain name.'), z.meta({ examples: ['Ethereum'] })),
+        slug: z
+          .string()
+          .check(z.describe('Stable chain slug.'), z.meta({ examples: ['ethereum'] })),
+      })
+      .check(z.describe('Chain shown in the route support matrix.'))
+
+    const Token = z
+      .object({
+        id: z.string().check(z.describe('Stable route token id.'), z.meta({ examples: ['usdc'] })),
+        name: z
+          .string()
+          .check(z.describe('Human-readable token name.'), z.meta({ examples: ['USD Coin'] })),
+        symbol: z
+          .string()
+          .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDC'] })),
+      })
+      .check(z.describe('Token shown in the route support matrix.'))
+
+    const WalletTransferProvider = z
+      .object({
+        modes: z
+          .array(z.enum(['exactDestination', 'exactSource']))
+          .check(
+            z.describe('Amount modes enabled for wallet transfers.'),
+            z.meta({ examples: [['exactSource']] }),
+          ),
+        providerId: z
+          .string()
+          .check(z.describe('Stable route provider id.'), z.meta({ examples: ['stargate'] })),
+      })
+      .check(z.describe('Provider with wallet-transfer support for the route.'))
+
+    const Subsidies = z
+      .object({
+        depositAddress: z
+          .boolean()
+          .check(
+            z.describe('Whether the route is eligible for a conditional deposit subsidy.'),
+            z.meta({ examples: [true] }),
+          ),
+        walletTransfer: z
+          .boolean()
+          .check(
+            z.describe('Whether the route is eligible for a conditional wallet-transfer subsidy.'),
+            z.meta({ examples: [false] }),
+          ),
+      })
+      .check(z.describe('Route-level subsidy eligibility before organization and amount checks.'))
+
+    const Route = z
+      .object({
+        depositAddressProviders: z
+          .array(z.string())
+          .check(
+            z.describe('Providers with deposit-address support for the route.'),
+            z.meta({ examples: [['relay']] }),
+          ),
+        destinationChain: Chain,
+        destinationToken: Token,
+        id: z
+          .string()
+          .check(
+            z.describe('Stable source-to-destination route id.'),
+            z.meta({ examples: ['eip155:1/usdc-eip155:4217/usdce'] }),
+          ),
+        quoteProviders: z
+          .array(z.string())
+          .check(
+            z.describe('Providers with quote support for the route.'),
+            z.meta({ examples: [['relay', 'stargate']] }),
+          ),
+        sourceChain: Chain,
+        sourceToken: Token,
+        subsidies: Subsidies,
+        walletTransferProviders: z
+          .array(WalletTransferProvider)
+          .check(
+            z.describe('Providers with wallet-transfer support for the route.'),
+            z.meta({ examples: [[{ modes: ['exactSource'], providerId: 'stargate' }]] }),
+          ),
+      })
+      .check(z.describe('One source-to-destination route and its published support.'))
+
+    /** Response body for the route support matrix. */
+    export const Response = z
+      .object({
+        data: z.array(Route).check(z.describe('Published route support matrix.')),
+        updatedAt: z
+          .string()
+          .check(
+            z.describe('ISO timestamp of the catalog publish.'),
+            z.meta({ examples: ['2026-09-14T12:00:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('Published route support matrix.'))
+  }
+}
+
+/** Read-only matrix of published route capabilities. */
+export function routesSupport() {
+  return new Hono<App.Environment>().get(
+    '/',
+    OpenApi.describeRoute({
+      operationId: 'getAdminRoutesSupport',
+      responses: OpenApi.responses({
+        success: {
+          description: 'Published route support matrix.',
+          schema: schema.getRoutesSupport.Response,
+        },
+      }),
+      summary: 'List route support',
+      tags: ['Routes'],
+    }),
+    async (c) => {
+      const catalog = await RoutesCatalog.read(Db.get(c.get('db')))
+      return c.json({
+        data: summarize(catalog.routes),
+        updatedAt: catalog.updatedAt,
+      })
+    },
+  )
+}
+
+function summarize(routes: readonly RoutesCatalog.ProviderRoute[]) {
+  type Row = {
+    depositAddressProviders: string[]
+    destinationChain: { id: string; name: string; slug: string }
+    destinationToken: { id: string; name: string; symbol: string }
+    id: string
+    quoteProviders: string[]
+    sourceChain: { id: string; name: string; slug: string }
+    sourceToken: { id: string; name: string; symbol: string }
+    subsidies: { depositAddress: boolean; walletTransfer: boolean }
+    walletTransferProviders: { modes: ('exactDestination' | 'exactSource')[]; providerId: string }[]
+  }
+
+  const rows = new Map<string, Row>()
+  for (const providerRoute of routes) {
+    const { capabilities, providerId, route } = providerRoute
+    const id = `${route.source.chain.id}/${route.source.slug}-${route.destination.chain.id}/${route.destination.slug}`
+    const row = rows.get(id) ?? {
+      depositAddressProviders: [],
+      destinationChain: pickChain(route.destination.chain),
+      destinationToken: pickToken(route.destination),
+      id,
+      quoteProviders: [],
+      sourceChain: pickChain(route.source.chain),
+      sourceToken: pickToken(route.source),
+      subsidies: { depositAddress: false, walletTransfer: false },
+      walletTransferProviders: [],
+    }
+    row.quoteProviders.push(providerId)
+    const usdPair =
+      route.destination.currency === 'USD' && route.source.currency === route.destination.currency
+    if (capabilities?.depositAddress) {
+      row.depositAddressProviders.push(providerId)
+      row.subsidies.depositAddress ||=
+        route.destination.chain.id === `eip155:${tempo.id}` && usdPair
+    }
+    if (capabilities?.transfer) {
+      row.walletTransferProviders.push({ modes: [...capabilities.transfer.modes], providerId })
+      row.subsidies.walletTransfer ||=
+        capabilities.transfer.modes.includes('exactSource') &&
+        route.source.chain.id === `eip155:${tempo.id}` &&
+        [`eip155:${base.id}`, `eip155:${mainnet.id}`].includes(route.destination.chain.id) &&
+        usdPair
+    }
+    rows.set(id, row)
+  }
+  return [...rows.values()]
+}
+
+function pickChain(chain: RoutesCatalog.ProviderRoute['route']['source']['chain']) {
+  return { id: chain.id, name: chain.name, slug: chain.slug }
+}
+
+function pickToken(token: RoutesCatalog.ProviderRoute['route']['source']) {
+  return { id: token.slug, name: token.name, symbol: token.symbol }
+}

package/src/admin/apps/routes.test.ts

@@ -0,0 +1,450 @@
+import type * as Db from '../../db/Db.js'
+import * as RoutesTransferTransactions from '../../db/tables/routesTransferTransactions.js'
+import * as Organizations from '../../db/tables/organizations.js'
+import * as Projects from '../../db/tables/projects.js'
+import * as Deposit from '../../internal/routes/Deposit.js'
+import * as DepositAddress from '../../internal/routes/DepositAddress.js'
+import * as Transfer from '../../internal/routes/Transfer.js'
+import * as TestAdmin from '../../../test/Admin.js'
+import * as TestApp from '../../../test/App.js'
+import * as TestRoutes from '../../../test/Routes.js'
+import * as AdminRoutes from './routes.js'
+
+describe('GET /routes/summary', () => {
+  test('counts each active resource in one lifecycle bucket', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    await seedTransfer(db, organization.id, project.id)
+    await seedDeposit(db, organization.id, project.id)
+
+    const response = await client.routes.summary.$get({ query: {} })
+    const body = await TestApp.json(response, AdminRoutes.schema.getRoutesSummary.Response)
+
+    expect(response.status).toBe(200)
+    expect(body).toMatchObject({
+      actionRequired: 0,
+      inProgress: 2,
+      resources: {
+        depositAddresses: { actionRequired: 0, inProgress: 0 },
+        deposits: { actionRequired: 0, inProgress: 1 },
+        transfers: { actionRequired: 0, inProgress: 1 },
+      },
+    })
+  })
+
+  test('applies the transaction method without counting deposit-address resources', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    await seedTransfer(db, organization.id, project.id)
+    await seedDeposit(db, organization.id, project.id)
+
+    const response = await client.routes.summary.$get({
+      query: { method: 'transaction' },
+    })
+    const body = await TestApp.json(response, AdminRoutes.schema.getRoutesSummary.Response)
+
+    expect(body.inProgress).toBe(1)
+    expect(body.resources.deposits.inProgress).toBe(0)
+  })
+})
+
+describe('GET /routes/transfers', () => {
+  test('searches transaction references and includes attribution', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { record, transactionRef } = await seedTransfer(db, organization.id, project.id)
+
+    const response = await client.routes.transfers.$get({ query: { query: transactionRef } })
+    const body = await TestApp.json(response, AdminRoutes.schema.listRoutesTransfers.Response)
+
+    expect(body.data).toHaveLength(1)
+    expect(body.data[0]).toMatchObject({
+      id: record.id,
+      organization: { id: organization.id, name: organization.name },
+      project: { id: project.id, name: project.name },
+      status: 'processing',
+    })
+  })
+
+  test('applies the in-progress preset across active statuses', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { record } = await seedTransfer(db, organization.id, project.id)
+    await Transfer.create(db, {
+      apiKeyId: 'key_admin_routes',
+      environment: 'production',
+      id: Transfer.generateId(new Date('2026-08-26T00:00:02.000Z')),
+      orgId: organization.id,
+      projectId: project.id,
+      providerState: { secret: 'hidden' },
+      snapshot: TestRoutes.transferSnapshot({
+        provider: { id: 'stargate', name: 'Stargate' },
+      }),
+    })
+
+    const response = await client.routes.transfers.$get({
+      query: { inProgress: 'true' },
+    })
+    const body = await TestApp.json(response, AdminRoutes.schema.listRoutesTransfers.Response)
+
+    expect(body.data.map(({ id }) => id)).toEqual([record.id])
+  })
+
+  test('filters by multiple lifecycle statuses', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { record } = await seedTransfer(db, organization.id, project.id)
+    const awaiting = await Transfer.create(db, {
+      apiKeyId: 'key_admin_routes',
+      environment: 'production',
+      id: Transfer.generateId(new Date('2026-08-26T00:00:02.000Z')),
+      orgId: organization.id,
+      projectId: project.id,
+      providerState: { secret: 'hidden' },
+      snapshot: TestRoutes.transferSnapshot({
+        provider: { id: 'stargate', name: 'Stargate' },
+      }),
+    })
+
+    const response = await client.routes.transfers.$get({
+      query: { status: 'awaiting-source,processing' },
+    })
+    const body = await TestApp.json(response, AdminRoutes.schema.listRoutesTransfers.Response)
+
+    expect(body.data.map(({ id }) => id).sort()).toEqual([awaiting.id, record.id].sort())
+  })
+})
+
+describe('GET /routes/transfers/:id', () => {
+  test('returns lifecycle events and safe transaction references', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { record, transactionRef } = await seedTransfer(db, organization.id, project.id)
+
+    const response = await client.routes.transfers[':id'].$get({
+      param: { id: record.id },
+    })
+    const body = await TestApp.json(response, AdminRoutes.schema.getRoutesTransfer.Response)
+
+    expect(body.events.map(({ status }) => status)).toEqual(['awaiting-source', 'processing'])
+    expect(body.transactions).toEqual([
+      {
+        chainId: 'eip155:8453',
+        createdAt: '2026-08-26T00:00:01.000Z',
+        role: 'source',
+        transactionRef,
+      },
+    ])
+    expect(body).not.toHaveProperty('providerState')
+  })
+})
+
+describe('GET /routes/deposit-addresses', () => {
+  test('searches deposit addresses and exposes safe polling state', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { address } = await seedDeposit(db, organization.id, project.id)
+
+    const response = await client.routes['deposit-addresses'].$get({
+      query: { query: address.address },
+    })
+    const body = await TestApp.json(
+      response,
+      AdminRoutes.schema.listRoutesDepositAddresses.Response,
+    )
+
+    expect(body.data[0]).toMatchObject({
+      consecutivePollFailures: 0,
+      id: address.id,
+      providerRequestIds: ['provider_address_request'],
+    })
+    expect(body.data[0]).not.toHaveProperty('providerState')
+  })
+
+  test('applies the needs-attention preset', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { address } = await seedDeposit(db, organization.id, project.id)
+    await DepositAddress.transition(db, {
+      expectedVersion: address.version,
+      id: address.id,
+      status: 'action-required',
+    })
+
+    const response = await client.routes['deposit-addresses'].$get({
+      query: { needsAttention: 'true' },
+    })
+    const body = await TestApp.json(
+      response,
+      AdminRoutes.schema.listRoutesDepositAddresses.Response,
+    )
+
+    expect(body.data.map(({ id }) => id)).toEqual([address.id])
+  })
+
+  test('filters terminal deactivated addresses', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { address } = await seedDeposit(db, organization.id, project.id)
+    await DepositAddress.transition(db, {
+      expectedVersion: address.version,
+      id: address.id,
+      status: 'deactivated',
+    })
+
+    const response = await client.routes['deposit-addresses'].$get({
+      query: { status: 'deactivated' },
+    })
+    const body = await TestApp.json(
+      response,
+      AdminRoutes.schema.listRoutesDepositAddresses.Response,
+    )
+
+    expect(body.data.map(({ id, status }) => ({ id, status }))).toEqual([
+      { id: address.id, status: 'deactivated' },
+    ])
+  })
+})
+
+describe('GET /routes/deposit-addresses/:id', () => {
+  test('returns an address created before the route ID rename', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { address } = await seedDeposit(db, organization.id, project.id, {
+      addressId: 'fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx',
+    })
+
+    const response = await client.routes['deposit-addresses'][':id'].$get({
+      param: { id: address.id },
+    })
+    const body = await TestApp.json(response, AdminRoutes.schema.getRoutesDepositAddress.Response)
+
+    expect(body.id).toBe(address.id)
+  })
+
+  test('returns 404 for an unknown address', async () => {
+    const { client } = TestAdmin.setup()
+    const response = await client.routes['deposit-addresses'][':id'].$get({
+      param: { id: 'rda_unknown' },
+    })
+    expect(response.status).toBe(404)
+  })
+})
+
+describe('GET /routes/deposits', () => {
+  test('searches source transactions and omits raw private state', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { deposit, transactionRef } = await seedDeposit(db, organization.id, project.id)
+
+    const response = await client.routes.deposits.$get({ query: { query: transactionRef } })
+    const body = await TestApp.json(response, AdminRoutes.schema.listRoutesDeposits.Response)
+
+    expect(body.data[0]).toMatchObject({
+      id: deposit.id,
+      retryAttempts: 2,
+      status: 'bridging',
+    })
+    expect(body.data[0]).not.toHaveProperty('providerState')
+    expect(body.data[0]).not.toHaveProperty('retryState')
+    expect(body.data[0]).not.toHaveProperty('settlementTransaction')
+  })
+
+  test('returns provider and Tempo subsidies with token details', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { deposit } = await seedDeposit(db, organization.id, project.id, {
+      subsidies: true,
+    })
+
+    const response = await client.routes.deposits.$get({ query: { query: deposit.id } })
+    const body = await TestApp.json(response, AdminRoutes.schema.listRoutesDeposits.Response)
+
+    expect(body.data[0]?.subsidies).toEqual([
+      {
+        amount: { baseUnits: '23838', currency: 'USD', decimals: 6, formatted: '0.023838' },
+        provider: 'relay',
+        token: deposit.snapshot.sourceToken,
+      },
+      {
+        amount: { baseUnits: '2', currency: 'USD', decimals: 6, formatted: '0.000002' },
+        provider: 'tempo',
+        token: deposit.snapshot.destinationToken,
+      },
+    ])
+  })
+
+  test('lists resources created before the route ID rename', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { address, deposit } = await seedDeposit(db, organization.id, project.id, {
+      addressId: 'fda_001785792000001_2ZPE2gvateYEQ0dQslgvkhjx',
+      depositId: 'fdp_001785792060001_2ZPE2gvateYEQ0dQslgvkhjx',
+    })
+
+    const addressResponse = await client.routes['deposit-addresses'].$get({
+      query: { query: address.address },
+    })
+    const addressBody = await TestApp.json(
+      addressResponse,
+      AdminRoutes.schema.listRoutesDepositAddresses.Response,
+    )
+    const depositResponse = await client.routes.deposits.$get({
+      query: { depositAddressId: address.id },
+    })
+    const depositBody = await TestApp.json(
+      depositResponse,
+      AdminRoutes.schema.listRoutesDeposits.Response,
+    )
+
+    expect(addressBody.data.map(({ id }) => id)).toEqual([address.id])
+    expect(depositBody.data.map(({ id }) => id)).toEqual([deposit.id])
+  })
+})
+
+describe('GET /routes/deposits/:id', () => {
+  test('returns the associated deposit address', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { address, deposit } = await seedDeposit(db, organization.id, project.id)
+
+    const response = await client.routes.deposits[':id'].$get({
+      param: { id: deposit.id },
+    })
+    const body = await TestApp.json(response, AdminRoutes.schema.getRoutesDeposit.Response)
+
+    expect(body.depositAddress.id).toBe(address.id)
+  })
+
+  test('returns a deposit created before the route ID rename', async () => {
+    const { client, db } = TestAdmin.setup()
+    const { organization, project } = await seedAttribution(db)
+    const { address, deposit } = await seedDeposit(db, organization.id, project.id, {
+      addressId: 'fda_001785792000002_2ZPE2gvateYEQ0dQslgvkhjx',
+      depositId: 'fdp_001785792060002_2ZPE2gvateYEQ0dQslgvkhjx',
+    })
+
+    const response = await client.routes.deposits[':id'].$get({
+      param: { id: deposit.id },
+    })
+    const body = await TestApp.json(response, AdminRoutes.schema.getRoutesDeposit.Response)
+
+    expect(body.depositAddress.id).toBe(address.id)
+    expect(body.id).toBe(deposit.id)
+  })
+})
+
+async function seedAttribution(db: Db.Db) {
+  const organization = await Organizations.create(db, {
+    id: 'org_admin_routes',
+    name: 'Acme',
+  })
+  const project = await Projects.create(db, { name: 'Checkout', orgId: organization.id })
+  return { organization, project }
+}
+
+async function seedTransfer(db: Db.Db, orgId: string, projectId: string) {
+  const record = await Transfer.create(db, {
+    apiKeyId: 'key_admin_routes',
+    environment: 'production',
+    id: Transfer.generateId(new Date('2026-08-26T00:00:00.000Z')),
+    orgId,
+    projectId,
+    providerState: { secret: 'hidden' },
+    snapshot: TestRoutes.transferSnapshot({
+      provider: { id: 'stargate', name: 'Stargate' },
+    }),
+  })
+  await Transfer.transition(db, {
+    expectedVersion: record.version,
+    id: record.id,
+    status: 'processing',
+  })
+  const transactionRef = `0x${'ab'.repeat(32)}`
+  await RoutesTransferTransactions.insert(db, {
+    chainId: 'eip155:8453',
+    createdAt: '2026-08-26T00:00:01.000Z',
+    role: 'source',
+    transactionRef,
+    transferId: record.id,
+  })
+  return { record, transactionRef }
+}
+
+async function seedDeposit(
+  db: Db.Db,
+  orgId: string,
+  projectId: string,
+  options: seedDeposit.Options = {},
+) {
+  const address = await DepositAddress.create(db, {
+    deliveryStrategy: 'tempo',
+    environment: 'production',
+    id: options.addressId ?? DepositAddress.generateId(new Date('2026-08-26T00:01:00.000Z')),
+    now: new Date('2026-08-26T00:01:00.000Z'),
+    orgId,
+    projectId,
+    providerOutputToken: TestRoutes.providerOutputToken(),
+    providerRequestIds: ['provider_address_request'],
+    providerState: { secret: 'hidden' },
+    snapshot: TestRoutes.depositAddressSnapshot(),
+  })
+  const transactionRef = 'cd'.repeat(32)
+  const deposit = await Deposit.create(db, {
+    id: options.depositId,
+    now: new Date('2026-08-26T00:02:00.000Z'),
+    providerRequestId: 'provider_deposit_request',
+    providerState: { secret: 'hidden' },
+    ...(options.subsidies
+      ? {
+          providerSubsidy: {
+            amount: {
+              baseUnits: '23838',
+              currency: 'USD',
+              decimals: 6,
+              formatted: '0.023838',
+            },
+            provider: 'relay',
+            token: address.snapshot.sourceToken,
+          },
+        }
+      : {}),
+    providerTransactionHashes: ['provider_transaction'],
+    retryState: { attempts: 2, secret: 'hidden' },
+    settlementTransaction: 'signed-transaction-bytes',
+    snapshot: TestRoutes.depositSnapshot(address.id, {
+      sourceTransactionHashes: [transactionRef],
+    }),
+    sourceTransactionHash: transactionRef,
+    sourceTransferIndex: 0,
+    ...(options.subsidies
+      ? {
+          settlementTransactionHash: `0x${'ef'.repeat(32)}`,
+          subsidyAmount: {
+            baseUnits: '2',
+            currency: 'USD',
+            decimals: 6,
+            formatted: '0.000002',
+          },
+        }
+      : {}),
+  })
+  await Deposit.transition(db, {
+    expectedVersion: deposit.version,
+    id: deposit.id,
+    status: 'bridging',
+  })
+  return { address, deposit, transactionRef }
+}
+
+declare namespace seedDeposit {
+  /** Legacy IDs used to seed records created before the route rename. */
+  type Options = {
+    /** Legacy deposit-address id override. */
+    addressId?: string | undefined
+    /** Legacy deposit id override. */
+    depositId?: string | undefined
+    /** Whether the deposit includes provider and Tempo subsidies. */
+    subsidies?: boolean | undefined
+  }
+}