tapimo 0.12.0 → 0.14.0

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,8 +229,10 @@ export namespace schema {
       z.object({
         amount: Schema.DecimalString,
         side: z.enum(['destination', 'source']),
+        token: z.optional(TokenRef),
       }),
     ),
+    providerState: z.optional(z.record(z.string(), z.unknown())),
     quality: GetQuoteResult.shape.quality,
     sampledAt: z.iso.datetime(),
   })
@@ -467,6 +471,51 @@ 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 for provider-specific source transaction verification. */
+export declare namespace verifySourceTransaction {
+  /** Stored transfer terms and submitted source transaction. */
+  type Parameters = {
+    /** Configured chain that receives the provider delivery. */
+    destinationChain: Chain
+    /** Private provider state captured while preparing the transfer. */
+    providerState?: Transfer.ProviderState | undefined
+    /** Current configuration for the stored provider route. */
+    routeConfiguration?: core_Catalog.Configuration | undefined
+    /** Configured chain containing the submitted transaction. */
+    sourceChain: Chain
+    /** Submitted transaction reference. */
+    transactionHash: string
+    /** Stored public transfer terms. */
+    transfer: Transfer.Snapshot
+  }
+
+  /** Source transaction verification outcome. */
+  type ReturnType =
+    | { type: 'invalid' }
+    | { type: 'pending' }
+    | {
+        /** Private provider evidence retained for reconciliation. */
+        providerState?: Transfer.ProviderState | undefined
+        /** The transaction matches the stored transfer terms. */
+        type: 'verified'
+      }
+}
+
 /** Contract of the provider `createDepositAddress` method. */
 export declare namespace createDepositAddress {
   /** Input passed to a provider provisioning one reusable deposit address. */
@@ -683,6 +732,15 @@ 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
+  /** Verifies a submitted source transaction, when supported. */
+  verifySourceTransaction?(
+    input: verifySourceTransaction.Parameters,
+    signal: AbortSignal,
+  ): Promise<verifySourceTransaction.ReturnType>
   /** Receives authenticated provider status events, when configured. */
   webhook?: Webhook | undefined
 }
@@ -734,6 +792,13 @@ export function canObserveDepositAddressRequest(provider: Provider): provider is
   return typeof provider.observeDepositAddressRequest === 'function'
 }
 
+/** Narrows a funding provider to one that verifies submitted source transactions. */
+export function canVerifySourceTransaction(provider: Provider): provider is Provider & {
+  verifySourceTransaction: NonNullable<Provider['verifySourceTransaction']>
+} {
+  return typeof provider.verifySourceTransaction === 'function'
+}
+
 /** Narrows a funding provider to one with authenticated webhook receipt. */
 export function canReceiveWebhook(provider: Provider): provider is Provider & {
   webhook: Webhook
@@ -952,6 +1017,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 +1190,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 +1223,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 +1343,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 +1383,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 +1393,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 +1429,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 +1654,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 +1666,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 +1694,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 +1904,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 })),
   )
 }
 

package/src/internal/funding/SourceObservation.ts

@@ -1,10 +1,10 @@
-import { AbiEvent, Address, RpcTransport } from 'ox'
-import { createClient, custom, fallback } from 'viem'
+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 Viem from '../Viem.js'
 import * as Value from '../Value.js'
 import * as Deposit from './Deposit.js'
 
