DEX Aggregation in VoidDex: Building an…

Finding the best swap rate isn't as simple as checking one DEX. VoidDex aggregates quotes from multiple protocols, evaluates split routes, considers multi-hop paths, and calculates the optimal execution strategy. This article covers the backend architecture that makes this work.

Quote Service Architecture

The NestJS backend organizes quote logic into specialized services:

TypeScript
@Module({
  imports: [ConfigModule, ProtocolModule, PoolModule],
  controllers: [QuoteController],
  providers: [
    QuoteService,           // Main entry point
    DexQuoteService,        // Fetches quotes from DEXes
    LiquidityGraphService,  // Builds graph of available liquidity
    PathfinderService,      // Finds optimal paths through the graph
    RouteQuoteService,      // Gets quotes for discovered routes
    RouteOptimizerService,  // Optimizes split routing
    FeeCalculatorService,   // Calculates fees in WETH
    PriceService,           // Token price lookups
  ],
  exports: [QuoteService],
})
export class QuoteModule {}

The routing architecture uses a dual-flow approach: a primary pathfinder flow for discovering multi-hop routes, with a fallback to direct DEX quotes for simple pairs.

Dual-Flow Quote Architecture

VoidDex implements a sophisticated two-tier routing system:

TypeScript
@Injectable()
export class QuoteService {
  constructor(
    private readonly dexQuoteService: DexQuoteService,
    private readonly routeOptimizer: RouteOptimizerService,
    private readonly feeCalculator: FeeCalculatorService,
    private readonly priceService: PriceService,
    private readonly pathfinderService: PathfinderService,
    private readonly routeQuoteService: RouteQuoteService,
  ) {}

  async getQuote(params: QuoteParams): Promise<QuoteResponse> {
    const { chainId, fromToken, toToken, amount, slippage = 0.5 } = params;

    // Resolve token addresses and get provider
    const provider = this.getProvider(chainId);
    const fromTokenAddress = this.resolveTokenAddress(chainId, fromToken);
    const toTokenAddress = this.resolveTokenAddress(chainId, toToken);
    const amountIn = parseUnits(amount, fromDecimals);

    // === PRIMARY FLOW: Dynamic Route Discovery ===
    // 1. Discover all possible routes using pathfinder
    const discoveredRoutes = await this.pathfinderService.findRoutes(
      chainId,
      fromTokenAddress,
      toTokenAddress,
    );

    // 2. If routes found, get quotes and optimize
    if (discoveredRoutes.length > 0) {
      const routeQuotes = await this.routeQuoteService.getQuotesForRoutes(
        chainId,
        provider,
        discoveredRoutes,
        amountIn,
        toDecimals,
      );

      if (routeQuotes.length > 0) {
        // Try route-level split optimization
        const splitResult = this.optimizeRouteSplit(routeQuotes, amountIn, ...);
        if (splitResult) {
          return this.buildSplitRouteResponse(...);
        }
      }
    }

    // === FALLBACK: Direct DEX Quotes ===
    const dexQuotes = await this.dexQuoteService.fetchAllQuotes(
      chainId, provider, fromTokenAddress, toTokenAddress, amountIn, ...
    );

    // Find optimal route (single or split)
    const optimalRoute = this.routeOptimizer.findOptimalRoute(dexQuotes, ...);

    // Calculate fees and return response
    const fees = await this.feeCalculator.calculateFees({...});
    return { ... };
  }
}

This dual-flow design ensures:

Multi-hop discovery: The pathfinder can find routes like WBTC -> WETH -> USDC when no direct pool exists
Fallback reliability: Direct DEX quotes work for simple pairs even if the graph is incomplete
Split optimization: Both flows support splitting across multiple routes for better execution

RouteQuoteService: The Route Pricing Engine

The RouteQuoteService is critical for getting accurate quotes on discovered routes. It simulates each hop in sequence:

TypeScript
@Injectable()
export class RouteQuoteService {
  /**
   * Get quotes for all discovered routes
   */
  async getQuotesForRoutes(
    chainId: number,
    provider: PublicClient,
    routes: DiscoveredRoute[],
    amountIn: bigint,
    toDecimals: number,
  ): Promise<RouteQuote[]> {
    const quotePromises = routes.map((route) =>
      this.getQuoteForRoute(chainId, provider, route, amountIn, toDecimals)
    );

    const results = await Promise.all(quotePromises);

    // Filter out failed quotes and sort by output (best first)
    const validQuotes = results
      .filter((q): q is RouteQuote => q !== null)
      .sort((a, b) => (b.amountOut > a.amountOut ? 1 : -1));

    return validQuotes;
  }

