dex-aggregator

Reusable local DEX route aggregator for liquidation systems.

This crate owns the DEX routing runtime only:

• Pool index loading.
• AMM instance construction and state synchronization.
• Direct / bridge / multi-hop path discovery.
• Route simulation and split-route optimization.
• Solidity DexRouter.SwapRoute compatible output.

It intentionally does not own protocol-specific liquidation logic:

• No Aave or Morpho user state.
• No health-factor computation.
• No executor or transaction broadcasting.
• No database.
• No PoolIndex generation pipeline.
• No direct dependency on application PriceService modules.

Integration Boundary

Applications provide:

• DexAggregatorConfig
• chain provider
• optional DexAggregatorNotifier
• request-time pricing context
• protocol-specific liquidation request mapping

The crate provides:

• DexAggregator
• RouteCalculator
• RouteRequest
• RouteCalculationRequest
• RouteBatchRequest
• AggregatedSwapRoutes
• SwapRoute / SwapStep

Pricing Model

The aggregator does not call external price services during route calculation. Applications pass prices at request time:

• Single request: RoutePricingContext
• Batch request: shared Arc<RoutePricingSnapshot>

This avoids async service calls, lock contention, and repeated price reads inside the hot route calculation path.

Notification Model

The crate exposes a minimal notifier trait:

#[async_trait::async_trait]
pub trait DexAggregatorNotifier: Send + Sync {
    async fn notify(&self, title: &str, body: &str);
}

If no notifier is provided, NoopDexAggregatorNotifier is used and notifications are ignored.

Ignored Tokens

Ignored tokens are passed through DexAggregatorConfig::ignored_tokens. The aggregator still returns route errors normally, but suppresses noisy route-failure notifications for ignored pairs.

Pool Index

This crate consumes an existing NDJSON PoolIndex file through DexAggregatorConfig::pool_index_path. PoolIndex generation is intentionally out of scope for the first extraction phase.

Validation

The repository includes the first migrated Ethereum mainnet baseline from the Aave liquidation project:

• test-data/pool_index_1.json
• test-data/aave_verification_routes_baseline.json

Useful commands:

just test
ETHEREUM_RPC_URL=... just verify-eth-routes
ETHEREUM_RPC_URL=... just generate-verification-routes
MAINNET_RPC_URL=... just forge-verify-routes

verify-eth-routes checks live Rust route selection against real AMM state. generate-verification-routes writes test-data/verification_routes.json. forge-verify-routes executes those vectors on a mainnet fork through the deployed DexRouter.

See docs/route-validation.md for the full validation boundary.

Multi-Chain Safety

PoolIndex owns an instance-level AddressNormalizer. There is no process-global address normalization state in runtime path discovery.