tapimo 0.15.1 → 0.18.0

package/src/internal/routes/providers/legacyMeshOutboundDelivery.ts

@@ -0,0 +1,473 @@
+import { AbiEvent, Address, Hex } from 'ox'
+import {
+  parseEventLogs,
+  publicActions,
+  TransactionReceiptNotFoundError,
+  type TransactionReceipt,
+} from 'viem'
+import * as z from 'zod/mini'
+
+import * as Schema from '../../Schema.js'
+import * as Tron from '../../Tron.js'
+import * as Viem from '../../Viem.js'
+import type * as Chain from '../Chain.js'
+import type * as Provider from '../Provider.js'
+
+// Canonical deployments: https://docs.usdt0.to/api/deployments.
+const composer = '0x759BA420bF1ded1765F18C2DC3Fc57A1964A2Ad1'
+const hubOft = '0x14E4A1B13bf7F943c8ff7C51fb60FA964A298D92'
+const hubAdapter = '0x77652D5aba086137b595875263FC200182919B92'
+const hubEndpoint = '0x1a44076050125825900e736c501f859c50fE728c'
+const destinationPool = 'TFG4wBaDQ8sHWWP1ACeSGnoNR6RRzevLPt'
+const destinationToken = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'
+const sourceToken = '0x20C00000000000000000000014f22CA97301EB73'
+const hubEid = 30_110
+const destinationEid = 30_420
+const maximumLogBlockRange = 10_000n
+const maximumEventPages = 5
+const maximumReceiptReads = 8
+const sent = AbiEvent.from('event Sent(bytes32 indexed guid, address indexed oft)')
+const retried = AbiEvent.from('event Retried(bytes32 indexed guid, address indexed oft)')
+const refunded = AbiEvent.from('event Refunded(bytes32 indexed guid, address indexed oft)')
+const sendFailed = AbiEvent.from('event SendFailed(bytes32 indexed guid, address indexed oft)')
+const decodeFailed = AbiEvent.from(
+  'event DecodeFailed(bytes32 indexed guid, address indexed oft, bytes message)',
+)
+const oftSent = AbiEvent.from(
+  'event OFTSent(bytes32 indexed guid, uint32 dstEid, address indexed fromAddress, uint256 amountSentLD, uint256 amountReceivedLD)',
+)
+const oftReceived = AbiEvent.from(
+  'event OFTReceived(bytes32 indexed guid, uint32 srcEid, address indexed toAddress, uint256 amountReceivedLD)',
+)
+const packetSent = AbiEvent.from(
+  'event PacketSent(bytes encodedPayload, bytes options, address sendLibrary)',
+)
+const transferEvent = AbiEvent.from(
+  'event Transfer(address indexed from, address indexed to, uint256 value)',
+)
+
+const stateSchema = z.object({
+  destinationBlockNumber: z.string().check(z.regex(/^\d+$/)),
+  hubBlockNumber: z.string().check(z.regex(/^\d+$/)),
+  legacyMeshOutbound: z.object({
+    amount: z.string().check(z.regex(/^[1-9]\d*$/)),
+    guid: Schema.Hash,
+  }),
+})
+const tronEvents = z.object({
+  data: z.array(
+    z.object({
+      block_number: z.number().check(z.int(), z.nonnegative()),
+      transaction_id: z.string().check(z.regex(/^[0-9a-fA-F]{64}$/)),
+      result: z.optional(
+        z.object({ guid: z.optional(z.string().check(z.regex(/^(?:0x)?[0-9a-fA-F]{64}$/))) }),
+      ),
+    }),
+  ),
+  meta: z.optional(
+    z.object({ fingerprint: z.optional(z.string().check(z.minLength(1), z.maxLength(2_048))) }),
+  ),
+  success: z.boolean(),
+})
+const eventCursor = z.object({
+  fingerprint: z.optional(z.string().check(z.minLength(1), z.maxLength(2_048))),
+  offset: z.number().check(z.int(), z.nonnegative()),
+})
+
+/** Verifies Arbitrum composition and solidified Tron USDT delivery. */
+export async function verifyDestinationDelivery(
+  options: verifyDestinationDelivery.Options,
+): Promise<Provider.verifyDestinationDelivery.ReturnType> {
+  const { destinationChain, sourceChain, transfer } = options
+  const state = stateSchema.safeParse(options.providerState)
+  if (
+    !state.success ||
+    !transfer.destinationAmount ||
+    sourceChain.id !== 'eip155:4217' ||
+    destinationChain.id !== 'tron:0x2b6653dc' ||
+    !Address.isEqual(transfer.sourceToken.address as Address.Address, sourceToken) ||
+    transfer.destinationToken.address !== destinationToken ||
+    !transfer.destinationAmountMin
+  )
+    return { type: 'invalid' }
+  const recipient = Tron.toEvmAddress(transfer.recipient)
+  const fetch = options.fetch ?? globalThis.fetch
+  const hub = Viem.createEvmClient({
+    chainId: 42161,
+    fetch,
+    signal: options.signal,
+    urls: options.hubRpcUrls ?? ['https://arb1.arbitrum.io/rpc'],
+  }).extend(publicActions)
+  const [chainId, head] = await Promise.all([
+    hub.getChainId(),
+    hub.getBlock({ blockTag: 'finalized', includeTransactions: false }),
+  ])
+  if (chainId !== 42161) return { type: 'invalid' }
+  const { destinationBlockNumber, hubBlockNumber, legacyMeshOutbound } = state.data
+  const amount = BigInt(legacyMeshOutbound.amount)
+  const forwarding = await (async () => {
+    for (
+      let toBlock = head.number;
+      toBlock >= BigInt(hubBlockNumber);
+      toBlock -= maximumLogBlockRange
+    ) {
+      const start = toBlock - maximumLogBlockRange + 1n
+      const logs = await hub.getLogs({
+        address: composer,
+        events: [sent, retried, refunded, sendFailed, decodeFailed],
+        fromBlock: start < BigInt(hubBlockNumber) ? BigInt(hubBlockNumber) : start,
+        strict: true,
+        toBlock,
+      })
+      const match = logs
+        .filter(({ args }) => Hex.isEqual(args.guid, legacyMeshOutbound.guid))
+        .sort((left, right) => {
+          if (left.blockNumber === right.blockNumber) return right.logIndex - left.logIndex
+          return left.blockNumber > right.blockNumber ? -1 : 1
+        })[0]
+      if (!match) continue
+      const receipt = await hub
+        .getTransactionReceipt({ hash: match.transactionHash })
+        .catch((cause) => {
+          if (cause instanceof TransactionReceiptNotFoundError) return undefined
+          throw cause
+        })
+      if (!receipt) return { type: 'pending' as const }
+      if (
+        receipt.status !== 'success' ||
+        receipt.blockNumber > head.number ||
+        !Hex.isEqual(receipt.blockHash, match.blockHash)
+      )
+        return { type: 'invalid' as const }
+      return verifyComposerOutcome({
+        guid: legacyMeshOutbound.guid,
+        logs: receipt.logs,
+        minimum: BigInt(transfer.destinationAmountMin!.baseUnits),
+        recipient,
+        sourceAmount: amount,
+      })
+    }
+    return { type: 'pending' as const }
+  })()
+  if (forwarding.type !== 'found') return forwarding
+
+  const tron = Tron.createClient({
+    fetch,
+    signal: options.signal,
+    urls: options.resolveRpcUrls?.(destinationChain) ?? destinationChain.rpcUrls,
+  })
+  const headBlock = await tron.getBlock()
+  const headNumber = headBlock.block_header.raw_data.number
+  const firstBlock = Number(destinationBlockNumber)
+  if (!Number.isSafeInteger(firstBlock) || firstBlock > headNumber) return { type: 'pending' }
+  // TronGrid provides an index; every matching row is checked against a solidified native receipt.
+  const saved = eventCursor.safeParse(options.providerState?.['tronEventCursor'])
+  let fingerprint = saved.success ? saved.data.fingerprint : undefined
+  let offset = saved.success ? saved.data.offset : 0
+  const seen = new Set<string>()
+  let receiptReads = 0
+  for (let pages = 0; pages < maximumEventPages; pages++) {
+    const url = new URL(
+      `/v1/contracts/${destinationPool}/events`,
+      options.tronEventsUrl ?? 'https://api.trongrid.io',
+    )
+    url.searchParams.set('event_name', 'OFTReceived')
+    url.searchParams.set('only_confirmed', 'true')
+    url.searchParams.set('order_by', 'block_timestamp,asc')
+    url.searchParams.set('min_timestamp', String(Date.parse(transfer.quote.sampledAt)))
+    url.searchParams.set('limit', '200')
+    if (fingerprint) url.searchParams.set('fingerprint', fingerprint)
+    const response = await fetch(url, {
+      signal: AbortSignal.any([
+        AbortSignal.timeout(10_000),
+        ...(options.signal ? [options.signal] : []),
+      ]),
+    })
+    if (!response.ok) {
+      if (fingerprint && (response.status === 400 || response.status === 422))
+        return pending({ fingerprint: undefined, offset: 0 }, options.providerState)
+      throw new Error(`Tron event index returned HTTP ${response.status}.`)
+    }
+    const page = tronEvents.parse(await response.json())
+    if (!page.success) throw new Error('Tron event index rejected the request.')
+    if (offset > page.data.length)
+      return pending({ fingerprint: undefined, offset: 0 }, options.providerState)
+    const selected = selectEventCandidates({
+      budget: maximumReceiptReads - receiptReads,
+      firstBlock,
+      guid: forwarding.guid,
+      headNumber,
+      offset,
+      page,
+    })
+    for (const event of selected.events) {
+      receiptReads++
+      const receipt = await tron.getTransactionReceipt({ hash: event.transaction_id })
+      if (!receipt) continue
+      if (receipt.blockNumber !== event.block_number) continue
+      const outcome = verifyTronReceipt({
+        amount: forwarding.amount,
+        guid: forwarding.guid,
+        recipient,
+        receipt,
+        transactionHash: event.transaction_id,
+      })
+      if (outcome.type === 'verified' || outcome.type === 'invalid') return outcome
+    }
+    if (selected.offset < page.data.length)
+      return pending({ fingerprint, offset: selected.offset }, options.providerState)
+    const next = page.meta?.fingerprint
+    // A full rescan after exhaustion can find deliveries indexed after their chronological page passed.
+    if (!next || next === fingerprint || seen.has(next) || page.data.length === 0)
+      return pending({ fingerprint: undefined, offset: 0 }, options.providerState)
+    seen.add(next)
+    fingerprint = next
+    offset = 0
+  }
+  return pending({ fingerprint, offset }, options.providerState)
+}
+
+/** Carries bounded index progress into the next reconciliation attempt. */
+function pending(
+  cursor: z.output<typeof eventCursor>,
+  providerState: Provider.verifyDestinationDelivery.Parameters['providerState'],
+) {
+  return {
+    providerState: {
+      ...providerState,
+      tronEventCursor: cursor.fingerprint || cursor.offset ? cursor : null,
+    },
+    type: 'pending' as const,
+  }
+}
+
+/** Selects one bounded page slice without losing an unprocessed receipt candidate. */
+export function selectEventCandidates(options: selectEventCandidates.Options) {
+  const { budget, firstBlock, guid, headNumber, offset, page } = options
+  const events: (typeof page.data)[number][] = []
+  for (let index = offset; index < page.data.length; index++) {
+    const event = page.data[index]!
+    if (event.block_number < firstBlock || event.block_number > headNumber) continue
+    if (
+      event.result?.guid &&
+      event.result.guid.replace(/^0x/, '').toLowerCase() !== guid.slice(2).toLowerCase()
+    )
+      continue
+    if (events.length === budget) return { events, offset: index }
+    events.push(event)
+  }
+  return { events, offset: page.data.length }
+}
+
+export declare namespace selectEventCandidates {
+  /** Indexed page and remaining native receipt budget for this attempt. */
+  type Options = {
+    /** Remaining native receipt calls allowed in this attempt. */
+    budget: number
+    /** Earliest possible delivery block. */
+    firstBlock: number
+    /** Arbitrum onward packet GUID. */
+    guid: Hex.Hex
+    /** Latest solidified Tron block. */
+    headNumber: number
+    /** First unprocessed row in the current page. */
+    offset: number
+    /** Validated TronGrid event page. */
+    page: z.output<typeof tronEvents>
+  }
+}
+
+export declare namespace verifyDestinationDelivery {
+  /** Stored transfer evidence and chain access for both delivery hops. */
+  type Options = Provider.verifyDestinationDelivery.Parameters & {
+    /** Fetch implementation for Arbitrum, Tron, and the Tron event index. */
+    fetch?: Provider.Fetch | undefined
+    /** Arbitrum RPC endpoints. */
+    hubRpcUrls?: readonly string[] | undefined
+    /** Preferred native Tron endpoints. */
+    resolveRpcUrls?: ((chain: Chain.Chain) => readonly string[]) | undefined
+    /** Optional cancellation signal. */
+    signal?: AbortSignal | undefined
+    /** TronGrid compatible event index endpoint. */
+    tronEventsUrl?: string | undefined
+  }
+}
+
+/** Checks the latest composer outcome and the exact onward packet. */
+export function verifyComposerOutcome(options: verifyForwarding.Options) {
+  const terminal = parseEventLogs({
+    abi: [sent, retried, refunded, sendFailed, decodeFailed],
+    logs: [...options.logs],
+    strict: true,
+  })
+    .filter(
+      ({ address, args }) =>
+        Address.isEqual(address, composer) && Hex.isEqual(args.guid, options.guid),
+    )
+    .sort((a, b) => b.logIndex - a.logIndex)[0]
+  if (
+    !terminal ||
+    !Address.isEqual(terminal.args.oft, terminal.eventName === 'Refunded' ? hubOft : hubAdapter)
+  )
+    return { type: 'invalid' as const }
+  if (terminal.eventName === 'Sent' || terminal.eventName === 'Retried')
+    return verifyForwarding(options)
+  return {
+    statusReason: {
+      code: 'manual_recovery_required' as const,
+      message:
+        terminal.eventName === 'Refunded'
+          ? 'The Arbitrum composer initiated a refund. Operator verification of Tempo repayment is required.'
+          : 'The Arbitrum composer failed to forward the transfer. Operator recovery is required.',
+    },
+    type: 'action-required' as const,
+  }
+}
+
+/** Correlates the source GUID with the hub adapter send and Tron packet. */
+export function verifyForwarding(options: verifyForwarding.Options) {
+  const terminals = parseEventLogs({
+    abi: [sent, retried, refunded, sendFailed, decodeFailed],
+    logs: [...options.logs],
+    strict: true,
+  }).filter(({ address }) => Address.isEqual(address, composer))
+  const matches = terminals.filter(
+    ({ args, eventName }) =>
+      Hex.isEqual(args.guid, options.guid) && (eventName === 'Sent' || eventName === 'Retried'),
+  )
+  const terminal = matches[0]
+  if (matches.length !== 1 || !terminal || !Address.isEqual(terminal.args.oft, hubAdapter))
+    return { type: 'invalid' as const }
+  const previous =
+    terminals.filter(({ logIndex }) => logIndex < terminal.logIndex).at(-1)?.logIndex ?? -1
+  const segment = options.logs.filter(
+    ({ logIndex }) => logIndex > previous && logIndex < terminal.logIndex,
+  )
+  const sends = parseEventLogs({ abi: [oftSent], logs: segment, strict: true }).filter(
+    ({ address, args }) =>
+      Address.isEqual(address, hubAdapter) && Address.isEqual(args.fromAddress, composer),
+  )
+  const send = sends[0]
+  if (
+    sends.length !== 1 ||
+    !send ||
+    send.args.dstEid !== destinationEid ||
+    send.args.amountSentLD !== options.sourceAmount ||
+    send.args.amountReceivedLD < options.minimum ||
+    send.args.amountReceivedLD > options.sourceAmount
+  )
+    return { type: 'invalid' as const }
+  const packets = parseEventLogs({ abi: [packetSent], logs: segment, strict: true }).filter(
+    ({ address, args, logIndex }) => {
+      const packet = args.encodedPayload
+      return (
+        Address.isEqual(address, hubEndpoint) &&
+        logIndex < send.logIndex &&
+        Hex.size(packet) === 153 &&
+        Hex.toNumber(Hex.slice(packet, 0, 1)) === 1 &&
+        Hex.toNumber(Hex.slice(packet, 9, 13)) === hubEid &&
+        Hex.isEqual(Hex.slice(packet, 13, 45), Hex.padLeft(hubAdapter, 32)) &&
+        Hex.toNumber(Hex.slice(packet, 45, 49)) === destinationEid &&
+        Hex.isEqual(
+          Hex.slice(packet, 49, 81),
+          Hex.padLeft(Tron.toEvmAddress(destinationPool), 32),
+        ) &&
+        Hex.isEqual(Hex.slice(packet, 81, 113), send.args.guid) &&
+        Hex.isEqual(Hex.slice(packet, 113, 145), Hex.padLeft(options.recipient, 32)) &&
+        Hex.toBigInt(Hex.slice(packet, 145, 153)) === send.args.amountReceivedLD
+      )
+    },
+  )
+  return packets.length === 1
+    ? { amount: send.args.amountReceivedLD, guid: send.args.guid, type: 'found' as const }
+    : { type: 'invalid' as const }
+}
+
+export declare namespace verifyForwarding {
+  /** Included Arbitrum receipt and exact registered transfer terms. */
+  type Options = {
+    /** GUID emitted by the Tempo source OFT. */
+    guid: Hex.Hex
+    /** Receipt logs in execution order. */
+    logs: readonly TransactionReceipt['logs'][number][]
+    /** Minimum amount accepted by the caller. */
+    minimum: bigint
+    /** Final Tron recipient represented as a 20-byte ABI address. */
+    recipient: Hex.Hex
+    /** Amount entering the Arbitrum composer. */
+    sourceAmount: bigint
+  }
+}
+
+/** Checks the indexed transaction against solidified OFT and USDT transfer logs. */
+export function verifyTronReceipt(
+  options: verifyTronReceipt.Options,
+): Provider.verifyDestinationDelivery.ReturnType {
+  const receipt = Tron.schema.Receipt.safeParse(options.receipt)
+  if (!receipt.success) return { type: 'invalid' }
+  const value = receipt.data
+  if (value.id.toLowerCase() !== options.transactionHash.toLowerCase()) return { type: 'invalid' }
+  const logs = value.log ?? []
+  const receivedEvents = logs
+    .filter(
+      (log) =>
+        log.address.toLowerCase() === Tron.toEvmAddress(destinationPool).slice(2).toLowerCase() &&
+        log.topics[0]?.toLowerCase() === AbiEvent.getSelector(oftReceived).slice(2).toLowerCase(),
+    )
+    .map((log) =>
+      AbiEvent.decode(oftReceived, {
+        data: `0x${log.data}`,
+        topics: log.topics.map((topic) => `0x${topic}`) as [Hex.Hex, ...Hex.Hex[]],
+      }),
+    )
+  const received = receivedEvents.filter((event) => Hex.isEqual(event.guid, options.guid))
+  if (received.length === 0) return { type: 'pending' }
+  if (value.receipt.result !== 'SUCCESS' || (value.result && value.result !== 'SUCCESS'))
+    return { type: 'invalid' }
+  const matched = received.filter(
+    (event) =>
+      event.srcEid === hubEid &&
+      Address.isEqual(event.toAddress, options.recipient) &&
+      event.amountReceivedLD === options.amount,
+  )
+  const transfers = logs
+    .filter(
+      (log) =>
+        log.address.toLowerCase() === Tron.toEvmAddress(destinationToken).slice(2).toLowerCase() &&
+        log.topics[0]?.toLowerCase() === AbiEvent.getSelector(transferEvent).slice(2).toLowerCase(),
+    )
+    .map((log) =>
+      AbiEvent.decode(transferEvent, {
+        data: `0x${log.data}`,
+        topics: log.topics.map((topic) => `0x${topic}`) as [Hex.Hex, ...Hex.Hex[]],
+      }),
+    )
+    .filter(
+      (event) =>
+        Address.isEqual(event.from, Tron.toEvmAddress(destinationPool)) &&
+        Address.isEqual(event.to, options.recipient) &&
+        event.value === options.amount,
+    )
+  if (matched.length !== 1 || transfers.length !== 1) return { type: 'invalid' }
+  return {
+    destinationAmount: options.amount.toString(),
+    transactionHash: `0x${options.transactionHash}`,
+    type: 'verified',
+  }
+}
+
+export declare namespace verifyTronReceipt {
+  /** Solidified Tron transaction and expected delivery. */
+  type Options = {
+    /** Exact beneficiary amount in USDT base units. */
+    amount: bigint
+    /** GUID in the Arbitrum onward packet. */
+    guid: Hex.Hex
+    /** Final Tron beneficiary as a 20-byte ABI address. */
+    recipient: Hex.Hex
+    /** Untrusted native Tron receipt. */
+    receipt: unknown
+    /** Hash returned by the Tron event index. */
+    transactionHash: string
+  }
+}