tapimo 0.12.0 → 0.13.0

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/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",

package/src/internal/funding/Provider.ts

@@ -216,10 +216,12 @@ export namespace schema {
   /** Executable preparation returned by a funding provider. */
   export const PrepareResult = z.object({
     action: Action.schema.Action,
-    correlation: z.object({
-      checkEndpoint: z.optional(z.string()),
-      requestId: z.string().check(z.minLength(1)),
-    }),
+    correlation: z.optional(
+      z.object({
+        checkEndpoint: z.optional(z.string()),
+        requestId: z.string().check(z.minLength(1)),
+      }),
+    ),
     destinationAmount: PositiveInteger,
     destinationAmountMin: PositiveInteger,
     expiresAt: z.optional(z.iso.datetime()),
@@ -227,6 +229,7 @@ export namespace schema {
       z.object({
         amount: Schema.DecimalString,
         side: z.enum(['destination', 'source']),
+        token: z.optional(TokenRef),
       }),
     ),
     quality: GetQuoteResult.shape.quality,
@@ -467,6 +470,21 @@ export declare namespace prepareTransfer {
   type ReturnType = z.output<typeof schema.PrepareResult>
 }
 
+/** Contract for provider-specific executable action validation. */
+export declare namespace validateTransferAction {
+  /** Prepared action and its curated route terms. */
+  type Parameters = prepareTransfer.Parameters & {
+    /** Executable action returned by the provider. */
+    action: Action.Action
+  }
+
+  /** Provider-specific constraints established by validation. */
+  type ReturnType = {
+    /** Exact native values independently validated against provider calldata. */
+    nativeValues?: readonly Action.NativeValue[] | undefined
+  }
+}
+
 /** Contract of the provider `createDepositAddress` method. */
 export declare namespace createDepositAddress {
   /** Input passed to a provider provisioning one reusable deposit address. */
@@ -683,6 +701,10 @@ export type Provider<id extends string = string> = core_Provider.Provider<id, 'f
     input: prepareTransfer.Parameters,
     signal: AbortSignal,
   ): Promise<prepareTransfer.ReturnType>
+  /** Validates provider-specific action semantics before generic persistence checks. */
+  validateTransferAction?(
+    input: validateTransferAction.Parameters,
+  ): validateTransferAction.ReturnType
   /** Receives authenticated provider status events, when configured. */
   webhook?: Webhook | undefined
 }
@@ -952,6 +974,7 @@ export function getQuoteCandidates(options: getQuoteCandidates.Options) {
     .filter((entry) => provider === undefined || entry.provider.id === provider.id)
     .map((entry) =>
       createQuoteCandidate({
+        configuration: entry.configuration,
         destinationToken: entry.route.destination,
         provider: entry.provider,
         route: entry.route,
@@ -1124,20 +1147,17 @@ export async function prepareTransfer(
     candidates.map(async ({ candidate, provider }) => {
       const start = performance.now()
       try {
+        const parameters = {
+          candidate,
+          method: options.method,
+          mode: options.mode,
+          recipient: options.recipient,
+          sender: options.sender,
+          slippageBps: options.slippageBps,
+        }
         const parsed = schema.PrepareResult.safeParse(
           await withTimeout(
-            (signal) =>
-              provider.prepareTransfer(
-                {
-                  candidate,
-                  method: options.method,
-                  mode: options.mode,
-                  recipient: options.recipient,
-                  sender: options.sender,
-                  slippageBps: options.slippageBps,
-                },
-                signal,
-              ),
+            (signal) => provider.prepareTransfer(parameters, signal),
             options.providerTimeoutMs ?? defaultPrepareTimeoutMs,
           ),
         )
@@ -1160,8 +1180,13 @@ export async function prepareTransfer(
         }
         if (result.action.type === 'evm:calls')
           try {
+            const constraints = provider.validateTransferAction?.({
+              ...parameters,
+              action: result.action,
+            })
             Action.validateEvmCalls({
               action: result.action,
+              nativeValues: constraints?.nativeValues,
               sourceAmount: candidate.sourceAmount.amount,
               sourceTokenAddress: candidate.sourceToken.address,
             })
@@ -1275,7 +1300,14 @@ export function getDepositAddressCandidates(options: getDepositAddressCandidates
     const provider = options.providers.find((candidate) => candidate.id === entry.providerId)
     if (!provider || !canCreateDepositAddress(provider)) return []
     return [
-      { candidate: createDepositAddressCandidate({ provider, route: entry.route }), provider },
+      {
+        candidate: createDepositAddressCandidate({
+          configuration: entry.configuration,
+          provider,
+          route: entry.route,
+        }),
+        provider,
+      },
     ]
   })
 }
@@ -1308,6 +1340,9 @@ export function getPrepareCandidates(options: getPrepareCandidates.Options) {
   if (!amount.success) throw new InvalidAmountError()
   const sourceChain = resolveSourceChain(options.sourceChain, options.catalog)
   const destinationChainId = `eip155:${options.destinationChainId}`
+  const selectedProvider = options.provider
+    ? resolveProvider(options.provider, options.providers)
+    : undefined
 
   return options.catalog.routes.flatMap((entry) => {
     if (entry.route.source.chain.id !== sourceChain.id) return []
@@ -1315,11 +1350,13 @@ export function getPrepareCandidates(options: getPrepareCandidates.Options) {
     if (!matchesToken(entry.route.source, options.sourceToken)) return []
     if (!matchesToken(entry.route.destination, options.destinationToken)) return []
     if (!entry.capabilities?.transfer?.modes.includes(options.mode)) return []
-    const provider = options.providers.find((candidate) => candidate.id === entry.providerId)
-    if (!provider || !canPrepareTransfer(provider)) return []
+    const provider =
+      selectedProvider ?? options.providers.find((candidate) => candidate.id === entry.providerId)
+    if (!provider || provider.id !== entry.providerId || !canPrepareTransfer(provider)) return []
     return [
       {
         candidate: createQuoteCandidate({
+          configuration: entry.configuration,
           destinationToken: entry.route.destination,
           provider,
           route: entry.route,
@@ -1349,6 +1386,8 @@ export declare namespace getPrepareCandidates {
     method: Transfer.Method
     /** Amount mode the caller selected. */
     mode: Transfer.Mode
+    /** Funding provider ID selected by the caller. */
+    provider?: string | undefined
     /** Funding providers considered by the request. */
     providers: readonly Provider[]
     /** Source amount in base units. */
@@ -1572,8 +1611,9 @@ function chainRef(chain: Chain): ChainRef {
   })
 }
 
-function createDepositAddressCandidate(options: { provider: Provider; route: core_Route.Route }) {
+function createDepositAddressCandidate(options: createDepositAddressCandidate.Options) {
   return {
+    ...(options.configuration ? { configuration: options.configuration } : {}),
     destinationChain: chainRef(options.route.destination.chain),
     destinationToken: tokenRef(options.route.destination),
     provider: schema.ProviderRef.parse(options.provider),
@@ -1583,14 +1623,17 @@ function createDepositAddressCandidate(options: { provider: Provider; route: cor
   } as const
 }
 
-function createQuoteCandidate(options: {
-  destinationToken: Token
-  provider: Provider
-  route: core_Route.Route
-  sourceAmount: ReturnType<typeof resolveSourceAmount>
-  sourceToken: Token
-}) {
+declare namespace createDepositAddressCandidate {
+  type Options = {
+    configuration?: core_Catalog.Configuration | undefined
+    provider: Provider
+    route: core_Route.Route
+  }
+}
+
+function createQuoteCandidate(options: createQuoteCandidate.Options) {
   return {
+    ...(options.configuration ? { configuration: options.configuration } : {}),
     destinationChain: chainRef(options.destinationToken.chain),
     destinationToken: tokenRef(options.destinationToken),
     id: [
@@ -1608,6 +1651,17 @@ function createQuoteCandidate(options: {
   } as const
 }
 
+declare namespace createQuoteCandidate {
+  type Options = {
+    configuration?: core_Catalog.Configuration | undefined
+    destinationToken: Token
+    provider: Provider
+    route: core_Route.Route
+    sourceAmount: ReturnType<typeof resolveSourceAmount>
+    sourceToken: Token
+  }
+}
+
 function normalizeInput(value: string) {
   return value.trim().toLowerCase()
 }
@@ -1807,7 +1861,7 @@ function resolveSourceChain(input: string, catalog: core_Catalog.Snapshot) {
 
 function getRoutes(catalog: core_Catalog.Snapshot, providers: readonly Provider[]) {
   return providers.flatMap((provider) =>
-    (catalog.routesByProvider.get(provider.id) ?? []).map((route) => ({ provider, route })),
+    (catalog.routesByProvider.get(provider.id) ?? []).map((entry) => ({ ...entry, provider })),
   )
 }