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

```bash
# 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

```bash
# 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

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

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

### Start Frontend

```bash
cd frontend-dapp
npm run dev
```

## Documentation

- [Implementation Summary](./IMPLEMENTATION_SUMMARY.md) - Overview of all components
- [API Documentation](./API_DOCUMENTATION.md) - Complete API reference
- [Deployment Guide](./DEPLOYMENT_GUIDE.md) - Step-by-step deployment instructions
- [Runbook](./RUNBOOK.md) - Operations and troubleshooting guide
- [Dodoex PMM Next Steps](./DODO_PMM_NEXT_STEPS.md) - Token coverage and swap+bridge+swap setup
- [CCIP and SwapBridgeSwapCoordinator](./trustless/CCIP_AND_SWAP_BRIDGE_COORDINATOR.md) - 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