BlockBridge — Cross-Chain Token Bridge Script for EVM Blockchains

A ready-to-deploy cross-chain bridge built on Hyperlane — connect any two EVM chains with a custom frontend and auditable smart contracts.

---

What Is BlockBridge?

BlockBridge is a complete bridge script that lets users transfer tokens between two EVM-compatible blockchains. It includes the smart contracts, a Next.js frontend, and deployment scripts needed to run a cross-chain token bridge on your own chains.

It is built on top of Hyperlane, a permissionless interoperability protocol. BlockBridge provides a custom bridge UI and custom warp route contracts — you are not locked into any third-party frontend or hosted service.

This is a full-source purchase. You receive all Solidity contracts, the complete Next.js frontend, deployment scripts, and configuration files. You can modify, rebrand, and deploy everything yourself.

---

What's Included

Smart Contracts (Solidity / Foundry)

• BlockBridgeHypNative — Lock native tokens (ETH, BNB, etc.) on the origin chain, mint a synthetic wrapped version on the destination chain
• BlockBridgeHypERC20 — Mint and burn synthetic ERC20 tokens on the destination chain
• BlockBridgeHypERC20Collateral — Lock an existing ERC20 token on the origin chain, mint a synthetic on the destination
• BlockBridgeMultisigISM — Interchain Security Module for multisig message verification
• BlockBridgeIGP — Interchain gas payment hook
• Foundry test suite (unit tests, integration tests, security tests, fork tests)
• Deployment scripts (forge create and cast send commands)

Frontend (Next.js 14 / React / Tailwind CSS)

• Bridge page with chain selector, token selector, amount input, fee estimation, and transfer review
• Transaction history page with message delivery tracking
• Wallet connection via WalletConnect / AppKit (MetaMask, Coinbase Wallet, WalletConnect, etc.)
• Automatic chain switching prompts
• ERC20 token approval flow (approve then bridge)
• Real-time fee quoting from on-chain quoteTransferRemote()
• Balance validation (prevents submitting transfers that exceed wallet balance)
• Documentation page with deployment guide
• Responsive, dark-themed UI
• Crypto icons via @blockshark/crypto-icons

Configuration & Scripts

• Chain configuration files (add any EVM chain)
• Token configuration files
• Warp route mapping
• Wagmi + viem chain definitions
• Shell deployment scripts for testnet

---

Supported Token Types

Type	How It Works	Example
Native	Lock native gas token on Chain A, mint wrapped synthetic on Chain B	ETH on Ethereum → wETH on your L2
ERC20 Collateral	Lock an existing ERC20 on Chain A, mint synthetic on Chain B	USDC on Ethereum → USDC on your L2
Synthetic	Burn synthetic on Chain B, unlock original on Chain A	wETH on your L2 → ETH on Ethereum

All three types support bidirectional bridging when routers are enrolled on both chains.

---

How It Works

BlockBridge uses Hyperlane's messaging protocol for cross-chain communication. Here is the flow for a bridge transfer:

1. User initiates transfer — Calls transferRemote() on the origin chain warp contract. Tokens are locked (native/collateral) or burned (synthetic).
2. Message dispatched — The warp contract sends a message to the Hyperlane Mailbox on the origin chain.
3. Validators sign — Hyperlane validators observe the message and sign a checkpoint.
4. Relayer delivers — A relayer submits the signed message to the destination chain Mailbox.
5. Tokens received — The destination Mailbox verifies the message via the ISM, then calls the destination warp contract, which mints or unlocks tokens to the recipient.

Transfer time is typically 2–5 minutes depending on chain finality and relayer speed.

---

Security Features

These are the security features implemented in the contracts:

• Pausable — Owner can pause all transfers on any warp contract (emergency stop)
• Reentrancy Guard — On HypNative to prevent reentrancy during native token transfers
• Transfer Caps — Configurable maximum transfer amount on HypNative
• Zero-Address Validation — All handle() functions reject the zero address as recipient
• Configurable ISM — Each contract exposes an interchain security module the Mailbox checks before delivering messages
• Router Enrollment — Only whitelisted remote routers can send messages to each contract
• Ownable — All contracts have an owner who can configure security settings and transfer ownership to a multisig

---

