liquidity & slippage docs

src/.vitepress/config.mts

@@ -86,6 +86,13 @@ export default defineConfig({
           {text: 'Fees', link: '/fees',},
         ]
       },
+      {
+        text: 'Docs',
+        items: [
+          {text: 'Liquidity', link: '/liquidity',},
+          {text: 'Slippage', link: '/slippage',},
+        ]
+      },
       {
         text: 'Legal',
         items: [

src/liquidity.md

@@ -0,0 +1,11 @@
+# Liquidity
+
+The term [liquidity](https://en.wikipedia.org/wiki/Market_liquidity) generally refers to the volume that counterparties are willing to immediately trade with you, without moving the price.
+
+In the DeFi world, liquidity is usually reported as the USD-value of assets held by the pool, rather than the value of tradeable assets near the current price.
+
+When you choose a pair to trade, Dexorder automatically selects the pool with the most liquidity.
+
+Dexorder calculates liquidity as the USD-marked value of the pool's balance of the stablecoin or "big" token called the *quote token*. So for WETH/USDC we report liquidity as the pool's balance of USDC.  For XXX/WETH, we report the USD value of the pool's WETH balance.  For XXX/YYY, we report the liquidity in terms of the YYY balance, but we do not give any USD-marked value if YYY is not on our list of official quote tokens.
+
+Liquidity in Uniswap v3 pools is complicated due to range-staking: the ability of liquidity providers to limit the prices where their liquidity is available. This means Uniswap v3 liquidity is not a single number but a distribution. The pool contract's method `liquidity()` reports only liquidity at the current "tick," which is frequently not even the peak liquidity, the tick with the most liquidity in it. The amount of liquidity in a Uniswap v3 pool also depends on whether you are buying or selling, and how close the current price is to the tick boundry. For all these complex reasons, liquidity is generally reported as "pool value," but traders should be aware that only a fraction of the reported liquidity will be available near the current price.

src/slippage.md

@@ -0,0 +1,13 @@
+# Slippage
+
+The term [slippage](https://en.wikipedia.org/wiki/Slippage_(finance)) refers to the difference between the price you expected, or the original market price, and the actual price you got when the trade was completed. The more volume you want to trade, the higher your slippage becomes.
+
+In DeFi, slippage can be mechanically caused by [MEV](https://ethereum.org/en/developers/docs/mev) actors within a single block, so proper slippage controls use either oracle prices or something like a time-weighted average price (TWAP) as the "true" price.
+
+Dexorder uses the 10-second TWAP as reported by the Uniswap v3 price oracles. If a price oracle has not been configured for a particular pool, Dexorder uses the pool's current reported price instead. The order's slippage control is then applied to this "true" price and the price limit is passed to the pool during the swap.
+
+Slippage is set to 0.30% by default, and may not be lower than 0.01%.
+
+If an attempted execution hits the slippage control, then it fills partially and enters a brief cooldown period before attempting the trade again.
+
+If your order is large enough to move the market and trigger slippage controls, consider using Dexorder's DCA or Dates tool to split up your order.