RouterV2 Contract Reference

The RouterV2 contract is the primary integration surface for swapping assets, adding or removing liquidity, and interacting with Lithos pairs. This reference documents every externally callable function, covering expected inputs, return values, and operational notes. Addresses for production deployments are listed in developer-documentation/deployed-contracts.md.

Key Concepts

• Factory – factory stores the address of the deployed PairFactory responsible for creating or resolving trading pairs.

• Wrapped ETH – wETH is the canonical wrapped gas token used for all ETH-denominated liquidity and swap flows.

• Route – The route struct ({ from, to, stable }) defines one hop in a swap path. Stable routes trade against stable pools; volatile routes trade against volatile pools.

• Deadline Guard – Most state-changing functions apply the ensure(deadline) modifier, reverting if the provided deadline is in the past.

Utility Queries

sortTokens(address tokenA, address tokenB) → (address token0, address token1)

Orders a token pair by address to achieve deterministic pair IDs. Reverts on identical or zero addresses.

pairFor(address tokenA, address tokenB, bool stable) → address pair

Predicts the pair address generated by the factory for the provided tokens and stability flag. Uses the factory's pairCodeHash for deterministic calculation.

getReserves(address tokenA, address tokenB, bool stable) → (uint256 reserveA, uint256 reserveB)

Fetches reserves for a pair, returning them in the same order as the input tokens.

getAmountOut(uint256 amountIn, address tokenIn, address tokenOut) → (uint256 amount, bool stable)

Simulates a single-hop swap between two tokens. Returns the expected output and whether the best rate comes from the stable or volatile pool variant.

getAmountsOut(uint256 amountIn, route[] routes) → uint256[] amounts

Simulates a multi-hop swap following the supplied routes. Returns the amount at each hop (index 0 is the input amount).

isPair(address pair) → bool

Pass-through helper that checks whether an address corresponds to a valid pair registered in the factory.

Liquidity Quoting Helpers

quoteAddLiquidity(address tokenA, address tokenB, bool stable, uint256 amountADesired, uint256 amountBDesired) → (uint256 amountA, uint256 amountB, uint256 liquidity)

Estimates the optimal token contribution and liquidity tokens minted if the pool already exists. For new pools the quote mirrors the desired amounts and subtracts the minimum liquidity burned by the pair.

quoteRemoveLiquidity(address tokenA, address tokenB, bool stable, uint256 liquidity) → (uint256 amountA, uint256 amountB)

Quotes the amounts retrieved when burning the provided liquidity tokens. Returns zeros if the pair does not exist.

Adding Liquidity

addLiquidity(address tokenA, address tokenB, bool stable, uint256 amountADesired, uint256 amountBDesired, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) → (uint256 amountA, uint256 amountB, uint256 liquidity)

Transfers the caller's tokens into the pair after running _addLiquidity to balance contributions. Mints liquidity tokens to to. Reverts if final amounts fall below the specified minimums.

addLiquidityETH(address token, bool stable, uint256 amountTokenDesired, uint256 amountTokenMin, uint256 amountETHMin, address to, uint256 deadline) → (uint256 amountToken, uint256 amountETH, uint256 liquidity)

Adds liquidity to a token/WETH pair. Wraps the supplied ETH, returns any unspent ETH to the caller, and mints liquidity tokens to to.

Removing Liquidity

removeLiquidity(address tokenA, address tokenB, bool stable, uint256 liquidity, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline) → (uint256 amountA, uint256 amountB)

Burns the caller's liquidity tokens and transfers underlying tokens to to, enforcing minimum output thresholds.

removeLiquidityETH(address token, bool stable, uint256 liquidity, uint256 amountTokenMin, uint256 amountETHMin, address to, uint256 deadline) → (uint256 amountToken, uint256 amountETH)

Variant of removeLiquidity for token/ETH pools. Withdraws WETH to native ETH before transferring to to.

removeLiquidityETHSupportingFeeOnTransferTokens(address token, bool stable, uint256 liquidity, uint256 amountTokenMin, uint256 amountETHMin, address to, uint256 deadline) → (uint256 amountToken, uint256 amountETH)

