tapimo 0.14.0 → 0.15.0

package/src/internal/{funding → routes}/DepositAddress.test.ts

@@ -1,18 +1,26 @@
 import * as DepositAddress from './DepositAddress.js'
 
 describe('generateId', () => {
-  test('generates a lexically time-ordered funding deposit address id', () => {
+  test('generates a lexically time-ordered route deposit address id', () => {
     const earlier = DepositAddress.generateId(new Date('2026-01-01T00:00:00.000Z'))
     const later = DepositAddress.generateId(new Date('2026-01-01T00:00:01.000Z'))
-    expect(earlier).toMatch(/^fda_\d{15}_[A-Za-z0-9]{24}$/)
+    expect(earlier).toMatch(/^rda_\d{15}_[A-Za-z0-9]{24}$/)
     expect(earlier < later).toBe(true)
   })
 })
 
 describe('canTransition', () => {
-  test('allows disabling and restoring a reusable address', () => {
+  test('allows recovery or terminal deactivation', () => {
     expect(DepositAddress.canTransition('active', 'action-required')).toBe(true)
     expect(DepositAddress.canTransition('action-required', 'active')).toBe(true)
+    expect(DepositAddress.canTransition('active', 'deactivated')).toBe(true)
+    expect(DepositAddress.canTransition('deactivated', 'active')).toBe(false)
     expect(DepositAddress.canTransition('active', 'active')).toBe(false)
   })
 })
+
+describe('isTerminal', () => {
+  test('only deactivated addresses are terminal', () => {
+    expect(DepositAddress.statuses.filter(DepositAddress.isTerminal)).toEqual(['deactivated'])
+  })
+})

package/src/internal/{funding → routes}/DepositAddress.ts

@@ -1,16 +1,19 @@
 import * as z from 'zod/mini'
 
 import type * as Db from '../../db/Db.js'
-import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js'
+import * as RoutesDepositAddresses from '../../db/tables/routesDepositAddresses.js'
 import * as Id from '../Id.js'
 import * as OpenApi from '../OpenApi.js'
 import * as Provider from './Provider.js'
 import * as Transfer from './Transfer.js'
 
-/** Public funding deposit address statuses. */
-export const statuses = ['action-required', 'active'] as const
+/** Internal route deposit address statuses. */
+export const statuses = ['action-required', 'active', 'deactivated'] as const
 
-/** Lifecycle status of a funding deposit address. */
+/** Route deposit address statuses exposed by the existing public API. */
+export const publicStatuses = ['action-required', 'active'] as const
+
+/** Lifecycle status of a route deposit address. */
 export type Status = (typeof statuses)[number]
 
 /** Internal responsibility for delivering the requested destination token. */
@@ -22,9 +25,18 @@ export type DeliveryStrategy = (typeof deliveryStrategies)[number]
 /** Bounded provider state retained privately for reconciliation. */
 export type ProviderState = Record<string, unknown>
 
+/** Matches the webhook owner cap; four 25-address poll batches complete below the five-minute overdue alert. */
+export const maximumPerCreator = 100
+
 const transitions: Record<Status, readonly Status[]> = {
-  'action-required': ['active'],
-  active: ['action-required'],
+  'action-required': ['active', 'deactivated'],
+  active: ['action-required', 'deactivated'],
+  deactivated: [],
+}
+
+/** Returns whether an address no longer needs reconciliation. */
+export function isTerminal(status: Status): boolean {
+  return status === 'deactivated'
 }
 
 /** Returns whether the lifecycle allows moving between address statuses. */
@@ -32,14 +44,14 @@ export function canTransition(from: Status, to: Status): boolean {
   return transitions[from].includes(to)
 }
 
-/** Generates a funding deposit address id (`fda_…`, lexically time-ordered). */
+/** Generates a route deposit address id (`rda_…`, lexically time-ordered). */
 export function generateId(now: Date = new Date()): string {
-  return Id.generateSortable('fda', now)
+  return Id.generateSortable('rda', now)
 }
 
-/** Zod schemas owned by the funding deposit address resource. */
+/** Zod schemas owned by the route deposit address resource. */
 export namespace schema {
-  /** Funding deposit address lifecycle status. */
+  /** Route deposit address lifecycle status. */
   export const Status = z
     .enum(statuses)
     .check(
@@ -47,6 +59,14 @@ export namespace schema {
       z.meta({ examples: ['active'] }),
     )
 
+  /** Public route deposit address lifecycle status. */
+  export const PublicStatus = z
+    .enum(publicStatuses)
+    .check(
+      z.describe('Whether the address can safely process new deposits.'),
+      z.meta({ examples: ['active'] }),
+    )
+
   /** Public fields persisted as the address snapshot. */
   export const Snapshot = z
     .object({
@@ -83,8 +103,8 @@ export namespace schema {
     })
     .check(z.describe('Public route and ownership-independent fields of a deposit address.'))
 
-  /** One reusable funding deposit address. */
-  export const FundingDepositAddress = OpenApi.component(
+  /** One reusable route deposit address. */
+  export const RoutesDepositAddress = OpenApi.component(
     z
       .object({
         address: Snapshot.shape.address,
@@ -99,16 +119,16 @@ export namespace schema {
         id: z
           .string()
           .check(
-            z.regex(/^fda_[A-Za-z0-9_-]+$/),
-            z.describe('Funding deposit address id (`fda_…`).'),
-            z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+            z.regex(/^(?:fda|rda)_[A-Za-z0-9_-]+$/),
+            z.describe('Route deposit address id (`rda_…`, or legacy `fda_…`).'),
+            z.meta({ examples: ['rda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
           ),
         provider: Snapshot.shape.provider,
         recipient: Snapshot.shape.recipient,
         refundAddress: Snapshot.shape.refundAddress,
         sourceChain: Snapshot.shape.sourceChain,
         sourceToken: Snapshot.shape.sourceToken,
-        status: Status,
+        status: PublicStatus,
         subsidize: Snapshot.shape.subsidize,
         updatedAt: z.iso
           .datetime()
@@ -117,41 +137,41 @@ export namespace schema {
             z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
           ),
       })
-      .check(z.describe('One reusable address for funding a Tempo account.')),
-    'FundingDepositAddress',
+      .check(z.describe('One reusable address for routes a Tempo account.')),
+    'RoutesDepositAddress',
   )
 
-  /** A reusable funding deposit address with terms sampled during creation. */
-  export const CreatedFundingDepositAddress = OpenApi.component(
+  /** A reusable route deposit address with terms sampled during creation. */
+  export const CreatedRoutesDepositAddress = OpenApi.component(
     z
       .object({
-        ...FundingDepositAddress.shape,
-        destinationAmount: Provider.schema.FundingQuote.shape.destinationAmount,
-        destinationAmountMin: Provider.schema.FundingQuote.shape.destinationAmountMin,
+        ...RoutesDepositAddress.shape,
+        destinationAmount: Provider.schema.RoutesQuote.shape.destinationAmount,
+        destinationAmountMin: Provider.schema.RoutesQuote.shape.destinationAmountMin,
         fees: z.array(Transfer.schema.Fee).check(z.describe('Fees applied to the quoted deposit.')),
         quote: Provider.schema.QuoteDetails,
-        sourceAmount: Provider.schema.FundingQuote.shape.sourceAmount,
+        sourceAmount: Provider.schema.RoutesQuote.shape.sourceAmount,
       })
-      .check(z.describe('A reusable funding deposit address with current quoted delivery terms.')),
-    'CreatedFundingDepositAddress',
+      .check(z.describe('A reusable route deposit address with current quoted delivery terms.')),
+    'CreatedRoutesDepositAddress',
   )
 }
 
-/** Stored public snapshot of a funding deposit address. */
+/** Stored public snapshot of a route deposit address. */
 export type Snapshot = z.output<typeof schema.Snapshot>
 
-/** A funding deposit address as returned by reads. */
-export type Public = z.output<typeof schema.FundingDepositAddress>
+/** A route deposit address as returned by reads. */
+export type Public = z.output<typeof schema.RoutesDepositAddress>
 
-/** A funding deposit address returned by creation with current quoted terms. */
-export type Created = z.output<typeof schema.CreatedFundingDepositAddress>
+/** A route deposit address returned by creation with current quoted terms. */
+export type Created = z.output<typeof schema.CreatedRoutesDepositAddress>
 
-/** Creates a durable funding deposit address for an already-provisioned provider address. */
+/** Creates a durable route deposit address for an already-provisioned provider address. */
 export async function create(
   db: Db.Db,
   input: create.Input,
-): Promise<FundingDepositAddresses.Record> {
-  return FundingDepositAddresses.insert(db, record(input))
+): Promise<RoutesDepositAddresses.Record> {
+  return RoutesDepositAddresses.insert(db, record(input))
 }
 
 /** Creates or returns the reusable address for the same owner and route. */
@@ -160,7 +180,7 @@ export async function createOrGet(
   input: createOrGet.Input,
 ): Promise<createOrGet.ReturnType> {
   const value = record(input)
-  const result = await FundingDepositAddresses.insertOrGet(db, {
+  const result = await RoutesDepositAddresses.insertOrGetWithinLimit(db, {
     match: {
       destinationTokenKey: value.destinationTokenKey,
       environment: value.environment,
@@ -172,9 +192,13 @@ export async function createOrGet(
       sourceTokenKey: value.sourceTokenKey,
       subsidize: value.subsidize,
     },
+    maxPerCreator: maximumPerCreator,
     record: value,
   }).catch((cause) => {
-    if (cause instanceof FundingDepositAddresses.ConflictError) throw new ConflictError()
+    if (cause instanceof RoutesDepositAddresses.ConflictError) throw new ConflictError()
+    if (cause instanceof RoutesDepositAddresses.LimitExceededError)
+      throw new LimitExceededError(cause.limit)
+    if (cause instanceof RoutesDepositAddresses.OwnerNotFoundError) throw new OwnerNotFoundError()
     throw cause
   })
   if (result.providerId !== value.providerId) throw new ConflictError()
@@ -188,13 +212,13 @@ export declare namespace createOrGet {
   /** Whether provisioning created or matched the stored reusable address. */
   type ReturnType = {
     /** Stored reusable deposit address. */
-    record: FundingDepositAddresses.Record
+    record: RoutesDepositAddresses.Record
     /** Whether the provider address was newly stored or matched an existing identity. */
     type: 'created' | 'existing'
   }
 }
 
-function record(input: create.Input): FundingDepositAddresses.Record {
+function record(input: create.Input): RoutesDepositAddresses.Record {
   const now = input.now ?? new Date()
   const parsed = schema.Snapshot.parse(input.snapshot)
   const snapshot = {
@@ -203,8 +227,8 @@ function record(input: create.Input): FundingDepositAddresses.Record {
   }
   return {
     address: snapshot.address,
-    apiKeyId: input.apiKeyId,
     createdAt: now.toISOString(),
+    creatorUserId: null,
     deliveryStrategy: input.deliveryStrategy,
     destinationTokenKey: snapshot.destinationToken.tokenKey,
     environment: input.environment,
@@ -226,6 +250,7 @@ function record(input: create.Input): FundingDepositAddresses.Record {
     sourceChainId: snapshot.sourceChain.id,
     sourceTokenKey: snapshot.sourceToken.tokenKey,
     status: 'active',
+    statusUpdatedAt: now.toISOString(),
     subsidize: snapshot.subsidize,
     updatedAt: now.toISOString(),
     version: 1,
@@ -235,8 +260,6 @@ function record(input: create.Input): FundingDepositAddresses.Record {
 export declare namespace create {
   /** Fields required to persist a provisioned deposit address. */
   type Input = {
-    /** API key that provisioned the address. */
-    apiKeyId: string
     /** Responsibility for delivering the requested destination token. */
     deliveryStrategy: DeliveryStrategy
     /** Key environment the address belongs to. */
@@ -260,25 +283,63 @@ export declare namespace create {
   }
 }
 
-/** Applies a version-guarded funding deposit address status transition. */
+/** Persists or returns a reusable address already provisioned before the current capacity check. */
+export async function recoverOrGet(
+  db: Db.Db,
+  input: recoverOrGet.Input,
+): Promise<recoverOrGet.ReturnType> {
+  const value = record(input)
+  const result = await RoutesDepositAddresses.insertProvisionedOrGet(db, {
+    match: {
+      destinationTokenKey: value.destinationTokenKey,
+      environment: value.environment,
+      orgId: value.orgId,
+      ...(value.projectId === null ? {} : { projectId: value.projectId }),
+      recipient: value.recipient,
+      refundAddress: value.refundAddress,
+      sourceChainId: value.sourceChainId,
+      sourceTokenKey: value.sourceTokenKey,
+      subsidize: value.subsidize,
+    },
+    record: value,
+  }).catch((cause) => {
+    if (cause instanceof RoutesDepositAddresses.ConflictError) throw new ConflictError()
+    if (cause instanceof RoutesDepositAddresses.OwnerNotFoundError) throw new OwnerNotFoundError()
+    throw cause
+  })
+  if (result.providerId !== value.providerId) throw new ConflictError()
+  return { record: result, type: result.id === value.id ? 'created' : 'existing' }
+}
+
+export declare namespace recoverOrGet {
+  /** Already-provisioned deposit address fields. */
+  type Input = create.Input
+
+  /** Whether recovery created or matched the stored reusable address. */
+  type ReturnType = createOrGet.ReturnType
+}
+
+/** Applies a version-guarded route deposit address status transition. */
 export async function transition(
   db: Db.Db,
   options: transition.Options,
 ): Promise<transition.Result> {
-  const current = await FundingDepositAddresses.get(db, options.id)
+  const current = await RoutesDepositAddresses.get(db, options.id)
   if (!current) return { type: 'not_found' }
   if (current.version !== options.expectedVersion) return { current, type: 'stale' }
   if (!canTransition(current.status, options.status)) return { current, type: 'invalid' }
 
-  const updated = await FundingDepositAddresses.update(db, {
+  const now = new Date().toISOString()
+  const updated = await RoutesDepositAddresses.update(db, {
     expectedVersion: options.expectedVersion,
     id: options.id,
     status: options.status,
-    updatedAt: new Date().toISOString(),
+    statusUpdatedAt: now,
+    updatedAt: now,
     version: current.version + 1,
   })
   if (updated) return { record: updated, type: 'applied' }
-  const latest = await FundingDepositAddresses.get(db, options.id)
+  const latest = await RoutesDepositAddresses.get(db, options.id)
   return latest ? { current: latest, type: 'stale' } : { type: 'not_found' }
 }
 
@@ -287,7 +348,7 @@ export declare namespace transition {
   type Options = {
     /** Version that the transition was computed against. */
     expectedVersion: number
-    /** Funding deposit address id (`fda_…`). */
+    /** Route deposit address id (`rda_…`). */
     id: string
     /** New lifecycle status. */
     status: Status
@@ -295,15 +356,15 @@ export declare namespace transition {
 
   /** Outcome of a guarded address transition. */
   type Result =
-    | { record: FundingDepositAddresses.Record; type: 'applied' }
-    | { current: FundingDepositAddresses.Record; type: 'invalid' }
-    | { current: FundingDepositAddresses.Record; type: 'stale' }
+    | { record: RoutesDepositAddresses.Record; type: 'applied' }
+    | { current: RoutesDepositAddresses.Record; type: 'invalid' }
+    | { current: RoutesDepositAddresses.Record; type: 'stale' }
     | { type: 'not_found' }
 }
 
 /** Serializes a stored address to the public read shape. */
-export function toPublic(record: FundingDepositAddresses.Record): Public {
-  return schema.FundingDepositAddress.parse({
+export function toPublic(record: RoutesDepositAddresses.Record): Public {
+  return schema.RoutesDepositAddress.parse({
     ...record.snapshot,
     createdAt: record.createdAt,
     id: record.id,
@@ -315,5 +376,23 @@ export function toPublic(record: FundingDepositAddresses.Record): Public {
 
 /** Error thrown when a provider conflicts with a stored reusable address. */
 export class ConflictError extends Error {
-  override name = 'FundingDepositAddress.ConflictError'
+  override name = 'RoutesDepositAddress.ConflictError'
+}
+
+/** Organization creator's deposit-address cap reached. */
+export class LimitExceededError extends Error {
+  override name = 'RoutesDepositAddress.LimitExceededError'
+
+  /** Maximum durable deposit addresses the canonical creator may own. */
+  limit: number
+
+  constructor(limit: number) {
+    super(`Route deposit address limit reached (${limit}).`)
+    this.limit = limit
+  }
+}
+
+/** Owning organization disappeared before address persistence. */
+export class OwnerNotFoundError extends Error {
+  override name = 'RoutesDepositAddress.OwnerNotFoundError'
 }

package/src/internal/{funding → routes}/DepositWebhook.test.ts

@@ -1,26 +1,26 @@
 import * as TestApp from '../../../test/App.js'
-import * as TestFunding from '../../../test/Funding.js'
+import * as TestRoutes from '../../../test/Routes.js'
+import * as RoutesDeposits from '../../db/tables/routesDeposits.js'
 import * as WebhookQueueEvents from '../../db/tables/webhookQueueEvents.js'
 import * as Webhooks from '../Webhooks.js'
 import * as Deposit from './Deposit.js'
-import * as FundingDepositAddress from './DepositAddress.js'
+import * as RoutesDepositAddress from './DepositAddress.js'
 import * as DepositWebhook from './DepositWebhook.js'
 
 const db = TestApp.database()
 
 describe('stage', () => {
   test('matches owner, environment, project, and filters with stable event ids', async () => {
-    const orgId = 'org_funding_deposit_webhook'
-    const projectId = 'prj_funding_deposit_webhook'
-    const address = await FundingDepositAddress.create(db, {
-      apiKeyId: 'key_funding_deposit_webhook',
+    const orgId = 'org_routes_deposit_webhook'
+    const projectId = 'prj_routes_deposit_webhook'
+    const address = await RoutesDepositAddress.create(db, {
       deliveryStrategy: 'provider',
       environment: 'production',
       now: new Date('2026-08-12T00:00:00.000Z'),
       orgId,
       projectId,
-      providerOutputToken: TestFunding.providerOutputToken(),
-      snapshot: TestFunding.depositAddressSnapshot({
+      providerOutputToken: TestRoutes.providerOutputToken(),
+      snapshot: TestRoutes.depositAddressSnapshot({
         address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
         recipient: `0x${'ab'.repeat(20)}`,
       }),
@@ -28,7 +28,7 @@ describe('stage', () => {
     const deposit = await Deposit.create(db, {
       now: new Date('2026-08-12T00:01:00.000Z'),
       providerRequestId: 'relay_deposit_webhook',
-      snapshot: TestFunding.depositSnapshot(address.id),
+      snapshot: TestRoutes.depositSnapshot(address.id),
       sourceTransactionHash: `0x${'aa'.repeat(32)}`,
       sourceTransferIndex: 0,
     })
@@ -46,7 +46,7 @@ describe('stage', () => {
     }
     const org = await subscription({ filters, orgId })
     const project = await subscription({ filters, orgId, projectId })
-    await subscription({ orgId, projectId: 'prj_funding_deposit_sibling' })
+    await subscription({ orgId, projectId: 'prj_routes_deposit_sibling' })
     await subscription({ environment: 'sandbox', orgId })
     await subscription({ filters: { status: 'refunded' }, orgId })
 
@@ -66,27 +66,26 @@ describe('stage', () => {
       data: { id: completed.record.id, status: 'completed' },
       id: first.references[0]!.eventId,
       subscriptionId: org.id,
-      type: 'funding:deposit.updated',
+      type: 'routes:deposit.updated',
     })
   })
 })
 
 describe('transition', () => {
   test('commits the deposit version with its webhook obligation', async () => {
-    const orgId = 'org_funding_deposit_transition'
-    const address = await FundingDepositAddress.create(db, {
-      apiKeyId: 'key_funding_deposit_transition',
+    const orgId = 'org_routes_deposit_transition'
+    const address = await RoutesDepositAddress.create(db, {
       deliveryStrategy: 'provider',
       environment: 'production',
       now: new Date('2026-08-12T01:00:00.000Z'),
       orgId,
-      providerOutputToken: TestFunding.providerOutputToken(),
-      snapshot: TestFunding.depositAddressSnapshot(),
+      providerOutputToken: TestRoutes.providerOutputToken(),
+      snapshot: TestRoutes.depositAddressSnapshot(),
     })
     const deposit = await Deposit.create(db, {
       now: new Date('2026-08-12T01:01:00.000Z'),
       providerRequestId: 'relay_deposit_transition',
-      snapshot: TestFunding.depositSnapshot(address.id),
+      snapshot: TestRoutes.depositSnapshot(address.id),
       sourceTransactionHash: `0x${'bb'.repeat(32)}`,
       sourceTransferIndex: 0,
     })
@@ -99,6 +98,50 @@ describe('transition', () => {
     })
     if (transitioned.result.type !== 'applied') throw new Error('Expected applied transition.')
 
+    for (let index = 0; index < 3; index++) {
+      const repeated = await DepositWebhook.transition(db, {
+        expectedVersion: transitioned.result.record.version,
+        id: deposit.id,
+        providerRequestIds: [...transitioned.result.record.providerRequestIds],
+        snapshot: {
+          ...transitioned.result.record.snapshot,
+          recipient: `0x${'cc'.repeat(20)}`,
+          sourceTransactionHashes: [`0x${'dd'.repeat(32)}`],
+        },
+        status: 'bridging',
+      })
+      expect(repeated).toEqual({
+        references: [],
+        result: { record: transitioned.result.record, type: 'unchanged' },
+      })
+    }
+    expect(await RoutesDeposits.get(db, deposit.id)).toEqual(transitioned.result.record)
+    const metadata = await DepositWebhook.transition(db, {
+      expectedVersion: transitioned.result.record.version,
+      id: deposit.id,
+      providerDeliveredAt: '2026-08-12T01:02:00.000Z',
+      providerState: { nested: { b: 2, a: 1 } },
+    })
+    if (metadata.result.type !== 'applied') throw new Error('Expected a metadata transition.')
+    expect(metadata.references).toHaveLength(1)
+    expect(
+      await DepositWebhook.transition(db, {
+        expectedVersion: metadata.result.record.version,
+        id: deposit.id,
+        providerDeliveredAt: '2026-08-12T01:03:00.000Z',
+        providerState: { nested: { a: 1, b: 2 } },
+      }),
+    ).toEqual({ references: [], result: { record: metadata.result.record, type: 'unchanged' } })
+    expect(
+      (
+        await DepositWebhook.transition(db, {
+          expectedVersion: transitioned.result.record.version,
+          id: deposit.id,
+          status: 'bridging',
+        })
+      ).result.type,
+    ).toBe('stale')
+
     expect(transitioned.references).toHaveLength(1)
     expect(await WebhookQueueEvents.get(db, transitioned.references[0]!)).toMatchObject({
       envelope: {
@@ -114,7 +157,7 @@ function subscription(options: subscription.Options) {
     chainId: 4217,
     destination: { type: 'url', url: 'https://example.com/webhooks/tempo' },
     environment: options.environment ?? 'production',
-    eventType: 'funding:deposit.updated',
+    eventType: 'routes:deposit.updated',
     filters: options.filters ?? { recipient: `0x${'ab'.repeat(20)}`, status: 'completed' },
     owner: { orgId: options.orgId, type: 'api_key' },
     ...(options.projectId === undefined ? {} : { projectId: options.projectId }),

package/src/internal/{funding → routes}/DepositWebhook.ts

@@ -1,5 +1,5 @@
 import type * as Db from '../../db/Db.js'
-import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
+import * as RoutesDeposits from '../../db/tables/routesDeposits.js'
 import * as WebhookSubscriptions from '../../db/tables/webhookSubscriptions.js'
 import * as Webhooks from '../Webhooks.js'
 import * as Deposit from './Deposit.js'
@@ -27,7 +27,7 @@ export declare namespace transition {
   }
 }
 
-/** Stages durable webhook obligations for committed funding deposit versions. */
+/** Stages durable webhook obligations for committed route deposit versions. */
 export async function stage(
   db: Db.Db,
   options: stage.Options,
@@ -37,10 +37,10 @@ export async function stage(
   for (const record of unique(options.records)) {
     const chainId = destinationChainId(record)
     if (chainId === undefined) continue
-    const subscriptions = await WebhookSubscriptions.listActiveForFundingEvent(db, {
+    const subscriptions = await WebhookSubscriptions.listActiveForRoutesEvent(db, {
       chainId,
       environment: record.environment,
-      eventType: 'funding:deposit.updated',
+      eventType: 'routes:deposit.updated',
       now,
       orgId: record.orgId,
       ...(record.projectId === null ? {} : { projectId: record.projectId }),
@@ -65,12 +65,12 @@ export async function stage(
 export declare namespace stage {
   /** Committed deposit changes eligible for customer webhook delivery. */
   type Options = {
-    /** Latest committed funding deposit records. */
-    records: readonly FundingDeposits.Record[]
+    /** Latest committed route deposit records. */
+    records: readonly RoutesDeposits.Record[]
   }
 }
 
-function destinationChainId(record: FundingDeposits.Record): number | undefined {
+function destinationChainId(record: RoutesDeposits.Record): number | undefined {
   const match = /^eip155:(\d+)$/.exec(record.snapshot.destinationChain.id)
   if (!match) return undefined
   const chainId = Number(match[1])
@@ -92,8 +92,8 @@ function matches(filters: Record<string, unknown>, deposit: Deposit.Public): boo
   return true
 }
 
-function unique(records: readonly FundingDeposits.Record[]): FundingDeposits.Record[] {
-  const byId = new Map<string, FundingDeposits.Record>()
+function unique(records: readonly RoutesDeposits.Record[]): RoutesDeposits.Record[] {
+  const byId = new Map<string, RoutesDeposits.Record>()
   for (const record of records) {
     const current = byId.get(record.id)
     if (!current || current.version < record.version) byId.set(record.id, record)

package/src/internal/routes/Economics.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'vitest'
+
+import * as Economics from './Economics.js'
+
+describe('differenceBps', () => {
+  test('normalizes decimals and preserves rebates', () => {
+    expect(
+      Economics.differenceBps({
+        reference: { baseUnits: '1000000', currency: 'USD', decimals: 6 },
+        value: { baseUnits: '990000000000000000', currency: 'USD', decimals: 18 },
+      }),
+    ).toBe(100)
+    expect(
+      Economics.differenceBps({
+        reference: { baseUnits: '1000000', currency: 'USD', decimals: 6 },
+        value: { baseUnits: '1001000', currency: 'USD', decimals: 6 },
+      }),
+    ).toBe(-10)
+  })
+
+  test('omits incomparable denominations', () => {
+    expect(
+      Economics.differenceBps({
+        reference: { baseUnits: '1000000', currency: 'USD', decimals: 6 },
+        value: { baseUnits: '1000000', currency: 'EUR', decimals: 6 },
+      }),
+    ).toBeUndefined()
+  })
+})
+
+describe('usd', () => {
+  test('converts USD base units', () => {
+    expect(Economics.usd({ baseUnits: '20705', currency: 'USD', decimals: 6 })).toBe(0.020705)
+    expect(Economics.usd({ baseUnits: '20705', currency: 'EUR', decimals: 6 })).toBeUndefined()
+  })
+})
+
+describe('units', () => {
+  test('converts base units without assuming a currency', () => {
+    expect(Economics.units({ baseUnits: '20705', currency: 'ETH', decimals: 6 })).toBe(0.020705)
+  })
+})