  /**
   * Get quote for a single route by simulating each hop
   */
  private async getQuoteForRoute(
    chainId: number,
    provider: PublicClient,
    route: DiscoveredRoute,
    amountIn: bigint,
    toDecimals: number,
  ): Promise<RouteQuote | null> {
    try {
      const hopsData: HopQuoteData[] = [];
      let currentAmount = amountIn;

      // Simulate each hop in sequence
      for (const hop of route.hops) {
        const hopQuote = await this.getHopQuote(chainId, provider, hop, currentAmount);

        if (!hopQuote) {
          return null; // Route fails if any hop fails
        }

        hopsData.push(hopQuote);
        currentAmount = hopQuote.amountOut; // Output becomes next hop's input
      }

      return {
        route,
        amountIn,
        amountOut: currentAmount,
        amountOutFormatted: formatUnits(currentAmount, toDecimals),
        priceImpact: this.estimatePriceImpact(route.totalHops, amountIn),
        estimatedGas: route.estimatedGas,
        hopsData,
      };
    } catch (error) {
      return null;
    }
  }

  /**
   * Get quote for a single hop (V2 or V3)
   */
  private async getHopQuote(
    chainId: number,
    provider: PublicClient,
    hop: RouteHop,
    amountIn: bigint,
  ): Promise<HopQuoteData | null> {
    const dexInfo = DEX_INFO[hop.dexId];
    const dexContracts = DEX_CONTRACTS[chainId]?.[hop.dexId];

    if (dexInfo.type === 'amm_v3') {
      return await this.getV3HopQuote(provider, dexContracts.quoter!, hop, amountIn);
    } else if (dexInfo.type === 'amm_v2') {
      return await this.getV2HopQuote(provider, dexContracts.router, hop, amountIn);
    }
    return null;
  }
}

The hop-by-hop simulation ensures accurate output calculations for complex multi-hop routes, where each intermediate swap's output becomes the next swap's input

DEX Quote Fetching

Each DEX requires different query methods. The service abstracts these differences:

TypeScript
@Injectable()
export class DexQuoteService {
  private readonly providers = new Map<number, PublicClient>();

  async fetchAllQuotes(
    chainId: number,
    fromToken: string,
    toToken: string,
    amount: string,
    path?: OptimalPath
  ): Promise<QuoteResults> {
    const dexes = this.getAvailableDexes(chainId);

    const quotePromises = dexes.map(async dex => {
      try {
        return await this.getQuoteFromDex(dex, chainId, fromToken, toToken, amount);
      } catch (error) {
        // DEX might not support this pair
        this.logger.debug(`${dex.name} quote failed: ${error.message}`);
        return null;
      }
    });

    const results = await Promise.allSettled(quotePromises);

    const quotes = results
      .filter((r): r is PromiseFulfilledResult<DexQuoteResult> => 
        r.status === 'fulfilled' && r.value !== null
      )
      .map(r => r.value)
      .sort((a, b) => BigInt(b.amountOut) - BigInt(a.amountOut) > 0n ? 1 : -1);

    return {
      quotes,
      bestOutput: quotes[0] ? BigInt(quotes[0].amountOut) : 0n,
    };
  }

  private async getQuoteFromDex(
    dex: DexConfig,
    chainId: number,
    fromToken: string,
    toToken: string,
    amount: string
  ): Promise<DexQuoteResult> {
    switch (dex.type) {
      case 'uniswap-v3':
        return this.getUniswapV3Quote(chainId, fromToken, toToken, amount, dex);
      case 'uniswap-v2':
        return this.getUniswapV2Quote(chainId, fromToken, toToken, amount, dex);
      default:
        throw new Error(`Unsupported DEX type: ${dex.type}`);
    }
  }
}

Uniswap V3 Quotes

Uniswap V3 has multiple fee tiers. We query all and pick the best:

