smom-dbis-138/docs/STATUS_AND_TOKEN_ROUTING.md

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

Companion to 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.

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 (< $10k), medium ($10k–$100k), large (> $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.