# 🌐 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.
