tapimo 0.11.0 → 0.13.0

package/src/internal/funding/Provider.ts

@@ -2,6 +2,7 @@ import { Address, Base58, Bytes, Hash, Value as core_Value } from 'ox'
 import * as z from 'zod/mini'
 
 import * as core_Provider from '../Provider.js'
+import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
 import * as Value from '../Value.js'
 import * as Action from './Action.js'
@@ -42,85 +43,97 @@ export namespace schema {
   export const PositiveInteger = z.string().check(z.regex(/^(?=.*[1-9])\d+$/))
 
   /** Normalized chain reference passed to funding providers. */
-  export const ChainRef = Schema.describe(
-    z.object({
-      addressFormat: z
-        .enum(['base58', 'base58check', 'hex'])
-        .check(
-          z.describe('Address encoding used by accounts and token identifiers on this chain.'),
-          z.meta({ examples: ['hex'] }),
-        ),
-      id: z.string().check(z.describe('CAIP-2 chain id.'), z.meta({ examples: ['eip155:8453'] })),
-      kind: z
-        .enum(['evm', 'solana', 'tron'])
-        .check(
-          z.describe('Chain execution family used for provider routing.'),
-          z.meta({ examples: ['evm'] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable chain name.'), z.meta({ examples: ['Base'] })),
-    }),
-    'A normalized chain reference for funding quotes.',
+  export const ChainRef = OpenApi.component(
+    Schema.describe(
+      z.object({
+        addressFormat: z
+          .enum(['base58', 'base58check', 'hex'])
+          .check(
+            z.describe('Address encoding used by accounts and token identifiers on this chain.'),
+            z.meta({ examples: ['hex'] }),
+          ),
+        id: z.string().check(z.describe('CAIP-2 chain id.'), z.meta({ examples: ['eip155:8453'] })),
+        kind: z
+          .enum(['evm', 'solana', 'tron'])
+          .check(
+            z.describe('Chain execution family used for provider routing.'),
+            z.meta({ examples: ['evm'] }),
+          ),
+        name: z
+          .string()
+          .check(z.describe('Human-readable chain name.'), z.meta({ examples: ['Base'] })),
+      }),
+      'A normalized chain reference for funding quotes.',
+    ),
+    'FundingChain',
   )
 
   /** Normalized token reference passed to funding providers. */
-  export const TokenRef = Schema.describe(
-    z.object({
-      address: z
-        .string()
-        .check(
-          z.describe('Contract address, mint, or issuer address on the token chain.'),
-          z.meta({ examples: ['0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
-        ),
-      currency: z
-        .string()
-        .check(
-          z.describe('Monetary denomination represented by this token.'),
-          z.meta({ examples: ['USD'] }),
-        ),
-      decimals: z
-        .number()
-        .check(
-          z.int(),
-          z.gte(0),
-          z.describe('Number of decimal places this token uses.'),
-          z.meta({ examples: [6] }),
-        ),
-      name: z
-        .string()
-        .check(z.describe('Human-readable token name.'), z.meta({ examples: ['USD Coin'] })),
-      standard: z
-        .string()
-        .check(z.describe('Token standard on the token chain.'), z.meta({ examples: ['ERC-20'] })),
-      symbol: z
-        .string()
-        .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDC'] })),
-      tokenKey: z.string().check(
-        z.describe('Stable Tempo token key scoped to the token chain.'),
-        z.meta({
-          examples: ['eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'],
-        }),
-      ),
-      verified: z
-        .boolean()
-        .check(
-          z.describe('Whether Tempo recognizes this token in its funding quote inventory.'),
-          z.meta({ examples: [true] }),
+  export const TokenRef = OpenApi.component(
+    Schema.describe(
+      z.object({
+        address: z
+          .string()
+          .check(
+            z.describe('Contract address, mint, or issuer address on the token chain.'),
+            z.meta({ examples: ['0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'] }),
+          ),
+        currency: z
+          .string()
+          .check(
+            z.describe('Monetary denomination represented by this token.'),
+            z.meta({ examples: ['USD'] }),
+          ),
+        decimals: z
+          .number()
+          .check(
+            z.int(),
+            z.gte(0),
+            z.describe('Number of decimal places this token uses.'),
+            z.meta({ examples: [6] }),
+          ),
+        name: z
+          .string()
+          .check(z.describe('Human-readable token name.'), z.meta({ examples: ['USD Coin'] })),
+        standard: z
+          .string()
+          .check(
+            z.describe('Token standard on the token chain.'),
+            z.meta({ examples: ['ERC-20'] }),
+          ),
+        symbol: z
+          .string()
+          .check(z.describe('Short token ticker symbol.'), z.meta({ examples: ['USDC'] })),
+        tokenKey: z.string().check(
+          z.describe('Stable Tempo token key scoped to the token chain.'),
+          z.meta({
+            examples: ['eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'],
+          }),
         ),
-    }),
-    'A normalized token reference for funding quotes.',
+        verified: z
+          .boolean()
+          .check(
+            z.describe('Whether Tempo recognizes this token in its funding quote inventory.'),
+            z.meta({ examples: [true] }),
+          ),
+      }),
+      'A normalized token reference for funding quotes.',
+    ),
+    'FundingToken',
   )
 
   /** Provider identity embedded in funding resources. */
-  export const ProviderRef = Schema.describe(
-    z.object({
-      id: z.string().check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
-      name: z
-        .string()
-        .check(z.describe('Human-readable provider name.'), z.meta({ examples: ['Relay'] })),
-    }),
-    'Provider metadata embedded in a funding quote.',
+  export const ProviderRef = OpenApi.component(
+    Schema.describe(
+      z.object({
+        id: z.string().check(z.describe('Stable provider id.'), z.meta({ examples: ['relay'] })),
+        name: z
+          .string()
+          .check(z.describe('Human-readable provider name.'), z.meta({ examples: ['Relay'] })),
+      }),
+      'Provider metadata embedded in a funding quote.',
+    ),
+    'FundingProvider',
   )
 
   /** Source amount unit accepted by a funding quote request. */
@@ -203,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()),
@@ -214,6 +229,7 @@ export namespace schema {
       z.object({
         amount: Schema.DecimalString,
         side: z.enum(['destination', 'source']),
+        token: z.optional(TokenRef),
       }),
     ),
     quality: GetQuoteResult.shape.quality,
@@ -264,84 +280,93 @@ export namespace schema {
   })
 
   /** Quote quality signals exposed to funding API callers. */
-  export const FundingQuoteQuality = Schema.describe(
-    z.object({
-      estimatedSeconds: z
-        .optional(z.number().check(z.int(), z.nonnegative()))
-        .check(
-          z.describe('Estimated settlement time in seconds, when known.'),
-          z.meta({ examples: [2] }),
-        ),
-      liquiditySource: z
-        .string()
-        .check(
-          z.describe('Provider source for the live quote quality signal.'),
-          z.meta({ examples: ['providerQuote'] }),
-        ),
-      sourceDetail: z
-        .optional(z.string())
-        .check(
-          z.describe('Provider-specific source or endpoint detail for the quality signal.'),
-          z.meta({ examples: ['providerEndpoint'] }),
-        ),
-      tier: z
-        .enum(['liquid', 'thin'])
-        .check(
-          z.describe('Machine-readable quote quality tier for a successful quote.'),
-          z.meta({ examples: ['liquid'] }),
-        ),
-    }),
-    'Machine-readable liquidity, fee, and source signals for a successful quote.',
+  export const FundingQuoteQuality = OpenApi.component(
+    Schema.describe(
+      z.object({
+        estimatedSeconds: z
+          .optional(z.number().check(z.int(), z.nonnegative()))
+          .check(
+            z.describe('Estimated settlement time in seconds, when known.'),
+            z.meta({ examples: [2] }),
+          ),
+        liquiditySource: z
+          .string()
+          .check(
+            z.describe('Provider source for the live quote quality signal.'),
+            z.meta({ examples: ['providerQuote'] }),
+          ),
+        sourceDetail: z
+          .optional(z.string())
+          .check(
+            z.describe('Provider-specific source or endpoint detail for the quality signal.'),
+            z.meta({ examples: ['providerEndpoint'] }),
+          ),
+        tier: z
+          .enum(['liquid', 'thin'])
+          .check(
+            z.describe('Machine-readable quote quality tier for a successful quote.'),
+            z.meta({ examples: ['liquid'] }),
+          ),
+      }),
+      'Machine-readable liquidity, fee, and source signals for a successful quote.',
+    ),
+    'FundingQuoteQuality',
   )
 
   /** Provider quote freshness data exposed to funding API callers. */
-  export const QuoteDetails = Schema.describe(
-    z.object({
-      expiresAt: z
-        .optional(z.iso.datetime())
-        .check(
-          z.describe('Timestamp after which the provider quote is no longer valid.'),
-          z.meta({ examples: ['2026-01-01T00:01:00Z'] }),
-        ),
-      sampledAt: z.iso
-        .datetime()
-        .check(
-          z.describe('Timestamp for the live quote request.'),
-          z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
-        ),
-    }),
-    'Freshness data for a provider funding quote.',
+  export const QuoteDetails = OpenApi.component(
+    Schema.describe(
+      z.object({
+        expiresAt: z
+          .optional(z.iso.datetime())
+          .check(
+            z.describe('Timestamp after which the provider quote is no longer valid.'),
+            z.meta({ examples: ['2026-01-01T00:01:00Z'] }),
+          ),
+        sampledAt: z.iso
+          .datetime()
+          .check(
+            z.describe('Timestamp for the live quote request.'),
+            z.meta({ examples: ['2026-01-01T00:00:00Z'] }),
+          ),
+      }),
+      'Freshness data for a provider funding quote.',
+    ),
+    'FundingQuoteDetails',
   )
 
   /** Successful normalized funding quote returned to callers. */
-  export const FundingQuote = Schema.describe(
-    z.object({
-      destinationAmount: Schema.TokenAmount.check(z.describe('Expected destination amount.')),
-      destinationAmountMin: z
-        .optional(Schema.TokenAmount)
-        .check(
-          z.describe(
-            'Provider-derived minimum destination amount. Symbiosis and Squid quotes use a fixed 1% slippage tolerance.',
+  export const FundingQuote = OpenApi.component(
+    Schema.describe(
+      z.object({
+        destinationAmount: Schema.TokenAmount.check(z.describe('Expected destination amount.')),
+        destinationAmountMin: z
+          .optional(Schema.TokenAmount)
+          .check(
+            z.describe(
+              'Provider-derived minimum destination amount. Symbiosis and Squid quotes use a fixed 1% slippage tolerance.',
+            ),
           ),
+        destinationChain: ChainRef.check(
+          z.describe('Destination chain, always Tempo mainnet in V1.'),
         ),
-      destinationChain: ChainRef.check(
-        z.describe('Destination chain, always Tempo mainnet in V1.'),
-      ),
-      destinationToken: TokenRef.check(z.describe('Tempo token expected from this quote.')),
-      id: z
-        .string()
-        .check(
-          z.describe('Stable deterministic funding quote id.'),
-          z.meta({ examples: ['base-usdc-tempo-usdce-relay'] }),
-        ),
-      provider: ProviderRef,
-      quality: FundingQuoteQuality,
-      quote: QuoteDetails,
-      sourceAmount: Schema.TokenAmount,
-      sourceChain: ChainRef.check(z.describe('Chain where the caller currently holds funds.')),
-      sourceToken: TokenRef.check(z.describe('Token the caller currently holds.')),
-    }),
-    'One successful provider-specific funding quote.',
+        destinationToken: TokenRef.check(z.describe('Tempo token expected from this quote.')),
+        id: z
+          .string()
+          .check(
+            z.describe('Stable deterministic funding quote id.'),
+            z.meta({ examples: ['base-usdc-tempo-usdce-relay'] }),
+          ),
+        provider: ProviderRef,
+        quality: FundingQuoteQuality,
+        quote: QuoteDetails,
+        sourceAmount: Schema.TokenAmount,
+        sourceChain: ChainRef.check(z.describe('Chain where the caller currently holds funds.')),
+        sourceToken: TokenRef.check(z.describe('Token the caller currently holds.')),
+      }),
+      'One successful provider-specific funding quote.',
+    ),
+    'FundingQuote',
   )
 }
 
@@ -445,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. */
@@ -661,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
 }
@@ -930,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,
@@ -1102,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,
           ),
         )
@@ -1138,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,
             })
@@ -1253,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,
+      },
     ]
   })
 }
@@ -1286,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 []
@@ -1293,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,
@@ -1327,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. */
@@ -1550,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),
@@ -1561,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: [
@@ -1586,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()
 }
@@ -1785,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 })),
   )
 }