d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
master
proxmox/docs/04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md
defiQUG b3a8fe4496
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details
chore: sync all changes to Gitea 
- Config, docs, scripts, and backup manifests
- Submodule refs unchanged (m = modified content in submodules)

Made-with: Cursor
2026-03-02 11:37:34 -08:00

12 KiB
Raw Permalink Blame History

Using DEX and Aggregators with ChainID 138 Coins/Tokens — Explainer

Last Updated: 2026-02-28
Purpose: Explain how to use DEXs and aggregators with coins/tokens from ChainID 138 (DeFi Oracle Meta Mainnet), and how routing works for swaps and cross-chain flows.

1. Chain 138 tokens in DEX flows

1.1 Tokens on Chain 138

Symbol Address Role in DEX / aggregator
cUSDT 0x93E66202A11B1772E55407B32B44e5Cd8eda7f22 Compliant stablecoin; pair with cUSDC, USDT, WETH in pools
cUSDC 0xf22258f57794CC8E06237084b353Ab30fFfa640b Compliant stablecoin; pair with cUSDT, USDC, WETH in pools
WETH 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 Wrapped ETH; bridge asset and quote currency
WETH10 0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f Alternative WETH; used in CCIP bridge flows
LINK 0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03 CCIP fee token; not typically a DEX pair

Official reference tokens (for pool pairs): USDT at 0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619, USDC per deployment. These are used in cUSDT/USDT and cUSDC/USDC DODO PMM pools so users can swap between compliant and official stablecoins.

When building swap UIs or aggregator integrations, use these addresses for tokenIn / tokenOut and for resolving symbols (e.g. from token list or /api/v1/tokens).

2. DEX layer on Chain 138

2.1 Native DEX: DODO PMM

On Chain 138, the primary DEX layer is DODO-style PMM (Proactive Market Maker) via:

  • DODOPMMIntegration — 0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D
    Creates and manages pools; exposes swap functions and pool state.
  • DODOPMMProvider — 0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0
    Used by routing/aggregation to get quotes and execute swaps for registered pools.

Pools (created and registered):

Pair Pool address Use case
cUSDT / cUSDC 0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8 Compliant↔compliant stablecoin
cUSDT / USDT 0xa3Ee6091696B28e5497b6F491fA1e99047250c59 Compliant↔official USDT
cUSDC / USDC 0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5 Compliant↔official USDC

How to swap on-chain (direct):

  • cUSDT ↔ cUSDC: DODOPMMIntegration.swapCUSDTForUSDC / swapUSDCForCUSDT(pool, amountIn, minAmountOut)
  • cUSDT ↔ USDT: swapCUSDTForUSDT / swapUSDTForCUSDT(pool, …)
  • cUSDC ↔ USDC: swapCUSDCForUSDC / swapUSDCForCUSDC(pool, …)

Caller must approve the integration contract for the input token. Use the pool addresses above for the pool argument.

Uniswap V2/V3 on 138: Not deployed by default. If you deploy Uniswap factories and create pools (e.g. cUSDT/WETH, cUSDC/WETH), the token-aggregation service can index them when CHAIN_138_UNISWAP_V2_FACTORY / CHAIN_138_UNISWAP_V3_FACTORY are set in env.

3. Token-aggregation API (quotes and discovery)

The token-aggregation service indexes tokens and liquidity pools (UniswapV2, UniswapV3, DODO from DODOPMMIntegration) and exposes a REST API. This is the main way to get quotes and pool data for Chain 138 tokens without calling the chain yourself.

Base URL: e.g. https://explorer.d-bis.org/api/v1 or the URL where the service is proxied (see REST_API_REFERENCE).

3.1 Single-hop quote (DEX quote)

Endpoint Method Purpose
/api/v1/quote GET Best single-hop swap quote for a token pair on one chain

Query: chainId=138, tokenIn=<address>, tokenOut=<address>, amountIn=<raw amount in smallest unit>.

Response: { amountOut, poolAddress?, dexType?, error? } — constant-product style from the first/best indexed pool for that pair. Use for “swap cUSDT → cUSDC” or “cUSDT → WETH” (if a pool exists and is indexed).

Limitation: Single-hop only. There is no N-hop path (e.g. cUSDT → WETH → cUSDC) in this API; routing is one direct pool per pair.

