Skip to content

feat(bridge): add multi-chain Wormhole / EVM bridge monitor with reconciliation#835

Merged
Mosas2000 merged 4 commits into
StellaBridge:mainfrom
Dannyswiss1:feat/add-multi-chain-Wormhole/EVM-bridge-monitor-with-reconciliation
Jul 20, 2026
Merged

feat(bridge): add multi-chain Wormhole / EVM bridge monitor with reconciliation#835
Mosas2000 merged 4 commits into
StellaBridge:mainfrom
Dannyswiss1:feat/add-multi-chain-Wormhole/EVM-bridge-monitor-with-reconciliation

Conversation

@Dannyswiss1

Copy link
Copy Markdown
Contributor

This PR adds a multi-chain bridge monitoring subsystem for Wormhole and EVM bridges to detect off-chain mismatches between EVM lock balances and Stellar wrapped supplies.

Closes #831

Problem

System only monitored Stellar-native bridges. For Wormhole and other multi-chain bridges, we had no visibility into EVM-side lock contracts. Mismatches between EVM locked assets and Stellar wrapped supply could go undetected.

Solution

EVM Bridge Watcher Module

  • New backend/src/bridges/watchers/evm-watcher.ts using viem to fetch lock contract balances
  • Supports multiple EVM endpoints: Ethereum, Polygon, Avalanche, BSC via EVM_RPC_URLS map
  • Fetches balanceOf / totalLocked from Wormhole Token Bridge contracts every 60s
  • Handles RPC failover + retries with exponential backoff; caches last good value on failure
  • Stores snapshots in bridge_lock_balances table: chain_id, contract_address, balance, block_number, recorded_at

Cross-Chain Reconciliation Metrics

  • New service backend/src/bridges/reconciliation.ts
  • Compares EVM lock totals vs Stellar wrapped supply from Horizon/Soroban indexer
  • Metric: reconciliation_ratio = evm_locked / stellar_wrapped
  • Anomaly detection: flags if |ratio - 1| > 0.02 (2% threshold configurable)
  • Exposes Prometheus metrics: bridge_evm_locked_total, bridge_stellar_wrapped_total, bridge_reconciliation_diff
  • Alerts: fires BridgeMismatchHigh if diff > threshold for >5 min

Database Configuration

  • Added bridges.config.json + wormhole.config.ts with Wormhole bridge addresses
  • Seeds: Wormhole Token Bridge 0x3ee18B2214AFF97000D974cf647E7C347E8fa585, emitter addresses per chain
  • Migration m_2024_12_evm_bridges: new evm_bridges table with chain, address, type=wrapped|native
  • Config loaded on startup, hot-reloadable via RELOAD_BRIDGES_CONFIG endpoint

Bridges Stats Tab

  • GET /api/v1/bridges/:id/evm-locks{ chain, address, lockedBalance, lastUpdated, blockNumber }
  • GET /api/v1/bridges/:id/reconciliation{ evmTotal, stellarTotal, diff, ratio, status: ok|warning|critical }
  • Frontend: BridgesStatsTab.tsx now shows EVM lock details table + reconciliation gauge
  • Displays per-chain breakdown with explorer links

Testing Done

  • Unit: EVM watcher fetches mocked balanceOf for 3 chains; retry on RPC timeout works
  • Reconciliation: EVM 1,000,000 USDC vs Stellar 980,000 → diff 2% → warning; 1,000,000 vs 950,000 → critical
  • Integration: seeded Wormhole config → watcher polls Sepolia + local Anvil → balances indexed
  • API: GET /bridges/wormhole/reconciliation returns ratio + status; anomaly triggers alert in logs
  • Frontend: Bridges tab shows EVM locks + gauge; loading/empty states handled
  • pnpm test bridges → 18 new tests pass
  • pnpm lint && pnpm typecheck → clean

Notes

Large subsystem: ~800 LOC + new tables. Requires EVM_RPC_URLS env var set. No breaking API changes; additive endpoints only. Threshold configurable via BRIDGE_RECONCILIATION_THRESHOLD=0.02. Future: add LayerZero support using same watcher interface.

Checklist

  • RPC failover tested
  • Migration applied locally
  • Metrics exposed at /metrics
  • Docs updated in docs/bridges/multi-chain.md

@Mosas2000
Mosas2000 merged commit bdebf20 into StellaBridge:main Jul 20, 2026
18 checks passed
Alaka-ibr pushed a commit to Alaka-ibr/Bridge-Watch that referenced this pull request Jul 21, 2026
…hain-Wormhole/EVM-bridge-monitor-with-reconciliation

feat(bridge): add multi-chain Wormhole / EVM bridge monitor with reconciliation
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: Add Multi-Chain Bridge Monitor for Wormhole / EVM Contracts

2 participants