proxmox/docs/04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md

Additional Paths and Extensions

Last Updated: 2026-03-06
Purpose: Catalog of path types and extension points for routing, bridging, and deployer gas. Use this when adding new chains, assets, or aggregators.

---

1. Routing registry (config/routing-registry.json)

• Outbound (138 → dest): WETH9, WETH10, LINK placeholder. Path types: CCIP, ALT.
• Inbound (dest → 138): One route per CCIP chain (1, 56, 137, 10, 42161, 43114, 8453, 100, 25, 42220, 1111). bridgeAddress for inbound is the source-chain bridge (user sends there); use .env per chain (e.g. MAINNET_CCIP_WETH9_BRIDGE) to replace placeholder 0x0.
• pathTypes: ALT, CCIP, LIFI, JUMPER (LIFI/JUMPER for future aggregator integration).

To add a path: Append a routes entry with fromChain, toChain, asset, pathType, bridgeAddress, bridgeChainId, label. Optionally note.

---

2. Token-aggregation bridge config (smom-dbis-138/services/token-aggregation/src/config/cross-chain-bridges.ts)

• Registry: getRouteFromRegistry(fromChain, toChain, asset) now loads config/routing-registry.json when available (env ROUTING_REGISTRY_JSON_PATH or resolved paths). Falls back to built-in ALT/CCIP logic.
• Lanes: CHAIN_138_BRIDGES CCIP WETH9/WETH10 lanes include all CCIP destinations: 1, 56, 137, 10, 42161, 43114, 8453, 100, 25, 42220, 1111, 651940 (selectors in code).
• pathType: RoutingRegistryEntry.pathType supports ALT | CCIP | LIFI | JUMPER.

To add a chain to lanes: Add an entry to CCIP_DEST_LANES with correct destSelector (from Chainlink CCIP docs).

---

3. Token mapping (config/token-mapping-multichain.json)

• Pairs: 138↔651940, 138↔public chains, 651940↔public; 138↔42793 (Etherlink) added with WETH9, cUSDT, cUSDC, LINK (addressTo placeholders until bridge/relay).
• chainNames: Includes 42793 "Etherlink".

To add a chain pair: Add to chainNames and add a pairs entry with fromChainId, toChainId, tokens[] (key, name, addressFrom, addressTo, notes).

---

4. Quote / bridge API (smom-dbis-138/orchestration/bridge/quote-service.ts)

• Route options: getRouteOptions() now includes LiFi and Jumper when LIFI_ENABLED/LIFI_API_URL or JUMPER_ENABLED/JUMPER_API_URL are set. Placeholder implementations return a route with provider: 'lifi' or 'jumper' (real API calls TODO).
• pathType: Route selection can expose pathType from registry for UI (ALT, CCIP, LIFI, JUMPER).

To wire LiFi/Jumper: Implement API calls in getLiFiRoute / getJumperRoute using env URLs; ensure 138 and destination chain are supported by the aggregator.

---

5. Same-chain (138) swap paths

• Current: DODO PMM cUSDT/cUSDC pool; token-aggregation quotes single-hop.
• Possible additions: c*↔WETH pool on 138; N-hop pathfinding (e.g. cUSDT→WETH→USDC); EnhancedSwapRouter deployment and wiring for size-based routing.

Docs: EXECUTION_CHECKLIST_MULTIPLE_ROUTES_AND_LIQUIDITY.md, PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md.

---

6. Deployer gas (config/deployer-gas-routes.json, config/cro-wemix-swap-routes.json)

• Chains: 138 (internal), 1, 56, 137, 100, 10, 42161, 8453, 43114, 25 (manual), 42220, 1111 (manual), 651940 (manual), 42793 Etherlink (manual, optional).
• Cronos/Wemix: Multiple swap routes in cro-wemix-swap-routes.json; script scripts/deployment/acquire-cro-and-wemix-gas.sh.

To add a chain: Add entry in deployer-gas-routes.json with chainId, name, nativeSymbol, thresholdEther, method (internal | protocolink | manual), and if manual: manualInstructions, manualLinks, optional swapRoutesConfig.

---

7. 13×13 routing matrix (smom-dbis-138/real-robinhood/data/routing-matrix-13x13.json)

• Chains: 138, 1, 56, 137, 10, 42161, 43114, 8453, 100, 25, 42220, 1111, 651940.
• Modes: B/SBS, via 138, ALT, TBD, —. Celo (42220) set to B/SBS (2026-03-06); Wemix (1111) remains TBD until bridge funded.

To add a chain to the matrix: Extend chainIndex and chainNames, and add row/column in matrix with appropriate mode (B/SBS when CCIP live, TBD otherwise).

---

8. Environment variables (summary)

Variable	Purpose
ROUTING_REGISTRY_JSON_PATH	Override path to routing-registry.json (token-aggregation).
LIFI_ENABLED, LIFI_API_URL	Enable LiFi route option in QuoteService.
JUMPER_ENABLED, JUMPER_API_URL	Enable Jumper route option in QuoteService.
Per-chain CCIP bridge	e.g. CCIPWETH9_BRIDGE_GNOSIS, CCIPWETH9_BRIDGE_CELO — used by complete-config and for inbound registry addresses.

See smom-dbis-138/env.additions.example for full list.

---

9. Quick reference: where to add what

Goal	Primary file(s)	Action
New outbound bridge route 138→X	config/routing-registry.json	Add route; optional WETH10/LINK.
New inbound route X→138	config/routing-registry.json	Add route; set bridgeAddress from .env for source chain.
New pathType (e.g. LIFI)	routing-registry.json + cross-chain-bridges.ts (pathType type) + quote-service	Add pathType; implement getXRoute in quote-service.
New CCIP destination lane	cross-chain-bridges.ts	Add to CCIP_DEST_LANES with selector.
New token-mapping chain pair	config/token-mapping-multichain.json	Add chainNames + pairs entry.
New deployer gas chain	config/deployer-gas-routes.json	Add chain entry; optional cro-wemix style JSON + script.
Update 13×13 matrix	smom-dbis-138/real-robinhood/data/routing-matrix-13x13.json	Update matrix + description.