tapimo 0.15.0 → 0.18.0

package/src/internal/routes/Action.ts

@@ -2,6 +2,7 @@ import { AbiFunction, Address, type Hex, Solidity } from 'ox'
 import * as z from 'zod/mini'
 
 import * as OpenApi from '../OpenApi.js'
+import * as Tron from '../Tron.js'
 
 /**
  * Executable source-chain actions returned by route transfer creation. A
@@ -59,10 +60,46 @@ export namespace schema {
     'RoutesEvmCallsAction',
   )
 
+  /** Ordered unsigned Tron calls, with native values expressed in SUN. */
+  export const TronCalls = OpenApi.component(
+    z
+      .object({
+        calls: z
+          .array(
+            z
+              .object({
+                data: Call.shape.data,
+                to: z
+                  .string()
+                  .check(
+                    z.regex(/^T[1-9A-HJ-NP-Za-km-z]{33}$/),
+                    z.describe('Tron contract address in Base58Check format.'),
+                    z.meta({ examples: ['TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'] }),
+                  ),
+                value: z
+                  .string()
+                  .check(
+                    z.regex(/^0x[0-9a-fA-F]+$/),
+                    z.describe('Native SUN value to send, as hex.'),
+                    z.meta({ examples: ['0x0'] }),
+                  ),
+              })
+              .check(z.describe('One unsigned Tron contract call.')),
+          )
+          .check(
+            z.minLength(1),
+            z.describe('Calls in submission order, signed and submitted separately.'),
+          ),
+        type: z.literal('tron:calls').check(z.describe('Action kind.')),
+      })
+      .check(z.describe('Ordered unsigned Tron calls to sign and submit on the source chain.')),
+    'RoutesTronCallsAction',
+  )
+
   /** Executable source-chain action attached to a creation response. */
   export const Action = OpenApi.component(
     z
-      .discriminatedUnion('type', [EvmCalls])
+      .discriminatedUnion('type', [EvmCalls, TronCalls])
       .check(z.describe('Executable source-chain action. Never returned by transfer reads.')),
     'RoutesAction',
   )
@@ -74,6 +111,9 @@ export type Call = z.output<typeof schema.Call>
 /** Ordered unsigned EVM calls (see {@link schema.EvmCalls}). */
 export type EvmCalls = z.output<typeof schema.EvmCalls>
 
+/** Ordered unsigned Tron calls (see {@link schema.TronCalls}). */
+export type TronCalls = z.output<typeof schema.TronCalls>
+
 /** Executable source-chain action (see {@link schema.Action}). */
 export type Action = z.output<typeof schema.Action>
 
@@ -166,6 +206,41 @@ export declare namespace validateEvmCalls {
   }
 }
 
+/** Validates Tron calls using the same exact approval and native-value bounds as EVM calls. */
+export function validateTronCalls(options: validateTronCalls.Options): void {
+  try {
+    const action = schema.TronCalls.parse(options.action)
+    validateEvmCalls({
+      action: {
+        calls: action.calls.map((call) => ({ ...call, to: Tron.toEvmAddress(call.to) })),
+        type: 'evm:calls',
+      },
+      nativeValues: options.nativeValues?.map((allowance) => ({
+        ...allowance,
+        to: Tron.toEvmAddress(allowance.to),
+      })),
+      sourceAmount: options.sourceAmount,
+      sourceTokenAddress: Tron.toEvmAddress(options.sourceTokenAddress),
+      tokenApprovals: options.tokenApprovals?.map((allowance) => ({
+        ...allowance,
+        spender: Tron.toEvmAddress(allowance.spender),
+        token: Tron.toEvmAddress(allowance.token),
+      })),
+    })
+  } catch (cause) {
+    if (cause instanceof InvalidActionError) throw cause
+    throw new InvalidActionError('Malformed Tron calls or allowances.')
+  }
+}
+
+export declare namespace validateTronCalls {
+  /** Expected route terms and provider-validated allowances for Tron calls. */
+  type Options = Omit<validateEvmCalls.Options, 'action'> & {
+    /** Prepared Tron calls. */
+    action: TronCalls
+  }
+}
+
 /** Error thrown when a provider returns an action outside the route's bounds. */
 export class InvalidActionError extends Error {
   override name = 'Routes.Action.InvalidActionError'

package/src/internal/routes/Chain.test.ts

@@ -73,6 +73,24 @@ describe('eip155Id', () => {
   })
 })
 
