Detailed Instructions

The aggregator's engine first ingests the user's transaction call, extracting the core parameters that define the trade. This includes the input token (e.g., 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 for WETH), the output token, and the exact input amount. It also reads any user-specified constraints, such as a maximum slippage tolerance (e.g., 0.5%) or a preference to avoid certain liquidity pools. This step establishes the immutable search space. The system must also account for the user's wallet address to check token approvals and calculate precise gas costs for different routes, as these are part of the total effective price.

Tip: Aggregators often simulate the transaction from the user's address to get an accurate gas estimate, which can vary based on token approvals and contract complexity.

Detailed Instructions

The system broadcasts a request to all integrated liquidity sources, which include major DEXs like Uniswap V2/V3, SushiSwap, Balancer, and Curve. For each source, it queries the specific pool or router contract for a quote. This involves calling the getAmountsOut function on Uniswap V2-style routers or the more complex quoteExactInputSingle on Uniswap V3. The query specifies the exact input amount and the token path. For complex multi-hop routes (e.g., ETH -> USDC -> DAI), the aggregator must query each leg sequentially or use a router that handles pathfinding. All queries are performed via a multicall contract (e.g., 0x5BA1e12693Dc8F9c48aAD8770482f4739bEeD696) to batch RPC calls and minimize latency.

solidityCopy
// Example multicall to get quotes from two different DEX routers
aggregate{[
    (dexARouter, dexARouter.getAmountsOut.selector, abi.encode(amountIn, path)),
    (dexBRouter, dexBRouter.quoteExactInputSingle.selector, abi.encode(params))
]}

Detailed Instructions

Raw output amounts from DEXs are not the final metric. The aggregator must calculate the net effective price the user will receive. This involves deducting the aggregator's own protocol fee (if any, often 0-10 bps) and, critically, estimating the gas cost for executing the swap on each potential route. A route using a complex Curve pool or multiple hops may have a higher gas cost than a simple Uniswap V2 swap, negating a slightly better nominal rate. The system fetches current gas prices from an oracle and simulates the transaction to estimate gas units used. The formula is: Effective Output = Raw Output - (Gas Price * Gas Units) - Protocol Fee. This creates an apples-to-apples comparison across heterogeneous sources.

Tip: For large trades, gas cost becomes a smaller percentage, making complex, optimized routes more viable. For small trades, a simple, low-gas route is often best.

Detailed Instructions

Before presenting a quote, the aggregator must validate the route's viability. This includes a liquidity check to ensure the quoted pool has sufficient depth to handle the trade without excessive slippage beyond the user's tolerance. It also involves a security audit of the pathway: verifying that all intermediary tokens are legitimate (not malicious) and that the router contracts are non-malicious and have been properly integrated. The system may check the time-weighted average price (TWAP) from an oracle like Chainlink to flag if the pool price has deviated significantly from the broader market, indicating potential manipulation. Finally, it confirms the user has sufficient token balance and, if needed, an adequate allowance set for the aggregator's router contract (e.g., 0x1111111254EEB25477B68fb85Ed929f73A960582).

Detailed Instructions

With all validated quotes and their calculated net effective outputs, the aggregator ranks them in descending order. The route yielding the highest final amount of the output token for the user is selected as optimal. The system then constructs the final transaction data. This includes the calldata for the swap, which encodes the function call to the aggregator's smart router, the exact path, the minimum output amount (based on slippage), and the recipient address. This complete quote—comprising the expected output, the transaction data, and the estimated gas cost—is returned to the user's wallet interface via a JSON-RPC response. The user can then review and sign the transaction, which will execute the trade along the pre-validated, optimal path.

jsonCopy
{
  "quoteResponse": {
    "expectedOutput": "105.75 DAI",
    "minOutput": "105.21 DAI",
    "gasEstimate": "145000",
    "txData": "0x..."
  }
}

Detailed Instructions

When a DeFi aggregator returns a quote, it is not just a single number. You must parse the quote payload to understand the route. This includes the sequence of protocols (e.g., Uniswap V3, Curve, Balancer), the specific pools involved, and the intermediate tokens. The final output amount is the key metric, but you must also check the minimum received or slippage tolerance parameter derived from it. For a swap of 10 ETH to USDC, a quote might specify a route through WETH/USDC 0.05% fee pool on Uniswap V3, yielding 31,500 USDC with a 0.5% slippage buffer.

• Sub-step 1: Decode the route data to list each hop and the protocol used.
• Sub-step 2: Verify the final quoted amount against live on-chain reserves for the final pool.
• Sub-step 3: Calculate the effective exchange rate and compare it to the market median.

javascriptCopy
// Example structure of an aggregated route
const quoteRoute = {
  inputAmount: '10000000000000000000', // 10 ETH in wei
  outputAmount: '31500000000', // 31,500 USDC (6 decimals)
  route: [
    {
      protocol: 'UNISWAP_V3',
      pool: '0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640',
      tokenIn: 'WETH',
      tokenOut: 'USDC'
    }
  ],
  estimatedGas: 150000
};

Tip: Always validate that the output token address in the quote matches your expected asset to avoid swapping into a worthless mock token.

Detailed Instructions

