tapimo 0.15.1 → 0.18.1

package/src/internal/routes/providers/legacyMeshDelivery.test.ts

@@ -0,0 +1,306 @@
+import { Hex } from 'ox'
+import { encodeAbiParameters, keccak256, parseAbiParameters, stringToHex } from 'viem'
+import { describe, expect, test } from 'vitest'
+
+import * as LegacyMeshDelivery from './legacyMeshDelivery.js'
+
+const amount = 1_000_000n
+const composer = '0x759BA420bF1ded1765F18C2DC3Fc57A1964A2Ad1'
+const destinationOft = '0xaf37E8B6C9ED7f6318979f56Fc287d76c30847ff'
+const endpoint = '0x1a44076050125825900e736c501f859c50fE728c'
+const hubAdapter = '0x77652d5aba086137b595875263fc200182919b92'
+const hubOft = '0x14E4A1B13bf7F943c8ff7C51fb60FA964A298D92'
+const guid = `0x${'11'.repeat(32)}` as const
+const onwardGuid = `0x${'22'.repeat(32)}` as const
+const otherGuid = `0x${'33'.repeat(32)}` as const
+const recipient = `0x${'44'.repeat(20)}` as const
+const otherRecipient = `0x${'55'.repeat(20)}` as const
+
+describe('verifyComposerOutcome', () => {
+  test.each(['SendFailed', 'DecodeFailed'] as const)(
+    'requires operator recovery after %s',
+    (terminal) => {
+      expect(outcome(fixture.logs({ terminal }).slice(2))).toMatchInlineSnapshot(`
+        {
+          "statusReason": {
+            "code": "manual_recovery_required",
+            "message": "The Arbitrum composer failed to forward the transfer. Operator recovery is required.",
+          },
+          "type": "action-required",
+        }
+      `)
+    },
+  )
+
+  test('requires Tron repayment verification after an adapter refund', () => {
+    expect(outcome(fixture.logs({ oft: hubAdapter, terminal: 'Refunded' }).slice(2)))
+      .toMatchInlineSnapshot(`
+        {
+          "statusReason": {
+            "code": "manual_recovery_required",
+            "message": "The Arbitrum composer initiated a refund. Operator verification of Tron repayment is required.",
+          },
+          "type": "action-required",
+        }
+      `)
+  })
+
+  test.each(['SendFailed', 'DecodeFailed', 'Refunded'] as const)(
+    'rejects forged %s emitters',
+    (terminal) => {
+      const logs = fixture
+        .logs({
+          oft: terminal === 'Refunded' ? hubAdapter : hubOft,
+          terminal,
+        })
+        .slice(2)
+      logs[0] = { ...logs[0]!, address: otherRecipient }
+      expect(outcome(logs)).toMatchInlineSnapshot(`
+        {
+          "type": "invalid",
+        }
+      `)
+    },
+  )
+
+  test.each(['SendFailed', 'DecodeFailed', 'Refunded'] as const)(
+    'rejects %s for a different GUID or OFT',
+    (terminal) => {
+      for (const options of [
+        { oft: terminal === 'Refunded' ? hubOft : hubAdapter },
+        { oft: terminal === 'Refunded' ? hubAdapter : hubOft, sourceGuid: otherGuid },
+      ] as const)
+        expect(outcome(fixture.logs({ ...options, terminal }).slice(2))).toMatchInlineSnapshot(`
+          {
+            "type": "invalid",
+          }
+        `)
+    },
+  )
+
+  test('uses the successful retry after an earlier failed composition', () => {
+    const failed = fixture.logs({ terminal: 'SendFailed' }).slice(2)
+    const retried = fixture.logs({ offset: 3, terminal: 'Retried' })
+    expect(outcome([...failed, ...retried])).toMatchInlineSnapshot(`
+      {
+        "guid": "0x2222222222222222222222222222222222222222222222222222222222222222",
+        "type": "found",
+      }
+    `)
+  })
+
+  test('uses the later refund outcome even when input logs are unordered', () => {
+    const failed = fixture.logs({ terminal: 'SendFailed' }).slice(2)
+    const refund = fixture.logs({ offset: 3, oft: hubAdapter, terminal: 'Refunded' }).slice(2)
+    expect(outcome([...refund, ...failed])).toMatchInlineSnapshot(`
+      {
+        "statusReason": {
+          "code": "manual_recovery_required",
+          "message": "The Arbitrum composer initiated a refund. Operator verification of Tron repayment is required.",
+        },
+        "type": "action-required",
+      }
+    `)
+  })
+})
+
+function outcome(logs: LegacyMeshDelivery.verifyForwarding.Options['logs']) {
+  return LegacyMeshDelivery.verifyComposerOutcome({ amount, guid, logs, recipient })
+}
+
+describe('verifyForwarding', () => {
+  test('correlates the source GUID with its distinct onward GUID', () => {
+    expect(verify(fixture.logs())).toMatchInlineSnapshot(`
+      {
+        "guid": "0x2222222222222222222222222222222222222222222222222222222222222222",
+        "type": "found",
+      }
+    `)
+  })
+
+  test('recognizes successful retries', () => {
+    expect(verify(fixture.logs({ terminal: 'Retried' })).type).toMatchInlineSnapshot('"found"')
+  })
+
+  test.each(['SendFailed', 'Refunded', 'DecodeFailed'] as const)(
+    'does not mistake %s for onward delivery',
+    (terminal) => {
+      expect(verify(fixture.logs({ terminal }))).toMatchInlineSnapshot(`
+        {
+          "type": "invalid",
+        }
+      `)
+    },
+  )
+
+  test.each([
+    ['packet GUID', { packetGuid: otherGuid }],
+    ['recipient', { recipient: otherRecipient }],
+    ['destination peer', { receiver: otherRecipient }],
+    ['amount', { amount: amount + 1n }],
+  ] as const)('rejects a different %s in the packet', (_, options) => {
+    expect(verify(fixture.logs(options))).toMatchInlineSnapshot(`
+      {
+        "type": "invalid",
+      }
+    `)
+  })
+
+  test('rejects truncated or composed packets', () => {
+    for (const packet of [
+      Hex.slice(fixture.packet(), 0, 121),
+      Hex.concat(fixture.packet(), '0x00'),
+    ])
+      expect(verify(fixture.logs({ packet })).type).toMatchInlineSnapshot('"invalid"')
+  })
+
+  test('rejects an OFTSent event with a different amount', () => {
+    const logs = fixture.logs()
+    logs[1] = {
+      ...logs[1]!,
+      data: encodeAbiParameters(parseAbiParameters('uint32,uint256,uint256'), [
+        30410,
+        amount,
+        amount - 1n,
+      ]),
+    }
+    expect(verify(logs).type).toMatchInlineSnapshot('"invalid"')
+  })
+
+  test('rejects forged OFT and endpoint emitters', () => {
+    for (const index of [0, 1]) {
+      const logs = fixture.logs()
+      logs[index] = { ...logs[index]!, address: otherRecipient }
+      expect(verify(logs).type).toMatchInlineSnapshot('"invalid"')
+    }
+  })
+
+  test('requires one unambiguous onward send before the composer terminal', () => {
+    const logs = fixture.logs()
+    logs.splice(2, 0, { ...logs[1]!, logIndex: 2 })
+    logs[3] = { ...logs[3]!, logIndex: 3 }
+    expect(verify(logs).type).toMatchInlineSnapshot('"invalid"')
+  })
+
+  test('does not reuse evidence across batched composer boundaries', () => {
+    const prior = fixture.logs({ sourceGuid: otherGuid })
+    const current = fixture.logs({ offset: 3 })
+    expect(verify([...prior, ...current]).type).toMatchInlineSnapshot('"found"')
+    expect(verify([...prior, current[2]!]).type).toMatchInlineSnapshot('"invalid"')
+    expect(verify([...prior, ...current.slice(1)]).type).toMatchInlineSnapshot('"invalid"')
+  })
+
+  test('permits a retry after a failed composition in the same receipt', () => {
+    const failed = fixture.logs({ terminal: 'SendFailed' }).slice(2)
+    expect(
+      verify([...failed, ...fixture.logs({ offset: 3, terminal: 'Retried' })]).type,
+    ).toMatchInlineSnapshot('"found"')
+  })
+})
+
+function verify(logs: LegacyMeshDelivery.verifyForwarding.Options['logs']) {
+  return LegacyMeshDelivery.verifyForwarding({ amount, guid, logs, recipient })
+}
+
+namespace fixture {
+  export function packet(options: packet.Options = {}) {
+    return Hex.concat(
+      Hex.fromNumber(1, { size: 1 }),
+      Hex.fromNumber(1, { size: 8 }),
+      Hex.fromNumber(30110, { size: 4 }),
+      Hex.padLeft(hubOft, 32),
+      Hex.fromNumber(30410, { size: 4 }),
+      Hex.padLeft(options.receiver ?? destinationOft, 32),
+      options.packetGuid ?? onwardGuid,
+      Hex.padLeft(options.recipient ?? recipient, 32),
+      Hex.fromNumber(options.amount ?? amount, { size: 8 }),
+    )
+  }
+
+  export declare namespace packet {
+    type Options = {
+      amount?: bigint | undefined
+      packetGuid?: Hex.Hex | undefined
+      receiver?: Hex.Hex | undefined
+      recipient?: Hex.Hex | undefined
+    }
+  }
+
+  export function logs(options: logs.Options = {}) {
+    const offset = options.offset ?? 0
+    const terminal = options.terminal ?? 'Sent'
+    return [
+      log({
+        address: endpoint,
+        data: encodeAbiParameters(parseAbiParameters('bytes,bytes,address'), [
+          options.packet ?? packet(options),
+          '0x',
+          endpoint,
+        ]),
+        logIndex: offset,
+        topics: [keccak256(stringToHex('PacketSent(bytes,bytes,address)'))],
+      }),
+      log({
+        address: hubOft,
+        data: encodeAbiParameters(parseAbiParameters('uint32,uint256,uint256'), [
+          30410,
+          amount,
+          amount,
+        ]),
+        logIndex: offset + 1,
+        topics: [
+          keccak256(stringToHex('OFTSent(bytes32,uint32,address,uint256,uint256)')),
+          onwardGuid,
+          Hex.padLeft(composer, 32),
+        ],
+      }),
+      log({
+        address: composer,
+        data:
+          terminal === 'DecodeFailed'
+            ? encodeAbiParameters(parseAbiParameters('bytes'), ['0x'])
+            : '0x',
+        logIndex: offset + 2,
+        topics: [
+          keccak256(
+            stringToHex(
+              `${terminal}(bytes32,address${terminal === 'DecodeFailed' ? ',bytes' : ''})`,
+            ),
+          ),
+          options.sourceGuid ?? guid,
+          Hex.padLeft(options.oft ?? hubOft, 32),
+        ],
+      }),
+    ]
+  }
+
+  export declare namespace logs {
+    type Options = packet.Options & {
+      offset?: number | undefined
+      oft?: Hex.Hex | undefined
+      packet?: Hex.Hex | undefined
+      sourceGuid?: Hex.Hex | undefined
+      terminal?: 'DecodeFailed' | 'Refunded' | 'Retried' | 'SendFailed' | 'Sent' | undefined
+    }
+  }
+
+  function log(options: log.Options): LegacyMeshDelivery.verifyForwarding.Options['logs'][number] {
+    return {
+      ...options,
+      blockHash: otherGuid,
+      blockNumber: 1n,
+      removed: false,
+      transactionHash: otherGuid,
+      transactionIndex: 0,
+    }
+  }
+
+  declare namespace log {
+    type Options = {
+      address: Hex.Hex
+      data: Hex.Hex
+      logIndex: number
+      topics: [Hex.Hex, ...Hex.Hex[]]
+    }
+  }
+}

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