What You Need to Deploy

Requirements

• Two EVM chains — Any combination of L1, L2, or L3 (Ethereum, BSC, Arbitrum, Optimism, Base, Polygon, your own appchain, etc.)
• Hyperlane Mailbox on each chain — Many major chains already have one (check the registry). For custom chains, you can deploy a Mailbox using the Hyperlane CLI.
• Deployer wallet — With native gas tokens on both chains
• Node.js 18+ and pnpm — For the frontend
• Foundry — For compiling, testing, and deploying contracts
• WalletConnect Project ID — Free from WalletConnect Cloud (for wallet connection in the UI)

For Production

• Validators and relayer — For supported chains (Ethereum, BSC, Arbitrum, etc.) Hyperlane runs public infrastructure. For custom chains, you need to run your own validator(s) and relayer.
• Multisig wallet — Gnosis Safe or similar, for contract ownership
• Security audit — Recommended before handling real value

---

Tech Stack

Layer	Technology
Smart Contracts	Solidity, OpenZeppelin, Foundry
Protocol	Hyperlane (permissionless interoperability)
Frontend	Next.js 14, React 18, TypeScript
Styling	Tailwind CSS, Framer Motion
Wallet	Reown AppKit (WalletConnect v2), wagmi, viem
State	Zustand
Icons	@blockshark/crypto-icons
Testing	Foundry (contracts), Vitest (frontend)

---

What You Can Customize

• Chains — Add any EVM chain by editing config files (chain ID, RPC, domain ID, explorer)
• Tokens — Add any ERC20 or native token with corresponding warp route contracts
• Branding — Change logo, name, colors, fonts — all in config files and CSS variables
• Theme — Dark theme included, all colors are CSS custom properties you can change
• Security settings — Transfer caps, ISM configuration, pause/unpause per contract

---

Installation Service

Don't want to set it up yourself? The web3.market support team offers a full installation service for you.

What's included:

• Deploy all smart contracts to your chosen chains
• Configure and enroll remote routers
• Set up the frontend with your branding, chains, and tokens
• Deploy the frontend to Vercel or your preferred hosting
• Verify contracts on block explorers
• Walk you through the admin panel (pause, transfer caps, ownership)

To request installation, contact the support team through web3.market.

---

What This Is Not

• This is not a hosted service — you deploy and run everything yourself (or use our $500 installation service)
• This is not a no-code solution — deployment requires Solidity and Next.js knowledge (or use our installation service)
• This does not include validators or relayers — for chains where Hyperlane doesn't run public infrastructure, you'll need to run your own (Docker configs are referenced in the docs)
• This has not been professionally audited — the contracts include a comprehensive test suite but you should arrange your own audit before mainnet use with real value

---

File Overview

blockbridge/
├── contracts/
│   ├── src/
│   │   ├── warp/
│   │   │   ├── BlockBridgeHypNative.sol
│   │   │   ├── BlockBridgeHypERC20.sol
│   │   │   └── BlockBridgeHypERC20Collateral.sol
│   │   ├── isms/
│   │   │   └── BlockBridgeMultisigISM.sol
│   │   └── hooks/
│   │       └── BlockBridgeIGP.sol
│   ├── test/
│   │   ├── unit/          (WarpRoute, MultisigISM, Security, Mailbox)
│   │   ├── integration/   (CrossChainTransfer)
│   │   └── fork/          (ForkBridgeTest)
│   └── script/            (DeployCore, DeployWarpRoute, ConfigureISM)
│
├── bridge-ui/
│   ├── src/
│   │   ├── app/           (pages: bridge, transactions, docs)
│   │   ├── components/    (bridge UI, wallet, transactions, layout)
│   │   ├── config/        (chains, tokens, warpRoutes, theme)
│   │   ├── hooks/         (useBridge, useTokenBalance, useGasEstimate, etc.)
│   │   ├── lib/           (wagmi config, viem clients, hyperlane utils)
│   │   ├── store/         (Zustand bridge state)
│   │   └── types/         (TypeScript interfaces)
│   ├── public/            (chain logos, assets)
│   └── tailwind.config.ts
│
├── config/                (chain address configs)
├── scripts/               (deployment shell scripts)
└── documentation.html