smom-dbis-138/docs/bridge/README.md

ChainID 138 Interoperability Bridge

Production-grade, extensible interoperability system enabling users to bridge and swap tokens from Chain 138 to EVM chains, XRPL, and Hyperledger Fabric networks.

Features

• Multi-Rail Support: Bridge to EVM chains (Polygon, Optimism, Base, Arbitrum, etc.), XRPL, and Fabric
• Native & Wrapped XRP: Support for both native XRP delivery and wrapped XRP (wXRP)
• HSM Security: Hardware Security Module integration for critical operations
• Route Intelligence: Multi-route quoting with health scoring and optimization
• Compliance Ready: Identity-gated routing with Verifiable Credentials support
• Enterprise Grade: Proof-of-reserves, multi-attestor quorum, comprehensive monitoring

Quick Start

Prerequisites

• Node.js 18+
• Foundry (for smart contracts)
• Chain 138 node access
• thirdweb account (for EVM bridges)

Installation

# Clone repository
git clone <repo-url>
cd smom-dbis-138

# Install dependencies
npm install
cd frontend-dapp && npm install && cd ..

# Set up environment
cp config/bridge.config.example.ts config/bridge.config.ts
# Edit config/bridge.config.ts with your values

Deploy Contracts

# Set environment variables
export CHAIN_138_RPC_URL=http://localhost:8545
export DEPLOYER_PRIVATE_KEY=0x...
export ADMIN_ADDRESS=0x...

# Deploy
./scripts/deployment/deploy-bridge-contracts.sh

Run Tests

# Test smart contracts
forge test --match-path test/bridge/interop/*

# Test integration
forge test --match-path test/bridge/interop/Integration.t.sol

Start Frontend

cd frontend-dapp
npm run dev

Documentation

• Implementation Summary - Overview of all components
• API Documentation - Complete API reference
• Deployment Guide - Step-by-step deployment instructions
• Runbook - Operations and troubleshooting guide
• Dodoex PMM Next Steps - Token coverage and swap+bridge+swap setup
• CCIP and SwapBridgeSwapCoordinator - CCIP config and atomic swap-then-bridge coordinator

Architecture

┌─────────────┐
│   Frontend  │
│  (React)    │
└──────┬──────┘
       │
┌──────▼─────────────────┐
│  FireFly Orchestration │
│  - Workflow Engine     │
│  - Quote Service       │
│  - Policy Engine       │
└──────┬─────────────────┘
       │
┌──────▼─────────────────┐
│   Smart Contracts      │
│  - EscrowVault         │
│  - Registry            │
│  - wXRP                │
└──────┬─────────────────┘
       │
┌──────▼─────────────────┐
│   Cacti Connectors     │
│  - EVM Connector       │
│  - XRPL Connector      │
│  - Fabric Connector    │
└────────────────────────┘

Supported Destinations

EVM Chains

• Polygon (137)
• Optimism (10)
• Base (8453)
• Arbitrum (42161)
• Avalanche (43114)
• BNB Chain (56)
• Ethereum (1)
• Monad (when supported)

Non-EVM

• XRPL (Native XRP)
• Hyperledger Fabric

Security

• HSM Integration: All critical operations require HSM signatures
• Multi-Attestor Quorum: Cross-chain verification via weighted attestor system
• Access Control: Role-based access control on all contracts
• Pausability: Emergency pause functionality
• Audit Trail: Comprehensive logging and monitoring

Monitoring

• Metrics: Prometheus metrics for all operations
• Dashboards: Grafana dashboards for visualization
• Alerts: Configurable alerting for critical events
• Logging: Structured logging with transfer ID correlation

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT

Support

• Documentation: docs/bridge/
• Issues: GitHub Issues
• Email: support@chain138.example.com