TypeScript
async getUniswapV3Quote(
  chainId: number,
  fromToken: string,
  toToken: string,
  amount: string,
  config: DexConfig
): Promise<DexQuoteResult> {
  const provider = this.providers.get(chainId);
  const quoter = new Contract(config.quoterAddress, QUOTER_V2_ABI, provider);

  const feeTiers = [100, 500, 3000, 10000]; // 0.01%, 0.05%, 0.3%, 1%
  let bestQuote: { amountOut: bigint; feeTier: number } | null = null;

  for (const feeTier of feeTiers) {
    try {
      const result = await quoter.callStatic.quoteExactInputSingle({
        tokenIn: fromToken,
        tokenOut: toToken,
        fee: feeTier,
        amountIn: parseUnits(amount, await this.getDecimals(fromToken)),
        sqrtPriceLimitX96: 0,
      });

      if (!bestQuote || result.amountOut > bestQuote.amountOut) {
        bestQuote = { amountOut: result.amountOut, feeTier };
      }
    } catch {
      // Pool doesn't exist for this fee tier
      continue;
    }
  }

  if (!bestQuote) {
    throw new Error('No Uniswap V3 pool found');
  }

  return {
    dexId: 'uniswap-v3',
    dexName: 'Uniswap V3',
    amountOut: bestQuote.amountOut.toString(),
    path: this.encodeUniswapV3Path(fromToken, toToken, bestQuote.feeTier),
    extraData: { feeTier: bestQuote.feeTier },
  };
}

private encodeUniswapV3Path(
  tokenIn: string,
  tokenOut: string,
  feeTier: number
): string {
  // Uniswap V3 path encoding: token + fee + token + fee + ...
  return encodePacked(
    ['address', 'uint24', 'address'],
    [tokenIn, feeTier, tokenOut]
  );
}

Multi-Hop Path Finding

Sometimes the best rate requires intermediate tokens. The pathfinder discovers these:

TypeScript
@Injectable()
export class PathfinderService {
  // Common bridge tokens for multi-hop
  private readonly bridgeTokens: Record<number, string[]> = {
    1: ['WETH', 'USDC', 'USDT', 'DAI', 'WBTC'], // Ethereum
    137: ['WMATIC', 'USDC', 'USDT', 'WETH'],     // Polygon
    42161: ['WETH', 'USDC', 'USDT', 'ARB'],      // Arbitrum
  };

  async findPaths(
    chainId: number,
    fromToken: string,
    toToken: string
  ): Promise<TokenPath[]> {
    const bridges = this.bridgeTokens[chainId] || [];
    const paths: TokenPath[] = [];

    for (const bridge of bridges) {
      const bridgeAddress = this.resolveToken(chainId, bridge);

      // Skip if bridge is one of the swap tokens
      if (
        bridgeAddress.toLowerCase() === fromToken.toLowerCase() ||
        bridgeAddress.toLowerCase() === toToken.toLowerCase()
      ) {
        continue;
      }

      // Check if path exists
      const hasFirstHop = await this.poolExists(chainId, fromToken, bridgeAddress);
      const hasSecondHop = await this.poolExists(chainId, bridgeAddress, toToken);

      if (hasFirstHop && hasSecondHop) {
        paths.push({
          tokens: [fromToken, bridgeAddress, toToken],
          description: `${this.getSymbol(fromToken)} → ${bridge} → ${this.getSymbol(toToken)}`,
        });
      }
    }

    return paths;
  }

  private async poolExists(
    chainId: number,
    tokenA: string,
    tokenB: string
  ): Promise<boolean> {
    // Check Uniswap V3 factory
    const factory = this.getUniswapFactory(chainId);
    for (const fee of [500, 3000, 10000]) {
      const pool = await factory.getPool(tokenA, tokenB, fee);
      if (pool !== ethers.constants.AddressZero) {
        return true;
      }
    }
    return false;
  }
}

Route Optimization

With all quotes collected, the optimizer finds the best execution strategy:

TypeScript
@Injectable()
export class RouteOptimizerService {
  optimize(
    quotes: DexQuoteResult[],
    options: OptimizeOptions
  ): OptimalRoute {
    // Strategy 1: Best single DEX
    const bestSingle = this.findBestSingle(quotes);

    // Strategy 2: Split across top DEXes
    const bestSplit = this.findBestSplit(quotes, options);

    // Strategy 3: Best multi-hop (already in quotes)
    const bestMultiHop = this.findBestMultiHop(quotes);

    // Compare and return best
    const candidates = [bestSingle, bestSplit, bestMultiHop].filter(Boolean);
    return this.selectBest(candidates);
  }

  private findBestSingle(quotes: DexQuoteResult[]): OptimalRoute | null {
    const directQuotes = quotes.filter(q => !q.isMultiHop);
    if (directQuotes.length === 0) return null;

    const best = directQuotes[0]; // Already sorted by output
    return {
      type: 'single',
      steps: [{
        dexId: best.dexId,
        percentage: 10000,
        minAmountOut: best.amountOut,
        dexData: best.extraData,
      }],
      totalOutput: BigInt(best.amountOut),
      isSplit: false,
    };
  }

