76143a8fe3
- Expand token-aggregation API (report routes), canonical tokens, pools - Add flash vault contracts + tests (indexed, DODO cwUSDC, XAUT borrow) - PMM pools JSON, deploy/export scripts, metamask verified list Co-authored-by: Cursor <cursoragent@cursor.com>
403 lines
11 KiB
Markdown
403 lines
11 KiB
Markdown
# 🌐 Multi-Chain Deployment Guide - Complete Package
|
||
|
||
**Version**: 1.0
|
||
**Last Updated**: 2026-05-09
|
||
**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) — optional streams **A–E**: [COSMOS_ECOSYSTEM_CHAIN138_OPTIONAL_INTEGRATIONS_RUNBOOK.md](../../../docs/11-references/COSMOS_ECOSYSTEM_CHAIN138_OPTIONAL_INTEGRATIONS_RUNBOOK.md), [`config/cosmos-chain138-optional/README.md`](../../../config/cosmos-chain138-optional/README.md)
|
||
- [ ] 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**: `6200` is the only validated FireFly runtime, `6201` is retired / standby, and `6202` / `6203` are not deployed in the current cluster.
|
||
|
||
**Deployment Steps**:
|
||
|
||
1. Initialize FireFly only after confirming `6200` is healthy and intentionally in scope:
|
||
```bash
|
||
ssh root@192.168.11.35
|
||
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
|
||
```
|
||
|
||
For current runtime truth, prefer [docs/03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md](../../../docs/03-deployment/DBIS_HYPERLEDGER_RUNTIME_STATUS.md).
|
||
|
||
---
|
||
|
||
## 🔧 **Hyperledger Integration**
|
||
|
||
### **Cacti (VMIDs 5200 / 5201 / 5202)**
|
||
|
||
**Status**: ⚠️ Needs Adapter
|
||
|
||
**Infrastructure**: `5200` is the primary Cacti / Besu connector node. `5201` and `5202` are the live Alltra/HYBX public Cacti surfaces and each also exposes a local Hyperledger Cacti API on `:4000`.
|
||
|
||
**Deployment Steps**:
|
||
|
||
1. Maintain the core connector deployment on VMID `5200`.
|
||
2. Keep VMIDs `5201` and `5202` healthy for the public Alltra/HYBX Cacti surfaces and local `:4000` APIs.
|
||
3. Configure the Besu connector plugin.
|
||
4. Configure the Fabric connector plugin if needed.
|
||
5. Deploy the `CactiAdapter` contract.
|
||
6. Create the 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**
|
||
|
||
- [Current Contract and Infrastructure Inventory](../MASTER_CONTRACTS_AND_INFRASTRUCTURE_LIST.md)
|
||
- [Tezos Adapter Production Checklist](../bridge/TEZOS_ADAPTER_PRODUCTION_CHECKLIST.md)
|
||
- [Integration Guide](../guides/INTEGRATION_GUIDE.md)
|
||
- [Oracle and Keeper Chain 138](../integration/ORACLE_AND_KEEPER_CHAIN138.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.
|