tapimo 0.11.0 → 0.13.0

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/Deposit.ts

@@ -4,6 +4,7 @@ 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 Id from '../Id.js'
+import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
 import * as Provider from './Provider.js'
 
@@ -115,22 +116,25 @@ export namespace schema {
     )
 
   /** Customer-safe explanation of a deposit status. */
-  export const StatusReason = z
-    .object({
-      code: z
-        .enum(statusReasonCodes)
-        .check(
-          z.describe('Stable machine-readable reason code.'),
-          z.meta({ examples: ['delivery_liquidity_unavailable'] }),
-        ),
-      message: z
-        .string()
-        .check(
-          z.describe('Human-readable explanation of the current status.'),
-          z.meta({ examples: ['The required destination amount is not currently available.'] }),
-        ),
-    })
-    .check(z.describe('Why a deposit needs attention or recovery.'))
+  export const StatusReason = OpenApi.component(
+    z
+      .object({
+        code: z
+          .enum(statusReasonCodes)
+          .check(
+            z.describe('Stable machine-readable reason code.'),
+            z.meta({ examples: ['delivery_liquidity_unavailable'] }),
+          ),
+        message: z
+          .string()
+          .check(
+            z.describe('Human-readable explanation of the current status.'),
+            z.meta({ examples: ['The required destination amount is not currently available.'] }),
+          ),
+      })
+      .check(z.describe('Why a deposit needs attention or recovery.')),
+    'FundingDepositStatusReason',
+  )
 
   /** Public fields persisted as the deposit snapshot. */
   export const Snapshot = z
@@ -189,54 +193,57 @@ export namespace schema {
     )
 
   /** One detected funding deposit. */