3.2 Token and pool discovery

Endpoint Purpose
GET /api/v1/tokens?chainId=138 List tokens; optional includeDodoPool, market data
GET /api/v1/tokens/:address?chainId=138 Token detail, market data, pools, DODO pool flag
GET /api/v1/tokens/:address/pools?chainId=138 All pools containing this token
GET /api/v1/report/token-list?chainId=138 Uniswap-style token list (for MetaMask / dApp)

Use these to resolve symbol→address, get logos, and see which pools exist for cUSDT, cUSDC, WETH on Chain 138.

3.3 Bridge routes and token mapping

Endpoint Purpose
GET /api/v1/bridge/routes CCIP WETH9/WETH10 bridge routes; Chain 138 bridge addresses
GET /api/v1/token-mapping?fromChain=138&toChain=1 Token address mapping 138↔other chain (for bridge UIs)
GET /api/v1/token-mapping/resolve?fromChain=&toChain=&address= Resolve one token address to the other chain

Use for “bridge WETH from 138 to Mainnet” or “what is cUSDT on 138 in Mainnet terms” (if a wrapped/bridged form exists).

4. Routing for DEXs — how it works

4.1 Single-hop routing (what’s live today)

  • On-chain: User (or contract) calls DODOPMMIntegration swap functions directly with the correct pool address. No on-chain “router” that picks the pool.
  • Off-chain (API): Client calls GET /api/v1/quote with chainId=138, tokenIn, tokenOut, amountIn. The service returns the best direct-pool quote from its index (DODO + any configured Uniswap). Client then executes the swap on the integration contract (or via a front-end that submits the tx).

So “routing” today = choose the right pool (cUSDT/cUSDC, cUSDT/USDT, or cUSDC/USDC) and call the matching swap function with that pool.

4.2 Multi-provider routing (design; not yet deployed)

EnhancedSwapRouter (contract) is designed to route one leg (e.g. WETH↔stable) across multiple providers:

  • By size: Small (<$10k) → Uniswap V3 / Dodoex; medium ($10k–$100k) → Dodoex → Balancer → Uniswap V3; large (>$100k) → Dodoex → Curve → Balancer.
  • By slippage / liquidity: Prefer Dodoex for low slippage; Balancer/Curve for deeper liquidity.

This contract is not deployed on Chain 138. When deployed (and when Uniswap/Balancer/Curve pools exist on 138), it would sit in front of multiple DEXs and return getQuotes(stablecoin, amountIn) and swapToStablecoin(...) so one call gets the best execution. DODOPMMProvider would be one of the registered providers.

4.3 Swap–bridge–swap (cross-chain routing)

For cross-chain flows (e.g. swap on 138 → bridge to Mainnet → swap on Mainnet):

  • Orchestration API: POST /api/bridge/quote — request includes source/destination chain, token, amount, destination address. Response can include:
    • sourceSwapQuote — optional quote to swap into the bridge asset on source (e.g. 138) when an EnhancedSwapRouter or equivalent is configured.
    • destinationSwapQuote — optional quote to swap on destination chain after the bridge.
  • On-chain coordinator (optional): SwapBridgeSwapCoordinator can perform “swap (source) → bridge → swap (destination)” in one transaction when deployed and configured.

So “routing for DEXs” in a cross-chain context = source DEX (138) + bridge + destination DEX, with the quote API and optional coordinator tying them together.

5. Using aggregators with Chain 138 tokens

5.1 Internal “aggregation” (token-aggregation service)

The token-aggregation service aggregates:

  • Pools: From DODO (DODOPMMIntegration) and, if configured, UniswapV2/V3.
  • Quote: Best single-hop quote for a given (tokenIn, tokenOut, amountIn) on one chain.

So for Chain 138, it acts as a single-hop quote aggregator over the indexed DEX (today: DODO PMM). It does not split orders across multiple pools or chains; it picks the best direct pool for the pair.