Supports fee-on-transfer tokens by measuring the router's balance delta after the burn. Remaining logic mirrors removeLiquidityETH.

Removing Liquidity with Permits

These methods accept an EIP-2612 permit to spend the caller's liquidity tokens before burning them.

removeLiquidityWithPermit(address tokenA, address tokenB, bool stable, uint256 liquidity, uint256 amountAMin, uint256 amountBMin, address to, uint256 deadline, bool approveMax, uint8 v, bytes32 r, bytes32 s) → (uint256 amountA, uint256 amountB)

Applies the permit on the LP token, optionally approving for type(uint256).max when approveMax is true, then removes liquidity.

removeLiquidityETHWithPermit(address token, bool stable, uint256 liquidity, uint256 amountTokenMin, uint256 amountETHMin, address to, uint256 deadline, bool approveMax, uint8 v, bytes32 r, bytes32 s) → (uint256 amountToken, uint256 amountETH)

ETH-enabled counterpart of removeLiquidityWithPermit.

removeLiquidityETHWithPermitSupportingFeeOnTransferTokens(address token, bool stable, uint256 liquidity, uint256 amountTokenMin, uint256 amountETHMin, address to, uint256 deadline, bool approveMax, uint8 v, bytes32 r, bytes32 s) → (uint256 amountToken, uint256 amountETH)

Combines permit support with the fee-on-transfer flow.

Swap Execution

swapExactTokensForTokensSimple(uint256 amountIn, uint256 amountOutMin, address tokenFrom, address tokenTo, bool stable, address to, uint256 deadline) → uint256[] amounts

Single-hop swap helper bridging amountIn tokens into tokenTo. Requires sufficient allowance and honors the amountOutMin safeguard.

swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, route[] routes, address to, uint256 deadline) → uint256[] amounts

General multi-hop swap. Transfers amountIn from the caller to the first pair and routes through the supplied path to to.

swapExactETHForTokens(uint256 amountOutMin, route[] routes, address to, uint256 deadline) → uint256[] amounts

Accepts native ETH, wraps it, and executes a multi-hop swap where the first hop must originate in WETH. Any shortfall relative to amountOutMin reverts.

swapExactTokensForETH(uint256 amountIn, uint256 amountOutMin, route[] routes, address to, uint256 deadline) → uint256[] amounts

Completes a multi-hop swap ending in WETH. After swapping, unwraps to native ETH and sends the output to to.

UNSAFE_swapExactTokensForTokens(uint256[] amounts, route[] routes, address to, uint256 deadline) → uint256[] amounts

Performs a swap using precomputed amounts. Skips output validation and should only be used when amounts are trusted (e.g., off-chain quoting).

swapExactTokensForTokensSupportingFeeOnTransferTokens(uint256 amountIn, uint256 amountOutMin, route[] routes, address to, uint256 deadline)

Processes swaps for fee-on-transfer tokens by measuring actual balance changes at the destination token. Requires a downstream balance increase of at least amountOutMin.

swapExactETHForTokensSupportingFeeOnTransferTokens(uint256 amountOutMin, route[] routes, address to, uint256 deadline)

Fee-on-transfer version of swapExactETHForTokens. Wraps ETH, executes the path, and validates the net token increase at to.

swapExactTokensForETHSupportingFeeOnTransferTokens(uint256 amountIn, uint256 amountOutMin, route[] routes, address to, uint256 deadline)

Fee-on-transfer variant of swapExactTokensForETH. The router unwraps any received WETH and sends native ETH to to.

ETH Handling

receive() external payable

Accepts ETH only from the configured WETH contract, ensuring native transfers originate from unwrap operations.

Integration Notes

• Ensure ERC-20 approvals are in place before calling any method that pulls tokens via _safeTransferFrom.

• When supplying routes, confirm that each hop's stable flag matches the intended pool type; incorrect flags will default to volatile pools if only those exist.

• The router emits a Swap event on each hop, exposing the input token, amount, destination, and stability flag for downstream analytics.