tapimo 0.11.0 → 0.13.0

package/src/internal/funding/Transfer.ts

@@ -4,6 +4,7 @@ import type * as Db from '../../db/Db.js'
 import * as FundingTransferEvents from '../../db/tables/fundingTransferEvents.js'
 import * as FundingTransfers from '../../db/tables/fundingTransfers.js'
 import * as Id from '../Id.js'
+import * as OpenApi from '../OpenApi.js'
 import * as Schema from '../Schema.js'
 import * as Action from './Action.js'
 import * as Provider from './Provider.js'
@@ -91,22 +92,25 @@ export namespace schema {
     )
 
   /** Customer-safe explanation of a status that needs context. */
-  export const StatusReason = z
-    .object({
-      code: z
-        .enum(statusReasonCodes)
-        .check(
-          z.describe('Stable machine-readable reason code.'),
-          z.meta({ examples: ['destination_amount_below_minimum'] }),
+  export const StatusReason = OpenApi.component(
+    z
+      .object({
+        code: z
+          .enum(statusReasonCodes)
+          .check(
+            z.describe('Stable machine-readable reason code.'),
+            z.meta({ examples: ['destination_amount_below_minimum'] }),
+          ),
+        message: z.string().check(
+          z.describe('Human-readable explanation of the reason.'),
+          z.meta({
+            examples: ['The verified destination amount did not satisfy the quoted minimum.'],
+          }),
         ),
-      message: z.string().check(
-        z.describe('Human-readable explanation of the reason.'),
-        z.meta({
-          examples: ['The verified destination amount did not satisfy the quoted minimum.'],
-        }),
-      ),
-    })
-    .check(z.describe('Why the transfer is in its current status, when context is needed.'))
+      })
+      .check(z.describe('Why the transfer is in its current status, when context is needed.')),
+    'FundingTransferStatusReason',
+  )
 
   /** Funding method selected at creation. */
   export const Method = z
@@ -122,39 +126,45 @@ export namespace schema {
     )
 
   /** One fee applied to the transfer. */
-  export const Fee = z
-    .object({
-      amount: Schema.TokenAmount,
-      side: z
-        .enum(['destination', 'source'])
-        .check(
-          z.describe('Which side of the transfer the fee is taken from.'),
-          z.meta({ examples: ['destination'] }),
-        ),
-      token: Provider.schema.TokenRef,
-      type: z
-        .enum(['provider'])
-        .check(z.describe('What the fee pays for.'), z.meta({ examples: ['provider'] })),
-    })
-    .check(z.describe('One fee applied to the transfer.'))
+  export const Fee = OpenApi.component(
+    z
+      .object({
+        amount: Schema.TokenAmount,
+        side: z
+          .enum(['destination', 'source'])
+          .check(
+            z.describe('Which side of the transfer the fee is taken from.'),
+            z.meta({ examples: ['destination'] }),
+          ),
+        token: Provider.schema.TokenRef,
+        type: z
+          .enum(['provider'])
+          .check(z.describe('What the fee pays for.'), z.meta({ examples: ['provider'] })),
+      })
+      .check(z.describe('One fee applied to the transfer.')),
+    'FundingTransferFee',
+  )
 
   /** Freshness and validity window of the selected quote. */
-  export const Quote = z
-    .object({
-      expiresAt: z
-        .string()
-        .check(
-          z.describe('When the quoted terms stop being executable (ISO 8601).'),
-          z.meta({ examples: ['2026-07-30T04:01:00.000Z'] }),
-        ),
-      sampledAt: z
-        .string()
-        .check(
-          z.describe('When the provider produced the quote (ISO 8601).'),
-          z.meta({ examples: ['2026-07-30T04:00:00.000Z'] }),
-        ),
-    })
-    .check(z.describe('Freshness and validity window of the selected quote.'))
+  export const Quote = OpenApi.component(
+    z
+      .object({
+        expiresAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the quoted terms stop being executable (ISO 8601).'),
+            z.meta({ examples: ['2026-07-30T04:01:00.000Z'] }),
+          ),
+        sampledAt: z.iso
+          .datetime()
+          .check(
+            z.describe('When the provider produced the quote (ISO 8601).'),
+            z.meta({ examples: ['2026-07-30T04:00:00.000Z'] }),
+          ),
+      })
+      .check(z.describe('Freshness and validity window of the selected quote.')),
+    'FundingTransferQuote',
+  )
 
   const hashesCheck = (description: string) => [
     z.describe(description),
@@ -219,8 +229,8 @@ export namespace schema {
     .check(z.describe('Quote terms and reconciled public fields of a funding transfer.'))
 
   const fundingTransferFields = {
-    createdAt: z
-      .string()
+    createdAt: z.iso
+      .datetime()
       .check(
         z.describe('When the transfer was created (ISO 8601).'),
         z.meta({ examples: ['2026-07-30T04:00:00.000Z'] }),
@@ -253,8 +263,8 @@ export namespace schema {
     sourceTransactionHashes: snapshotFields.sourceTransactionHashes,
     status: Status,
     statusReason: z.optional(StatusReason),
-    updatedAt: z
-      .string()
+    updatedAt: z.iso
+      .datetime()
       .check(
         z.describe('When the transfer last materially changed (ISO 8601).'),
         z.meta({ examples: ['2026-07-30T04:00:20.000Z'] }),
@@ -270,73 +280,86 @@ export namespace schema {
   }
 
   /** A funding transfer as returned by reads. Reads never include `action`. */
-  export const FundingTransfer = z
-    .object(fundingTransferFields)
-    .check(z.describe('One durable funding transfer.'))
+  export const FundingTransfer = OpenApi.component(
+    z.object(fundingTransferFields).check(z.describe('One durable funding transfer.')),
+    'FundingTransfer',
+  )
 
   /** A created funding transfer: the read shape plus the executable action. */
-  export const CreatedFundingTransfer = z
-    .object({ action: Action.schema.Action, ...fundingTransferFields })
-    .check(z.describe('The created funding transfer, including its one-time executable action.'))
+  export const CreatedFundingTransfer = OpenApi.component(
+    z
+      .object({ action: Action.schema.Action, ...fundingTransferFields })
+      .check(z.describe('The created funding transfer, including its one-time executable action.')),
+    'CreatedFundingTransfer',
+  )
 
   /** Request body accepted by funding transfer creation. */
-  export const CreateRequest = z
-    .strictObject({
-      amount: z
-        .string()
-        .check(
-          z.regex(/^[1-9]\d*$/),
-          z.describe('Amount in base units of the token the mode fixes.'),
-          z.meta({ examples: ['1000000'] }),
-        ),
-      destinationToken: z
-        .string()
-        .check(
-          z.minLength(1),
-          z.describe('Tempo destination token symbol, contract address, or token key.'),
-          z.meta({ examples: ['pathusd'] }),
-        ),
-      mode: Mode,
-      recipient: z
-        .string()
-        .check(
-          z.regex(/^0x[0-9a-fA-F]{40}$/),
-          z.describe('Final beneficiary of the transfer.'),
-          z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
-        ),
-      sender: z
-        .string()
-        .check(
-          z.regex(/^0x[0-9a-fA-F]{40}$/),
-          z.describe('Source-chain account that signs the funding action.'),
-          z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
-        ),
-      slippageBps: z.optional(
-        z
-          .number()
+  export const CreateRequest = OpenApi.component(
+    z
+      .strictObject({
+        amount: z
+          .string()
           .check(
-            z.int(),
-            z.gte(0),
-            z.lte(10_000),
-            z.describe('Maximum acceptable slippage in basis points.'),
-            z.meta({ examples: [50] }),
+            z.regex(/^[1-9]\d*$/),
+            z.describe('Amount in base units of the token the mode fixes.'),
+            z.meta({ examples: ['1000000'] }),
           ),
-      ),
-      sourceChain: z
-        .string()
-        .check(
-          z.describe('Source chain CAIP-2 id, slug, or alias.'),
-          z.meta({ examples: ['base', 'eip155:8453'] }),
-        ),
-      sourceToken: z
-        .string()
-        .check(
-          z.minLength(1),
-          z.describe('Source token symbol, contract address, or token key.'),
-          z.meta({ examples: ['usdc'] }),
+        destinationToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Tempo destination token symbol, contract address, or token key.'),
+            z.meta({ examples: ['pathusd'] }),
+          ),
+        mode: Mode,
+        provider: z
+          .optional(z.string().check(z.minLength(1)))
+          .check(
+            z.describe('Funding provider ID. Omit to select the best available provider.'),
+            z.meta({ examples: ['relay'] }),
+          ),
+        recipient: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Final beneficiary of the transfer.'),
+            z.meta({ examples: [`0x${'11'.repeat(20)}`] }),
+          ),
+        sender: z
+          .string()
+          .check(
+            z.regex(/^0x[0-9a-fA-F]{40}$/),
+            z.describe('Source-chain account that signs the funding action.'),
+            z.meta({ examples: [`0x${'22'.repeat(20)}`] }),
+          ),
+        slippageBps: z.optional(
+          z
+            .number()
+            .check(
+              z.int(),
+              z.gte(0),
+              z.lte(10_000),
+              z.describe('Maximum acceptable slippage in basis points.'),
+              z.meta({ examples: [50] }),
+            ),
         ),
-    })
-    .check(z.describe('Funding transfer creation request.'))
+        sourceChain: z
+          .string()
+          .check(
+            z.describe('Source chain CAIP-2 id, slug, or alias.'),
+            z.meta({ examples: ['base', 'eip155:8453'] }),
+          ),
+        sourceToken: z
+          .string()
+          .check(
+            z.minLength(1),
+            z.describe('Source token symbol, contract address, or token key.'),
+            z.meta({ examples: ['usdc'] }),
+          ),
+      })
+      .check(z.describe('Funding transfer creation request.')),
+    'CreateFundingTransferRequest',
+  )
 }
 
 /** Stored public snapshot of a funding transfer (see {@link schema.Snapshot}). */

package/src/internal/funding/providers/index.test.ts

@@ -4,6 +4,7 @@ import * as Across from './across.js'
 import * as Relay from './relay.js'
 import * as Rhino from './rhino.js'
 import * as Squid from './squid.js'
+import * as Stargate from './stargate.js'
 import * as Symbiosis from './symbiosis.js'
 
 const now = () => new Date('2026-01-01T00:00:00.000Z')
@@ -21,6 +22,7 @@ const providers = [
     integratorId: 'squid-integrator-id',
     userAddress: '0x1111111111111111111111111111111111111111',
   }),
+  Stargate.stargate(),
   Symbiosis.symbiosis({ userAddress: '0x1111111111111111111111111111111111111111' }),
 ] as const
 
@@ -335,6 +337,12 @@ describe('funding providers', () => {
     })
   })
 
