metamask-integration/docs/BRIDGE_INTEGRATION_GUIDE.md

Bridge Integration Guide for ChainID 138

Complete guide for integrating bridge functionality with MetaMask on ChainID 138.

Overview

This guide covers bridge integration options for ChainID 138, enabling users to transfer assets between ChainID 138 and other networks.

Bridge Options

Option 1: Partner with Existing Bridge Providers

Recommended Providers

1. LayerZero

   • Cross-chain messaging protocol
   • Supports multiple chains
   • Well-established infrastructure
   • Contact: https://layerzero.network

2. Wormhole

   • Cross-chain bridge protocol
   • Supports 30+ chains
   • Security audited
   • Contact: https://wormhole.com

3. Axelar

   • Cross-chain communication
   • Supports multiple chains
   • Developer-friendly
   • Contact: https://axelar.network

4. Stargate

   • LayerZero-based bridge
   • Optimized for stablecoins
   • High liquidity
   • Contact: https://stargate.finance

Integration Steps

1. Contact Bridge Provider:

   • Request ChainID 138 integration
   • Provide network information
   • Discuss integration requirements

2. Technical Requirements:

   • RPC endpoints (provided)
   • Token contracts (deployed)
   • Network stability (verified)
   • Security audit (if required)

3. Integration Process:

   • Deploy bridge contracts on ChainID 138
   • Configure bridge endpoints
   • Test bridge functionality
   • Launch bridge

Option 2: Implement Custom Bridge

Architecture

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│  ChainID 1  │ ──────► │ Bridge Router│ ◄────── │  ChainID    │
│ (Ethereum)  │         │              │         │    138       │
└─────────────┘         └──────────────┘         └─────────────┘
                              │
                              ▼
                        ┌──────────────┐
                        │  Validators  │
                        │  / Relayers  │
                        └──────────────┘

Components

1. Lockbox Contract (ChainID 138)

   • Locks tokens on source chain
   • Emits lock events
   • Handles unlocks

2. Inbox Contract (Destination Chain)

   • Receives bridge messages
   • Mints/burns tokens
   • Validates messages

3. Bridge Router

   • Routes messages between chains
   • Validates transactions
   • Manages liquidity

4. Relayer Network

   • Monitors lock events
   • Submits unlock transactions
   • Provides redundancy

Implementation Steps

1. Deploy Contracts:

   # Deploy Lockbox on ChainID 138
   forge script script/bridge/DeployLockbox.s.sol --rpc-url $RPC_URL_138
   
   # Deploy Inbox on destination chain
   forge script script/bridge/DeployInbox.s.sol --rpc-url $DEST_RPC
   

2. Configure Bridge:

   • Set up relayer network
   • Configure message routing
   • Set up monitoring

3. Security Audit:

   • Conduct security audit
   • Fix identified issues
   • Deploy audited contracts

4. Testing:

   • Test bridge functionality
   • Test edge cases
   • Test security scenarios

Option 3: Use Bridge Aggregator

Aggregators

1. Socket.tech

   • Bridge aggregator
   • Supports multiple bridges
   • Best route selection
   • Integration: https://docs.socket.tech

2. LI.FI

   • Cross-chain bridge aggregator
   • Supports 30+ chains
   • SDK available
   • Integration: https://docs.li.fi

3. Bungee Exchange

   • Bridge aggregator
   • Supports multiple chains
   • Simple integration
   • Integration: https://docs.bungee.exchange

MetaMask Bridge Integration

Requirements

1. Bridge Provider Partnership:

   • Partner with bridge provider
   • Get bridge API access
   • Configure bridge endpoints

2. Token Support:

   • Supported tokens on both chains
   • Liquidity on both sides
   • Token metadata complete

3. Security:

   • Security audit completed
   • Monitoring in place
   • Risk management

4. Consensys Approval:

   • Submit bridge for MetaMask approval
   • Provide security documentation
   • Complete integration review

Integration Process

1. Phase 1: Bridge Setup (Month 1-2)

   • Deploy bridge contracts
   • Configure bridge endpoints
   • Test bridge functionality

2. Phase 2: Security Audit (Month 2-3)

   • Conduct security audit
   • Fix identified issues
   • Deploy audited contracts

3. Phase 3: MetaMask Integration (Month 3-6)

   • Submit to MetaMask
   • Complete integration review
   • Test MetaMask integration
   • Launch bridge

Bridge Configuration

Supported Tokens

• cUSDT: Bridgeable to/from Ethereum Mainnet
• cUSDC: Bridgeable to/from Ethereum Mainnet
• WETH: Bridgeable to/from Ethereum Mainnet
• LINK: Bridgeable to/from Ethereum Mainnet

Bridge Fees

• Bridge Fee: 0.1% - 0.5% (configurable)
• Gas Fees: Paid by user
• Relayer Fees: Included in bridge fee

Bridge Limits

• Minimum: 1 token (or equivalent)
• Maximum: Based on liquidity
• Daily Limit: Configurable per token

Testing

Test Scenarios

1. Basic Bridge:

   • Bridge tokens from ChainID 138 to Ethereum
   • Bridge tokens from Ethereum to ChainID 138
   • Verify balances on both chains

2. Edge Cases:

   • Bridge minimum amount
   • Bridge maximum amount
   • Bridge during high congestion
   • Bridge with failed transactions

3. Security:

   • Test invalid messages
   • Test replay attacks
   • Test double-spend prevention
   • Test validator rotation

Monitoring

Metrics to Monitor

• Bridge transaction volume
• Bridge success rate
• Bridge fees collected
• Bridge latency
• Liquidity levels
• Security events

Alerts

• Failed bridge transactions
• Low liquidity warnings
• Security incidents
• High latency alerts

Documentation

User Documentation

• How to bridge tokens
• Bridge fees and limits
• Bridge time estimates
• Troubleshooting guide

Developer Documentation

• Bridge API documentation
• Integration examples
• SDK documentation
• Contract addresses

Support

User Support

• Bridge transaction issues
• Bridge fee questions
• Bridge time questions
• Troubleshooting

Developer Support

• Integration help
• API questions
• Contract questions
• Testing support

---

Last Updated: 2026-01-26