tapimo 0.12.0 → 0.14.0

package/src/internal/Webhooks.test.ts

@@ -1,5 +1,7 @@
 import { Webhooks } from 'tapimo'
+import { sql } from 'kysely'
 import * as TestApp from '../../test/App.js'
+import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import * as Metrics from '../Metrics.js'
 import * as Cursor from './Cursor.js'
 
@@ -170,6 +172,49 @@ describe('createSubscription', () => {
   })
 })
 
+describe('listActiveForFundingEvent', () => {
+  test('keeps selected subscriptions until the caller transaction commits', async () => {
+    const getDb = TestApp.databaseFactory()
+    const owner = { orgId: 'org_funding_subscription_lock', type: 'api_key' } as const
+    const subscription = await Webhooks.createSubscription(
+      getDb(),
+      createInput({
+        environment: 'production',
+        eventType: 'funding:transfer.updated',
+        owner,
+      }),
+    )
+    const locked = Promise.withResolvers<void>()
+    const release = Promise.withResolvers<void>()
+    const read = getDb().transaction(async (tx) => {
+      const subscriptions = await WebhookSubscriptions.listActiveForFundingEvent(tx, {
+        chainId: 4217,
+        environment: 'production',
+        eventType: 'funding:transfer.updated',
+        now: new Date().toISOString(),
+        orgId: owner.orgId,
+      })
+      locked.resolve()
+      await release.promise
+      return subscriptions
+    })
+    await locked.promise
+
+    const deletion = await getDb()
+      .transaction(async (tx) => {
+        await sql`select set_config('lock_timeout', '100ms', true)`.execute(tx.kysely)
+        return Webhooks.deleteSubscription(tx, owner, subscription.id)
+      })
+      .catch((cause: unknown) => cause)
+    release.resolve()
+
+    await expect(read).resolves.toEqual([subscription])
+    expect(deletion).toBeInstanceOf(Error)
+    expect(String(deletion)).toContain('lock timeout')
+    await expect(Webhooks.deleteSubscription(getDb(), owner, subscription.id)).resolves.toBe(true)
+  })
+})
+
 describe('owner isolation', () => {
   test('an owner cannot read or list another owner subscriptions', async () => {
     const db = TestApp.database()

package/src/internal/funding/Action.test.ts

@@ -132,7 +132,47 @@ describe('validateEvmCalls', () => {
         sourceTokenAddress: sourceToken,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[Funding.Action.InvalidActionError: Stablecoin funding calls must not carry native value.]`,
+      `[Funding.Action.InvalidActionError: Native value must match a validated provider fee.]`,
     )
   })
+
+  test('accepts an exact provider-validated native value', () => {
+    Action.validateEvmCalls({
+      action: {
+        calls: [approveCall(1_000_000n), { ...depositCall, value: '0x10' }],
+        type: 'evm:calls',
+      },
+      nativeValues: [{ to: spender, value: '0x10' }],
+      sourceAmount: '1000000',
+      sourceTokenAddress: sourceToken,
+    })
+  })
+
+  test('rejects malformed native value allowances', () => {
+    expect(() =>
+      Action.validateEvmCalls({
+        action: { calls: [approveCall(1_000_000n), depositCall], type: 'evm:calls' },
+        nativeValues: [{ to: spender, value: '10' }],
+        sourceAmount: '1000000',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Funding.Action.InvalidActionError: Malformed native value allowance.]`,
+    )
+  })
+
+  test('rejects native values outside the exact provider allowance', () => {
+    for (const call of [
+      { ...depositCall, to: `0x${'99'.repeat(20)}`, value: '0x10' },
+      { ...depositCall, value: '0x11' },
+    ])
+      expect(() =>
+        Action.validateEvmCalls({
+          action: { calls: [approveCall(1_000_000n), call], type: 'evm:calls' },
+          nativeValues: [{ to: spender, value: '0x10' }],
+          sourceAmount: '1000000',
+          sourceTokenAddress: sourceToken,
+        }),
+      ).toThrow(Action.InvalidActionError)
+  })
 })

package/src/internal/funding/Action.ts

@@ -1,6 +1,8 @@
 import { AbiFunction, Address, type Hex, Solidity } from 'ox'
 import * as z from 'zod/mini'
 
+import * as OpenApi from '../OpenApi.js'
+
 /**
  * Executable source-chain actions returned by funding transfer creation. A
  * strict discriminated union: transfer reads never include an action.
@@ -12,49 +14,58 @@ const approveSelector = AbiFunction.getSelector(approve)
 /** Zod schemas owned by funding actions. */
 export namespace schema {
   /** One unsigned EVM call, in the exchange quote API's call shape. */
-  export const Call = z
-    .object({
-      data: z
-        .string()
-        .check(
-          z.regex(/^0x(?:[0-9a-fA-F]{2})*$/),
-          z.describe('ABI-encoded calldata.'),
-          z.meta({ examples: ['0x095ea7b3'] }),
-        ),
-      to: z
-        .string()
-        .check(
-          z.regex(/^0x[0-9a-fA-F]{40}$/),
-          z.describe('Contract the call targets.'),
-          z.meta({ examples: [`0x${'44'.repeat(20)}`] }),
-        ),
-      value: z
-        .string()
-        .check(
-          z.regex(/^0x[0-9a-fA-F]+$/),
-          z.describe('Native value to send, as hex.'),
-          z.meta({ examples: ['0x0'] }),
-        ),
-    })
-    .check(z.describe('One unsigned EVM call.'))
+  export const Call = OpenApi.component(
+    z
+      .object({
+        data: z
+          .string()
+          .check(
+            z.regex(/^0x(?:[0-9a-fA-F]{2})*$/),
+            z.describe('ABI-encoded calldata.'),
+            z.meta({ examples: ['0x095ea7b3'] }),
+          ),
+        to: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Contract the call targets.'),
+            z.meta({ examples: [`0x${'44'.repeat(20)}`] }),
+          ),
+        value: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]+$/),
+            z.describe('Native value to send, as hex.'),
+            z.meta({ examples: ['0x0'] }),
+          ),
+      })
+      .check(z.describe('One unsigned EVM call.')),
+    'FundingActionCall',
+  )
 
   /** Ordered unsigned EVM calls the caller signs and submits on the source chain. */