+  test('exposes Base and Ethereum Stargate quote candidates', () => {
+    expect(
+      ['base', 'ethereum'].map((sourceChain) => quoteCandidate('stargate', { sourceChain }).id),
+    ).toEqual(['base-usdc-tempo-usdce-stargate', 'ethereum-usdc-tempo-usdce-stargate'])
+  })
+
   test('maps successful Symbiosis quotes to available quote results', async () => {
     const requests: RecordedRequest[] = []
     const candidate = quoteCandidate('symbiosis')
@@ -961,6 +969,20 @@ describe('funding providers', () => {
     })
   })
 
+  test('returns bounded Stargate failure diagnostics', () => {
+    expect(
+      FundingProvider.failure({
+        cause: new TypeError('network failure'),
+        operation: 'getQuote',
+        provider: getProvider('stargate'),
+      }),
+    ).toEqual({
+      failure: 'network',
+      id: 'stargate',
+      operation: 'getQuote',
+    })
+  })
+
   test('returns bounded Symbiosis failure diagnostics', () => {
     expect(
       FundingProvider.failure({

package/src/internal/funding/providers/relay.test.ts

@@ -147,8 +147,8 @@ describe.skipIf(!apiKey)('relay.prepareTransfer (live)', () => {
       expect(call.data).toMatch(/^0x[0-9a-fA-F]*$/)
       expect(call.value).toBe('0x0')
     }
-    expect(result.correlation.requestId).toMatch(/^0x[0-9a-f]{64}$/)
-    expect(result.correlation.checkEndpoint).toContain('/intents/status/v3')
+    expect(result.correlation?.requestId).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(result.correlation?.checkEndpoint).toContain('/intents/status/v3')
     expect(BigInt(result.destinationAmount) > 0n).toBe(true)
     expect(BigInt(result.destinationAmountMin) > 0n).toBe(true)
     expect(BigInt(result.destinationAmountMin) <= BigInt(result.destinationAmount)).toBe(true)

package/src/internal/funding/providers/stargate.test.ts

@@ -0,0 +1,163 @@
+import { AbiFunction, Hex } from 'ox'
+
+import type * as Action from '../Action.js'
+import type * as Catalog from '../Catalog.js'
+import * as FundingProvider from '../Provider.js'
+import * as Stargate from './stargate.js'
+
+const amount = 1_000_000n
+const destinationToken = '0x20C000000000000000000000b9537d11c60E8b50'
+const nativeFee = 10_000n
+const otherAddress = '0x9999999999999999999999999999999999999999'
+const pool = '0x27a16dc786820B16E5c9028b75B99F6f604b5d26'
+const recipient = '0x1111111111111111111111111111111111111111'
+const sender = '0x2222222222222222222222222222222222222222'
+const sourceToken = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
+
+const approve = AbiFunction.from('function approve(address spender, uint256 amount)')
+const sendToken = AbiFunction.from(
+  'function sendToken((uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd) sendParam, (uint256 nativeFee, uint256 lzTokenFee) fee, address refundAddress) payable returns ((bytes32 guid, uint64 nonce, (uint256 nativeFee, uint256 lzTokenFee) fee) msgReceipt, (uint256 amountSentLD, uint256 amountReceivedLD) oftReceipt, (uint72 ticketId, bytes passengerBytes) ticket)',
+)
+
+describe('stargate', () => {
+  test('creates a credential-free quote and transfer provider', () => {
+    expect(Stargate.stargate()).toMatchObject({
+      getQuote: expect.any(Function),
+      id: 'stargate',
+      name: 'Stargate',
+      prepareTransfer: expect.any(Function),
+    })
+  })
+})
+
+describe('validateAction', () => {
+  test('accepts the exact approval and Taxi send calls', () => {
+    expect(validate(action())).toEqual([{ to: pool, value: Hex.fromNumber(nativeFee) }])
+  })
+
+  test('rejects calls outside the curated Stargate route', () => {
+    const invalid = [
+      action({ approvalAmount: amount + 1n }),
+      action({ approvalSpender: otherAddress }),
+      action({ composeMsg: '0x01' }),
+      action({ destinationEid: 1 }),
+      action({ executionTarget: otherAddress }),
+      action({ extraOptions: '0x01' }),
+      action({ lzTokenFee: 1n }),
+      action({ minimumAmount: amount - 1n }),
+      action({ oftCmd: '0x01' }),
+      action({ recipient: otherAddress }),
+      action({ refundAddress: otherAddress }),
+      action({ sourceAmount: amount + 1n }),
+    ]
+    for (const candidate of invalid)
+      expect(() => validate(candidate)).toThrowError(FundingProvider.ProviderPayloadError)
+    expect(() => validate(action(), { sourceTokenAddress: otherAddress })).toThrowError(
+      FundingProvider.ProviderPayloadError,
+    )
+    expect(() => validate(action(), { destinationTokenAddress: otherAddress })).toThrowError(
+      FundingProvider.ProviderPayloadError,
+    )
+  })
+
+  test('rejects malformed selectors and mismatched native value', () => {
+    const malformed = action()
+    malformed.calls[1]!.data = '0xdeadbeef'
+    expect(() => validate(malformed)).toThrowError(FundingProvider.ProviderPayloadError)
+
+    const mismatched = action()
+    mismatched.calls[1]!.value = Hex.fromNumber(nativeFee + 1n)
+    expect(() => validate(mismatched)).toThrowError(FundingProvider.ProviderPayloadError)
+  })
+
+  test('rejects missing or mismatched route configuration', () => {
+    expect(() =>
+      Stargate.validateAction({
+        action: action(),
+        destinationTokenAddress: destinationToken,
+        recipient,
+        sender,
+        sourceAmount: amount.toString(),
+        sourceChainId: 'eip155:8453',
+        sourceTokenAddress: sourceToken,
+      }),
+    ).toThrowError(FundingProvider.ProviderPayloadError)
+    expect(() => validate(action(), { configuration: { poolAddress: otherAddress } })).toThrowError(
+      FundingProvider.ProviderPayloadError,
+    )
+  })
+})
+
+function action(options: action.Options = {}): Action.EvmCalls {
+  const executionFee = options.nativeFee ?? nativeFee
+  const sendParam = {
+    amountLD: options.sourceAmount ?? amount,
+    composeMsg: options.composeMsg ?? '0x',
+    dstEid: options.destinationEid ?? 30_410,
+    extraOptions: options.extraOptions ?? '0x',
+    minAmountLD: options.minimumAmount ?? amount,
+    oftCmd: options.oftCmd ?? '0x',
+    to: Hex.padLeft(options.recipient ?? recipient, 32),
+  } as const
+  return {
+    calls: [
+      {
+        data: AbiFunction.encodeData(approve, [
+          options.approvalSpender ?? pool,
+          options.approvalAmount ?? amount,
+        ]),
+        to: sourceToken,
+        value: '0x0',
+      },
+      {
+        data: AbiFunction.encodeData(sendToken, [
+          sendParam,
+          { lzTokenFee: options.lzTokenFee ?? 0n, nativeFee: executionFee },
+          options.refundAddress ?? sender,
+        ]),
+        to: options.executionTarget ?? pool,
+        value: Hex.fromNumber(executionFee),
+      },
+    ],
+    type: 'evm:calls',
+  }
+}
+
+declare namespace action {
+  type Options = {
+    approvalAmount?: bigint | undefined
+    approvalSpender?: `0x${string}` | undefined
+    composeMsg?: Hex.Hex | undefined
+    destinationEid?: number | undefined
+    executionTarget?: `0x${string}` | undefined
+    extraOptions?: Hex.Hex | undefined
+    lzTokenFee?: bigint | undefined
+    minimumAmount?: bigint | undefined
+    nativeFee?: bigint | undefined
+    oftCmd?: Hex.Hex | undefined
+    recipient?: Hex.Hex | undefined
+    refundAddress?: `0x${string}` | undefined
+    sourceAmount?: bigint | undefined
+  }
+}
+
+function validate(candidate: Action.EvmCalls, options: validate.Options = {}) {
+  return Stargate.validateAction({
+    action: candidate,
+    configuration: options.configuration ?? { poolAddress: pool },
+    destinationTokenAddress: options.destinationTokenAddress ?? destinationToken,
+    recipient,
+    sender,
+    sourceAmount: amount.toString(),
+    sourceChainId: 'eip155:8453',
+    sourceTokenAddress: options.sourceTokenAddress ?? sourceToken,
+  })
+}
+
+declare namespace validate {
+  type Options = {
+    configuration?: Catalog.Configuration | undefined
+    destinationTokenAddress?: string | undefined
+    sourceTokenAddress?: string | undefined
+  }
+}