How to Build Uniswap V2 From Scratch (Line by Line, 207 Tests)

TL;DR — Quick Summary

• Rebuilding Uniswap V2 from scratch is the fastest way to actually understand what a fork inherits — the good, the bad, and the subtle design decisions that matter.
• The protocol is smaller than people think: one Factory contract, one Pair contract (the AMM itself), a Router, and a Library. That is the whole thing.
• The core math is the constant product formula x * y = k, with a 0.3% fee wrapped around every swap to keep the invariant drifting upward.
• You will implement: reserves tracking, minting and burning LP tokens, the swap function with its K-invariant check, flash swaps via callback, TWAP price accumulators, and proper safety rails against fee-on-transfer and rebasing tokens.
• Zealynx Academy's Uniswap V2 module walks you through the build across 8 sections with 207 automated tests. You do not finish until every test passes.
• You emerge understanding exactly what a fork is actually copying — which is the point.

Why Build From Scratch Before You Fork

Uniswap V2 Architecture: The Four Contracts That Matter

UniswapV2Factory

UniswapV2Pair (the AMM)

UniswapV2Router

UniswapV2Library

The Core Math: Constant Product With a Fee Twist

How a Swap Works Conceptually

Why This Matters for Your Build

• Forgetting the fee on the k check. Some forks apply fees correctly on the numerator but forget to adjust when re-checking the invariant. The result: the invariant can decrease, and arbitrageurs drain the pool.
• Integer rounding in the wrong direction. Solidity integer division rounds toward zero. In a swap, the output amount must always round DOWN (favoring the protocol) to avoid leaking value. Getting this wrong in one direction costs LPs. Getting it wrong in the other direction enables draining.
• Using balance vs reserve incorrectly. balance is the current ERC-20 balance of the token in the Pair. reserve is the stored state from the last sync. They diverge any time someone sends tokens directly to the Pair without calling a function (which happens a lot — this is how flash swaps and optimistic transfers work).

Mapping to Zealynx Academy's 8 Sections

Section 1: Introduction + Scaffolding

Section 2: The Library Math

Section 3: The ERC-20 Pair Token

Section 4: Reserves and Sync

Section 5: Minting and Burning LP Tokens

Section 6: The Swap Function

1. Validate amounts are positive and below reserves.
2. Optimistically transfer tokens to the recipient.
3. If data.length > 0, trigger a flash swap callback on the recipient.
4. Read balances (not reserves — balances, because someone may have sent tokens in).
5. Compute fee-adjusted balances.
6. Check the K-invariant: balance0Adjusted * balance1Adjusted >= reserve0 * reserve1 * 1000^2.
7. Update reserves via _update().

Section 7: TWAP Price Accumulators

Section 8: Final Build + Test Suite

• K-invariant holds after every swap
• Reentrancy guards are in place
• Flash-swap callback is triggered correctly
• LP token accounting is pro-rata after mint and burn
• Fee-on-transfer tokens do not corrupt reserves
• Sync recovers from direct-transfer token donations
• Permit signatures verify against EIP-712 domain

What 207 Tests Actually Test For

1function test_swap_preserves_k_invariant() public {
2    uint256 kBefore = reserve0 * reserve1;
3    pair.swap(0, 1 ether, bob, "");
4    uint256 kAfter = reserve0 * reserve1;
5    assertGe(kAfter, kBefore); // K must only grow
6}

1function test_swap_blocks_reentrancy() public {
2    // Malicious token that calls back into swap during transfer
3    // Expect revert
4}

1function test_flashswap_triggers_callback() public {
2    pair.swap(1 ether, 0, address(callback), "trigger");
3    // Expect callback.uniswapV2Call was called with correct args
4}

1function test_firstDepositor_cannot_manipulate_ratio() public {
2    // Attempting to deposit 1 wei first and set unfair ratio should fail
3    // Because MINIMUM_LIQUIDITY is locked
4}

1function test_swap_handles_fee_on_transfer_tokens() public {
2    // Tokens that deduct a fee on transfer should not break K
3}

The Common Pitfalls When Building

What You Understand After

• Why does Uniswap V2 use uint112 for reserves instead of uint256? (Packing + uint224 for cumulative price math.)
• What happens if someone transfers tokens directly to a Pair without calling a function? (The extra balance can be swept by calling sync() or used in the next swap's K check.)
• Why is the flash-swap callback triggered before the balance check? (So the borrower can use the tokens, put them back, and close the swap atomically.)
• How does the TWAP oracle prevent short-term manipulation? (By using accumulators over time intervals, short-lived price spikes average out.)
• Why does the first liquidity provider lock MINIMUM_LIQUIDITY? (To prevent a first-depositor donating a tiny amount of tokens to manipulate the price ratio and stealing subsequent deposits.)

Where to Start

Zealynx Academy Is Part of the Ethereum Security QF Round

Conclusion

FAQ

Glossary