Ethereum ↔ Osmosis Universal Cross-Chain Token Bridge (Lock & Mint)

A full-stack, bidirectional multi-token cross-chain bridge connecting Ethereum Sepolia and Osmosis Testnet (osmo-test-5) using a lock-and-mint architecture.

• Universal Multi-Token Support: Bridge any ERC-20 token on Sepolia (e.g., TT, LINK, USDC) to Osmosis without redeploying contracts.
• Dynamic Osmosis Token Factory: Wrapped denoms (factory/<relayer>/<denom>) are created and managed on-demand with native Cosmos SDK bank balances.
• Dynamic Decimal Scaling: Seamlessly converts between EVM 18-decimal tokens and Cosmos / 6-decimal tokens (e.g., USDC).
• Fault-Tolerant Relayer: Autonomous event listeners with state persistence, isolated retry loops, and automatic startup recovery for pending unlocks.
• Modern Web Interface: Built with React, TypeScript, and Vite with dual-wallet integration (MetaMask & Keplr).

---

🏗 Architecture

sequenceDiagram
    autonumber
    actor U as User
    participant ERC20 as ERC-20 (Sepolia)
    participant BL as BridgeLock (Sepolia Gateway)
    participant R as Relayer (Off-Chain)
    participant TF as Osmosis Token Factory
    participant OW as Osmosis Wallet

    rect rgb(235,245,255)
    note over U,OW: Forward Flow: Sepolia -> Osmosis (Lock & Mint)
    U->>ERC20: approve(BridgeLock, amount)
    U->>BL: lock(tokenAddress, amount, osmoRecipient)
    BL->>BL: Escrow tokens in contract
    BL-->>R: emit Locked(nonce, token, sender, osmoRecipient, amount)
    R->>TF: Auto-create denom if first time & MsgMint wrapped tokens
    TF-->>OW: Credit factory/<relayer>/<token> to recipient
    end

    rect rgb(255,245,235)
    note over U,OW: Reverse Flow: Osmosis -> Sepolia (Burn & Unlock)
    OW->>R: MsgSend(wrappedToken, amount -> relayer, memo = evmRecipient)
    R->>TF: MsgBurn(wrappedToken, amount)
    R->>BL: unlock(tokenAddress, evmRecipient, amount, osmoBurnTxHash)
    BL-->>U: Release escrowed ERC-20 tokens to recipient
    end

Loading

---

📦 Project Structure

Directory / File	Description
ethereum/	Solidity smart contracts using Foundry (BridgeLock.sol, TestToken.sol, deploy scripts, and tests).
offchain/	TypeScript relayer service with dynamic denom factory, multi-token watcher, and CLI scripts.
frontend/	Web application built with React + Vite + TypeScript, supporting MetaMask and Keplr.
verify/	Local verification scripts for Anvil and Osmosis protobuf checks.

---

⚙️ Key Features & Innovations

1. Dynamic Token Denom Creation

When bridging a new ERC-20 token for the first time, the relayer queries the token's metadata on Ethereum, dynamically registers a new Token Factory subdenom on Osmosis (factory/<relayer>/<subdenom>), sets its on-chain display metadata, and mints the wrapped asset to the user.

2. Multi-Decimal Precision Normalization

• Supports standard 18-decimal ERC-20 tokens (e.g. TT, LINK).
• Supports 6-decimal tokens (e.g. USDC).
• Automatically handles unit conversion and display scaling across both EVM and Cosmos environments.

3. Fault-Tolerant Relayer & Startup Auto-Recovery

• Independent Loops: EVM event listener and Osmosis block scanner operate in isolated try-catch scopes to prevent RPC timeouts on one chain from affecting the other.
• Replay Protection: Dual-layer protection using on-chain processedBurns mapping on Sepolia and persistent offchain/state.json.
• Startup Sync (retryPendingUnlocks): On reboot, the relayer audits past burned transactions and automatically executes any pending Sepolia unlocks that were interrupted by RPC rate limits.

---

🚀 Getting Started

Prerequisites

• Foundry (forge, cast)
• Node.js (v20+)
• Funded Sepolia Testnet account (EVM)
• Funded Osmosis Testnet account (osmo-test-5)

Installation

# 1. Clone the repository
git clone https://github.com/Yourmix0x/cross-chain.git
cd cross-chain

# 2. Setup Foundry & Ethereum Contracts
cd ethereum
forge install
forge build
forge test

# 3. Setup Relayer & Dependencies
cd ../offchain
npm install

# 4. Setup Frontend
cd ../frontend
npm install

Environment Configuration

Copy .env.example to .env in the root directory and fill in your keys:

cp .env.example .env

Key configuration variables:

• SEPOLIA_RPC_URL: Sepolia JSON-RPC endpoint (e.g., Alchemy / Infura).
• DEPLOYER_PRIVATE_KEY: Private key for deploying contracts.
• RELAYER_EVM_PRIVATE_KEY: Relayer's Ethereum private key.
• RELAYER_OSMO_MNEMONIC: 24-word seed phrase for Osmosis relayer account.
• BRIDGE_LOCK_ADDRESS: Address of the deployed BridgeLock.sol.
• TOKEN_ADDRESS: Address of the ERC-20 token on Sepolia.

---

🔄 Running the Bridge

1. Start the Off-Chain Relayer

cd offchain
npm run relayer

2. Launch the Web Interface

cd frontend
npm run dev

Open http://localhost:5173 in your browser to interact with the bridge using MetaMask and Keplr.

---

🌐 Deploying to Vercel

The frontend is fully configured for deployment on Vercel:

1. Import the repository in your Vercel Dashboard.
2. Set the Root Directory to frontend.
3. Vercel will automatically detect Vite and configure the build settings (npm run build, output: dist).
4. Click Deploy.

---

🛡 Security & Design Scope

• Lock & Mint Model: Native tokens are escrowed safely on Ethereum; wrapped tokens are minted exclusively through the Osmosis Token Factory module.
• POC Notice: This bridge is designed for demonstration and testnet purposes. For mainnet production, multi-relayer MPC / threshold signatures and timelocked circuit breakers should be incorporated.