-  export const EvmCalls = z
-    .object({
-      calls: z
-        .array(Call)
-        .check(
-          z.minLength(1),
-          z.describe('Calls in submission order; they may require separate transactions.'),
-        ),
-      type: z.literal('evm:calls').check(z.describe('Action kind.')),
-    })
-    .check(z.describe('Ordered unsigned EVM calls to sign and submit on the source chain.'))
+  export const EvmCalls = OpenApi.component(
+    z
+      .object({
+        calls: z
+          .array(Call)
+          .check(
+            z.minLength(1),
+            z.describe('Calls in submission order; they may require separate transactions.'),
+          ),
+        type: z.literal('evm:calls').check(z.describe('Action kind.')),
+      })
+      .check(z.describe('Ordered unsigned EVM calls to sign and submit on the source chain.')),
+    'FundingEvmCallsAction',
+  )
 
   /** Executable source-chain action attached to a creation response. */
-  export const Action = z
-    .discriminatedUnion('type', [EvmCalls])
-    .check(z.describe('Executable source-chain action. Never returned by transfer reads.'))
+  export const Action = OpenApi.component(
+    z
+      .discriminatedUnion('type', [EvmCalls])
+      .check(z.describe('Executable source-chain action. Never returned by transfer reads.')),
+    'FundingAction',
+  )
 }
 
 /** One unsigned EVM call (see {@link schema.Call}). */
@@ -66,6 +77,14 @@ export type EvmCalls = z.output<typeof schema.EvmCalls>
 /** Executable source-chain action (see {@link schema.Action}). */
 export type Action = z.output<typeof schema.Action>
 
