proxmox/INTEGRATIONS_AND_LIFI_PURCHASE_GUIDE.md

# Complete Integrations List & Li.Fi Purchase Guide
**Date:** 2026-01-31  
**Status:** ✅ Comprehensive Integration & Purchase Workflow Guide

**Implemented (2026-01-31):** Ramp API (metamask-integration) - MoonPay, Ramp, Onramper, Transak, Banxa, Coinbase, Stripe, Cybrid, Sardine, HoneyCoin. Exchange Registry (dbis_core) - Binance, Kraken, Oanda, FXCM. DeFi Router (alltra-lifi-settlement) - 1inch, ParaSwap, 0x. See [INTEGRATIONS_QUICK_REFERENCE.md](INTEGRATIONS_QUICK_REFERENCE.md).

---

## 📋 Table of Contents

1. [All Recommended Integrations](#all-recommended-integrations)
2. [Li.Fi Purchase Workflow](#lifi-purchase-workflow)
3. [Complete Task List](#complete-task-list)
4. [Integration Priority Matrix](#integration-priority-matrix)

---

## 🌐 All Recommended Integrations

### 🔴 Critical Priority Integrations

#### 1. Bridge Providers (Cross-Chain Asset Transfers)

##### Active Bridges ✅
1. **Chainlink CCIP Bridge**
   - **Status:** ✅ Deployed and Active
   - **Router (ChainID 138):** `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e`
   - **Router (Ethereum):** `0x2A0840e5117683b11682ac46f5CF5621E67269E3`
   - **Supported Tokens:** WETH, WETH10, cUSDT, cUSDC, LINK
   - **Fees:** Paid in LINK token
   - **Documentation:** `smom-dbis-138/docs/bridge/`
   - **Use Case:** Primary bridge for ChainID 138 ↔ Ethereum

2. **Bridge Vault (Multi-Chain)**
   - **Status:** ✅ Deployed
   - **Vault Address:** `0x31884f84555210FFB36a19D2471b8eBc7372d0A8`
   - **Supported Tokens:** cUSDT, cUSDC
   - **Destination Chains:** Ethereum, Polygon, BNB Chain
   - **Use Case:** Multi-chain stablecoin bridging

##### Recommended Bridge Providers (Pending Integration) ⚠️

3. **LayerZero**
   - **Type:** Cross-chain messaging protocol
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://layerzero.network
   - **Benefits:** Well-established, supports multiple chains
   - **Integration Steps:**
     - Request ChainID 138 integration
     - Deploy LayerZero contracts
     - Configure endpoints
   - **Priority:** 🔴 High

4. **Wormhole**
   - **Type:** Cross-chain bridge protocol
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://wormhole.com
   - **Benefits:** Supports 30+ chains, security audited
   - **Integration Steps:**
     - Request ChainID 138 integration
     - Deploy Wormhole contracts
     - Configure guardians
   - **Priority:** 🔴 High

5. **Axelar**
   - **Type:** Cross-chain communication
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://axelar.network
   - **Benefits:** Developer-friendly, multiple chains
   - **Integration Steps:**
     - Request ChainID 138 integration
     - Deploy Axelar contracts
     - Configure validators
   - **Priority:** 🟡 Medium

6. **Stargate**
   - **Type:** LayerZero-based bridge
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://stargate.finance
   - **Benefits:** Optimized for stablecoins, high liquidity
   - **Integration Steps:**
     - Request ChainID 138 integration
     - Deploy Stargate contracts
     - Add liquidity pools
   - **Priority:** 🟡 Medium

7. **Socket.tech**
   - **Type:** Bridge aggregator
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://docs.socket.tech
   - **Benefits:** Best route selection, multiple bridges
   - **Integration Steps:**
     - Request ChainID 138 integration
     - Integrate Socket SDK
     - Configure routing
   - **Priority:** 🟡 Medium

8. **Li.Fi (Li.Fi Pay)**
   - **Type:** Cross-chain bridge aggregator
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** support@li.fi, https://discord.gg/lifi
   - **Benefits:** Smart aggregation, 30+ chains, SDK available
   - **Current Status:** ❌ ChainID 138 NOT supported
   - **Integration Steps:**
     - Request ChainID 138 support (see `alltra-lifi-settlement/docs/REQUESTING_CCIP_LIFI_SUPPORT.md`)
     - Wait for Li.Fi team to add support
     - Update configuration when added
   - **Priority:** 🔴 High (for purchase routing)

9. **Bungee Exchange**
   - **Type:** Bridge aggregator
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://docs.bungee.exchange
   - **Benefits:** Simple integration, multiple chains
   - **Priority:** 🟢 Low

---

#### 2. DEX (Decentralized Exchange) Integrations

##### Recommended DEX Providers

1. **Uniswap**
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://uniswap.org
   - **Benefits:** Largest DEX by volume, V3/V4 support
   - **Integration Steps:**
     - Request ChainID 138 integration
     - Deploy Uniswap V3 contracts
     - Add liquidity pools
   - **Priority:** 🔴 High

2. **1inch**
   - **Type:** DEX aggregator
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://1inch.io
   - **Benefits:** Best price routing, supports 100+ DEXs
   - **Integration Steps:**
     - Request ChainID 138 integration
     - Integrate 1inch API
     - Configure routing
   - **Priority:** 🔴 High

3. **0x Protocol**
   - **Type:** DEX aggregation protocol
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://0x.org
   - **Benefits:** Open source, developer-friendly
   - **Priority:** 🟡 Medium

4. **ParaSwap**
   - **Type:** DEX aggregator
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://paraswap.io
   - **Benefits:** Gas optimization, multi-chain support
   - **Priority:** 🟡 Medium

5. **Curve Finance**
   - **Type:** Stablecoin DEX
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://curve.fi
   - **Benefits:** Optimized for stablecoins, low slippage
   - **Priority:** 🟡 Medium

---

#### 3. On-Ramp / Off-Ramp Providers (Fiat ↔ Crypto)

##### Recommended On-Ramp Providers

1. **MoonPay**
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://www.moonpay.com/business
   - **Integration Docs:** https://developers.moonpay.com
   - **Benefits:** 100+ countries, multiple payment methods
   - **Payment Methods:** Credit card, bank transfer, Apple Pay, Google Pay
   - **Priority:** 🔴 High

2. **Ramp Network**
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://ramp.network
   - **Integration Docs:** https://docs.ramp.network
   - **Benefits:** European-focused, fast KYC, competitive fees
   - **Priority:** 🔴 High

3. **Transak**
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://transak.com
   - **Integration Docs:** https://docs.transak.com
   - **Benefits:** Global coverage, developer-friendly
   - **Priority:** 🟡 Medium

4. **Wyre**
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://www.sendwyre.com
   - **Integration Docs:** https://docs.sendwyre.com
   - **Benefits:** US-focused, bank transfers, ACH support
   - **Priority:** 🟡 Medium

5. **Banxa**
   - **Status:** ⚠️ Pending - Request integration
   - **Contact:** https://banxa.com
   - **Integration Docs:** https://docs.banxa.com
   - **Benefits:** Global coverage, fast processing
   - **Priority:** 🟢 Low

---

#### 4. Oracle Providers

##### Active Oracles ✅

1. **Chainlink Price Feeds**
   - **Status:** ✅ Deployed
   - **Oracle Address:** `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6`
   - **Use Case:** ETH/USD price feeds
   - **Documentation:** `smom-dbis-138/docs/oracle/`

##### Recommended Oracle Providers

2. **Chainlink CCIP**
   - **Status:** ✅ Active for ChainID 138
   - **Use Case:** Cross-chain messaging and token transfers
   - **Priority:** ✅ Active

3. **Band Protocol**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://bandprotocol.com
   - **Priority:** 🟢 Low

4. **UMA Protocol**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://umaproject.org
   - **Priority:** 🟢 Low

---

#### 5. Wallet Integrations

##### Active Wallet Integrations ✅

1. **MetaMask**
   - **Status:** ✅ Integrated
   - **SDK:** MetaMask SDK
   - **Features:** Network switching, transaction signing
   - **Documentation:** `metamask-integration/`
   - **Priority:** ✅ Active

2. **MetaMask Embedded Wallets**
   - **Status:** ✅ Configured
   - **Features:** Social login, key management
   - **Documentation:** `metamask-integration/docs/METAMASK_EMBEDDED_WALLETS_GUIDE.md`
   - **Priority:** ✅ Active

##### Recommended Wallet Integrations

3. **WalletConnect**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://walletconnect.com
   - **Benefits:** Multi-wallet support
   - **Priority:** 🟡 Medium

4. **Coinbase Wallet**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://www.coinbase.com/wallet
   - **Priority:** 🟢 Low

5. **Rainbow Wallet**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://rainbow.me
   - **Priority:** 🟢 Low

---

#### 6. Payment & Settlement Integrations

##### Active Payment Systems ✅

1. **Alltra Li.Fi Settlement**
   - **Status:** ✅ Implemented
   - **Location:** `alltra-lifi-settlement/`
   - **Features:** Li.Fi Pay routing, settlement orchestration
   - **Supported Chains (Inbound):** Ethereum, Base, Arbitrum
   - **Use Case:** Accept payments on public chains, settle on ChainID 138
   - **Priority:** ✅ Active

2. **CCIP Bridge System**
   - **Status:** ✅ Active
   - **Use Case:** Cross-chain token transfers
   - **Priority:** ✅ Active

##### Recommended Payment Integrations

3. **Stripe Crypto**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://stripe.com/crypto
   - **Priority:** 🟡 Medium

4. **Circle Payments**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://www.circle.com
   - **Priority:** 🟡 Medium

---

#### 7. Monitoring & Analytics Integrations

##### Recommended Monitoring Tools

1. **The Graph**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://thegraph.com
   - **Benefits:** Blockchain indexing, subgraph support
   - **Priority:** 🟡 Medium

2. **Dune Analytics**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://dune.com
   - **Benefits:** On-chain analytics, dashboards
   - **Priority:** 🟢 Low

3. **Nansen**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://www.nansen.ai
   - **Benefits:** Wallet labeling, analytics
   - **Priority:** 🟢 Low

---

#### 8. Infrastructure Integrations

##### Active Infrastructure ✅

1. **Proxmox VE**
   - **Status:** ✅ Active
   - **MCP Server:** `mcp-proxmox/`
   - **Features:** VM/container management, 55+ tools
   - **Priority:** ✅ Active

2. **Cloudflare**
   - **Status:** ✅ Active
   - **Features:** DNS, SSL, Tunnels, Zero Trust
   - **Documentation:** `docs/04-configuration/cloudflare/`
   - **Priority:** ✅ Active

3. **UniFi / Omada Network Management**
   - **Status:** ✅ Active
   - **MCP Servers:** `mcp-unifi/`, `mcp-omada/`
   - **Priority:** ✅ Active

##### Recommended Infrastructure

4. **AWS Services**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Services:** KMS, S3, Secrets Manager
   - **Priority:** 🟡 Medium (for HSM migration)

5. **Azure Services**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Services:** Key Vault, Blob Storage
   - **Priority:** 🟡 Medium (for HSM migration)

6. **HashiCorp Vault**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Use Case:** Secrets management, HSM alternative
   - **Priority:** 🔴 High (for security migration)

---

#### 9. Blockchain Explorer Integrations

##### Active Explorers ✅

1. **Blockscout**
   - **Status:** ✅ Deployed
   - **URL:** https://explorer.d-bis.org
   - **Features:** Block explorer, contract verification
   - **Priority:** ✅ Active

##### Recommended Explorer Features

2. **The Graph Subgraph**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Benefits:** Advanced indexing, custom queries
   - **Priority:** 🟡 Medium

---

#### 10. Compliance & KYC Integrations

##### Recommended Compliance Providers

1. **Sumsub**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://sumsub.com
   - **Benefits:** KYC/AML, identity verification
   - **Priority:** 🟡 Medium

2. **Onfido**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://onfido.com
   - **Benefits:** Identity verification, document checks
   - **Priority:** 🟢 Low

3. **Jumio**
   - **Status:** ⚠️ Pending - Evaluate integration
   - **Contact:** https://www.jumio.com
   - **Benefits:** KYC/AML, biometric verification
   - **Priority:** 🟢 Low

---

### 🟡 Medium Priority Integrations

#### 11. Multi-Chain Adapters

##### Active Adapters ✅

1. **XDC Network Adapter**
   - **Status:** ✅ Implemented
   - **Location:** `smom-dbis-138/contracts/bridge/adapters/evm/XDCAdapter.sol`
   - **Priority:** ✅ Active

2. **Alltra Mainnet Adapter**
   - **Status:** ✅ Implemented
   - **Location:** `smom-dbis-138/contracts/bridge/adapters/evm/AlltraAdapter.sol`
   - **Priority:** ✅ Active

3. **XRPL Adapter**
   - **Status:** ✅ Implemented
   - **Location:** `smom-dbis-138/contracts/bridge/adapters/non-evm/XRPLAdapter.sol`
   - **Priority:** ✅ Active

4. **Firefly Adapter**
   - **Status:** ✅ Implemented
   - **Location:** `smom-dbis-138/contracts/bridge/adapters/hyperledger/FireflyAdapter.sol`
   - **Priority:** ✅ Active

##### Recommended Additional Adapters

5. **Stellar Adapter**
   - **Status:** ⚠️ Pending
   - **Priority:** 🟡 Medium

6. **Algorand Adapter**
   - **Status:** ⚠️ Pending
   - **Priority:** 🟡 Medium

7. **Hedera Adapter**
   - **Status:** ⚠️ Pending
   - **Priority:** 🟡 Medium

8. **Tron Adapter**
   - **Status:** ⚠️ Pending
   - **Priority:** 🟡 Medium

9. **Solana Adapter**
   - **Status:** ⚠️ Pending
   - **Priority:** 🟡 Medium

---

### 🟢 Low Priority / Future Integrations

#### 12. Advanced Features

1. **NFT Marketplace Integration**
   - **Status:** ⚠️ Future consideration
   - **Priority:** 🟢 Low

2. **DeFi Protocol Integrations**
   - **Status:** ⚠️ Future consideration
   - **Protocols:** Aave, Compound, MakerDAO
   - **Priority:** 🟢 Low

3. **Gaming Integrations**
   - **Status:** ⚠️ Future consideration
   - **Priority:** 🟢 Low

---

## 💰 Li.Fi Purchase Workflow: ETH from ChainID 138

### ⚠️ Important Note: ChainID 138 Does NOT Support Li.Fi

**Current Status:**
- ❌ **ChainID 138:** Li.Fi NOT supported (`lifiSupported: false`)
- ✅ **Ethereum, Base, Arbitrum:** Li.Fi supported

**Implication:** You cannot use Li.Fi directly from ChainID 138. You must bridge ETH to a Li.Fi-supported chain first.

---

## 🔄 Complete Workflow: ETH from ChainID 138 → Purchase via Li.Fi

### Phase 1: Bridge ETH from ChainID 138 to Li.Fi-Supported Chain

#### Option A: Bridge to Ethereum Mainnet (Recommended)

**Step 1: Wrap ETH to WETH9 on ChainID 138**

```bash
# Prerequisites
- ETH balance on ChainID 138
- LINK tokens for CCIP fees (0.1-2 LINK typically)
- Private key with sufficient balance

# Contract Addresses (ChainID 138)
WETH9_ADDRESS="0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
CCIP_BRIDGE_ADDRESS="0x89dd12025bfCD38A168455A44B400e913ED33BE2"
LINK_TOKEN="0x514910771AF9Ca656af840dff83E8264EcF986CA"

# Wrap ETH to WETH9
AMOUNT_WEI=$(cast --to-wei 1.0 ether)
cast send "$WETH9_ADDRESS" \
  "deposit()" \
  --value "$AMOUNT_WEI" \
  --rpc-url https://rpc.d-bis.org \
  --private-key $PRIVATE_KEY
```

**Step 2: Approve Bridge Contract**

```bash
MAX_UINT256="115792089237316195423570985008687907853269984665640564039457584007913129639935"

cast send "$WETH9_ADDRESS" \
  "approve(address,uint256)" \
  "$CCIP_BRIDGE_ADDRESS" \
  "$MAX_UINT256" \
  --rpc-url https://rpc.d-bis.org \
  --private-key $PRIVATE_KEY
```

**Step 3: Bridge WETH9 to Ethereum Mainnet**

```bash
ETHEREUM_SELECTOR="5009297550715157269"
RECIPIENT="0xYourEthereumAddress"

cast send "$CCIP_BRIDGE_ADDRESS" \
  "sendCrossChain(uint64,address,uint256)" \
  "$ETHEREUM_SELECTOR" \
  "$RECIPIENT" \
  "$AMOUNT_WEI" \
  --rpc-url https://rpc.d-bis.org \
  --private-key $PRIVATE_KEY
```

**Step 4: Wait for Bridge Confirmation**
- **Time:** 1-5 minutes
- **Monitor:** Check transaction on explorer
- **Verify:** Check WETH9 balance on Ethereum Mainnet

---

#### Option B: Use Automated Script

```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
./scripts/wrap-and-bridge-weth9-to-mainnet.sh \
  <amount_in_eth> \
  <ethereum_recipient_address> \
  <private_key>
```

**Example:**
```bash
./scripts/wrap-and-bridge-weth9-to-mainnet.sh \
  1.0 \
  0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb \
  0xYourPrivateKey
```

---

### Phase 2: Use Li.Fi for Purchase on Ethereum Mainnet

**Step 5: Initialize Li.Fi Service**

```typescript
import { LiFiRoutingService } from '@order-of-hospitallers/alltra-lifi-settlement';
import { ethers } from 'ethers';

// Initialize Li.Fi service
const lifiService = new LiFiRoutingService({
  apiKey: process.env.LIFI_API_KEY, // Optional: 200 req/min vs 200 req/2hrs
  integrator: 'YourAppName',
});

// Connect to Ethereum Mainnet
const provider = new ethers.JsonRpcProvider('https://eth.llamarpc.com');
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
```

**Step 6: Get Li.Fi Route for Purchase**

```typescript
// Get route from WETH to USDC (for purchase)
const route = await lifiService.getRoute({
  fromChainId: 1, // Ethereum Mainnet
  fromToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
  toChainId: 1, // Stay on Ethereum
  toToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  amount: ethers.parseEther('1.0'), // 1 WETH
  toAddress: '0xYourAddress',
  slippageBps: 50, // 0.5% slippage
});

console.log('Route found:', route);
console.log('Estimated output:', route.estimate.toAmount);
console.log('Gas estimate:', route.estimate.gasCosts);
```

**Step 7: Execute Li.Fi Route**

```typescript
// Execute the route
const result = await lifiService.executeRoute({
  route,
  signer,
  onRouteUpdate: (updatedRoute) => {
    console.log('Route update:', updatedRoute.status);
  },
});

console.log('Transaction hash:', result.txHash);
console.log('Route ID:', result.routeId);
```

**Step 8: Monitor Transaction Status**

```typescript
// Monitor route status
const status = await lifiService.getRouteStatus(result.routeId);
console.log('Status:', status.status);
console.log('Steps completed:', status.stepsCompleted);
```

---

## 📋 Complete Task List: ETH from ChainID 138 → Purchase via Li.Fi

### Prerequisites Checklist

- [ ] **ETH Balance on ChainID 138**
  - Minimum: Amount to bridge + gas fees (~0.01 ETH)
  - Recommended: Amount + 0.1 ETH buffer

- [ ] **LINK Tokens on ChainID 138**
  - Minimum: 0.1 LINK (for small bridges)
  - Recommended: 1-2 LINK (for larger bridges)
  - **Address:** `0x514910771AF9Ca656af840dff83E8264EcF986CA`

- [ ] **Ethereum Mainnet Wallet**
  - Address to receive bridged WETH9
  - Sufficient ETH for gas fees on Ethereum

- [ ] **Li.Fi API Key (Optional but Recommended)**
  - **Without Key:** 200 requests per 2 hours
  - **With Key:** 200 requests per minute
  - **Get Key:** https://docs.li.fi/rate-limits-and-api-key
  - **Contact:** support@li.fi

- [ ] **Access to RPC Endpoints**
  - ChainID 138 RPC: `https://rpc.d-bis.org`
  - Ethereum RPC: `https://eth.llamarpc.com` or your preferred provider

---

### Task 1: Prepare Environment

**Duration:** 5 minutes

```bash
# 1.1 Set environment variables
export PRIVATE_KEY="0xYourPrivateKey"
export CHAIN138_RPC="https://rpc.d-bis.org"
export ETHEREUM_RPC="https://eth.llamarpc.com"
export LIFI_API_KEY="your-lifi-api-key" # Optional

# 1.2 Verify ETH balance on ChainID 138
cast balance $YOUR_ADDRESS --rpc-url $CHAIN138_RPC

# 1.3 Verify LINK balance on ChainID 138
cast call "0x514910771AF9Ca656af840dff83E8264EcF986CA" \
  "balanceOf(address)" \
  $YOUR_ADDRESS \
  --rpc-url $CHAIN138_RPC
```

**Verification:**
- ✅ ETH balance sufficient
- ✅ LINK balance sufficient (or acquire LINK)
- ✅ Environment variables set

---

### Task 2: Wrap ETH to WETH9 on ChainID 138

**Duration:** 1-2 minutes

```bash
# 2.1 Set amount to wrap
AMOUNT_ETH="1.0"  # Adjust as needed
AMOUNT_WEI=$(cast --to-wei $AMOUNT_ETH ether)

# 2.2 Wrap ETH to WETH9
cast send "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" \
  "deposit()" \
  --value "$AMOUNT_WEI" \
  --rpc-url $CHAIN138_RPC \
  --private-key $PRIVATE_KEY \
  --gas-price 20000000000 \
  --legacy

# 2.3 Verify WETH9 balance
cast call "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" \
  "balanceOf(address)" \
  $YOUR_ADDRESS \
  --rpc-url $CHAIN138_RPC
```

**Verification:**
- ✅ WETH9 balance matches wrapped amount
- ✅ Transaction confirmed on explorer

---

### Task 3: Approve Bridge Contract

**Duration:** 1-2 minutes

```bash
# 3.1 Set maximum approval
MAX_UINT256="115792089237316195423570985008687907853269984665640564039457584007913129639935"
CCIP_BRIDGE="0x89dd12025bfCD38A168455A44B400e913ED33BE2"

# 3.2 Approve bridge
cast send "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" \
  "approve(address,uint256)" \
  "$CCIP_BRIDGE" \
  "$MAX_UINT256" \
  --rpc-url $CHAIN138_RPC \
  --private-key $PRIVATE_KEY \
  --gas-price 20000000000 \
  --legacy

# 3.3 Verify approval
cast call "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" \
  "allowance(address,address)" \
  $YOUR_ADDRESS \
  "$CCIP_BRIDGE" \
  --rpc-url $CHAIN138_RPC
```

**Verification:**
- ✅ Approval set to maximum
- ✅ Transaction confirmed

---

### Task 4: Bridge WETH9 to Ethereum Mainnet

**Duration:** 1-5 minutes (bridge confirmation)

```bash
# 4.1 Set bridge parameters
ETHEREUM_SELECTOR="5009297550715157269"
ETHEREUM_RECIPIENT="0xYourEthereumAddress"  # Can be same as sender

# 4.2 Execute bridge
cast send "$CCIP_BRIDGE" \
  "sendCrossChain(uint64,address,uint256)" \
  "$ETHEREUM_SELECTOR" \
  "$ETHEREUM_RECIPIENT" \
  "$AMOUNT_WEI" \
  --rpc-url $CHAIN138_RPC \
  --private-key $PRIVATE_KEY \
  --gas-price 20000000000 \
  --legacy

# 4.3 Note transaction hash
BRIDGE_TX_HASH="0x..."  # From previous command output
```

**Verification:**
- ✅ Bridge transaction submitted
- ✅ Transaction hash recorded
- ⏳ Wait 1-5 minutes for CCIP confirmation

---

### Task 5: Verify Bridge Completion

**Duration:** 1-2 minutes (after bridge confirmation)

```bash
# 5.1 Check WETH9 balance on Ethereum Mainnet
cast call "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" \
  "balanceOf(address)" \
  $ETHEREUM_RECIPIENT \
  --rpc-url $ETHEREUM_RPC

# 5.2 Verify on Etherscan
# Visit: https://etherscan.io/address/$ETHEREUM_RECIPIENT
```

**Verification:**
- ✅ WETH9 balance on Ethereum matches bridged amount
- ✅ Transaction visible on Etherscan

---

### Task 6: Set Up Li.Fi Integration

**Duration:** 10-15 minutes

```bash
# 6.1 Install dependencies (if not already installed)
cd alltra-lifi-settlement
npm install

# 6.2 Configure environment
export LIFI_API_KEY="your-api-key"  # Optional but recommended
export ETHEREUM_RPC="https://eth.llamarpc.com"
```

**Code Setup:**

```typescript
// 6.3 Initialize Li.Fi service
import { LiFiRoutingService } from '@order-of-hospitallers/alltra-lifi-settlement';
import { ethers } from 'ethers';

const lifiService = new LiFiRoutingService({
  apiKey: process.env.LIFI_API_KEY, // Optional
  integrator: 'YourAppName',
});

// 6.4 Connect to Ethereum
const provider = new ethers.JsonRpcProvider(process.env.ETHEREUM_RPC!);
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
```

**Verification:**
- ✅ Li.Fi service initialized
- ✅ Ethereum connection established
- ✅ Signer configured

---

### Task 7: Get Li.Fi Route for Purchase

**Duration:** 2-5 seconds (API call)

```typescript
// 7.1 Define purchase parameters
const purchaseParams = {
  fromChainId: 1, // Ethereum Mainnet
  fromToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
  toChainId: 1, // Stay on Ethereum (or bridge to another chain)
  toToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC (or desired token)
  amount: ethers.parseEther('1.0'), // Amount of WETH
  toAddress: '0xYourAddress',
  slippageBps: 50, // 0.5% slippage tolerance
};

// 7.2 Get route
const route = await lifiService.getRoute(purchaseParams);

// 7.3 Review route
console.log('Route Details:');
console.log('- Estimated output:', ethers.formatUnits(route.estimate.toAmount, 6), 'USDC');
console.log('- Gas estimate:', route.estimate.gasCosts);
console.log('- Steps:', route.steps.length);
console.log('- Estimated time:', route.estimate.executionDuration, 'seconds');
```

**Verification:**
- ✅ Route found successfully
- ✅ Estimated output acceptable
- ✅ Gas costs reasonable
- ✅ Route steps reviewed

---

### Task 8: Execute Li.Fi Route

**Duration:** 1-5 minutes (transaction confirmation)

```typescript
// 8.1 Execute route with status updates
const result = await lifiService.executeRoute({
  route,
  signer,
  onRouteUpdate: (updatedRoute) => {
    console.log(`Step ${updatedRoute.stepsCompleted}/${updatedRoute.steps.length}: ${updatedRoute.status}`);
    
    // Log each step status
    updatedRoute.steps.forEach((step, index) => {
      if (step.execution) {
        console.log(`  Step ${index + 1}: ${step.type} - ${step.execution.status}`);
        if (step.execution.transactionHash) {
          console.log(`    TX: ${step.execution.transactionHash}`);
        }
      }
    });
  },
});

console.log('Route execution started:');
console.log('- Route ID:', result.routeId);
console.log('- Transaction hash:', result.txHash);
```

**Verification:**
- ✅ Route execution started
- ✅ Transaction hash received
- ✅ Status updates received

---

### Task 9: Monitor Route Status

**Duration:** Ongoing (until completion)

```typescript
// 9.1 Monitor route status
async function monitorRoute(routeId: string) {
  const status = await lifiService.getRouteStatus(routeId);
  
  console.log('Route Status:', status.status);
  console.log('Steps completed:', status.stepsCompleted, '/', status.steps.length);
  
  // Check if complete
  if (status.status === 'DONE') {
    console.log('✅ Route completed successfully!');
    console.log('Final amount received:', ethers.formatUnits(status.toAmount, 6), 'USDC');
    return true;
  }
  
  // Check if failed
  if (status.status === 'FAILED') {
    console.error('❌ Route failed:', status.error);
    return false;
  }
  
  // Still in progress
  console.log('⏳ Route in progress...');
  return false;
}

// 9.2 Poll status every 5 seconds
const pollInterval = setInterval(async () => {
  const isComplete = await monitorRoute(result.routeId);
  if (isComplete) {
    clearInterval(pollInterval);
  }
}, 5000);
```

**Verification:**
- ✅ Route status monitored
- ✅ Completion detected
- ✅ Final amount verified

---

### Task 10: Verify Final Balance

**Duration:** 1 minute

```bash
# 10.1 Check USDC balance on Ethereum Mainnet
cast call "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" \
  "balanceOf(address)" \
  $YOUR_ADDRESS \
  --rpc-url $ETHEREUM_RPC

# 10.2 Verify on Etherscan
# Visit: https://etherscan.io/token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48?a=$YOUR_ADDRESS
```

**Verification:**
- ✅ USDC balance increased by expected amount
- ✅ Transaction visible on Etherscan
- ✅ Purchase complete

---

## 📊 Complete Task Summary

### Quick Reference Checklist

| Task | Duration | Status | Dependencies |
|------|----------|--------|--------------|
| 1. Prepare Environment | 5 min | ⚠️ Manual | ETH, LINK, RPC access |
| 2. Wrap ETH to WETH9 | 1-2 min | ✅ Automated script available | Task 1 |
| 3. Approve Bridge | 1-2 min | ✅ Automated script available | Task 2 |
| 4. Bridge to Ethereum | 1-5 min | ✅ Automated script available | Task 3 |
| 5. Verify Bridge | 1-2 min | ⚠️ Manual | Task 4 |
| 6. Set Up Li.Fi | 10-15 min | ✅ Code ready | Task 5 |
| 7. Get Li.Fi Route | 2-5 sec | ✅ Code ready | Task 6 |
| 8. Execute Route | 1-5 min | ✅ Code ready | Task 7 |
| 9. Monitor Status | Ongoing | ✅ Code ready | Task 8 |
| 10. Verify Balance | 1 min | ⚠️ Manual | Task 9 |

**Total Estimated Time:** 20-35 minutes (excluding wait times)

---

## 🔄 Alternative Workflows

### Workflow A: Direct Bridge to Purchase Chain

If purchasing on a chain other than Ethereum:

1. **Bridge ETH from ChainID 138 → Target Chain** (Base, Arbitrum, etc.)
2. **Use Li.Fi on Target Chain** for purchase

**Example: Bridge to Base**

```bash
# Bridge to Base (if Base bridge is configured)
BASE_SELECTOR="15971525489660198786"
cast send "$CCIP_BRIDGE" \
  "sendCrossChain(uint64,address,uint256)" \
  "$BASE_SELECTOR" \
  "$BASE_RECIPIENT" \
  "$AMOUNT_WEI" \
  --rpc-url $CHAIN138_RPC \
  --private-key $PRIVATE_KEY
```

Then use Li.Fi on Base for purchase.

---

### Workflow B: Multi-Hop via Intermediate Chain

If direct bridge not available:

1. **Bridge ChainID 138 → Ethereum**
2. **Use Li.Fi to bridge Ethereum → Target Chain**
3. **Purchase on Target Chain**

---

## ⚠️ Important Considerations

### Current Limitations

1. **ChainID 138 Li.Fi Support:** ❌ NOT SUPPORTED
   - Cannot use Li.Fi directly from ChainID 138
   - Must bridge to Li.Fi-supported chain first

2. **Bridge Fees:**
   - CCIP fees: ~0.1-2 LINK per bridge
   - Gas fees: ~0.01 ETH total (wrap + approve + bridge)
   - Li.Fi fees: Included in route (typically 0.1-0.5%)

3. **Bridge Time:**
   - Wrap: ~15 seconds
   - Approve: ~10 seconds
   - Bridge: 1-5 minutes (CCIP confirmation)
   - Li.Fi route: 1-5 minutes (depending on route complexity)

### Cost Estimate (1 ETH Example)

| Item | Cost |
|------|------|
| Wrap Gas (ChainID 138) | ~0.001 ETH |
| Approve Gas (ChainID 138) | ~0.001 ETH |
| Bridge Gas (ChainID 138) | ~0.005 ETH |
| CCIP Fee (LINK) | ~0.1-2 LINK |
| Li.Fi Route Fee | ~0.1-0.5% of amount |
| Ethereum Gas (Li.Fi) | ~0.01-0.05 ETH |
| **Total ETH Cost** | **~0.017-0.057 ETH** |
| **Total LINK Cost** | **~0.1-2 LINK** |

---

## 🎯 Integration Priority Matrix

### 🔴 High Priority (Immediate Value)

1. **Li.Fi Support Request** - Enable direct Li.Fi routing from ChainID 138
2. **LayerZero Integration** - Major bridge provider
3. **Wormhole Integration** - Security audited, 30+ chains
4. **Uniswap Integration** - Largest DEX, high liquidity
5. **1inch Integration** - Best price routing
6. **MoonPay Integration** - Leading on-ramp, 100+ countries
7. **Ramp Network Integration** - Fast KYC, competitive fees

### 🟡 Medium Priority (Short Term)

8. **Axelar Integration** - Developer-friendly
9. **Stargate Integration** - Stablecoin optimized
10. **Socket.tech Integration** - Bridge aggregator
11. **Transak Integration** - Global on-ramp
12. **0x Protocol Integration** - DEX aggregation
13. **ParaSwap Integration** - Gas optimization
14. **HashiCorp Vault** - Secrets management

### 🟢 Low Priority (Future)

15. **Additional DEXs** - Curve, SushiSwap, etc.
16. **Additional On-Ramps** - Wyre, Banxa, etc.
17. **Monitoring Tools** - The Graph, Dune, Nansen
18. **Compliance Tools** - Sumsub, Onfido, Jumio
19. **Additional Chain Adapters** - Stellar, Algorand, etc.

---

## 📝 Next Steps for Li.Fi Integration

### Immediate Actions

1. **Request Li.Fi Support for ChainID 138**
   - **Contact:** support@li.fi or https://discord.gg/lifi
   - **Template:** See `alltra-lifi-settlement/scripts/support-request-templates.md`
   - **Information Needed:**
     - Chain ID: 138
     - Network Name: DeFi Oracle Meta Mainnet
     - RPC URL: https://rpc.d-bis.org
     - Explorer: https://explorer.d-bis.org
     - ChainList: https://chainlist.org/chain/138

2. **Set Up Automated Support Monitoring**
   ```bash
   cd alltra-lifi-settlement
   # Set up daily check for Li.Fi support
   crontab -e
   # Add: 0 0 * * * cd /path/to/alltra-lifi-settlement && ts-node scripts/scheduled-support-check.ts --notify
   ```

3. **Prepare Configuration Update**
   - When Li.Fi adds support, update `chains.ts`:
   ```typescript
   CHAIN138: {
     // ... existing config
     lifiSupported: true, // Update this
   }
   ```

---

## 🔗 Related Documentation

- **Bridge Configuration:** `smom-dbis-138/docs/bridge/`
- **CCIP Integration:** `smom-dbis-138/docs/ccip/`
- **Li.Fi Integration:** `alltra-lifi-settlement/docs/`
- **MetaMask Integration:** `metamask-integration/docs/`
- **Multi-Chain Deployment:** `smom-dbis-138/docs/deployment/MULTI_CHAIN_DEPLOYMENT_GUIDE.md`

---

**Last Updated:** 2026-01-26  
**Status:** ✅ Complete integration list and purchase workflow documented