398 lines
9.8 KiB
Markdown
398 lines
9.8 KiB
Markdown
|
# 🌐 Multi-Chain Deployment Guide - Complete Package
|
||
|
|
|
||
|
|
**Version**: 1.0
|
||
|
|
**Last Updated**: 2026-01-24
|
||
|
|
**Status**: ✅ Foundation Complete - Ready for Expansion
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📋 **Table of Contents**
|
||
|
|
|
||
|
|
1. [Overview](#overview)
|
||
|
|
2. [Architecture](#architecture)
|
||
|
|
3. [Deployment Checklist](#deployment-checklist)
|
||
|
|
4. [Chain-Specific Guides](#chain-specific-guides)
|
||
|
|
5. [Hyperledger Integration](#hyperledger-integration)
|
||
|
|
6. [Admin Dashboard Configuration](#admin-dashboard-configuration)
|
||
|
|
7. [Testing & Verification](#testing--verification)
|
||
|
|
8. [Troubleshooting](#troubleshooting)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🎯 **Overview**
|
||
|
|
|
||
|
|
This guide covers the complete deployment of the Universal Cross-Chain Asset Hub across:
|
||
|
|
|
||
|
|
- **10 EVM Chains**: ChainID 138, Ethereum, Polygon, Arbitrum, Optimism, Base, Avalanche, BSC, XDC, Alltra
|
||
|
|
- **8 Non-EVM Chains**: XRPL, Stellar, Algorand, Hedera, Tron, TON, Cosmos, Solana
|
||
|
|
- **4 Hyperledger Frameworks**: Firefly, Cacti, Fabric, Indy
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🏗️ **Architecture**
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────┐
|
||
|
|
│ Universal Bridge Router │
|
||
|
|
│ (BridgeOrchestrator + ChainRegistry) │
|
||
|
|
└──────────────────────┬────────────────────────────────────────┘
|
||
|
|
│
|
||
|
|
┌──────────────┼──────────────┐
|
||
|
|
│ │ │
|
||
|
|
┌───────▼──────┐ ┌────▼──────┐ ┌─────▼──────────┐
|
||
|
|
│ EVM Adapters│ │Non-EVM │ │ Hyperledger │
|
||
|
|
│ │ │Adapters │ │ Adapters │
|
||
|
|
│ - XDC │ │- XRPL │ │- Firefly │
|
||
|
|
│ - Alltra │ │- Stellar │ │- Cacti │
|
||
|
|
│ - Polygon │ │- Algorand │ │- Fabric │
|
||
|
|
│ - etc. │ │- etc. │ │- Indy │
|
||
|
|
└──────────────┘ └───────────┘ └────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## ✅ **Deployment Checklist**
|
||
|
|
|
||
|
|
### **Phase 1: Core Infrastructure** ✅
|
||
|
|
|
||
|
|
- [x] ChainRegistry contract
|
||
|
|
- [x] IChainAdapter interface
|
||
|
|
- [x] XDC adapter
|
||
|
|
- [x] Alltra adapter
|
||
|
|
- [x] XRPL adapter
|
||
|
|
- [x] Firefly adapter
|
||
|
|
|
||
|
|
### **Phase 2: Remaining EVM Chains** ⚠️
|
||
|
|
|
||
|
|
- [ ] Standard EVM adapter template
|
||
|
|
- [ ] Polygon deployment script
|
||
|
|
- [ ] Arbitrum deployment script
|
||
|
|
- [ ] Optimism deployment script
|
||
|
|
- [ ] Base deployment script
|
||
|
|
- [ ] Avalanche deployment script
|
||
|
|
- [ ] BSC deployment script
|
||
|
|
- [ ] Ethereum Mainnet deployment script
|
||
|
|
|
||
|
|
### **Phase 3: Non-EVM Chains** ⚠️
|
||
|
|
|
||
|
|
- [ ] Stellar adapter + oracle service
|
||
|
|
- [ ] Algorand adapter + oracle service
|
||
|
|
- [ ] Hedera adapter + oracle service
|
||
|
|
- [ ] Tron adapter + oracle service
|
||
|
|
- [ ] TON adapter + oracle service
|
||
|
|
- [ ] Cosmos adapter (IBC integration)
|
||
|
|
- [ ] Solana adapter (Wormhole integration)
|
||
|
|
|
||
|
|
### **Phase 4: Hyperledger** ⚠️
|
||
|
|
|
||
|
|
- [x] Firefly adapter + service client
|
||
|
|
- [ ] Cacti adapter + connector service
|
||
|
|
- [ ] Fabric chaincode + adapter + listener
|
||
|
|
- [ ] Indy verifier contract + agent service
|
||
|
|
|
||
|
|
### **Phase 5: Deployment Automation** ⚠️
|
||
|
|
|
||
|
|
- [x] Deployment orchestrator script
|
||
|
|
- [ ] Per-chain deployment scripts
|
||
|
|
- [ ] Configuration templates
|
||
|
|
- [ ] Verification scripts
|
||
|
|
|
||
|
|
### **Phase 6: Admin Dashboard** ⚠️
|
||
|
|
|
||
|
|
- [ ] Chain management UI
|
||
|
|
- [ ] Deployment status dashboard
|
||
|
|
- [ ] Bridge monitoring
|
||
|
|
- [ ] Configuration templates UI
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🔗 **Chain-Specific Guides**
|
||
|
|
|
||
|
|
### **XDC Network (Chain ID 50)**
|
||
|
|
|
||
|
|
**Status**: ✅ Adapter Created
|
||
|
|
|
||
|
|
**Deployment Steps**:
|
||
|
|
|
||
|
|
1. Deploy XDCAdapter:
|
||
|
|
```bash
|
||
|
|
forge script script/deploy/adapters/DeployXDCAdapter.s.sol \
|
||
|
|
--rpc-url https://rpc.xinfin.network \
|
||
|
|
--broadcast \
|
||
|
|
--private-key $PRIVATE_KEY
|
||
|
|
```
|
||
|
|
|
||
|
|
2. Register in ChainRegistry:
|
||
|
|
```solidity
|
||
|
|
chainRegistry.registerEVMChain(
|
||
|
|
50,
|
||
|
|
xdcAdapterAddress,
|
||
|
|
"https://explorer.xdc.network",
|
||
|
|
12, // min confirmations
|
||
|
|
2, // avg block time
|
||
|
|
"" // additional data
|
||
|
|
);
|
||
|
|
```
|
||
|
|
|
||
|
|
**Special Notes**:
|
||
|
|
- XDC uses `xdc` prefix instead of `0x`
|
||
|
|
- Adapter includes conversion functions
|
||
|
|
- Very low fees (~0.001 XDC per tx)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### **ALL Mainnet**
|
||
|
|
|
||
|
|
**Status**: ✅ Adapter Created (Chain ID: 651940)
|
||
|
|
|
||
|
|
**Chain Information**:
|
||
|
|
- **Chain ID**: 651940 (0x9f2a4)
|
||
|
|
- **Network Name**: ALL Mainnet
|
||
|
|
- **Native Currency**: ALL (18 decimals)
|
||
|
|
- **RPC**: https://mainnet-rpc.alltra.global
|
||
|
|
- **Explorer**: https://alltra.global
|
||
|
|
- **ChainList**: https://chainlist.org/chain/651940
|
||
|
|
|
||
|
|
**Deployment Steps**:
|
||
|
|
|
||
|
|
1. ✅ Chain ID updated in `AlltraAdapter.sol` (651940)
|
||
|
|
2. ⚠️ Verify CCIP support via CCIP Directory
|
||
|
|
3. ⚠️ Verify LiFi support via LiFi API
|
||
|
|
4. Deploy adapter
|
||
|
|
5. Register in ChainRegistry
|
||
|
|
|
||
|
|
**Configuration Needed**:
|
||
|
|
- [x] Confirm ALL Mainnet Chain ID (651940)
|
||
|
|
- [x] Get RPC endpoint (https://mainnet-rpc.alltra.global)
|
||
|
|
- [x] Get block explorer URL (https://alltra.global)
|
||
|
|
- [ ] Verify CCIP chain selector (if supported)
|
||
|
|
- [ ] Verify USDC deployment on ALL Mainnet
|
||
|
|
- [ ] Update routing logic based on CCIP/LiFi support status
|
||
|
|
|
||
|
|
**Important**: Distinguish between:
|
||
|
|
- **ALL Mainnet** (chain, chainId 651940) - The EVM blockchain
|
||
|
|
- **ALLTRA** (orchestration layer) - The hybrid service layer
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### **XRPL (XRP Ledger)**
|
||
|
|
|
||
|
|
**Status**: ✅ Adapter Created
|
||
|
|
|
||
|
|
**Deployment Steps**:
|
||
|
|
|
||
|
|
1. Deploy XRPLAdapter
|
||
|
|
2. Deploy Oracle Service (monitors XRPL transactions)
|
||
|
|
3. Register in ChainRegistry
|
||
|
|
|
||
|
|
**Oracle Service Requirements**:
|
||
|
|
- Monitor XRPL for bridge transactions
|
||
|
|
- Call `confirmXRPLTransaction()` on adapter
|
||
|
|
- Handle XRP drops conversion
|
||
|
|
|
||
|
|
**XRPL Features**:
|
||
|
|
- Destination tags (for exchanges)
|
||
|
|
- Very low fees (~0.000012 XRP)
|
||
|
|
- Fast finality (3-5 seconds)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### **Hyperledger Firefly**
|
||
|
|
|
||
|
|
**Status**: ✅ Adapter + Service Client Created
|
||
|
|
|
||
|
|
**Infrastructure**: ✅ VMIDs 6202, 6203 deployed
|
||
|
|
|
||
|
|
**Deployment Steps**:
|
||
|
|
|
||
|
|
1. Initialize Firefly on VMID 6202:
|
||
|
|
```bash
|
||
|
|
ssh root@192.168.11.175
|
||
|
|
ff init alltra-bridge --multiparty
|
||
|
|
```
|
||
|
|
|
||
|
|
2. Connect to Besu (ChainID 138):
|
||
|
|
```bash
|
||
|
|
ff accounts create --key /path/to/besu/key.json
|
||
|
|
```
|
||
|
|
|
||
|
|
3. Deploy FireflyAdapter contract
|
||
|
|
|
||
|
|
4. Configure Firefly namespace in adapter
|
||
|
|
|
||
|
|
5. Start Firefly event listener service
|
||
|
|
|
||
|
|
**Firefly Configuration**:
|
||
|
|
```yaml
|
||
|
|
# firefly/config/firefly.core.yml
|
||
|
|
namespaces:
|
||
|
|
predefined:
|
||
|
|
- name: alltra-bridge
|
||
|
|
plugins:
|
||
|
|
blockchain:
|
||
|
|
- ethereum:
|
||
|
|
ethconnect:
|
||
|
|
url: http://192.168.11.172:8545
|
||
|
|
tokens:
|
||
|
|
- erc20_erc721
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🔧 **Hyperledger Integration**
|
||
|
|
|
||
|
|
### **Cacti (VMID 5201)**
|
||
|
|
|
||
|
|
**Status**: ⚠️ Needs Adapter
|
||
|
|
|
||
|
|
**Deployment Steps**:
|
||
|
|
|
||
|
|
1. Install Cacti API server on VMID 5201
|
||
|
|
2. Configure Besu connector plugin
|
||
|
|
3. Configure Fabric connector plugin (if needed)
|
||
|
|
4. Deploy CactiAdapter contract
|
||
|
|
5. Create Cacti client service
|
||
|
|
|
||
|
|
**Cacti Configuration**:
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"plugins": [
|
||
|
|
{
|
||
|
|
"packageName": "@hyperledger/cactus-plugin-ledger-connector-besu",
|
||
|
|
"options": {
|
||
|
|
"rpcApiHttpHost": "http://192.168.11.172:8545",
|
||
|
|
"instanceId": "alltra-besu-connector"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### **Fabric**
|
||
|
|
|
||
|
|
**Status**: ⚠️ Needs Network Deployment
|
||
|
|
|
||
|
|
**Required Infrastructure**:
|
||
|
|
- [ ] Deploy Fabric network (peers, orderers, CAs)
|
||
|
|
- [ ] Create bridge-channel
|
||
|
|
- [ ] Deploy bridge chaincode
|
||
|
|
- [ ] Create Fabric event listener
|
||
|
|
- [ ] Deploy FabricAdapter contract
|
||
|
|
|
||
|
|
**Fabric Chaincode** (Go):
|
||
|
|
```go
|
||
|
|
// fabric/chaincode/bridge/bridge.go
|
||
|
|
// See implementation guide for full code
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### **Indy**
|
||
|
|
|
||
|
|
**Status**: ⚠️ Needs Network Deployment
|
||
|
|
|
||
|
|
**Required Infrastructure**:
|
||
|
|
- [ ] Deploy Indy steward nodes
|
||
|
|
- [ ] Create credential schemas
|
||
|
|
- [ ] Deploy IndyVerifier contract
|
||
|
|
- [ ] Create Indy verifier agent
|
||
|
|
|
||
|
|
**Use Cases**:
|
||
|
|
- KYC verification for bridge
|
||
|
|
- Accredited investor status
|
||
|
|
- Jurisdiction compliance
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🎛️ **Admin Dashboard Configuration**
|
||
|
|
|
||
|
|
### **Chain Management UI**
|
||
|
|
|
||
|
|
**Location**: `frontend-dapp/src/components/admin/ChainManagement.tsx`
|
||
|
|
|
||
|
|
**Features Needed**:
|
||
|
|
- Add/remove chains
|
||
|
|
- Enable/disable chains
|
||
|
|
- View chain status
|
||
|
|
- Configure adapters
|
||
|
|
- Test connectivity
|
||
|
|
|
||
|
|
### **Deployment Dashboard**
|
||
|
|
|
||
|
|
**Features Needed**:
|
||
|
|
- View deployment status per chain
|
||
|
|
- Trigger deployments
|
||
|
|
- View contract addresses
|
||
|
|
- Monitor deployment progress
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🧪 **Testing & Verification**
|
||
|
|
|
||
|
|
### **Unit Tests**
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Test adapters
|
||
|
|
forge test --match-contract XDCAdapter
|
||
|
|
forge test --match-contract XRPLAdapter
|
||
|
|
forge test --match-contract FireflyAdapter
|
||
|
|
```
|
||
|
|
|
||
|
|
### **Integration Tests**
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Test cross-chain flows
|
||
|
|
forge test --match-path test/integration/MultiChainBridge.t.sol
|
||
|
|
```
|
||
|
|
|
||
|
|
### **Verification**
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Verify contracts on each chain
|
||
|
|
forge verify-contract <ADDRESS> <CONTRACT> \
|
||
|
|
--chain-id <CHAIN_ID> \
|
||
|
|
--etherscan-api-key <KEY>
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🐛 **Troubleshooting**
|
||
|
|
|
||
|
|
### **Common Issues**
|
||
|
|
|
||
|
|
1. **Adapter Not Found**
|
||
|
|
- Check ChainRegistry registration
|
||
|
|
- Verify adapter address
|
||
|
|
- Check adapter is active
|
||
|
|
|
||
|
|
2. **Oracle Not Confirming**
|
||
|
|
- Check oracle service is running
|
||
|
|
- Verify oracle has ORACLE_ROLE
|
||
|
|
- Check event logs
|
||
|
|
|
||
|
|
3. **Firefly Not Responding**
|
||
|
|
- Check Firefly service status
|
||
|
|
- Verify namespace configuration
|
||
|
|
- Check WebSocket connection
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📚 **Additional Resources**
|
||
|
|
|
||
|
|
- [Chain Registry Documentation](./CHAIN_REGISTRY.md)
|
||
|
|
- [Adapter Development Guide](./ADAPTER_DEVELOPMENT.md)
|
||
|
|
- [Hyperledger Integration Guide](./HYPERLEDGER_INTEGRATION.md)
|
||
|
|
- [Oracle Service Setup](./ORACLE_SERVICE_SETUP.md)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## ✅ **Summary**
|
||
|
|
|
||
|
|
**Foundation Complete**: ✅
|
||
|
|
**Ready for Expansion**: ✅
|
||
|
|
**Next Priority**: Complete remaining adapters and deployment automation
|
||
|
|
|
||
|
|
This deployment package provides everything needed to expand the Universal Bridge to **22+ chains** across EVM, non-EVM, and enterprise blockchain ecosystems.
|