tapimo 0.14.0 → 0.15.0

package/src/internal/routes/Reconciliation.unattributed.test.ts

@@ -0,0 +1,250 @@
+import * as NodeBuffer from 'node:buffer'
+import { AbiEvent, AbiParameters, Hex } from 'ox'
+
+import * as TestApp from '../../../test/App.js'
+import * as TestRelay from '../../../test/Relay.js'
+import * as TestRoutes from '../../../test/Routes.js'
+import * as Metrics from '../../Metrics.js'
+import * as RoutesCatalog from '../../db/tables/routesCatalog.js'
+import * as RoutesDepositAddresses from '../../db/tables/routesDepositAddresses.js'
+import * as RoutesDeposits from '../../db/tables/routesDeposits.js'
+import * as Webhooks from '../Webhooks.js'
+import * as Chain from './Chain.js'
+import * as DepositAddress from './DepositAddress.js'
+import * as Evidence from './Evidence.js'
+import * as Reconciliation from './Reconciliation.js'
+import * as SourceObservation from './SourceObservation.js'
+import * as Relay from './providers/relay.js'
+
+const db = TestApp.database()
+
+describe('createTracker', () => {
+  test('bounds dust work, advances after failures, revisits old rows, and accepts late attribution', async () => {
+    const route = TestRoutes.transferSnapshot()
+    const address = await DepositAddress.create(db, {
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-01-01T00:00:00.000Z'),
+      orgId: 'org_unattributed',
+      providerOutputToken: route.destinationToken,
+      snapshot: {
+        ...TestRoutes.depositAddressSnapshot(),
+        address: `0x${'44'.repeat(20)}`,
+        destinationChain: route.destinationChain,
+        destinationToken: route.destinationToken,
+        refundAddress: `0x${'55'.repeat(20)}`,
+        sourceChain: route.sourceChain,
+        sourceToken: route.sourceToken,
+      },
+    })
+    const seed = async (index: number, now: Date) => {
+      const observed = await SourceObservation.observe(db, {
+        addressId: address.id,
+        amount: index === 59 ? '1000000' : '1',
+        chainId: route.sourceChain.id,
+        now,
+        recipient: address.address,
+        sender: address.refundAddress,
+        tokenAddress: route.sourceToken.address,
+        transactionHash: Hex.fromNumber(index + 1, { size: 32 }),
+        transferIndex: 0,
+      })
+      if (observed.type === 'ignored') throw new Error('Expected a source deposit.')
+      return observed.record
+    }
+    const deposits = []
+    for (let index = 0; index < 60; index++)
+      deposits.push(await seed(index, new Date('2026-01-01T00:01:00.000Z')))
+    deposits.sort((left, right) => (left.id < right.id ? -1 : 1))
+    const reads: string[] = []
+    const deliveries: Webhooks.QueueReference[] = []
+    const counts: Parameters<Metrics.Metrics['count']>[] = []
+    let failedHash: string | undefined
+    let attributedHash: string | undefined
+    let now = new Date('2026-01-01T00:02:00.000Z')
+    const destinationHash = `0x${'ff'.repeat(32)}`
+    const server = await TestRelay.createServer(async (request, response) => {
+      response.setHeader('content-type', 'application/json')
+      if (request.method === 'GET') {
+        response.end(
+          JSON.stringify({
+            requests: attributedHash
+              ? [
+                  {
+                    createdAt: '2026-01-01T00:02:00.000Z',
+                    data: { inTxs: [], outTxs: [{ txHash: destinationHash }] },
+                    depositAddress: { depositTxHash: attributedHash },
+                    id: 'late-request',
+                    status: 'success',
+                    updatedAt: '2026-01-01T00:03:00.000Z',
+                  },
+                ]
+              : [],
+          }),
+        )
+        return
+      }
+      const chunks: Uint8Array[] = []
+      for await (const chunk of request) chunks.push(chunk)
+      const body = JSON.parse(NodeBuffer.Buffer.concat(chunks).toString()) as {
+        id: number
+        method: string
+        params?: string[] | undefined
+      }
+      const hash = body.params?.[0]
+      if (body.method === 'eth_getTransactionReceipt') reads.push(hash!)
+      if (body.method === 'eth_getTransactionReceipt' && hash === failedHash) {
+        response.end(
+          JSON.stringify({
+            error: { code: -32000, message: 'Receipt unavailable' },
+            id: body.id,
+            jsonrpc: '2.0',
+          }),
+        )
+        return
+      }
+      const destination = hash === destinationHash
+      const amount = destination || hash === Hex.fromNumber(60, { size: 32 }) ? 1_000_000n : 1n
+      const result =
+        body.method === 'eth_blockNumber'
+          ? '0x10'
+          : {
+              blockNumber: '0x10',
+              logs: [
+                {
+                  address: destination ? route.destinationToken.address : route.sourceToken.address,
+                  data: Hex.fromNumber(amount, { size: 32 }),
+                  logIndex: '0x0',
+                  topics: [
+                    AbiEvent.getSelector('event Transfer(address,address,uint256)'),
+                    AbiParameters.encode([{ type: 'address' }], [address.refundAddress as Hex.Hex]),
+                    AbiParameters.encode(
+                      [{ type: 'address' }],
+                      [(destination ? address.recipient : address.address) as Hex.Hex],
+                    ),
+                  ],
+                },
+              ],
+              status: '0x1',
+            }
+      response.end(JSON.stringify({ id: body.id, jsonrpc: '2.0', result }))
+    })
+    try {
+      await RoutesCatalog.publish(db, {
+        chainTokens: [],
+        chains: [route.sourceChain, route.destinationChain].map((chain) => ({
+          aliases: [],
+          id: chain.id as Chain.Id,
+          name: chain.name,
+          parentChainId: null,
+          rpcUrls: [server.url],
+          slug: chain.name.toLowerCase(),
+        })),
+        routes: [],
+        tokens: [],
+      })
+      await Webhooks.createSubscription(db, {
+        chainId: 4217,
+        destination: { type: 'url', url: 'https://example.com/webhooks' },
+        environment: 'production',
+        eventType: 'routes:deposit.updated',
+        filters: {},
+        owner: { orgId: address.orgId, type: 'api_key' },
+      })
+      const tracker = () =>
+        Reconciliation.createTracker({
+          db,
+          dispatch: async () => undefined,
+          dispatchDepositUpdates: async (references) => {
+            deliveries.push(...references)
+            return references.length
+          },
+          metrics: Metrics.from({
+            count: (...parameters) => {
+              counts.push(parameters)
+            },
+            flush() {},
+            gauge() {},
+            histogram() {},
+          }),
+          now: () => now,
+          providers: [Relay.relay({ apiKey: 'test-key', baseUrl: server.url })],
+          verifyTransfers: Evidence.createVerifier({ db }),
+        })
+      const reconcile = () =>
+        tracker().reconcile({
+          addressId: address.id,
+          trigger: 'poll',
+          type: 'routes:deposit-address:reconcile',
+        })
+      expect(await reconcile()).toMatchObject({ type: 'completed', updated: 25 })
+      expect(reads.sort()).toEqual(
+        deposits
+          .slice(0, 25)
+          .map((deposit) => deposit.sourceTransactionHash)
+          .sort(),
+      )
+      expect(deliveries).toHaveLength(25)
+      const first = await RoutesDeposits.get(db, deposits[0]!.id)
+      const newcomer = await seed(60, new Date('2026-01-01T00:02:01.000Z'))
+      now = new Date('2026-01-01T00:03:00.000Z')
+      reads.length = 0
+      failedHash = deposits[25]!.sourceTransactionHash
+      await expect(reconcile()).rejects.toThrow('Unattributed deposit reconciliation failed.')
+      expect(new Set(reads)).toEqual(
+        new Set(deposits.slice(25, 50).map((deposit) => deposit.sourceTransactionHash)),
+      )
+      expect(counts).toContainEqual([
+        'routes_deposit_reconciliation_count',
+        1,
+        { outcome: 'failed', provider: 'relay', trigger: 'poll' },
+      ])
+      failedHash = undefined
+      reads.length = 0
+      expect(await reconcile()).toMatchObject({ type: 'completed', updated: 10 })
+      expect(reads.sort()).toEqual(
+        deposits
+          .slice(50)
+          .map((deposit) => deposit.sourceTransactionHash)
+          .sort(),
+      )
+      expect((await RoutesDeposits.get(db, newcomer.id))?.status).toBe('detected')
+      reads.length = 0
+      expect(await reconcile()).toMatchObject({ type: 'completed', updated: 0 })
+      expect(reads.sort()).toEqual(
+        deposits
+          .slice(0, 25)
+          .map((deposit) => deposit.sourceTransactionHash)
+          .sort(),
+      )
+      expect(await RoutesDeposits.get(db, deposits[0]!.id)).toEqual(first)
+      expect(deliveries).toHaveLength(59)
+      expect(await reconcile()).toMatchObject({ type: 'completed', updated: 1 })
+      expect(await reconcile()).toMatchObject({ type: 'completed', updated: 1 })
+      expect((await RoutesDeposits.get(db, newcomer.id))?.status).toBe('bridging')
+      attributedHash = Hex.fromNumber(60, { size: 32 })
+      await reconcile()
+      const legitimate = deposits.find(
+        (deposit) => deposit.sourceTransactionHash === attributedHash,
+      )!
+      expect(await RoutesDeposits.get(db, legitimate.id)).toMatchObject({
+        providerRequestId: 'late-request',
+        snapshot: { destinationAmount: { baseUnits: '1000000' } },
+        status: 'completed',
+      })
+      expect(
+        await RoutesDeposits.listByAddress(
+          db,
+          { environment: 'production', orgId: address.orgId },
+          address.id,
+          { limit: 100 },
+        ),
+      ).toHaveLength(61)
+      expect(await RoutesDepositAddresses.get(db, address.id)).toMatchObject({
+        pollLeaseUntil: null,
+      })
+    } finally {
+      await server.closeAsync()
+    }
+  })
+})

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

