# Current Status & Token Routing / Token-Aggregation (Incl. Multihop)

Companion to [MASTER_CONTRACTS_AND_INFRASTRUCTURE_LIST.md](MASTER_CONTRACTS_AND_INFRASTRUCTURE_LIST.md). This doc covers: **current status** of all major components, **token-aggregation** API and routing, and **multihop** routing (on-chain and off-chain).

---

## 1. Current status overview

| Area | Status | Notes |
|------|--------|--------|
| **Contracts (Solidity)** | Implemented | Full repo: bridges, vault, reserve, oracles, DEX/PMM, registries, adapters. **Build:** `forge build` currently fails due to missing `contracts/emoney/` files; all other contracts (dex, vault, reserve, bridge, ccip, nft, etc.) are present and consistent. |
| **CCIP bridges** | Deployed (mainnet refs) | WETH9/WETH10 bridges and router addresses documented for Ethereum and other chains; Chain 138 deployment per runbooks. |
| **Trustless bridge** | Implemented + deployed (Lockbox 138) | Lockbox138 on Chain 138; Ethereum stack (InboxETH, BondManager, etc.) deployable per `script/bridge/trustless/DeployTrustlessBridge.s.sol`. |
| **Oracles** | Implemented | XAUOracle, ReserveSystem, OraclePriceFeed, PriceFeedKeeper, PMMPriceProvider; optional ReserveSystem on DODOPMMIntegration. |
| **Mappers** | Implemented | AddressMapper (138), AddressMapperEmpty (other chains); deploy scripts available. |
| **Reserve system** | Implemented | ReserveSystem, OraclePriceFeed, keeper; SetupPriceFeeds and DeployReserveSystem scripts. |
| **Vault system** | Implemented | Ledger, Vault, XAUOracle, VaultFactory, CollateralAdapter, Liquidation, RateAccrual, PMMPriceProvider. |
| **PMM / DEX** | Implemented | DODOPMMIntegration (oracle-backed getPoolPriceOrOracle), DODOPMMProvider, PrivatePoolRegistry; pool indexer can ingest from DODOPMMIntegration when `CHAIN_138_DODO_PMM_INTEGRATION` is set. |
| **Token-aggregation service** | Implemented & runnable | Node service; indexes tokens/pools (UniswapV2/V3, DODO PMM from integration or PoolManager); report, quote, bridge, token-mapping APIs. Requires DB (PostgreSQL/TimescaleDB) and RPC. |
| **Orchestration (bridge quote)** | Implemented | QuoteService (swap+bridge+swap); optional EnhancedSwapRouter source/destination quotes. |
| **Token mapping (multichain)** | Implemented | `config/token-mapping.json`, `config/token-mapping-multichain.json`; token-aggregation exposes `/api/v1/token-mapping` when run from monorepo with loader. |

---

## 2. Token-aggregation service — API summary

Base URL: `/api/v1` (e.g. `http://localhost:3000/api/v1`). See [services/token-aggregation/docs/REST_API_REFERENCE.md](../services/token-aggregation/docs/REST_API_REFERENCE.md).

### 2.1 Health & meta

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Health check (DB, indexer). |
| GET | `/` | Service name, version, endpoint hints. |

### 2.2 Chains & config

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/chains` | Supported chains (138, 651940). |
| GET | `/api/v1/networks` | EIP-3085 network params (RPC, explorer, oracles) for wallet_addEthereumChain. |
| GET | `/api/v1/config` | Oracles/config per chain (optional `?chainId=`). |

### 2.3 Tokens & pools

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/tokens` | List tokens for a chain; optional market data, `includeDodoPool` / PMM pool. |
| GET | `/api/v1/tokens/:address` | Token detail by chain + address (market, pools, external enrichment). |
| GET | `/api/v1/tokens/:address/pools` | Pools for a token. |
| GET | `/api/v1/tokens/:address/ohlcv` | OHLCV for charts (interval, from, to, poolAddress). |
| GET | `/api/v1/tokens/:address/signals` | Trending/signals. |
| GET | `/api/v1/search` | Search (e.g. by symbol). |
| GET | `/api/v1/pools/:poolAddress` | Pool detail (query `chainId`). |

### 2.4 Quote (single-hop)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/quote` | **Single-hop** swap quote: `chainId`, `tokenIn`, `tokenOut`, `amountIn`. Returns best constant-product quote from indexed pools (UniswapV2-style); one pool per pair. No multihop pathfinding in this API. |

### 2.5 Bridge routes & token mapping

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/bridge/routes` | CCIP (WETH9/WETH10) and Trustless routes; `chain138Bridges`; optional `tokenMappingApi` hint. |
| GET | `/api/v1/token-mapping` | Token mapping for chain pair (`fromChain`, `toChain`); from `config/token-mapping-multichain.json` when loader available. |
| GET | `/api/v1/token-mapping/pairs` | All defined chain pairs. |
| GET | `/api/v1/token-mapping/resolve` | Resolve address on target chain (`fromChain`, `toChain`, `address`). |

### 2.6 Report (CMC / CoinGecko style)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/report/all` | All tokens, pools, liquidity, volume (unified) + cross-chain summary; optional `?chainId=`. |
| GET | `/api/v1/report/cross-chain` | Cross-chain pools, bridge volume, atomic swaps (Chain 138, ALL). |
| GET | `/api/v1/report/coingecko` | Format for CoinGecko submission. |
| GET | `/api/v1/report/cmc` | Format for CoinMarketCap submission. |
| GET | `/api/v1/report/token-list` | Uniswap-style token list with logoURI (optional `?chainId=`). |

