chore: sync submodule state (parent ref update)

Made-with: Cursor

docs/deployment/ALL_MAINNET_ROUTING_LOGIC.md

@@ -0,0 +1,253 @@
+# ALL Mainnet (651940) Routing Logic
+
+**Date**: 2026-01-26  
+**Status**: ✅ **IMPLEMENTED**
+
+---
+
+## Overview
+
+This document describes the routing logic for ALL Mainnet (651940) based on verified support status:
+
+- **CCIP**: ❌ NOT SUPPORTED
+- **LiFi**: ❌ NOT SUPPORTED
+- **USDC**: ✅ DEPLOYED - `0xa95EeD79f84E6A0151eaEb9d441F9Ffd50e8e881` (AUSDC)
+
+---
+
+## Routing Decision Tree
+
+```typescript
+// Pseudo-code for routing decisions
+
+function routePayment(sourceChainId: number, destinationChainId: number) {
+  // Check if destination is ALL Mainnet
+  if (destinationChainId === 651940) {
+    // ALL Mainnet routing
+    if (isCCIPSupported(sourceChainId) && isCCIPSupported(651940)) {
+      // Use CCIP bridge
+      return routeViaCCIP(sourceChainId, 651940);
+    } else {
+      // Use AlltraAdapter (custom bridge)
+      return routeViaAlltraAdapter(sourceChainId, 651940);
+    }
+  }
+  
+  // Check if source is ALL Mainnet
+  if (sourceChainId === 651940) {
+    // Outbound from ALL Mainnet
+    if (isCCIPSupported(651940) && isCCIPSupported(destinationChainId)) {
+      // Use CCIP bridge
+      return routeViaCCIP(651940, destinationChainId);
+    } else {
+      // Use AlltraAdapter (custom bridge)
+      return routeViaAlltraAdapter(651940, destinationChainId);
+    }
+  }
+  
+  // Standard routing for other chains
+  if (isLiFiSupported(sourceChainId) && isLiFiSupported(destinationChainId)) {
+    return routeViaLiFi(sourceChainId, destinationChainId);
+  }
+  
+  // Fallback to CCIP if supported
+  if (isCCIPSupported(sourceChainId) && isCCIPSupported(destinationChainId)) {
+    return routeViaCCIP(sourceChainId, destinationChainId);
+  }
+  
+  throw new Error(`No routing path available: ${sourceChainId} → ${destinationChainId}`);
+}
+```
+
+---
+
+## Inbound Payments (Public Chain → ALL Mainnet)
+
+### Current Status: Use AlltraAdapter
+
+Since CCIP and LiFi are not supported for ALL Mainnet:
+
+1. **Payment arrives on public chain** (Ethereum, Base, Arbitrum)
+2. **LiFi routes to vault** (if LiFi supported for source chain)
+3. **Vault receives USDC** on public chain
+4. **Settlement service detects deposit**
+5. **Mint CompliantUSDC on ChainID 138** (not ALL Mainnet directly)
+6. **Bridge to ALL Mainnet** (if needed) via AlltraAdapter
+
+**Note**: The current architecture settles on ChainID 138, not directly on ALL Mainnet. If settlement on ALL Mainnet is required, use AlltraAdapter for the final leg.
+
+---
+
+## Outbound Payments (ALL Mainnet → Public Chain)
+
+### Current Status: Use AlltraAdapter
+
+1. **User initiates withdrawal** from ALL Mainnet
+2. **Check CCIP support**: ❌ Not available
+3. **Use AlltraAdapter** to bridge to intermediate chain
+4. **Bridge to destination** via CCIP/LiFi if supported
+
+**Alternative Flow** (if intermediate chain needed):
+1. ALL Mainnet → ChainID 138 (via AlltraAdapter)
+2. ChainID 138 → Public Chain (via CCIP)
+
+---
+
+## Implementation Examples
+
+### Example 1: Payment to ALL Mainnet Vault
+
+```typescript
+import { isLiFiSupported, isCCIPSupported, getChainConfig } from './config/chains';
+import { LiFiRoutingService } from './payments/lifi/lifi-routing.service';
+import { AlltraAdapter } from './bridge/adapters/AlltraAdapter';
+
+async function routeToAllMainnet(
+  sourceChainId: number,
+  amount: string,
+  recipient: string
+) {
+  const allMainnetConfig = getChainConfig(651940);
+  
+  // Step 1: Route to public chain vault (if LiFi supported)
+  if (isLiFiSupported(sourceChainId)) {
+    const lifiService = new LiFiRoutingService();
+    const route = await lifiService.getRoute({
+      fromChainId: sourceChainId,
+      fromToken: 'native',
+      amount,
+      toAddress: vaultAddress, // Vault on source chain
+      slippageBps: 30,
+    });
+    // Execute route...
+  }
+  
+  // Step 2: Bridge to ALL Mainnet (if needed)
+  // Note: Current architecture settles on ChainID 138
+  // If direct settlement on ALL Mainnet is required:
+  if (needsAllMainnetSettlement) {
+    // Use AlltraAdapter for bridging
+    const adapter = new AlltraAdapter(admin, bridgeAddress);
+    await adapter.bridge(
+      tokenAddress,
+      amount,
+      recipientAddress,
+      additionalData
+    );
+  }
+}
+```
+
+### Example 2: Withdrawal from ALL Mainnet
+
+```typescript
+async function withdrawFromAllMainnet(
+  amount: string,
+  destinationChainId: number,
+  recipient: string
+) {
+  // Check routing options
+  if (isCCIPSupported(651940) && isCCIPSupported(destinationChainId)) {
+    // Use CCIP (not available currently)
+    return routeViaCCIP(651940, destinationChainId);
+  }
+  
+  // Use AlltraAdapter
+  const adapter = new AlltraAdapter(admin, bridgeAddress);
+  
+  // Option 1: Direct bridge (if supported)
+  try {
+    return await adapter.bridge(
+      tokenAddress,
+      amount,
+      recipientAddress,
+      additionalData
+    );
+  } catch (error) {
+    // Option 2: Bridge via intermediate chain (ChainID 138)
+    // ALL Mainnet → ChainID 138 → Destination
+    return routeViaIntermediateChain(651940, 138, destinationChainId);
+  }
+}
+```
+
+---
+
+## Telemetry Labels
+
+Use consistent labels for ALL Mainnet metrics:
+
+```typescript
+import { getTelemetryLabels } from './config/chains';
+
+const labels = getTelemetryLabels(651940);
+// Returns:
+// {
+//   chainId: 651940,
+//   chainKey: "all-mainnet",
+//   displayName: "ALL Mainnet"
+// }
+```
+
+---
+
+## Error Handling
+
+### LiFi Not Supported
+
+```typescript
+try {
+  const route = await lifiService.getRoute(params);
+} catch (error) {
+  if (error.message.includes('LiFi is not supported')) {
+    // Fallback to direct transfer or alternative routing
+    return routeViaAlternative(params);
+  }
+  throw error;
+}
+```
+
+### CCIP Not Supported
+
+```typescript
+if (!isCCIPSupported(chainId)) {
+  // Use AlltraAdapter or alternative bridge
+  return useCustomBridge(chainId);
+}
+```
+
+---
+
+## Configuration Updates
+
+✅ **USDC Verification Complete** (2026-01-26):
+
+1. ✅ Updated `chains.ts`:
+   ```typescript
+   ALL_MAINNET: {
+     // ...
+     usdcAddress: '0xa95EeD79f84E6A0151eaEb9d441F9Ffd50e8e881', // AUSDC
+   }
+   ```
+
+2. ⚠️ Register vault for ALL Mainnet (when vault deployed):
+   ```typescript
+   vaultService.registerVault(
+     651940,
+     vaultAddress,
+     '0xa95EeD79f84E6A0151eaEb9d441F9Ffd50e8e881' // AUSDC
+   );
+   ```
+
+3. ✅ USDC available - routing can use AUSDC for settlements
+
+---
+
+## Next Steps
+
+1. ✅ CCIP support verified: NOT SUPPORTED
+2. ✅ LiFi support verified: NOT SUPPORTED
+3. ⚠️ Verify USDC deployment on ALL Mainnet
+4. ⚠️ Test AlltraAdapter with actual ALL Mainnet network
+5. ⚠️ Update routing services to use AlltraAdapter for ALL Mainnet
+6. ⚠️ Add telemetry/metrics for ALL Mainnet transactions