Before signing, perform a local simulation using eth_call on the aggregated transaction data. This tests the transaction against the state of a recent block (e.g., the latest block minus 2) without broadcasting it. The goal is to catch failures like insufficient liquidity, expired price quotes, or reverts due to maximum slippage being exceeded. Pass the exact data, to (aggregator router address), from, and value fields you intend to use in the real transaction. A successful call returns the expected output amount; a revert provides error data.

• Sub-step 1: Construct the transaction object with all parameters from the aggregator.
• Sub-step 2: Execute eth_call using a node provider like Alchemy or Infura.
• Sub-step 3: Parse the return data or error message to confirm viability.

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

Tip: Use a block number a few blocks prior to 'latest' for more consistent simulation results, as 'latest' can be a pending block.

Detailed Instructions

Static slippage (e.g., always 0.5%) often leads to failed transactions or unnecessary value loss. Calculate dynamic slippage by analyzing the pool's recent price volatility and current network congestion. For a stablecoin pair, 0.1% may suffice. For a volatile meme coin, 5% or more might be needed. Check the price impact from your trade size using the pool's bonding curve. Also, consult the current base fee and priority fee (e.g., from Etherscan's gas tracker) to estimate block inclusion time; higher congestion requires higher slippage tolerance to account for price movement.

• Sub-step 1: Query the pool's historical trades for the last 10 blocks to gauge volatility.
• Sub-step 2: Use the aggregator's SDK or a library like @uniswap/v3-sdk to calculate price impact.
• Sub-step 3: Set slippage as: (price_impact %) + (volatility_buffer %) + (network_delay_buffer %).

javascriptCopy
// Example dynamic slippage calculation
const priceImpact = 0.15; // 0.15% from SDK
const volatilityBuffer = 0.05; // Based on recent swings
const networkBuffer = (currentBaseFee > 50) ? 0.10 : 0.05; // Gwei threshold
const dynamicSlippageBips = (priceImpact + volatilityBuffer + networkBuffer) * 100; // Convert to basis points
// e.g., 0.3% -> 30 bips. Set in aggregator parameters as slippage: 30.

Tip: For MEV-sensitive trades, consider using a private RPC or a service like Flashbots Protect to submit the transaction and reduce front-running risk.

Detailed Instructions

With a validated quote and dynamic slippage, construct the final transaction. Use the aggregator's router contract ABI to encode the call. The most common function is something like swap or executeSwap. Critical parameters are the exact input amount, the minimum output amount (calculated from quoted output minus slippage), the route path, and a deadline (e.g., block.timestamp + 600 for 10 minutes). For gas optimization, use a recent base fee estimate and add a priority fee (tip) sufficient for timely inclusion—consult a gas estimation API. Sign and broadcast the transaction via your wallet or a direct node connection.

• Sub-step 1: Encode the transaction data using the router ABI and your finalized parameters.
• Sub-step 2: Fetch current gas estimates from a provider like Blocknative or ETH Gas Station.
• Sub-step 3: Set maxFeePerGas and maxPriorityFeePerGas accordingly.
• Sub-step 4: Sign and send the transaction, monitoring its status via transaction hash.

solidityCopy
// Common aggregator router interface excerpt
interface IAggregatorRouter {
    struct SwapDescription {
        address srcToken;
        address dstToken;
        address srcReceiver;
        address dstReceiver;
        uint256 amount;
        uint256 minReturnAmount;
        uint256 flags; // For hints like chipless tokens
    }
    function swap(
        address caller,
        SwapDescription calldata desc,
        bytes calldata data // Encoded route data
    ) external payable returns (uint256 returnAmount);
}

Tip: Always include a reasonable deadline parameter to prevent your transaction from being executed minutes later at a worse price if it gets stuck in the mempool.

Detailed Instructions

After broadcast, monitor the transaction receipt. A status of 1 indicates success. You must then verify the actual output amount received in your wallet or by the destination address. Parse the transaction logs to find the Swap or Transfer event from the aggregator or the final DEX pool. Compare the amount or output field in the log to your calculated minReturnAmount. The difference is your execution slippage. If the received amount is significantly below the quote (beyond your tolerance), investigate potential causes like sandwich attacks, a sudden large trade just before yours, or an incorrect route simulation. Tools like Tenderly or Etherscan's transaction decoder can help analyze the execution path.

• Sub-step 1: Fetch the transaction receipt using eth_getTransactionReceipt.
• Sub-step 2: Decode logs to find the key event emitting the final token transfer amount.
• Sub-step 3: Calculate execution slippage: ((quotedAmount - actualAmount) / quotedAmount) * 100.
• Sub-step 4: If slippage is high, review the block's transactions for adversarial activity.

javascriptCopy
// Example: Parsing a Uniswap V3 Swap event log
// Event Swap(address indexed sender, address indexed recipient, int256 amount0, int256 amount1, ...)
const iface = new ethers.utils.Interface(uniswapABI);
const log = receipt.logs[5]; // The relevant log index
const parsedLog = iface.parseLog(log);
const actualOutput = parsedLog.args.amount1; // This is the output token amount
console.log(`Actual USDC received: ${actualOutput}`);

Tip: For maximum transparency, use aggregators that provide a post-trade receipt or proof, detailing each hop's execution, which can be verified on-chain.