Detailed Instructions

The aggregator's routing engine queries APIs from integrated protocols (e.g., Uniswap V3, Curve, 1inch Fusion) to gather the current state of all potential paths. This includes fetching reserve sizes, fee tiers, and spot prices for each token pair. Data must be normalized to a common denominator, typically the input token, to enable direct comparison. For cross-chain routes, the system also pulls bridge latency estimates and destination chain gas costs.

• Sub-step 1: Call getReserves() on relevant pool contracts or use subgraph queries for historical depth.
• Sub-step 2: Convert all output amounts to the input token using the discovered spot price on each path.
• Sub-step 3: Apply protocol-specific fee models (e.g., 0.05% for Uniswap V3, variable fees for Balancer) to adjust the effective rate.

typescriptCopy
// Example: Fetching pool data from multiple sources
const poolData = await Promise.all([
  uniswapV3Quoter.quoteExactInputSingle(params),
  curvePool.get_dy(i, j, amountIn),
  balancerVault.queryBatchSwap(swapKind, swaps, assets, funds)
]);

Tip: Implement robust fallback mechanisms. If a primary data source (e.g., a node RPC) is slow, switch to a decentralized data network like The Graph or a secondary provider.

Detailed Instructions

Each liquidity pool or bridge is represented as a directed edge in a graph, with nodes as tokens. The edge weight is the effective exchange rate after fees. The system constructs this graph for all connected assets. To manage computational complexity, it performs graph pruning by removing edges with prohibitively high fees or insufficient depth for the trade size. A minimum liquidity threshold (e.g., 10x the trade size) is often applied. For cross-chain swaps, edges include bridge transfer time as a non-cost weight factor.

• Sub-step 1: Create adjacency list mapping token addresses to arrays of connected pools and their calculated output rates.
• Sub-step 2: Apply filters: discard pools where reserveOut < minLiquidityRatio * tradeSize.
• Sub-step 3: For multi-hop paths, compute the aggregate slippage using the product of exchange rates along the path.

pythonCopy
# Example: Simple graph pruning logic
def prune_graph(graph, trade_amount, min_liquidity_multiplier=10):
    pruned_edges = []
    for edge in graph.edges:
        if edge.liquidity < (trade_amount * min_liquidity_multiplier):
            continue
        if edge.fee_bps > MAX_ACCEPTABLE_FEE:
            continue
        pruned_edges.append(edge)
    return Graph(pruned_edges)

Tip: Use a k-shortest paths or Yen's algorithm to find the top N candidate paths instead of just the single best, providing fallback options if the primary route fails.

Detailed Instructions

This is a constrained optimization problem. The objective is to maximize total output subject to the constraint that the sum of input splits equals the total trade size. The system models each path's marginal return, which decreases with larger amounts due to slippage (often approximated as a quadratic function). Solvers use techniques like linear programming for simple fee models or iterative bisection for complex, non-linear curves. The output is a list of {pathId, amountIn} pairs. For cross-chain, the algorithm may optimize for lowest cost versus fastest time based on user preference.

• Sub-step 1: For each candidate path, generate a price impact function, e.g., getAmountOut(amountIn) from the pool's bonding curve.
• Sub-step 2: Formulate the objective: Maximize Σ getAmountOut_i(x_i) where Σ x_i = totalInput.
• Sub-step 3: Run the solver (e.g., using the simplex method or a greedy algorithm with decay).

solidityCopy
// Simplified view of a split calculation in a smart contract
function findOptimalSplit(uint256 totalIn, Path[] memory paths) internal view returns (uint256[] memory splits) {
    splits = new uint256[](paths.length);
    // ... Iterative logic to allocate `totalIn` across `paths`
    // based on marginal output `paths[i].quote(allocatedAmount + delta)`
}

Tip: In production, the algorithm must account for gas costs of executing multiple transactions, which can negate gains from small splits. Bundle gas into the cost function.

Detailed Instructions

Before submitting transactions, the aggregator must simulate the entire bundle on a forked network or via an eth_call RPC. This checks for transaction reverts, validates that simulated output meets the minimum required amount (slippage tolerance), and confirms final state changes. It also estimates gas consumption for the multi-transaction bundle. For MEV protection, simulations check for sandwich attack vulnerability by evaluating price impact before and after the trade. The system compares the simulated net outcome to a benchmark rate (e.g., a single DEX trade) to ensure improvement.

• Sub-step 1: For each split path, call staticcall to the target contract with the proposed amountIn and user parameters.
• Sub-step 2: Sum all simulated amountOut values and subtract estimated total gas cost in the output token.
• Sub-step 3: If netOutput < (benchmarkOutput * (1 - slippageTolerance)), re-run the optimization.

javascriptCopy
// Example: Simulating a split trade bundle
const simulations = await Promise.all(
  splitPlan.map(path => 
    provider.call({
      to: path.router,
      data: encodeSwap(path, userAddress)
    })
  )
);
const totalOutput = simulations.reduce((sum, sim) => sum + decodeOutput(sim), 0n);
const isProfitable = totalOutput > benchmarkOutput;

Tip: Use a block-state from 1-2 blocks ago for simulation to avoid frontrunning your own validation and to get a more realistic gas estimate.

Detailed Instructions

