V4-vs-V3 (#749)

Co-authored-by: saucepoint <[email protected]>

docs/contracts/v4/concepts/01-v4-vs-v3.mdx

@@ -1,30 +1,63 @@
 ---
-title: v4-versus-v3
+title: V4 vs V3
 ---
 
-While Uniswap v4's underlying concetrated liquidity is the same as Uniswap v3, there are some key differences in the architecture
-and accounting.
+While Uniswap v4's underlying concentrated liquidity is the same as Uniswap v3,
+there are some key differences in the architecture and accounting.
 
 # Singleton Design
 
 ### Pool Creation
 
-(TODO: talk about singleton vs factory, state vs contract/V3Pool)
+**V4**: The singleton contract facilitates the creation of a pool and 
+also stores its state. This pattern reduces costs when creating a pool
+and doing multi-hop swaps. Because pools are _contract state_ and not entirely new _contracts_ themselves, pool creation is significantly cheaper.
+
+**V3**: A factory contract is responsible for pool creation. The pool is
+a separate contract instance that manages its own state. Pool initialization
+is costly because contract creation is gas-intensive
 
 ### Flash Accounting
 
-(TODO: talk about flash accounting, multi-hop swaps)
+**V4**: The singleton uses _flash accounting_, meaning a caller that unlocks the PoolManager
+is allowed to cause balance-changing operations (multiple swaps, multiple liquidity modifications, etc)
+and only needs to perform token transfers at the very end of the sequence.
+
+**V3**: Because flash accounting is missing from V3, it is the responsibility
+of the integrating contract to perform token transfers, after each individual call, to each individual pool contract
 
-# Liquidity Fee Accounting
+# Liquidity Fee Accounting 
 
-(TODO: talk about how fees must be collected on liquidity operation)
+**V4**: Accrued fees act like a credit when modifying liquidity.
+Increasing liquidity will convert the fee revenue to liquidity
+inside the position while decreasing liquidity will automatically
+require the withdrawal of unclaimed fee revenue.
 
-(TODO: talk about fees are automatically credited in increase liquidity)
+An additional parameter _salt_ can be provided when creating liquidity. The
+_salt_ is used to distinguish positions of the same range on the same pool.
+This separation may be preferred to simplify fee accounting. If two users share the same
+range and state in `PoolManager`, integrating contracts must be careful in managing
+fees
 
-(TODO: talk about salts)
+**V3**: Liquidity positions of the same range and pool will share the same state. While believed to 
+be more gas efficient at the time, integrating contracts will need to handle fee management since
+the state is shared on the core pool contract
 
 # Native ETH
 
-(TODO: talk about native ETH vs WETH)
+**V4**: Pool pairs support native tokens, in doing so ETH swappers and
+liquidity providers benefit from gas cost reductions from cheaper
+transfers and removal of additional wrapping costs.
+
+**V3**: ETH needs to be wrapped first before being paired with other tokens.
+This results in higher gas costs because of wrapping and transferring
+a wrapped native token.
+
+# Subscribers
+
+Only V4: Owners can now set a subscriber for their positions.
+A subscriber contract will get notified every time the position's liquidity
+or owner changes. Subscribers enable staking / liquidity-mining, but users do not need
+to transfer their ERC-721 token.
 
-# Subscribers
+**V3**: Staking in v3 requires users to transfer their ERC-721 token to a contract, putting the underlying assets at risk for malicious behavior.