Bridge Tx Pairing Methodology

How /api/cross-chain/follow/{txHash} tries to identify the destination transaction for a given bridge deposit.

Inputs

txHash on the source chain — must already be in the HotGraph by-hash index.
That tx must touch a known bridge contract (see BridgeRegistry, 22 contracts across LayerZero V2, Wormhole, Stargate, Across, and the canonical Arbitrum / Base / Optimism / Polygon bridges).

If either is missing, the endpoint returns tx_not_found. We do not synthesize candidates from address heuristics alone.

Per-bridge windows

Each bridge has a (windowSec, valueLogTol) heuristic in CrossChainAdvancedApi.BridgePairingHeuristics:

Bridge	Window	valueLog tolerance	Why
LayerZero V2 Endpoint	180 s	±2	Deterministic relayers, fast
Stargate Router	180 s	±2	Same as LayerZero
Wormhole Core	1,800 s (30 min)	±2	Guardian relay typically 15–30 min
Across HubPool / SpokePool	300 s	±2	UMA-relayer, fast
Arbitrum L1 Inbox / ERC-20 Gateway	1,500 s	±4	Native bridge, fee deductions
Optimism L1 Standard Bridge	1,500 s	±4	Native bridge
Base L1 Standard Bridge	1,500 s	±4	Native bridge
Polygon ERC-20 PoS Bridge	3,600 s	±4	Heimdall checkpoint cadence
Polygon Plasma Bridge	604,800 s (7 d)	±6	Plasma withdrawals
(default for unknown bridges)	600 s	±4	Conservative fallback

valueLog is the discretized base-2 log of the wei value stored on each edge. ±2 lets us tolerate small fee deductions without false-negative-ing genuine pairs.

Confidence formula

For every candidate destination edge inside the window, we score:


tier      = 40 if exact valueTier match
          else max(0, 40 - 15 * |Δ valueTier|)
value     = 40 if |Δ valueLog| ≤ tolerance
          else max(0, 40 - 8 * (|Δ valueLog| - tolerance))
time      = round(20 * (1 - latencySec / windowSec))   # immediate=20, edge=0
confidence = clamp(tier + value + time, 0, 100)

Labels:

high — confidence ≥ 80
medium — confidence ≥ 50
low — anything else

We return the top-N by confidence (N = 5 by default), highest first. The header includes the heuristic so callers can audit.

Known limitations

No tx-hash-pair confirmation. Pre-deploy of receipts ingestion (#6 in the engineering TODO), we infer pairs from value+time, not from the bridge's emitted log events. A real same-protocol message ID would supersede confidence-scoring entirely.
Depends on dest-chain hot-ingestion timing. If the destination chain hasn't been polled since the bridge delivered, no candidate edges exist yet and the call returns no pairs. Callers should retry after a few windowSec worth of clock time.
Same-chain "bridges" are out of scope. Some Across configurations bridge ETH→ETH via a fast-relay; we treat those as in-chain transfers, not bridge events.
No Plasma-exit fingerprint. For Polygon Plasma the 7-day window is correct but not specific — any roughly-matching withdrawal in that window scores high. Treat Plasma confidence as "consistent with" rather than "identifies".
Address namespace collision. Same EVM address on two chains is the same addrId in the HotGraph. This is correct for EOAs. For contracts deployed at the same address by CREATE2 it is also correct but may surprise readers.

Endpoint surface


GET /api/cross-chain/follow/{txHash}
  → { src: {...}, candidates: [ {confidenceScore, confidenceLabel, ...} ],
      heuristic: "...", bridgeHeuristic: { bridge, windowSec, valueLogTol },
      latencyMs }

Disclaimer

Bridge pairing is investigative-grade, not evidentiary. A high-confidence pair is a strong lead; it is not on-chain proof of a same-message hop. Use the result to direct a human investigator to the candidate destination tx, then confirm via the bridge's own message-id / receipt log.