+/** One exact native-value allowance established by provider-specific validation. */
+export type NativeValue = {
+  /** Contract that may receive the native value. */
+  to: string
+  /** Exact native value allowed, as a JSON-RPC quantity. */
+  value: string
+}
+
 /**
  * Validates prepared EVM calls before persistence. Token calls, approval
  * targets, spenders, amounts, selectors, and native value must match the route.
@@ -73,9 +92,16 @@ export type Action = z.output<typeof schema.Action>
 export function validateEvmCalls(options: validateEvmCalls.Options): void {
   const action = schema.EvmCalls.safeParse(options.action)
   if (!action.success) throw new InvalidActionError('Malformed EVM calls.')
+  const nativeValues = new Set<string>()
+  for (const { to, value } of options.nativeValues ?? []) {
+    if (!Address.validate(to, { strict: false }) || !/^0x[0-9a-fA-F]+$/.test(value))
+      throw new InvalidActionError('Malformed native value allowance.')
+    nativeValues.add(`${to.toLowerCase()}:${BigInt(value).toString()}`)
+  }
   for (const [index, call] of action.data.calls.entries()) {
-    if (BigInt(call.value) !== 0n)
-      throw new InvalidActionError('Stablecoin funding calls must not carry native value.')
+    const callValue = BigInt(call.value)
+    if (callValue > 0n && !nativeValues.has(`${call.to.toLowerCase()}:${callValue.toString()}`))
+      throw new InvalidActionError('Native value must match a validated provider fee.')
     const targetsSourceToken = Address.isEqual(
       call.to as Address.Address,
       options.sourceTokenAddress as Address.Address,
@@ -104,6 +130,8 @@ export declare namespace validateEvmCalls {
   type Options = {
     /** The prepared action to validate. */
     action: EvmCalls
+    /** Exact native values established by provider-specific validation. */
+    nativeValues?: readonly NativeValue[] | undefined
     /** Source amount in base units. */
     sourceAmount: string
     /** Source token contract address. */

package/src/internal/funding/Catalog.test.ts

@@ -309,3 +309,37 @@ describe('route capabilities', () => {
     ).toThrow()
   })
 })
+
+describe('route configuration', () => {
+  const configuration = { poolAddress: `0x${'11'.repeat(20)}` }
+
+  test('carries configuration into hydrated provider routes', () => {
+    const snapshot = Catalog.compile(rows({ routes: [{ ...data.routes[0]!, configuration }] }))
+    expect(snapshot.routes[0]?.configuration).toStrictEqual(configuration)
+    expect(snapshot.routesByProvider.get('relay')?.[0]?.configuration).toStrictEqual(configuration)
+  })
+
+  test('omits configuration when it is absent or null', () => {
+    const absent = Catalog.compile(rows())
+    const nulled = Catalog.compile(rows({ routes: [{ ...data.routes[0]!, configuration: null }] }))
+    expect('configuration' in absent.routes[0]!).toBe(false)
+    expect('configuration' in nulled.routes[0]!).toBe(false)
+  })
+
+  test('publishes configuration through the write boundary', async () => {
+    const db = TestApp.database()
+    const snapshot = await Catalog.publish(db, {
+      ...data,
+      routes: [{ ...data.routes[0]!, configuration }],
+    })
+    expect(snapshot.routes[0]?.configuration).toStrictEqual(configuration)
+  })
+
+  test('rejects non-object configuration', () => {
+    expect(() =>
+      Catalog.compile(
+        rows({ routes: [{ ...data.routes[0]!, configuration: 'invalid' as never }] }),
+      ),
+    ).toThrow()
+  })
+})

package/src/internal/funding/Catalog.ts

@@ -55,10 +55,16 @@ export namespace schema {
       z.describe('Funding capabilities enabled on one provider route.'),
     )
 
-  // Absent or null `capabilities` keeps a route quote-only, so transfer and
-  // deposit-address support enable through reviewed seed edits.
+  /** Provider-specific configuration for one funding route. */
+  export const Configuration = z
+    .record(z.string(), z.unknown())
+    .check(z.describe('Provider-specific configuration for one funding route.'))
+
+  // Absent or null `capabilities` keeps a route quote-only. Absent or null
+  // `configuration` lets providers decide whether a route is configured.
   const Route = z.extend(db_Schema.FundingRoute, {
     capabilities: z.optional(z.nullable(Capabilities)),
+    configuration: z.optional(z.nullable(Configuration)),
   })
 
   /** Complete funding catalog content accepted by the publish boundary. */
