🌉 NexBridge

A Production-Grade, Bidirectional Cross-Chain Bridge Architecture

English · 简体中文

---

📖 Introduction

NexBridge is an industrial-grade, bidirectional cross-chain bridge infrastructure demonstration built from the ground up. Beyond a simplistic "admin-mint" tool, it fully implements cryptographic signature verification, decentralized relayer buffering, and a stunning Glassmorphism Web3 frontend.

Deeply refactored from Hardhat to the Foundry framework, this project boasts lightning-fast compilation, rigorous security testing, and serves as an incredibly extensible, open-source reference for DeFi interoperability.

---

✨ Key Features

• 🔄 True Bidirectionality: Seamless paths for Locking (Sepolia) -> Minting (Arbitrum) and the reverse route of Burning & Unlocking.
• 🛡️ Peer Authentication (Trusted Remotes): A deep-layer security mechanism. More than just signature validation, the message payload strictly couples the corresponding remote contract addresses, eliminating the risk of rogue contracts spoofing signed events.
• 🔐 Replay Protection: Integrated process-cache mapping guarantees that cross-chain payloads (via TxHash) are executed strictly once, terminating double-spend possibilities.
• 🏎️ Resilient Node.js Relayer: A robust background daemon equipped with Exponential Backoff retry mechanics, comprehensive exception catching, and multi-network concurrency.
• 🎨 Hypercar-Level UI/UX: Next-generation DApp interface powered by React + Vite. Features Ethers v6 hooks, proactive MetaMask network sensing, and dynamic state-driven animations.

---

🏗️ Architecture Overview

sequenceDiagram
    participant User as 👤 User
    participant ChainA as ⛓️ Chain A (Sepolia)
    participant Relayer as 🤖 Relayer (Node.js)
    participant ChainB as ⛓️ Chain B (Arbitrum)
    
    User->>ChainA: 1. Lock Tokens (Emit `Locked` Event)
    activate ChainA
    ChainA-->>Relayer: 2. Listen & Catch `Locked` Hash
    deactivate ChainA
    activate Relayer
    Relayer->>Relayer: 3. Verify Tx & Local Process Cache
    Relayer->>Relayer: 4. Sign Message (ECDSA + Peer Address)
    Relayer->>ChainB: 5. Submit `Mint` Transaction
    deactivate Relayer
    activate ChainB
    ChainB->>ChainB: 6. Require(Signer == Validator)
    ChainB->>ChainB: 7. Require(Source == TrustedRemote)
    ChainB-->>User: 8. Tokens Minted on Target Chain
    deactivate ChainB

Loading

---

📂 Repository Structure

📦 NexBridge
 ┣ 📂 src                 # Smart Contract Source
 ┃ ┣ 📜 Token.sol        # Omni-Chain ERC20 Asset
 ┃ ┣ 📜 Lock.sol         # Cross-chain Vault Hub
 ┃ ┗ 📜 Mint.sol         # Cross-chain Mint/Burn Engine
 ┣ 📂 test                # TDD Environment
 ┃ ┗ 📜 Crosschain.t.sol # Comprehensive Foundry suite (inc. malicious intercept tests)
 ┣ 📂 script              # DevOps & Deployment
 ┃ ┣ 📜 Deploy.s.sol     # Automated pipeline
 ┃ ┗ 📜 InitRemotes.s.sol# Peer Auth Network Bonding
 ┣ 📂 scripts             # Off-chain Node.js Cluster
 ┃ ┣ 📜 relayer.js       # Bidirectional listening daemon
 ┃ ┗ 📜 test-*.js        # P2P integration smoke tests
 ┗ 📂 frontend            # Modern Web3.0 Application
   ┣ 📜 src/App.jsx      # Ethers v6 state machine
   ┗ 📜 src/App.css      # Next-Gen Glassmorphism presentation

---

🚀 Quick Start

1. Prerequisites

Ensure Foundry and Node.js are properly installed on your machine.

# 1. Install Foundry Solidity dependencies
forge install

# 2. Install Relayer runtime dependencies
npm install

# 3. Boot up the aesthetic frontend
cd frontend
npm install
npm run dev

2. Compile & Test

forge build
forge test -vv

3. Multi-Chain Deployment

(Note: Manage your API keys and deployer credentials via the .env file)

# Stage 1: Contract On-ramping (Sepolia & Arbitrum)
source .env &&
export DEPLOY_MODE=BIDIRECTIONAL &&
export TOKEN_NAME=TokenA &&
export TOKEN_SYMBOL=TKA &&
forge script script/Deploy.s.sol --rpc-url $SEPOLIA_RPC --broadcast

source .env &&
export DEPLOY_MODE=BIDIRECTIONAL &&
export TOKEN_NAME=TokenB &&
export TOKEN_SYMBOL=TKB &&
forge script script/Deploy.s.sol --rpc-url $ARBITRUM_SEPOLIA_RPC --broadcast

# Stage 2: Extract the generated contract addresses to the repository's `.env`

# Stage 3: Establish Peer Authentication Trust Network
source .env && forge script script/InitRemotes.s.sol --rpc-url $SEPOLIA_RPC --broadcast
source .env && forge script script/InitRemotes.s.sol --rpc-url $ARBITRUM_SEPOLIA_RPC --broadcast

4. Activate the Relayer Nerve Center

# Launch the background observer to ferry signals in real-time
npm run relayer

5. Dive into the NexBridge UI

Navigate to 👉 http://localhost:5173 to interact with your freshly spawned cross-chain network via MetaMask. No complex configurations needed; the UI orchestrates the entire bridge flawlessly.

---

🤝 Contributing & License

• This open-source demo aims to lower the barrier for aspiring blockchain developers entering the realm of top-tier cross-chain infrastructure.
• Always ensure forge test coverage passes before submitting PRs.
• License: MIT