@@ -1,15 +1,15 @@
 import type * as Chain from './Chain.js'
 import type * as Token from './Token.js'
 
-/** A supported funding path between two chain-scoped tokens. */
+/** A supported routes path between two chain-scoped tokens. */
 export type Route = {
-  /** Token received on Tempo. */
+  /** Token received on the destination chain. */
   destination: Token.Resolved
-  /** Token supplied by the caller. */
+  /** Token supplied on the source chain. */
   source: Token.Resolved
 }
 
-/** Creates funding routes from destination and source chain-token selections. */
+/** Creates provider routes from destination and source chain-token selections. */
 export function from(options: from.Options): Route[] {
   return options.sources.flatMap((source) =>
     source.tokens.flatMap((token) =>
@@ -19,11 +19,11 @@ export function from(options: from.Options): Route[] {
 }
 
 export declare namespace from {
-  /** Funding route definition. */
+  /** Provider route definition. */
   type Options = {
-    /** Chain and tokens received on Tempo. */
+    /** Chain and tokens received at the route destination. */
     destination: Chain.Selection
-    /** Chains and tokens accepted as funding inputs. */
+    /** Chains and tokens accepted as route inputs. */
     sources: readonly Chain.Selection[]
   }
 }

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

@@ -2,9 +2,9 @@ import * as NodeBuffer from 'node:buffer'
 
 import { AbiEvent } from 'ox'
 
-import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
+import * as RoutesDeposits from '../../db/tables/routesDeposits.js'
 import * as TestApp from '../../../test/App.js'
-import * as TestFunding from '../../../test/Funding.js'
+import * as TestRoutes from '../../../test/Routes.js'
 import * as TestRelay from '../../../test/Relay.js'
 import * as DepositAddress from './DepositAddress.js'
 import * as Reconciliation from './Reconciliation.js'
@@ -17,7 +17,7 @@ const transferEvent = AbiEvent.from(
 
 describe('scan', () => {
   test('finds confirmed transfers into active routes', async () => {
-    const route = TestFunding.transferSnapshot()
+    const route = TestRoutes.transferSnapshot()
     const address = `0x${'44'.repeat(20)}`
     const sender = `0x${'55'.repeat(20)}`
     const transactionHash = `0x${'aa'.repeat(32)}`
@@ -57,7 +57,7 @@ describe('scan', () => {
     try {
       const result = await SourceObservation.scan({
         chainId: route.sourceChain.id,
-        routes: [{ address, id: 'fda_source_observation' }],
+        routes: [{ address, id: 'rda_source_observation' }],
         rpcUrls: [server.url],
         tokenAddress: route.sourceToken.address,
       })
@@ -95,7 +95,7 @@ describe('scan', () => {
             "head": 16n,
             "observations": [
               {
-                "addressId": "fda_source_observation",
+                "addressId": "rda_source_observation",
                 "amount": "1000000",
                 "blockNumber": 16n,
                 "chainId": "eip155:8453",
@@ -117,15 +117,14 @@ describe('scan', () => {
 describe('observe', () => {
   test('creates one chain-detected deposit and attaches the Relay request later', async () => {
     const database = TestApp.databaseFactory()
-    const route = TestFunding.transferSnapshot()
+    const route = TestRoutes.transferSnapshot()
     const providerAddress = `0x${'44'.repeat(20)}`
     const sender = `0x${'55'.repeat(20)}`
     const sourceTransactionHash = `0x${'aa'.repeat(32)}`
     const address = await DepositAddress.create(database(), {
-      apiKeyId: 'key_source_observation',
       deliveryStrategy: 'provider',
       environment: 'production',
-      id: 'fda_source_observation',
+      id: 'rda_source_observation',
       now: new Date('2026-01-01T00:00:00.000Z'),
       orgId: 'org_source_observation',
       providerOutputToken: route.destinationToken,
@@ -180,7 +179,7 @@ describe('observe', () => {
       const pending = await tracker.reconcile({
         addressId: address.id,
         trigger: 'chain',
-        type: 'funding:deposit-address:reconcile',
+        type: 'routes:deposit-address:reconcile',
       })
       const reconciled = await Reconciliation.reconcileRequest(database(), {
         address,
@@ -203,7 +202,7 @@ describe('observe', () => {
           },
         ],
       })
-      const [record] = await FundingDeposits.listBySourceTransaction(database(), {
+      const [record] = await RoutesDeposits.listBySourceTransaction(database(), {
         depositAddressId: address.id,
         sourceTransactionHash,
       })
@@ -231,7 +230,7 @@ describe('observe', () => {
         })(),
       }).toMatchInlineSnapshot(
         {
-          dispatches: [[{ addressId: expect.any(String) }, { delaySeconds: 1 }]],
+          dispatches: [[{ addressId: expect.any(String) }, { delaySeconds: 5 }]],
         },
         `
         {
@@ -244,10 +243,10 @@ describe('observe', () => {
                   "kind": "provider",
                 },
                 "trigger": "chain",
-                "type": "funding:deposit-address:reconcile",
+                "type": "routes:deposit-address:reconcile",
               },
               {
-                "delaySeconds": 1,
+                "delaySeconds": 5,
               },
             ],
           ],
@@ -284,7 +283,7 @@ describe('observe', () => {
           "routes": [
             {
               "address": "0x4444444444444444444444444444444444444444",
-              "id": "fda_source_observation",
+              "id": "rda_source_observation",
             },
           ],
           "sameDeposit": true,

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

@@ -2,8 +2,8 @@ import { AbiEvent, Address } from 'ox'
 import { getBlockNumber, getLogs } from 'viem/actions'
 
 import type * as Db from '../../db/Db.js'
-import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js'
-import * as FundingDeposits from '../../db/tables/fundingDeposits.js'
+import * as RoutesDepositAddresses from '../../db/tables/routesDepositAddresses.js'
+import * as RoutesDeposits from '../../db/tables/routesDeposits.js'
 import * as Viem from '../Viem.js'
 import * as Value from '../Value.js'
 import * as Deposit from './Deposit.js'
@@ -20,13 +20,13 @@ const transferEvent = AbiEvent.from(
 export type Route = {
   /** Provider-owned reusable address. */
   address: string
-  /** Funding deposit address id. */
+  /** Route deposit address id. */
   id: string
 }
 
 /** Verified source transfer discovered directly from an EVM log. */
 export type Observation = {
-  /** Funding deposit address that received the transfer. */
+  /** Route deposit address that received the transfer. */
   addressId: string
   /** Source token quantity in base units. */
   amount: string
@@ -157,14 +157,14 @@ export async function listRoutes(
   db: Db.Db,
   options: listRoutes.Options,
 ): Promise<readonly Route[]> {
-  const records = await FundingDepositAddresses.listActiveSources(db, options)
+  const records = await RoutesDepositAddresses.listActiveSources(db, options)
   return records.map((record) => ({ address: record.address, id: record.id }))
 }
 
 export declare namespace listRoutes {
   /** Provider and source asset identifying one observer shard. */
   type Options = {
-    /** Funding provider that owns the deposit addresses. */
+    /** Route provider that owns the deposit addresses. */
     providerId: string
     /** Source chain CAIP-2 id. */
     sourceChainId: string
@@ -175,7 +175,7 @@ export declare namespace listRoutes {
 
 /** Persists one verified source transfer before provider indexing. */
 export async function observe(db: Db.Db, input: observe.Input): Promise<observe.Result> {
-  const address = await FundingDepositAddresses.get(db, input.addressId)
+  const address = await RoutesDepositAddresses.get(db, input.addressId)
   if (
     !address ||
     address.providerId !== 'relay' ||
@@ -189,10 +189,10 @@ export async function observe(db: Db.Db, input: observe.Input): Promise<observe.
   )
     return { type: 'ignored' }
 
-  return FundingDeposits.withSourceTransaction(db, {
+  return RoutesDeposits.withSourceTransaction(db, {
     depositAddressId: address.id,
     fn: async (tx) => {
-      const existing = await FundingDeposits.listBySourceTransaction(tx, {
+      const existing = await RoutesDeposits.listBySourceTransaction(tx, {
         depositAddressId: address.id,
         sourceTransactionHash: input.transactionHash,
       })
@@ -224,7 +224,7 @@ export async function observe(db: Db.Db, input: observe.Input): Promise<observe.
 export declare namespace observe {
   /** Verified source transfer and route identity. */
   type Input = {
-    /** Funding deposit address id. */
+    /** Route deposit address id. */
     addressId: string
     /** Source token quantity in base units. */
     amount: string
@@ -246,7 +246,7 @@ export declare namespace observe {
 
   /** Persistence outcome for one chain-observed source transfer. */
   type Result =
-    | { record: FundingDeposits.Record; type: 'created' | 'existing' }
+    | { record: RoutesDeposits.Record; type: 'created' | 'existing' }
     | { type: 'ignored' }
 }
 
@@ -255,9 +255,9 @@ function minimum(left: bigint, right: bigint) {
 }
 
 class ConfigurationError extends Error {
-  override name = 'FundingSourceObservation.ConfigurationError'
+  override name = 'RoutesSourceObservation.ConfigurationError'
 
   constructor(field: string) {
-    super(`Invalid ${field} configured for funding source observation.`)
+    super(`Invalid ${field} configured for routes source observation.`)
   }
 }

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

@@ -31,7 +31,7 @@ describe.skipIf(runtime.mode !== 'localnet')('create', () => {
     })
     const prepared = await settler.prepare({
       amount: 100_000n,
-      depositId: 'fdp_local_pathusd',
+      depositId: 'rdp_local_pathusd',
       recipient: recipient.address,
       token: Addresses.pathUsd,
     })
@@ -42,7 +42,7 @@ describe.skipIf(runtime.mode !== 'localnet')('create', () => {
       validBefore: envelope.validBefore,
     }).toMatchInlineSnapshot(`
       {
-        "nonceKey": 30469680684220070457389426308647765119962481996559904707083080710737939923517n,
+        "nonceKey": 14178250741649427376283123442251407630964943884632271002311413890375899489334n,
         "validBefore": undefined,
       }
     `)
@@ -87,7 +87,7 @@ describe.skipIf(runtime.mode !== 'localnet')('create', () => {
     })
     const prepared = await settler.prepare({
       amount: 100_000n,
-      depositId: 'fdp_local_activity_usd',
+      depositId: 'rdp_local_activity_usd',
       recipient: recipient.address,
       token: destinationToken,
     })
@@ -132,21 +132,21 @@ describe.skipIf(runtime.mode !== 'localnet')('create', () => {
     await expect(
       settler.prepare({
         amount: 100_000n,
-        depositId: 'fdp_local_unlisted',
+        depositId: 'rdp_local_unlisted',
         recipient: recipient.address,
         token,
       }),
-    ).rejects.toThrowErrorMatchingInlineSnapshot(`[Funding.Subsidy.LiquidityUnavailableError]`)
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[Routes.Subsidy.LiquidityUnavailableError]`)
   })
 
   test('reports unavailable pathUSD balance from transaction simulation', async () => {
     await expect(
       settler.prepare({
         amount: 2n ** 120n,
-        depositId: 'fdp_local_insufficient_balance',
+        depositId: 'rdp_local_insufficient_balance',
         recipient: recipient.address,
         token: Addresses.pathUsd,
       }),
-    ).rejects.toThrowErrorMatchingInlineSnapshot(`[Funding.Subsidy.BalanceUnavailableError]`)
+    ).rejects.toThrowErrorMatchingInlineSnapshot(`[Routes.Subsidy.BalanceUnavailableError]`)
   })
 })