@@ -77,10 +83,15 @@ export namespace schema {
 /** Funding capabilities enabled on one provider route. */
 export type Capabilities = z.output<typeof schema.Capabilities>
 
+/** Provider-specific configuration for one funding route. */
+export type Configuration = z.output<typeof schema.Configuration>
+
 /** One hydrated provider route in a funding catalog snapshot. */
 export type ProviderRoute = {
   /** Funding capabilities; absent means the route is quote-only. */
   capabilities?: Capabilities | undefined
+  /** Provider-specific route configuration. */
+  configuration?: Configuration | undefined
   /** Funding provider that supports the route. */
   providerId: string
   /** Hydrated source-to-destination funding route. */
@@ -93,8 +104,8 @@ export type Snapshot = {
   chainsByKey: ReadonlyMap<string, Chain.Chain>
   /** Hydrated provider routes in stable catalog order. */
   routes: readonly ProviderRoute[]
-  /** Hydrated routes grouped by provider id. */
-  routesByProvider: ReadonlyMap<string, readonly Route.Route[]>
+  /** Hydrated provider routes grouped by provider id. */
+  routesByProvider: ReadonlyMap<string, readonly ProviderRoute[]>
   /** Canonical funding tokens indexed by stable id. */
   tokensById: ReadonlyMap<string, Token.Token>
   /** ISO timestamp of the catalog's last publish. */
@@ -176,7 +187,7 @@ export function compile(rows: core_Catalog.Rows): Snapshot {
   }
 
   const routes: ProviderRoute[] = []
-  const routesByProvider = new Map<string, Route.Route[]>()
+  const routesByProvider = new Map<string, ProviderRoute[]>()
   for (const row of data.routes) {
     const route = {
       destination: resolvePlacement(
@@ -187,14 +198,16 @@ export function compile(rows: core_Catalog.Rows): Snapshot {
       ),
       source: resolvePlacement(chainsById, tokensById, row.sourceChainId, row.sourceTokenId),
     }
-    routes.push({
+    const entry = {
       ...(row.capabilities ? { capabilities: row.capabilities } : {}),
+      ...(row.configuration ? { configuration: row.configuration } : {}),
       providerId: row.providerId,
       route,
-    })
+    }
+    routes.push(entry)
     const providerRoutes = routesByProvider.get(row.providerId)
-    if (providerRoutes) providerRoutes.push(route)
-    else routesByProvider.set(row.providerId, [route])
+    if (providerRoutes) providerRoutes.push(entry)
+    else routesByProvider.set(row.providerId, [entry])
   }
 
   return {
@@ -219,10 +232,14 @@ export async function publish(db: Db.Db, input: publish.Input): Promise<Snapshot
     catalog: { id: 'default', updatedAt: emptyUpdatedAt, version: 'validation' },
     ...data,
   })
-  // Absent `capabilities` persists as null; both mean indicative-only.
+  // Optional route data persists as null so every stored row has one shape.
   await core_Catalog.publish(db, {
     ...data,
-    routes: data.routes.map((route) => ({ ...route, capabilities: route.capabilities ?? null })),
+    routes: data.routes.map((route) => ({
+      ...route,
+      capabilities: route.capabilities ?? null,
+      configuration: route.configuration ?? null,
+    })),
   })
   return prime(db, await read(db))
 }

package/src/internal/funding/DepositWebhook.ts

@@ -37,9 +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.listActiveForFundingDeposit(db, {
+    const subscriptions = await WebhookSubscriptions.listActiveForFundingEvent(db, {
       chainId,
       environment: record.environment,
+      eventType: 'funding:deposit.updated',
       now,
       orgId: record.orgId,
       ...(record.projectId === null ? {} : { projectId: record.projectId }),

package/src/internal/funding/Evidence.ts

@@ -1,5 +1,5 @@
 import { AbiEvent, Address, Base58, Bytes, Hash, Hex, RpcSchema, RpcTransport } from 'ox'
-import { createClient, custom, fallback, TransactionReceiptNotFoundError } from 'viem'
+import { TransactionReceiptNotFoundError } from 'viem'
 import { getBlockNumber, getTransactionReceipt } from 'viem/actions'
 import * as z from 'zod/mini'
 
@@ -195,7 +195,7 @@ async function verifyEvm(
   parameters: Reconciliation.VerifyTransfers.Parameters,
   options: FetchOptions & { confirmations: number },
 ): Promise<readonly Reconciliation.TransferEvidence[]> {
-  const client = jsonRpcClient(options)
+  const client = Viem.createEvmClient(options)
   const [receipt, head] = await Promise.all([
     getTransactionReceipt(client, { hash: parameters.transactionHash as Hex.Hex }).catch(
       (cause) => {
@@ -334,17 +334,6 @@ async function verifyTron(
   })
 }
 
-function jsonRpcClient(options: FetchOptions) {
-  return createClient({
-    transport: fallback(
-      options.urls.map((url) => {
-        const transport = RpcTransport.fromHttp(url, { fetchFn: options.fetch })
-        return custom(transport, { retryCount: 0 })
-      }),
-    ),
-  })
-}
-
 async function requestSolana(
   options: FetchOptions,
   request: SolanaRpcSchema['Request'],

package/src/internal/funding/Provider.test.ts

@@ -5,6 +5,7 @@ import * as Across from './providers/across.js'
 import * as Relay from './providers/relay.js'
 import * as Rhino from './providers/rhino.js'
 import * as Squid from './providers/squid.js'
+import * as Stargate from './providers/stargate.js'
 import * as Symbiosis from './providers/symbiosis.js'
 
 const providers = [
@@ -19,6 +20,7 @@ const providers = [
     integratorId: 'squid-integrator-id',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
+  Stargate.stargate(),
   Symbiosis.symbiosis({ userAddress: '0x1111111111111111111111111111111111111111' }),
 ] as const
 
@@ -831,9 +833,63 @@ describe('prepareTransfer', () => {
       { operation: 'prepareTransfer', outcome: 'unavailable', provider: 'relay' },
     ])
   })
+
+  test('accepts preparations without correlation', async () => {
+    const { correlation: _correlation, ...result } = preparedResult()
+    const spender = `0x${'44'.repeat(20)}`
+    const selected = FundingProvider.prepareTransfer({
+      ...prepareOptions,
+      providers: [
+        withPrepareTransfer('relay', async () => {
+          return {
+            ...result,
+            action: {
+              calls: [
+                {
+                  data: `0x095ea7b3${spender.slice(2).padStart(64, '0')}${(1_000_000).toString(16).padStart(64, '0')}`,
+                  to: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
+                  value: '0x0',
+                },
+                { data: '0xe8017952', to: spender, value: '0x0' },
+              ],
+              type: 'evm:calls',
+            },
+          }
+        }),
+      ],
+    })
+
+    expect((await selected)?.result.correlation).toBeUndefined()
+  })
 })
 
 describe('getPrepareCandidates', () => {
+  test('restricts candidates to the requested provider', () => {
+    const relay = withPrepareTransfer('relay', async () => preparedResult())
+    const stargate = withPrepareTransfer('stargate', async () => preparedResult())
+    const route = TestFunding.data.routes.find(
+      (entry) => entry.providerId === 'relay' && entry.capabilities?.transfer,
+    )!
+    const catalog = FundingCatalog.compile({
+      catalog: {
+        id: 'default',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        version: 'test',
+      },
+      ...TestFunding.data,
+      routes: [...TestFunding.data.routes, { ...route, providerId: 'stargate' }],
+    })
+
+    expect(
+      FundingProvider.getPrepareCandidates({
+        ...prepareOptions,
+        catalog,
+        provider: 'stargate',
+        providers: [relay, stargate],
+      }).map(({ provider }) => provider.id),
+    ).toEqual(['stargate'])
+  })
+
   test('restricts candidates to the selected destination chain', () => {
     const provider = withPrepareTransfer('relay', async () => preparedResult())
     expect(
@@ -1110,6 +1166,19 @@ describe('getQuoteCandidates', () => {
     expect(candidate?.sourceAmount).toEqual({ amount: '1250000', formatted: '1.25' })
   })
 
+  test('carries provider route configuration without duplicating token metadata', () => {
+    const [candidate] = FundingProvider.getQuoteCandidates({
+      ...baseUsdcRequest,
+      provider: 'stargate',
+      providers,
+    })
+
+    expect(candidate?.configuration).toEqual({
+      poolAddress: '0x27a16dc786820B16E5c9028b75B99F6f604b5d26',
+    })
+    expect(candidate?.sourceToken.address).toBe('0x833589fcd6edb6e08f4c7c32d4f71b54bda02913')
+  })
+
   test('resolves normalized catalog aliases', () => {
     const catalog = FundingCatalog.compile({
       catalog: {
@@ -1341,6 +1410,10 @@ describe('getProviders', () => {
           "id": "squid",
           "name": "Squid",
         },
+        {
+          "id": "stargate",
+          "name": "Stargate",
+        },
         {
           "id": "symbiosis",
           "name": "Symbiosis",