-  export const FundingDeposit = z
-    .object({
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the deposit was first detected (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:01:00.000Z'] }),
-        ),
-      depositAddressId: Snapshot.shape.depositAddressId,
-      detectionTrigger: z.optional(DetectionTrigger),
-      destinationAmount: Snapshot.shape.destinationAmount,
-      destinationAmountRequired: Snapshot.shape.destinationAmountRequired,
-      destinationChain: Snapshot.shape.destinationChain,
-      destinationToken: Snapshot.shape.destinationToken,
-      destinationTransactionHashes: Snapshot.shape.destinationTransactionHashes,
-      id: z
-        .string()
-        .check(
-          z.regex(/^fdp_[A-Za-z0-9_-]+$/),
-          z.describe('Funding deposit id (`fdp_…`).'),
-          z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-        ),
-      provider: Snapshot.shape.provider,
-      recipient: Snapshot.shape.recipient,
-      refundAddress: Snapshot.shape.refundAddress,
-      refundAmount: Snapshot.shape.refundAmount,
-      refundTransactionHashes: Snapshot.shape.refundTransactionHashes,
-      sender: Snapshot.shape.sender,
-      sourceAmount: Snapshot.shape.sourceAmount,
-      sourceChain: Snapshot.shape.sourceChain,
-      sourceToken: Snapshot.shape.sourceToken,
-      sourceTransactionHashes: Snapshot.shape.sourceTransactionHashes,
-      sourceTransferIndex: z
-        .optional(z.number().check(z.int(), z.minimum(0)))
-        .check(
-          z.describe('Verified transfer position within the source transaction.'),
-          z.meta({ examples: [0] }),
-        ),
-      status: Status,
-      statusReason: z.optional(StatusReason),
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the deposit last materially changed (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:02:00.000Z'] }),
-        ),
-    })
-    .check(z.describe('One detected deposit and its delivery status.'))
+  export const FundingDeposit = OpenApi.component(
+    z
+      .object({
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit was first detected (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:01:00.000Z'] }),
+          ),
+        depositAddressId: Snapshot.shape.depositAddressId,
+        detectionTrigger: z.optional(DetectionTrigger),
+        destinationAmount: Snapshot.shape.destinationAmount,
+        destinationAmountRequired: Snapshot.shape.destinationAmountRequired,
+        destinationChain: Snapshot.shape.destinationChain,
+        destinationToken: Snapshot.shape.destinationToken,
+        destinationTransactionHashes: Snapshot.shape.destinationTransactionHashes,
+        id: z
+          .string()
+          .check(
+            z.regex(/^fdp_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit id (`fdp_…`).'),
+            z.meta({ examples: ['fdp_001785792060000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+        provider: Snapshot.shape.provider,
+        recipient: Snapshot.shape.recipient,
+        refundAddress: Snapshot.shape.refundAddress,
+        refundAmount: Snapshot.shape.refundAmount,
+        refundTransactionHashes: Snapshot.shape.refundTransactionHashes,
+        sender: Snapshot.shape.sender,
+        sourceAmount: Snapshot.shape.sourceAmount,
+        sourceChain: Snapshot.shape.sourceChain,
+        sourceToken: Snapshot.shape.sourceToken,
+        sourceTransactionHashes: Snapshot.shape.sourceTransactionHashes,
+        sourceTransferIndex: z
+          .optional(z.number().check(z.int(), z.minimum(0)))
+          .check(
+            z.describe('Verified transfer position within the source transaction.'),
+            z.meta({ examples: [0] }),
+          ),
+        status: Status,
+        statusReason: z.optional(StatusReason),
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit last materially changed (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:02:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('One detected deposit and its delivery status.')),
+    'FundingDeposit',
+  )
 }
 
 /** Stored public snapshot of a funding deposit. */

package/src/internal/funding/DepositAddress.ts

@@ -3,6 +3,7 @@ import * as z from 'zod/mini'
 import type * as Db from '../../db/Db.js'
 import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.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'
 
@@ -83,51 +84,57 @@ export namespace schema {
     .check(z.describe('Public route and ownership-independent fields of a deposit address.'))
 
   /** One reusable funding deposit address. */
-  export const FundingDepositAddress = z
-    .object({
-      address: Snapshot.shape.address,
-      createdAt: z
-        .string()
-        .check(
-          z.describe('When the deposit address was created (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
-        ),
-      destinationChain: Snapshot.shape.destinationChain,
-      destinationToken: Snapshot.shape.destinationToken,
-      id: z
-        .string()
-        .check(
-          z.regex(/^fda_[A-Za-z0-9_-]+$/),
-          z.describe('Funding deposit address id (`fda_…`).'),
-          z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
-        ),
-      provider: Snapshot.shape.provider,
-      recipient: Snapshot.shape.recipient,
-      refundAddress: Snapshot.shape.refundAddress,
-      sourceChain: Snapshot.shape.sourceChain,
-      sourceToken: Snapshot.shape.sourceToken,
-      status: Status,
-      subsidize: Snapshot.shape.subsidize,
-      updatedAt: z
-        .string()
-        .check(
-          z.describe('When the deposit address last materially changed (ISO 8601).'),
-          z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
-        ),
-    })
-    .check(z.describe('One reusable address for funding a Tempo account.'))
+  export const FundingDepositAddress = OpenApi.component(
+    z
+      .object({
+        address: Snapshot.shape.address,
+        createdAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit address was created (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
+          ),
+        destinationChain: Snapshot.shape.destinationChain,
+        destinationToken: Snapshot.shape.destinationToken,
+        id: z
+          .string()
+          .check(
+            z.regex(/^fda_[A-Za-z0-9_-]+$/),
+            z.describe('Funding deposit address id (`fda_…`).'),
+            z.meta({ examples: ['fda_001785792000000_2ZPE2gvateYEQ0dQslgvkhjx'] }),
+          ),
+        provider: Snapshot.shape.provider,
+        recipient: Snapshot.shape.recipient,
+        refundAddress: Snapshot.shape.refundAddress,
+        sourceChain: Snapshot.shape.sourceChain,
+        sourceToken: Snapshot.shape.sourceToken,
+        status: Status,
+        subsidize: Snapshot.shape.subsidize,
+        updatedAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the deposit address last materially changed (ISO 8601).'),
+            z.meta({ examples: ['2026-08-04T00:00:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('One reusable address for funding a Tempo account.')),
+    'FundingDepositAddress',
+  )
 
   /** A reusable funding deposit address with terms sampled during creation. */
-  export const CreatedFundingDepositAddress = z
-    .object({
-      ...FundingDepositAddress.shape,
-      destinationAmount: Provider.schema.FundingQuote.shape.destinationAmount,
-      destinationAmountMin: Provider.schema.FundingQuote.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,
-    })
-    .check(z.describe('A reusable funding deposit address with current quoted delivery terms.'))
+  export const CreatedFundingDepositAddress = OpenApi.component(
+    z
+      .object({
+        ...FundingDepositAddress.shape,
+        destinationAmount: Provider.schema.FundingQuote.shape.destinationAmount,
+        destinationAmountMin: Provider.schema.FundingQuote.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,
+      })
+      .check(z.describe('A reusable funding deposit address with current quoted delivery terms.')),
+    'CreatedFundingDepositAddress',
+  )
 }
 
 /** Stored public snapshot of a funding deposit address. */

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