### 2.7 Admin (protected)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/v1/admin/auth/login` | Admin login. |
| GET | `/api/v1/admin/dex-factories` | DEX factory config. |
| POST | `/api/v1/admin/dex-factories` | Update DEX factories. |
| GET | `/api/v1/admin/status` | Service status. |
| GET | `/api/v1/admin/audit-log` | Audit log. |
| *(+ API keys, endpoints)* | | See admin routes. |

---

## 3. Token routing capabilities

### 3.1 Token-aggregation (API)

- **Quote:** Single-hop only. `GET /api/v1/quote` uses the pool DB to find pools that contain the (tokenIn, tokenOut) pair and returns the best constant-product quote. It does **not** compute multi-hop paths (e.g. A → B → C).
- **Pools:** Indexed from UniswapV2 (PairCreated), UniswapV3 (PoolCreated), and DODO. DODO pools are sourced from either:
  - **PoolManager** (ABI: `allPools`, `poolRegistry`) when `CHAIN_138_DODO_POOL_MANAGER` is set, or
  - **DODOPMMIntegration** (ABI: `getAllPools`, `getPoolConfig`, `getPoolReserves`, `getPoolPriceOrOracle`) when `CHAIN_138_DODO_PMM_INTEGRATION` is set.
- **Token mapping:** Cross-chain address resolution for bridge UIs (138↔651940 and other pairs) via `token-mapping` endpoints and `config/token-mapping-multichain.json` (or loader).

### 3.2 On-chain routing (multiprotocol, size-based)

- **EnhancedSwapRouter** (`contracts/bridge/trustless/EnhancedSwapRouter.sol`):
  - **WETH → stablecoin:** Multi-provider routing by size: Uniswap V3, Dodoex PMM, Balancer, Curve, 1inch. Size categories: small (&lt; $10k), medium ($10k–$100k), large (&gt; $100k). Returns best quote across enabled providers.
  - **Arbitrary pair:** `swapTokenToToken(tokenIn, tokenOut, amountIn, amountOutMin)` when a Dodoex pool is configured for that pair (single hop).
  - **Quotes:** `getQuotes(stablecoinToken, amountIn)` returns provider list and amounts.
  - Not N-hop pathfinding (e.g. A→B→C) on-chain; it selects among different DEXs for one leg (WETH↔stable).

### 3.3 Swap–bridge–swap (multihop across chains)

- **SwapBridgeSwapCoordinator** (on-chain): Coordinates **swap (source) → bridge → swap (destination)** in one flow. One hop on source, bridge, one hop on destination.
- **Orchestration QuoteService** (`orchestration/bridge/quote-service.ts`):
  - **POST /api/bridge/quote** (orchestration): Bridge transfer quote; optionally includes **sourceSwapQuote** (e.g. EnhancedSwapRouter on source) and **destinationSwapQuote** (destination swap router) for swap+bridge+swap.
  - Requires `RPC_URL`, `BRIDGE_REGISTRY_ADDRESS`; optional `ENHANCED_SWAP_ROUTER_ADDRESS`, `DESTINATION_RPC_URL`, `DESTINATION_SWAP_ROUTER_ADDRESS`.

### 3.4 Liquidity provider layer

- **LiquidityManager** + **DODOPMMProvider**: DODOPMMProvider returns quotes via `getPoolPriceOrOracle` (oracle-backed when ReserveSystem set on DODOPMMIntegration). Used as one liquidity source in a multi-provider setup; no pathfinding in this contract.

---

## 4. Multihop routing — summary

| Layer | Multihop? | What exists |
|-------|-----------|-------------|
| **Token-aggregation API** | No | Single-hop quote only (best direct pool for tokenIn/tokenOut). |
| **EnhancedSwapRouter** | No (single leg) | Multi-**provider** choice for one leg (WETH↔stable); optional single-leg Dodoex for arbitrary pair when pool configured. |
| **SwapBridgeSwapCoordinator** | Yes (cross-chain) | Swap (source) → bridge → swap (destination). |
| **Orchestration QuoteService** | Yes (swap+bridge+swap) | Quote for bridge + optional source/destination swap quotes. |
| **N-hop path (A→B→C on one chain)** | No | No generic A→B→C path finder in API or on-chain (e.g. no graph-based multi-hop swap API). |

---

## 5. Config and env affecting token routing

- **Token-aggregation:** `CHAIN_138_RPC_URL`, `CHAIN_651940_RPC_URL`, `DATABASE_URL`, `CHAIN_138_DODO_PMM_INTEGRATION` (and optionally `CHAIN_138_DODO_POOL_MANAGER`), canonical token env vars (`CUSDC_ADDRESS_138`, etc.).
- **Bridge routes:** `LOCKBOX_138`, `INBOX_ETH`, optional `BRIDGE_LIST_JSON_URL`.
- **Token mapping:** `config/token-mapping-multichain.json` (or loader from `config/token-mapping-loader.cjs`) when service runs from monorepo.
- **Orchestration quote:** `RPC_URL`, `BRIDGE_REGISTRY_ADDRESS`, `ENHANCED_SWAP_ROUTER_ADDRESS`, `DESTINATION_RPC_URL`, `DESTINATION_SWAP_ROUTER_ADDRESS`.

---

*For the full contract/infrastructure list, see [MASTER_CONTRACTS_AND_INFRASTRUCTURE_LIST.md](MASTER_CONTRACTS_AND_INFRASTRUCTURE_LIST.md).*