5.2 External DEX aggregators (1inch, 0x, ParaSwap)

  • 1inch, 0x, ParaSwap and similar aggregators support many chains and DEXs. They do not support ChainID 138 unless they add it.
  • To use them with Chain 138: The aggregator would need to add Chain 138 to their config, index or connect to DODO PMM (and any other DEX on 138), and expose 138 in their API/UI. Today you would contact them for integration (see DEX_INTEGRATION_GUIDE).
  • Until then: Use the token-aggregation API for quotes and the DODOPMMIntegration contract for execution on 138.

5.3 Explorer / bridge aggregator (Go backend)

The explorer-monorepo backend has a bridge aggregator that uses Li.Fi, Socket, Squid, Symbiosis, Relay, Stargate. That aggregation is for bridge routes, not for on-chain DEX swaps on 138. For swap + bridge + swap, the orchestration POST /api/bridge/quote and optional SwapBridgeSwapCoordinator are the relevant pieces.

6. End-to-end flows (summary)

Flow A: Swap on Chain 138 only (same chain)

  1. Resolve tokens: GET /api/v1/tokens?chainId=138 or token list; get addresses for cUSDT, cUSDC, WETH.
  2. Get quote: GET /api/v1/quote?chainId=138&tokenIn=<cUSDT>&tokenOut=<cUSDC>&amountIn=...
  3. Execute: User signs a tx calling DODOPMMIntegration.swapCUSDTForUSDC(pool, amountIn, minAmountOut) (or the matching function for the pair), with approval for the input token.

Flow B: Bridge from Chain 138 (no destination swap)

  1. Bridge routes: GET /api/v1/bridge/routes for WETH9/WETH10 and Chain 138 bridge addresses.
  2. Token mapping: If needed, GET /api/v1/token-mapping/resolve for 138→destination.
  3. User sends a bridge tx (e.g. CCIP) from 138 to the destination chain; no DEX swap on 138 unless they first swap into WETH/WETH10.

Flow C: Swap on 138 → bridge → swap on destination

  1. Quote: POST /api/bridge/quote with source chain 138, destination chain, token, amount, destination address. Response may include sourceSwapQuote and destinationSwapQuote.
  2. Source (138): If user holds cUSDT/cUSDC, optionally swap to WETH via DODOPMMIntegration (or future router) using Flow A.
  3. Bridge: User (or coordinator) executes bridge transfer.
  4. Destination: Optional swap using destinationSwapQuote or destination-chain DEX.

7. Config and env (integrators)

Use case Env / config
Token-aggregation indexing DODO on 138 CHAIN_138_DODO_PMM_INTEGRATION=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D (and RPC, DB). Optional: CHAIN_138_DODO_POOL_MANAGER, CHAIN_138_DODO_VENDING_MACHINE.
Uniswap on 138 (if deployed) CHAIN_138_UNISWAP_V2_FACTORY, CHAIN_138_UNISWAP_V2_ROUTER, CHAIN_138_UNISWAP_V2_START_BLOCK (and V3 equivalents).
Bridge quote (swap+bridge+swap) RPC_URL, BRIDGE_REGISTRY_ADDRESS; optional ENHANCED_SWAP_ROUTER_ADDRESS, DESTINATION_RPC_URL, DESTINATION_SWAP_ROUTER_ADDRESS.
Token list / MetaMask Token-aggregation GET /api/v1/report/token-list?chainId=138 or static list; point MetaMask/dApp to this URL.

8. Reference

Document Content
PMM_DEX_ROUTING_STATUS.md DEX/PMM deployment status, what’s live vs not
TASKS_TO_INCREASE_ALL_E2E_FLOWS.md Tasks required to complete Flow A, B, C and cross-cutting E2E
STATUS_AND_TOKEN_ROUTING.md Token-aggregation API summary, routing layers, multihop
REST_API_REFERENCE.md Full token-aggregation API
DODO_PMM_INTEGRATION.md Pool creation, swap functions, liquidity
ENHANCED_ROUTING.md Multi-provider routing design (EnhancedSwapRouter)
DEX_INTEGRATION_GUIDE.md Partner DEX/aggregator options (1inch, 0x, ParaSwap)
ADDRESS_MATRIX_AND_STATUS.md All Chain 138 addresses (tokens, pools, contracts)

Explorer (Chain 138): https://explorer.d-bis.org
RPC (public): https://rpc-core.d-bis.org (deployment should use Core RPC; see runbooks.)

Reference in New Issue View Git Blame Copy Permalink