The final step is transaction construction and submission. The aggregator's smart contract router (e.g., 1inch AggregationRouterV5) is called with encoded data for all split paths. A single approve transaction for the input token to the router is often batched. For cross-chain splits, the system may use a cross-chain messaging protocol (e.g., LayerZero, Axelar) to orchestrate transactions on destination chains. The bundle is sent to a private transaction pool or via a Flashbots bundle to mitigate MEV extraction. The user receives a single signature request for the aggregated transaction.

• Sub-step 1: Encode multicall data for the router: aggregatorRouter.multicall([swapDataForPath1, swapDataForPath2]).
• Sub-step 2: Set a deadline (e.g., block.timestamp + 300) and slippage limit in each swap's parameters.
• Sub-step 3: Submit the signed transaction through a configured RPC endpoint, prioritizing speed or cost based on user settings.

solidityCopy
// Example core of an aggregator router function
function swap(
    IAggregationExecutor executor,
    SwapDescription calldata desc,
    bytes calldata permit,
    bytes calldata data // Encoded calls for each split
) external payable returns (uint256 returnAmount) {
    // ... Transfers input token, executes splits via executor
    returnAmount = executor.callBytes{value: msg.value}(data);
    require(returnAmount >= desc.minReturnAmount, "Return amount too low");
}

Tip: Implement robust failure handling. If one leg of a split fails, the entire transaction should revert to prevent partial execution, unless the router supports partial fill mode.

Detailed Instructions

First, define the core trade parameters: the input token (e.g., 1000 USDC), the output token (e.g., WETH), and the acceptable slippage tolerance (e.g., 0.5%). The aggregator's router contract then queries its integrated liquidity sources—such as Uniswap V3, Curve, and Balancer—for potential swap routes. It requests quotes for the full amount on each possible path, receiving data on expected output, fees, and gas costs. This raw data includes the effective exchange rate for each route, which is the amount of output token received per unit of input, net of fees. The system logs all viable single-source paths before optimization begins.

typescriptCopy
const tradeRequest = {
  inputToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  outputToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
  amountIn: '1000000000', // 1000 USDC (6 decimals)
  slippageTolerance: 0.005 // 0.5%
};

Tip: Aggregators often use a quote caching layer to reduce latency and RPC calls, but for optimal splits, fresh on-chain queries are essential.

Detailed Instructions

With all single-path quotes gathered, the aggregator's smart order router executes an optimization algorithm. This typically involves solving a knapsack problem or using linear programming to maximize the total output. The algorithm evaluates splitting the input amount between two or more routes. For instance, it might calculate that sending 600 USDC through a Uniswap V3 pool and 400 USDC through a Balancer pool yields a better aggregate rate than any single route. Key constraints include respecting each pool's liquidity depth to avoid excessive price impact and ensuring the combined gas cost of multiple transactions doesn't erode gains. The algorithm outputs a set of split proportions and their corresponding routes.

pythonCopy
# Simplified optimization logic
potential_splits = []
for route_a in all_routes:
    for route_b in all_routes:
        if route_a != route_b:
            for split_pct in [0.1, 0.2, ..., 0.9]:
                amount_a = total_input * split_pct
                amount_b = total_input * (1 - split_pct)
                total_output = route_a.quote(amount_a) + route_b.quote(amount_b)
                potential_splits.append((total_output, split_pct, route_a, route_b))
optimal_split = max(potential_splits, key=lambda x: x[0])

Tip: In practice, algorithms use more efficient methods like dynamic programming to evaluate thousands of split combinations across dozens of pools in milliseconds.

Detailed Instructions

Before presenting the quote to the user, the aggregator must validate the proposed split trade via gas-estimated simulation. It calls the eth_call RPC method on the router contract, passing the optimized split parameters. This static call simulates the transaction against the current state of each involved DEX without broadcasting it. The simulation checks for critical failures: insufficient liquidity, slippage beyond tolerance, or router contract errors. It also calculates the precise net output after gas, subtracting the estimated cost of the more complex multi-swap transaction. The final validated output is compared against a benchmark, like the best single-source quote, to confirm the price improvement. If simulation fails, the algorithm reverts to the next best split configuration.

bashCopy
# Example curl for a simulation request
curl -X POST \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0xrouterAddress","data":"0xcalldataForSplitSwap"},"latest"],"id":1}' \
  https://eth-mainnet.g.alchemy.com/v2/your-api-key

Tip: Always simulate with a slightly higher slippage tolerance as a buffer; final user slippage is applied in the live transaction.

Detailed Instructions

After successful simulation, the aggregator constructs the final transaction. The router contract's swap function is encoded with all necessary parameters for the split. This includes an array of path descriptors, each specifying a DEX adapter, token path, and portion of the input funds. For our example, the calldata would instruct the router to send 600 USDC to Uniswap V3 via its specific adapter (e.g., 0xAdapterA) and 400 USDC to Balancer via 0xAdapterB. The transaction also enforces a minimum total output amount, derived from the simulated output minus the user's defined slippage. The returned payload is a complete, signed-ready transaction object containing the to address (the router), data, value (if involving ETH), and a recommended gasLimit based on the simulation.

solidityCopy
// Simplified router interface for a multi-swap
interface IRouter {
    struct SwapDescription {
        address adapter;
        address[] path;
        uint256 amount;
    }
    function swap(
        SwapDescription[] calldata swaps,
        address recipient,
        uint256 minTotalOutput
    ) external payable returns (uint256 totalOutput);
}

Tip: The single transaction abstraction is key; users approve funds once to the router, which manages the complexity of interacting with multiple protocols atomically.