+describe('settlementBlockTag', () => {
+  test('accepts safe Base blocks and retains finalized settlement for other EVM chains', () => {
+    expect(
+      [
+        Chain.from({ id: 'eip155:8453', name: 'Base', slug: 'base' }),
+        Chain.from({ id: 'eip155:1', name: 'Ethereum', slug: 'ethereum' }),
+        Chain.from({ id: 'eip155:4217', name: 'Tempo', slug: 'tempo' }),
+      ].map(Chain.settlementBlockTag),
+    ).toMatchInlineSnapshot(`
+      [
+        "safe",
+        "finalized",
+        "finalized",
+      ]
+    `)
+  })
+})
+
 function metadata(chain: Chain.Chain) {
   const { addressFormat, aliases, id, kind, name, slug } = chain
   return { addressFormat, aliases, id, kind, name, slug }

package/src/internal/routes/Chain.ts

@@ -114,6 +114,11 @@ export function eip155Id(chain: Chain): string {
   return match[1]
 }
 
+/** Returns the settlement block tag for EVM routes, accepting Base mainnet once its batches are safe. */
+export function settlementBlockTag(chain: Chain) {
+  return chain.id === 'eip155:8453' ? 'safe' : 'finalized'
+}
+
 /** Error thrown when a route chain identifier is invalid for an operation. */
 export class InvalidIdError extends Error {
   override name = 'Routes.Chain.InvalidIdError'

package/src/internal/routes/DepositAddress.ts

@@ -5,6 +5,7 @@ import * as RoutesDepositAddresses from '../../db/tables/routesDepositAddresses.
 import * as Id from '../Id.js'
 import * as OpenApi from '../OpenApi.js'
 import * as Provider from './Provider.js'
+import * as Policy from './Policy.js'
 import * as Transfer from './Transfer.js'
 
 /** Internal route deposit address statuses. */
@@ -185,6 +186,8 @@ export async function createOrGet(
       destinationTokenKey: value.destinationTokenKey,
       environment: value.environment,
       orgId: value.orgId,
+      policyKey: Policy.depositKey(value.providerState),
+      providerId: value.providerId,
       ...(value.projectId === null ? {} : { projectId: value.projectId }),
       recipient: value.recipient,
       refundAddress: value.refundAddress,
@@ -294,6 +297,8 @@ export async function recoverOrGet(
       destinationTokenKey: value.destinationTokenKey,
       environment: value.environment,
       orgId: value.orgId,
+      policyKey: Policy.depositKey(value.providerState),
+      providerId: value.providerId,
       ...(value.projectId === null ? {} : { projectId: value.projectId }),
       recipient: value.recipient,
       refundAddress: value.refundAddress,

package/src/internal/routes/Evidence.test.ts

@@ -83,6 +83,70 @@ describe('resolveRpcUrls', () => {
 })
 
 describe('createVerifier', () => {
+  test('falls back when a Solana RPC stalls after response headers', async () => {
+    const solana = TestRoutes.transferSnapshot({
+      sourceChain: {
+        addressFormat: 'base58',
+        id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+        kind: 'solana',
+        name: 'Solana',
+      },
+      sourceToken: {
+        address: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        currency: 'USD',
+        decimals: 6,
+        name: 'USD Coin',
+        standard: 'SPL',
+        symbol: 'USDC',
+        tokenKey:
+          'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+        verified: true,
+      },
+    })
+    const requests: string[] = []
+    const server = await TestRelay.createServer((request, response) => {
+      requests.push(request.url ?? '')
+      request.resume()
+      response.writeHead(200, { 'content-type': 'application/json' })
+      if (request.url === '/stalled') {
+        response.write('{"jsonrpc":')
+        return
+      }
+      response.end(JSON.stringify({ id: 1, jsonrpc: '2.0', result: null }))
+    })
+
+    try {
+      await RoutesCatalog.publish(db, {
+        chainTokens: [],
+        chains: [
+          {
+            aliases: [],
+            id: solana.sourceChain.id as Chain.Id,
+            name: solana.sourceChain.name,
+            parentChainId: null,
+            rpcUrls: [new URL('/stalled', server.url).toString(), server.url],
+            slug: 'solana',
+          },
+        ],
+        routes: [],
+        tokens: [],
+      })
+      const verify = Evidence.createVerifier({ db })
+      await expect(
+        verify({
+          chain: solana.sourceChain,
+          recipient: 'RelayRecipient11111111111111111111111111111',
+          token: solana.sourceToken,
+          transactionHash: 'solana-transaction',
+        }),
+      ).resolves.toEqual([])
+      expect(requests).toEqual(['/stalled', '/'])
+    } finally {
+      server.closeAllConnections()
+      await server.closeAsync()
+    }
+  }, 20_000)
+
   test('verifies finalized Solana and one-confirmation Tron token transfers', async () => {
     const tron = TestRoutes.depositAddressSnapshot()
     const solana = TestRoutes.transferSnapshot({

package/src/internal/routes/Evidence.ts

@@ -4,6 +4,7 @@ import { getBlockNumber, getTransactionReceipt } from 'viem/actions'
 import * as z from 'zod/mini'
 
 import * as Db from '../../db/Db.js'
+import * as Timeout from '../Timeout.js'
 import * as Viem from '../Viem.js'
 import * as Catalog from './Catalog.js'
 import * as Chain from './Chain.js'
@@ -15,6 +16,7 @@ const transferEvent = AbiEvent.from(
 const transferTopic = AbiEvent.getSelector(transferEvent).slice(2)
 const catalogCacheTtlMs = 60_000
 const defaultConfirmations = 1
+const solanaRpcTimeoutMs = 10_000
 
 type SolanaRpcSchema = RpcSchema.From<{
   Request: {
@@ -341,9 +343,15 @@ async function requestSolana(
   let cause: unknown
   for (const rpcUrl of options.urls) {
     try {
-      return await RpcTransport.fromHttp<false, SolanaRpcSchema>(rpcUrl, {
-        fetchFn: options.fetch,
-      }).request(request)
+      // The transport's own timeout covers fetch headers only, so bound its full request.
+      return await Timeout.run(
+        (signal) =>
+          RpcTransport.fromHttp<false, SolanaRpcSchema>(rpcUrl, {
+            fetchFn: options.fetch,
+            fetchOptions: { signal },
+          }).request(request),
+        { timeout: solanaRpcTimeoutMs },
+      )
     } catch (error) {
       cause = error
     }

package/src/internal/routes/EvmTransferSettlement.ts

@@ -0,0 +1,213 @@
+import { getAddress } from 'viem'
+
+import type * as Metrics from '../../Metrics.js'
+import * as Value from '../Value.js'
+import * as Observability from './Observability.js'
+import * as Transfer from './Transfer.js'
+import type * as TransferSettlement from './TransferSettlement.js'
+import * as TransferSubsidy from './TransferSubsidy.js'
+
+/** Advances an EVM subsidy through nonce reservation, broadcast, and finality. */
+export async function settle(options: settle.Options): Promise<TransferSettlement.Result> {
+  let current = options.current
+  const snapshot = current.snapshot
+  let transaction = TransferSubsidy.read(current.providerState?.['transferSubsidy'])
+  const settler = transaction
+    ? options.settlers?.[0]
+    : options.settlers?.find(
+        ({ account }) => account.toLowerCase() === current.subsidyAccount?.toLowerCase(),
+      )
+  if (!settler) {
+    options.recordSubsidy('unavailable')
+    return {
+      reason: {
+        code: 'subsidy_failed',
+        message: 'Destination subsidy settlement is unavailable.',
+      },
+      record: current,
+      type: 'action-required',
+    }
+  }
+  if (!transaction) {
+    const commitment = current.subsidyCommitmentAmount
+    if (!commitment || options.deficit > BigInt(commitment.baseUnits)) {
+      options.recordSubsidy('routes_subsidy_limit_exceeded')
+      return {
+        reason: {
+          code: 'routes_subsidy_limit_exceeded',
+          message: 'The required destination subsidy exceeds its approved commitment.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    const pendingNonce = await settler.pendingNonce({ chain: options.destinationChain })
+    const subsidyAmount = Value.tokenAmount({
+      baseUnits: options.deficit,
+      currency: snapshot.destinationToken.currency,
+      decimals: snapshot.destinationToken.decimals,
+    })
+    const reserved = await Transfer.reserveSubsidy(options.db, {
+      account: settler.account,
+      chainId: options.destinationChain.id,
+      id: current.id,
+      orgId: current.orgId,
+      pendingNonce,
+      prepare: ({ nonce, reservations }) =>
+        settler.prepare({
+          amount: options.deficit,
+          chain: options.destinationChain,
+          nonce,
+          recipient: getAddress(snapshot.recipient),
+          reservations,
+          token: getAddress(snapshot.destinationToken.address),
+        }),
+      subsidyAmount,
+      tokenAddress: snapshot.destinationToken.address,
+    }).catch((cause) => {
+      if (cause instanceof Transfer.SubsidyEvidenceError) {
+        options.recordSubsidy('evidence_conflict')
+        throw cause
+      }
+      if (cause instanceof TransferSubsidy.BalanceUnavailableError) return undefined
+      if (cause instanceof Transfer.SubsidySignerBlockedError) return 'blocked' as const
+      if (TransferSubsidy.isPermanentPreparationError(cause)) return 'rejected' as const
+      throw cause
+    })
+    if (reserved === 'blocked') {
+      options.recordSubsidy('signer_blocked')
+      return {
+        reason: {
+          code: 'subsidy_failed',
+          message: 'Destination subsidy settlement requires operator recovery.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    if (reserved === 'rejected') {
+      options.recordSubsidy('prepare_rejected')
+      return {
+        reason: {
+          code: 'subsidy_failed',
+          message: 'The destination subsidy transaction could not be prepared.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    if (!reserved) {
+      options.recordSubsidy('balance_unavailable')
+      return {
+        reason: {
+          code: 'subsidy_balance_unavailable',
+          message: 'Tempo lacks enough destination token inventory or transaction fee funds.',
+        },
+        record: current,
+        type: 'action-required',
+      }
+    }
+    if (reserved.type === 'invalid' || reserved.type === 'not_found') {
+      options.recordOutcome('invalid_state')
+      return { type: 'ignored' }
+    }
+    transaction = reserved.transaction
+    current = reserved.record
+    if (
+      (reserved.type === 'reserved' || reserved.type === 'shared') &&
+      options.dispatchTransferUpdates &&
+      reserved.references.length > 0
+    )
+      await options.dispatchTransferUpdates(reserved.references)
+    if (reserved.type === 'reserved') options.recordSubsidy('prepared')
+    if (reserved.type === 'shared') options.recordSubsidy('shared')
+  }
+  const status = await settler.status({
+    chain: options.destinationChain,
+    recipient: getAddress(snapshot.recipient),
+    token: getAddress(snapshot.destinationToken.address),
+    transaction,
+  })
+  if (status.type === 'reverted') {
+    options.recordSubsidy('reverted')
+    return {
+      reason: {
+        code: 'subsidy_failed',
+        message: 'The destination subsidy transaction reverted.',
+      },
+      record: current,
+      state: {
+        subsidyAmount: Value.tokenAmount({
+          baseUnits: 0n,
+          currency: snapshot.destinationToken.currency,
+          decimals: snapshot.destinationToken.decimals,
+        }),
+      },
+      type: 'action-required',
+    }
+  }
+  if (status.type === 'pending') {
+    if (status.broadcast) {
+      const rejected = await settler
+        .broadcast({ chain: options.destinationChain, transaction })
+        .then(() => false)
+        .catch((cause) => {
+          if (alreadyKnown(cause)) return false
+          if (
+            cause instanceof TransferSubsidy.TransactionHashMismatchError ||
+            TransferSubsidy.isPermanentBroadcastError(cause)
+          )
+            return true
+          options.recordSubsidy('broadcast_failed')
+          throw cause
+        })
+      if (rejected) {
+        options.recordSubsidy('broadcast_rejected')
+        const blocked = await Transfer.blockSubsidy(options.db, {
+          id: current.id,
+          statusReason: {
+            code: 'subsidy_failed',
+            message: 'The destination subsidy transaction was rejected.',
+          },
+        })
+        if (blocked.type === 'applied') {
+          Observability.recordTransfer(options.metrics, {
+            previous: current,
+            record: blocked.record,
+          })
+          if (options.dispatchTransferUpdates && blocked.references.length > 0)
+            await options.dispatchTransferUpdates(blocked.references)
+        }
+        return { type: 'ignored' }
+      }
+      options.recordSubsidy('broadcast')
+    }
+    return { type: 'pending' }
+  }
+  options.recordSubsidy('completed')
+  return {
+    amount: BigInt(transaction.amount),
+    hash: transaction.hash,
+    record: current,
+    type: 'success',
+  }
+}
+
+export declare namespace settle {
+  /** Dependencies for one EVM settlement attempt. */
+  type Options = TransferSettlement.Options & {
+    /** Optional transfer metrics. */
+    metrics?: Metrics.Metrics | undefined
+    /** Emits a bounded transfer outcome. */
+    recordOutcome: (outcome: string) => void
+    /** Available EVM subsidy signers. */
+    settlers?: readonly TransferSubsidy.Settler[] | undefined
+  }
+}
+
+function alreadyKnown(cause: unknown): boolean {
+  if (!(cause instanceof Error)) return false
+  const message =
+    `${cause.message} ${'details' in cause ? String(cause.details) : ''}`.toLowerCase()
+  return message.includes('already known') || message.includes('known transaction')
+}