  private findBestSplit(
    quotes: DexQuoteResult[],
    options: OptimizeOptions
  ): OptimalRoute | null {
    const directQuotes = quotes.filter(q => !q.isMultiHop);
    if (directQuotes.length < 2) return null;

    // Try different split ratios
    const splitRatios = this.generateSplitRatios(options.maxSplits);
    let bestSplit: OptimalRoute | null = null;

    for (const ratio of splitRatios) {
      if (ratio.length > directQuotes.length) continue;

      // Calculate output for this split
      let totalOutput = 0n;
      const steps = [];

      for (let i = 0; i < ratio.length; i++) {
        const quote = directQuotes[i];
        const percentage = ratio[i];
        
        // Estimate output for partial amount
        // This is simplified; real implementation would re-query with partial amounts
        const partialOutput = (BigInt(quote.amountOut) * BigInt(percentage)) / 10000n;
        totalOutput += partialOutput;

        steps.push({
          dexId: quote.dexId,
          percentage,
          minAmountOut: partialOutput.toString(),
          dexData: quote.extraData,
        });
      }

      if (!bestSplit || totalOutput > bestSplit.totalOutput) {
        bestSplit = {
          type: 'split',
          steps,
          totalOutput,
          isSplit: true,
        };
      }
    }

    return bestSplit;
  }

  private generateSplitRatios(maxSplits: number): number[][] {
    // Common split patterns
    return [
      [5000, 5000],           // 50-50
      [6000, 4000],           // 60-40
      [7000, 3000],           // 70-30
      [5000, 3000, 2000],     // 50-30-20
      [4000, 3000, 3000],     // 40-30-30
    ].filter(r => r.length <= maxSplits);
  }

  private findBestMultiHop(quotes: DexQuoteResult[]): OptimalRoute | null {
    const multiHopQuotes = quotes.filter(q => q.isMultiHop);
    if (multiHopQuotes.length === 0) return null;

    const best = multiHopQuotes[0];
    return {
      type: 'multi-hop',
      steps: best.hops.map((hop, i) => ({
        dexId: hop.dexId,
        tokenOut: hop.tokenOut,
        minAmountOut: hop.expectedOutput,
        dexData: hop.extraData,
      })),
      totalOutput: BigInt(best.amountOut),
      isSplit: false,
      isSequential: true,
    };
  }

  private selectBest(candidates: OptimalRoute[]): OptimalRoute {
    // Simple: pick highest output
    // Could factor in gas costs, execution complexity
    return candidates.reduce((best, current) => 
      current.totalOutput > best.totalOutput ? current : best
    );
  }
}

Fee Calculation

All fees in VoidDex are denominated in WETH. The fee calculator handles two components: the protocol fee and the broadcaster fee.

TypeScript
@Injectable()
export class FeeCalculatorService {
  private readonly VOIDDEX_FEE_BPS = 5; // 0.05% of input amount
  private readonly BROADCASTER_PROFIT_MARGIN = 15; // 15% profit margin on gas

  constructor(
    private readonly priceService: PriceService,
    private readonly gasService: GasService,
  ) {}

  async calculate(inputAmount: string, chainId: number): Promise<FeeBreakdown> {
    // Protocol fee: 0.05% of INPUT amount (not output)
    const inputBigInt = BigInt(inputAmount);
    const voidDexFee = (inputBigInt * BigInt(this.VOIDDEX_FEE_BPS)) / 10000n;

    // Broadcaster fee: estimated gas cost + 15% profit margin
    const estimatedGas = await this.gasService.estimateSwapGas(chainId);
    const gasPrice = await this.gasService.getGasPrice(chainId);
    const gasCostWei = estimatedGas * gasPrice;
    const broadcasterFee = (gasCostWei * BigInt(100 + this.BROADCASTER_PROFIT_MARGIN)) / 100n;

    // Convert protocol fee to WETH if input token is not WETH
    const voidDexFeeWeth = await this.priceService.convertToWeth(
      voidDexFee, inputAmount, chainId
    );

    const totalFeeWeth = voidDexFeeWeth + broadcasterFee;

    return {
      broadcasterFee: broadcasterFee.toString(),
      voidDexFee: voidDexFeeWeth.toString(),
      totalFeeWeth: totalFeeWeth.toString(),
      voidDexFeeBps: this.VOIDDEX_FEE_BPS,
    };
  }
}

Key points about the fee structure:

VoidDex Protocol Fee: 0.05% (5 basis points) calculated on the INPUT amount, not the output
Broadcaster Fee: Covers gas costs plus a 15% profit margin for the transaction broadcaster
All fees are in WETH: Regardless of the input/output tokens, fees are always denominated in WETH

Price Impact Calculation

Price impact is estimated using heuristics based on trade size in USD. The RouteOptimizerService uses a tiered linear interpolation approach:

TypeScript
/**
 * Estimate price impact based on trade size
 */
estimatePriceImpact(amountUsd: number): number {
  if (amountUsd < 1000) return 0.1;
  if (amountUsd < 10000) return 0.2 + (amountUsd - 1000) * 0.00001;
  if (amountUsd < 100000) return 0.3 + (amountUsd - 10000) * 0.000005;
  if (amountUsd < 1000000) return 0.8 + (amountUsd - 100000) * 0.000002;
  return 3; // Cap at 3%
}

This provides graduated estimates:

Under $1,000: 0.1% (minimal impact)
$1,000 - $10,000: 0.2% - 0.29% (linear interpolation)
$10,000 - $100,000: 0.3% - 0.75% (slower growth)
$100,000 - $1,000,000: 0.8% - 2.6% (larger trades face more impact)
Over $1,000,000: Capped at 3%

For multi-hop routes, the RouteQuoteService has a separate heuristic that factors in hop count:

TypeScript
/**
 * Estimate price impact based on hops and amount
 */
private estimatePriceImpact(hops: number, amountIn: bigint): number {
  // Base impact per hop
  const baseImpact = 0.3;
  // Additional impact for larger amounts (simplified)
  const amountFactor = Number(amountIn) / 1e18;
  const amountImpact = Math.min(amountFactor * 0.001, 1);

  return baseImpact * hops + amountImpact;
}

This estimates 0.3% base impact per hop, plus an amount-based factor that scales with trade size (capped at 1% additional).

Response Formatting

The final quote response provides everything the frontend needs:

TypeScript
interface FeeBreakdown {
  broadcasterFee: string;   // Gas cost + 15% margin (in WETH)
  voidDexFee: string;       // 0.05% of input (in WETH)
  totalFeeWeth: string;     // Sum of all fees (in WETH)
  voidDexFeeBps: number;    // Fee rate in basis points (5)
}

interface QuoteResponse {
  fromToken: string;
  toToken: string;
  fromAmount: string;
  toAmount: string;
  route: {
    steps: RouteStep[];
    totalSteps: number;
    isSplit: boolean;
    isSequential?: boolean;
  };
  fees: FeeBreakdown;
  meta: {
    priceImpact: string;
    exchangeRate: string;
    minReceived: string;
    expiresAt: number; // Unix timestamp
  };
}

// Example response
{
  "fromToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  "toToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "fromAmount": "1000000000000000000",
  "toAmount": "3245670000",
  "route": {
    "steps": [
      {
        "dexId": "uniswap-v3",
        "percentage": 10000,
        "minAmountOut": "3245670000",
        "dexData": { "feeTier": 500 }
      }
    ],
    "totalSteps": 1,
    "isSplit": false
  },
  "fees": {
    "broadcasterFee": "2300000000000000",
    "voidDexFee": "500000000000000",
    "totalFeeWeth": "2800000000000000",
    "voidDexFeeBps": 5
  },
  "meta": {
    "priceImpact": "0.05",
    "exchangeRate": "3245.67",
    "minReceived": "3229.45",
    "expiresAt": 1705430400000
  }
}

The example response shows a single-DEX route using Uniswap V3. The fees are denominated in WETH (wei units), with the broadcaster fee covering gas costs plus a 15% profit margin.

The frontend uses this to display the route visualization, show the user what they'll receive, and encode the on-chain transaction.

Keep reading

VoidDex Router: Designing a Multi-DEX Swap Router with Split Routing
Deep dive into VoidDex's smart contract architecture, covering the router design, DEX adapter system, and split routing for optimal execution.
Privacy Architecture in VoidDex: Integrating Railgun's zkSNARK System
How VoidDex implements private token swaps using Railgun's zero-knowledge proof system, covering the shield/unshield flow, client-side proof generation, and the Waku P2P broadcaster network.
Building VoidDex: A Technical Deep Dive into Privacy-Preserving DEX Aggregation
Every swap you make on a decentralized exchange is public. VoidDex is my attempt at building a DEX aggregator that maintains the benefits of decentralized trading while adding a cryptographic privacy layer using zkSNARK proofs.

DEX Aggregation in VoidDex: Building an Optimal Route Finder

Uniswap V3 Quotes

Keep reading