# 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](../00-meta/EXECUTION_CHECKLIST_MULTIPLE_ROUTES_AND_LIQUIDITY.md), [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](../03-deployment/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. |