@@ -0,0 +1,320 @@
+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 Viem from '../../Viem.js'
+import type * as Chain from '../Chain.js'
+import type * as RoutesProvider from '../Provider.js'
+
+// Canonical deployments: https://docs.usdt0.to/api/deployments.
+const composer = '0x759BA420bF1ded1765F18C2DC3Fc57A1964A2Ad1'
+const hubAdapter = '0x77652d5aba086137b595875263fc200182919b92'
+const hubOft = '0x14E4A1B13bf7F943c8ff7C51fb60FA964A298D92'
+const hubEndpoint = '0x1a44076050125825900e736c501f859c50fE728c'
+const destinationOft = '0xaf37E8B6C9ED7f6318979f56Fc287d76c30847ff'
+const destinationToken = '0x20C00000000000000000000014f22CA97301EB73'
+const maximumLogBlockRange = 10_000n
+const zeroAddress = '0x0000000000000000000000000000000000000000'
+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+$/)),
+  legacyMesh: z.object({
+    amount: z.string().check(z.regex(/^[1-9]\d*$/)),
+    guid: Schema.Hash,
+  }),
+})
+
+/** Verifies both the Arbitrum forwarding evidence and the final Tempo token delivery. */
+export async function verifyDestinationDelivery(
+  options: verifyDestinationDelivery.Options,
+): Promise<RoutesProvider.verifyDestinationDelivery.ReturnType> {
+  const { destinationChain, transfer } = options
+  const state = stateSchema.safeParse(options.providerState)
+  if (
+    !state.success ||
+    destinationChain.id !== 'eip155:4217' ||
+    destinationChain.kind !== 'evm' ||
+    !Address.validate(transfer.recipient, { strict: false }) ||
+    !Address.validate(transfer.destinationToken.address, { strict: false }) ||
+    !Address.isEqual(transfer.destinationToken.address as Address.Address, destinationToken) ||
+    transfer.destinationAmount?.baseUnits !== state.data.legacyMesh.amount
+  )
+    return { type: 'invalid' }
+
+  const { destinationBlockNumber, hubBlockNumber, legacyMesh } = state.data
+  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 destination = Viem.createEvmClient({
+    chainId: 4217,
+    fetch,
+    signal: options.signal,
+    urls: options.resolveRpcUrls?.(destinationChain) ?? destinationChain.rpcUrls,
+  }).extend(publicActions)
+  const [hubChainId, destinationChainId, hubHead, destinationHead] = await Promise.all([
+    hub.getChainId(),
+    destination.getChainId(),
+    hub.getBlock({ blockTag: 'finalized', includeTransactions: false }),
+    destination.getBlock({ blockTag: 'latest', includeTransactions: false }),
+  ])
+  if (hubChainId !== 42161 || destinationChainId !== 4217) return { type: 'invalid' }
+  const amount = BigInt(legacyMesh.amount)
+  const recipient = transfer.recipient as Address.Address
+  const forwarding = await (async () => {
+    // Search newest finalized events first so a later retry supersedes an earlier failure.
+    for (
+      let toBlock = hubHead.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, legacyMesh.guid))
+        .sort((a, b) => {
+          if (a.blockNumber === b.blockNumber) return b.logIndex - a.logIndex
+          return a.blockNumber > b.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 > hubHead.number ||
+        receipt.blockHash !== match.blockHash
+      )
+        return { type: 'invalid' as const }
+
+      return verifyComposerOutcome({ amount, guid: legacyMesh.guid, logs: receipt.logs, recipient })
+    }
+    return { type: 'pending' as const }
+  })()
+  if (forwarding.type !== 'found') return forwarding
+
+  for (
+    let fromBlock = BigInt(destinationBlockNumber);
+    fromBlock <= destinationHead.number;
+    fromBlock += maximumLogBlockRange
+  ) {
+    const end = fromBlock + maximumLogBlockRange - 1n
+    const logs = await destination.getLogs({
+      address: destinationOft,
+      args: { guid: forwarding.guid },
+      event: oftReceived,
+      fromBlock,
+      strict: true,
+      toBlock: end > destinationHead.number ? destinationHead.number : end,
+    })
+    if (logs.length > 1) return { type: 'invalid' }
+    const match = logs[0]
+    if (!match) continue
+    if (
+      match.args.srcEid !== 30110 ||
+      !Address.isEqual(match.args.toAddress, recipient) ||
+      match.args.amountReceivedLD !== amount
+    )
+      return { type: 'invalid' }
+    const receipt = await destination
+      .getTransactionReceipt({ hash: match.transactionHash })
+      .catch((cause) => {
+        if (cause instanceof TransactionReceiptNotFoundError) return undefined
+        throw cause
+      })
+    if (!receipt) return { type: 'pending' }
+    if (
+      receipt.status !== 'success' ||
+      receipt.blockNumber > destinationHead.number ||
+      receipt.blockHash !== match.blockHash
+    )
+      return { type: 'invalid' }
+    const received = parseEventLogs({
+      abi: [oftReceived],
+      logs: receipt.logs,
+      strict: true,
+    }).filter(
+      ({ address, args }) =>
+        Address.isEqual(address, destinationOft) &&
+        Hex.isEqual(args.guid, forwarding.guid) &&
+        args.srcEid === 30110 &&
+        Address.isEqual(args.toAddress, recipient) &&
+        args.amountReceivedLD === amount,
+    )
+    const transfers = parseEventLogs({
+      abi: [transferEvent],
+      logs: receipt.logs,
+      strict: true,
+    }).filter(
+      ({ address, args }) =>
+        Address.isEqual(address, destinationToken) &&
+        Address.isEqual(args.from, zeroAddress) &&
+        Address.isEqual(args.to, recipient) &&
+        args.value === amount,
+    )
+    if (received.length !== 1 || transfers.length !== 1) return { type: 'invalid' }
+    return { transactionHash: receipt.transactionHash, type: 'verified' }
+  }
+  return { type: 'pending' }
+}
+
+export declare namespace verifyDestinationDelivery {
+  /** Transfer evidence and read-only RPC configuration for both delivery hops. */
+  type Options = RoutesProvider.verifyDestinationDelivery.Parameters & {
+    /** Fetch implementation for chain RPC requests. */
+    fetch?: RoutesProvider.Fetch | undefined
+    /** Arbitrum RPC endpoints used to verify forwarding. */
+    hubRpcUrls?: readonly string[] | undefined
+    /** RPC endpoints for the configured destination chain. */
+    resolveRpcUrls?: ((chain: Chain.Chain) => readonly string[]) | undefined
+    /** Cancellation signal for RPC requests. */
+    signal?: AbortSignal | undefined
+  }
+}
+
+/** Classifies the latest composer outcome without treating an initiated refund as completed repayment. */
+export function verifyComposerOutcome(options: verifyComposerOutcome.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' ? hubAdapter : hubOft)
+  )
+    return { type: 'invalid' as const }
+  if (terminal.eventName === 'Sent' || terminal.eventName === 'Retried')
+    return verifyForwarding(options)
+
+  // Refunded proves the reverse send started, not that Tron repayment settled.
+  return {
+    statusReason: {
+      code: 'manual_recovery_required' as const,
+      message:
+        terminal.eventName === 'Refunded'
+          ? 'The Arbitrum composer initiated a refund. Operator verification of Tron repayment is required.'
+          : 'The Arbitrum composer failed to forward the transfer. Operator recovery is required.',
+    },
+    type: 'action-required' as const,
+  }
+}
+
+export declare namespace verifyComposerOutcome {
+  /** Canonical composer receipt logs and the registered transfer terms. */
+  type Options = verifyForwarding.Options
+}
+
+/** Correlates a source GUID with its exact onward packet inside a composer transaction. */
+export function verifyForwarding(options: verifyForwarding.Options) {
+  // Composer emits the source GUID after its nested OFT send; retries emit Retried instead of Sent.
+  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, hubOft))
+    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, hubOft) && Address.isEqual(args.fromAddress, composer),
+  )
+  const send = sends[0]
+  if (
+    sends.length !== 1 ||
+    !send ||
+    send.args.dstEid !== 30410 ||
+    send.args.amountSentLD !== options.amount ||
+    send.args.amountReceivedLD !== options.amount
+  )
+    return { type: 'invalid' as const }
+  const guid = send.args.guid
+  // PacketV1's 113-byte header precedes recipient bytes32 and amountSD uint64. USDT0 local and shared amounts both use six decimals.
+  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)) === 30110 &&
+        Hex.isEqual(Hex.slice(packet, 13, 45), Hex.padLeft(hubOft, 32)) &&
+        Hex.toNumber(Hex.slice(packet, 45, 49)) === 30410 &&
+        Hex.isEqual(Hex.slice(packet, 49, 81), Hex.padLeft(destinationOft, 32)) &&
+        Hex.isEqual(Hex.slice(packet, 81, 113), guid) &&
+        Hex.isEqual(Hex.slice(packet, 113, 145), Hex.padLeft(options.recipient, 32)) &&
+        Hex.toBigInt(Hex.slice(packet, 145, 153)) === options.amount
+      )
+    },
+  )
+  if (packets.length !== 1) return { type: 'invalid' as const }
+  return { guid, type: 'found' as const }
+}
+
+export declare namespace verifyForwarding {
+  /** Confirmed source terms and raw receipt logs. */
+  type Options = {
+    /** Exact amount forwarded, in six-decimal USDT units. */
+    amount: bigint
+    /** GUID emitted on the original source chain. */
+    guid: Hex.Hex
+    /** Included Arbitrum transaction logs in execution order. */
+    logs: readonly TransactionReceipt['logs'][number][]
+    /** Final Tempo beneficiary. */
+    recipient: Address.Address
+  }
+}