@@ -52,13 +52,9 @@ export async function scan(options: scan.Options): Promise<scan.Result> {
     throw new ConfigurationError('source token address')
   if (options.rpcUrls.length === 0) throw new ConfigurationError('source RPC URL')
 
-  const client = createClient({
-    transport: fallback(
-      options.rpcUrls.map((url) => {
-        const transport = RpcTransport.fromHttp(url, { fetchFn: options.fetch ?? globalThis.fetch })
-        return custom(transport, { retryCount: 0 })
-      }),
-    ),
+  const client = Viem.createEvmClient({
+    fetch: options.fetch ?? globalThis.fetch,
+    urls: options.rpcUrls,
   })
   const head = await getBlockNumber(client, { cacheTime: 0 })
   const confirmations = BigInt(options.confirmations ?? defaultConfirmations)

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

@@ -42,6 +42,7 @@ describe('canTransition', () => {
         "completed": [],
         "expired": [],
         "processing": [
+          "awaiting-source",
           "refunding",
           "completed",
           "action-required",
@@ -129,6 +130,160 @@ describe('create', () => {
   })
 })
 
+describe('registerSourceTransaction', () => {
+  const transactionHash = `0x${'a2'.repeat(32)}`
+
+  test('atomically assigns source evidence and starts reconciliation', async () => {
+    const record = await Transfer.create(
+      db,
+      createInput({
+        providerState: {
+          routeConfiguration: {
+            destinationPoolAddress: `0x${'cc'.repeat(20)}`,
+            poolAddress: `0x${'dd'.repeat(20)}`,
+            sourceEid: 30_184,
+          },
+        },
+        snapshot: TestFunding.transferSnapshot({ provider: { id: 'stargate', name: 'Stargate' } }),
+      }),
+    )
+    vi.setSystemTime(new Date('2026-01-01T00:00:10.000Z'))
+    const result = await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { stargate: { guid: `0x${'bb'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash: `0x${'a1'.repeat(32)}`,
+    })
+    expect(result.type).toBe('registered')
+    if (result.type !== 'registered') return
+    expect({
+      providerState: result.record.providerState,
+      sourceTransactionHashes: result.record.snapshot.sourceTransactionHashes,
+      status: result.record.status,
+      version: result.record.version,
+    }).toMatchInlineSnapshot(`
+      {
+        "providerState": {
+          "routeConfiguration": {
+            "destinationPoolAddress": "0xcccccccccccccccccccccccccccccccccccccccc",
+            "poolAddress": "0xdddddddddddddddddddddddddddddddddddddddd",
+            "sourceEid": 30184,
+          },
+          "stargate": {
+            "guid": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+            "sourceEid": 30184,
+          },
+        },
+        "sourceTransactionHashes": [
+          "0xa1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
+        ],
+        "status": "processing",
+        "version": 2,
+      }
+    `)
+  })
+
+  test('replays the same assignment and rejects reuse by another transfer', async () => {
+    const first = await Transfer.create(db, createInput())
+    const second = await Transfer.create(db, createInput())
+    const options = {
+      chainId: 'eip155:8453',
+      id: first.id,
+      providerState: { stargate: { guid: `0x${'bb'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash,
+    }
+    await Transfer.registerSourceTransaction(db, options)
+    const replayed = await Transfer.registerSourceTransaction(db, options)
+    const conflict = await Transfer.registerSourceTransaction(db, { ...options, id: second.id })
+    expect({
+      conflict: conflict.type,
+      replayed: replayed.type,
+      replayedVersion: replayed.type === 'replayed' ? replayed.record.version : undefined,
+    }).toEqual({ conflict: 'conflict', replayed: 'replayed', replayedVersion: 2 })
+  })
+})
+
+describe('reopenSourceTransaction', () => {
+  test('removes invalidated source evidence and accepts a replacement', async () => {
+    const record = await Transfer.create(db, createInput())
+    const transactionHash = `0x${'a4'.repeat(32)}`
+    await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { stargate: { guid: `0x${'bb'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash,
+    })
+
+    const reopened = await Transfer.reopenSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { routeConfiguration: { poolAddress: `0x${'cc'.repeat(20)}` } },
+      transactionHash: transactionHash.toUpperCase(),
+    })
+    expect(reopened.type).toBe('reopened')
+    if (reopened.type !== 'reopened') return
+    expect({
+      providerState: reopened.record.providerState,
+      sourceTransactionHashes: reopened.record.snapshot.sourceTransactionHashes,
+      status: reopened.record.status,
+      version: reopened.record.version,
+    }).toEqual({
+      providerState: { routeConfiguration: { poolAddress: `0x${'cc'.repeat(20)}` } },
+      sourceTransactionHashes: undefined,
+      status: 'awaiting-source',
+      version: 3,
+    })
+
+    const replacement = await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { stargate: { guid: `0x${'dd'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash: `0x${'a5'.repeat(32)}`,
+    })
+    expect(replacement.type).toBe('registered')
+  })
+})
+
+describe('complete', () => {
+  test('records verified destination evidence and completes once', async () => {
+    const record = await Transfer.create(db, createInput())
+    await Transfer.registerSourceTransaction(db, {
+      chainId: 'eip155:8453',
+      id: record.id,
+      providerState: { stargate: { guid: `0x${'bb'.repeat(32)}`, sourceEid: 30_184 } },
+      transactionHash: `0x${'a3'.repeat(32)}`,
+    })
+    const options = {
+      chainId: 'eip155:4217',
+      destinationAmount: TestFunding.transferSnapshot().destinationAmount!,
+      id: record.id,
+      transactionHash: `0x${'cc'.repeat(32)}`,
+    }
+    const completed = await Transfer.complete(db, options)
+    const replayed = await Transfer.complete(db, options)
+    expect({
+      completed: completed.type,
+      destinationTransactionHashes:
+        completed.type === 'completed'
+          ? completed.record.snapshot.destinationTransactionHashes
+          : undefined,
+      replayed: replayed.type,
+      status: completed.type === 'completed' ? completed.record.status : undefined,
+      version: completed.type === 'completed' ? completed.record.version : undefined,
+    }).toMatchInlineSnapshot(`
+      {
+        "completed": "completed",
+        "destinationTransactionHashes": [
+          "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+        ],
+        "replayed": "replayed",
+        "status": "completed",
+        "version": 3,
+      }
+    `)
+  })
+})
+
 describe('transition', () => {
   test('applies a guarded status change and appends an event', async () => {
     const record = await Transfer.create(db, createInput())