Compound is a decentralized protocol which establishes money markets with algorithmically set interest rates based on supply and demand, allowing users to frictionlessly exchange the time value of Ethereum assets*.

Compound V2 is one of the most important protocols on EVM chains. According to Defillama, it is the second most forked project by TVL.

In this post, we are going to analyze the most important components of Compound, primarily money markets (cTokens) and its governance model.

NOTE: You should have a good understanding of the basic Ethereum and Defi concepts to follow along. Primarily, you should be comfortable reading Solidity and the basics of Defi (erc20 tokens, incentives, etc.)

This post is divided in 2 parts:

→ The first part goes through the general protocol architecture.

→ The second part goes through hands-on examples that demonstrate everything that was covered.

NOTE: You can find the github repo here. We will go through the source in the second part, but it is advisable to read the code as we understand each topic.

Protocol Architecture

Money Markets

The first concept to understand is money markets. You can think of a money market as a smart contract that holds 2 assets:

1. The underlying asset (Eth, Dai, USDC, etc.).

2. The token representation of the underlying asset (cToken).

NOTE: There are cases where money markets hold more than 2 assets, but compound V2 doesn’t.

In simple terms, you deposit an asset (think of Eth) into a smart contract and get a representation of it (cEth) in return. This token will increase or decrease in value depending on the rules of the smart contract.

The main conceptual difference between a money market and a traditional lending / borrowing platform is that the former is on-chain (trustless) while the latter requires you trusting an intermediate (platform).

One of the main benefits of this is that you can read the code and know that something will be executed with certainty and you also know the exact amount of liquidity that there is.

cTokens

As previously mentioned, each market is implemented as a smart contract and the token representation in Compound is known as a “cToken”.

The cToken is basically an ERC20 compatible token with extra functionality.

You can mint cTokens by depositing the underlying token to the cToken smart contract.

*You can find the full API of a cToken contract here.

Some important characteristics of a cToken:

• Each cToken will increase its value on a (almost) per block basis due to the interests earned.

• You can use the cToken as collateral to borrow funds. You can also use it in other markets (it is an ERC20 compatible token).

Exchange Rate: The exchange rate between a cToken and the underlying asset e.g. (dai vs cDai or eth vs cEth) begins at 0.020 and increases at a rate equal to the compounding market interest rate.

Where:

getCash(): The amount of underlying balance owned by this cToken contract.

totalBorrows(): The amount of underlying currently loaned out by the market, and the amount upon which interest is accumulated to suppliers of the market.

totalReserves(): Reserves are an accounting entry in each cToken contract that represents a portion of historical interest set aside as cash which can be withdrawn or transferred through the protocol’s governance.

totalSupply(): The number of tokens currently in circulation in this cToken market.

NOTE: All cTokens have 8 decimals, while the underlying token can vary.

Interest Rates

Interest rates are updated on every block as long as the ratio of borrowed assets to supplied assets has changed. The amount of the rates depend on the specific implementation of the smart contract.

There is an external smart contract that calculates the rates, both borrow and supply.

Let’s take the cEther money market as an example.

If we want to find out about the borrow rate per block, we would call the borrowRatePerBlock function from the specific cToken contract. The cToken contract (cEther for our example) will call another external contract that will get the rates.

function borrowRatePerBlock() override external view returns (uint) {
        return interestRateModel.getBorrowRate(getCashPrior(), totalBorrows, totalReserves);
    }

This is the reason why each cToken may have different interest rate implementations. For the cEther contract, the interest rate contract is called “LegacyJumpRateModelV2” you can find it here.

Liquidations

A user who has negative account liquidity is subject to liquidation by other users of the protocol to return his/her account liquidity back to positive (i.e. above the collateral requirement). When a liquidation occurs, a liquidator may repay some or all of an outstanding borrow on behalf of a borrower and in return receive a discounted amount of collateral held by the borrower; this discount is defined as the liquidation incentive.

A user’s account liquidity (you can read more about it here) is the amount in USD that a user is able to borrow.

We are going to go through an example to grasp this better, but before that we need to understand the collateral factor.

The collateral factor is a percentage that ranges between 0-90% that represents the amount that a user can borrow from minting cTokens. The more stable and liquid an asset is, the higher the collateral factor and vice versa.

Ok, so let’s suppose that Alice supplies 1 Eth to Compound. The price of Eth is $1,000 usd and the collateral factor is 90%. This means that Alice will have an account liquidity of $900 usd (90% of $1,000).

Then Alice borrows 900 usd of DAI, her new account liquidity would be 0. If the price of Eth goes down, her account liquidity would be negative and liquidators would be able to trigger this liquidation.

*To see this in code, go to the file located under test/AccounLiquidity.t.sol

One last characteristic to understand is that the system doesn’t guarantee that a liquidation will take place. It provides incentives so users (liquidators) are constantly watching for a liquidation opportunity so they call the liquidation function and get some money in return.

Comptroller

The Comptroller is the risk management layer of the Compound protocol; it determines how much collateral a user is required to maintain, and whether (and by how much) a user can be liquidated. Each time a user interacts with a cToken, the Comptroller is asked to approve or deny the transaction.

You can think of the Comptroller as a provider and verifier contract that gives information to the cTokens and checks that a user can execute a given transaction.

* You can find the Comptroller here.

NOTE: This diagram is not 100% accurate as the architecture is implemented through upgradable proxies but the general concept remains intact.

Governance

One crucial aspect of smart contract systems is its governance model.

This is probably the most important governance smart contracts in EVM chains, it is used in many protocols.

This is a complex topic for a short post, so to simplify it, we can think of what governance is by asking the following questions:

• Are the contracts upgradable ? If they are, Who can upgrade them ?

• Are there any other special privileges in the contracts ? For example, can an admin key blacklist certain users ?

These are the most fundamental points that we should focus on smart contract systems. If there are privileged keys that can blacklist users, upgrade the contracts or pause them, then the system is not very trustless or secure.

Ok, let’s go back to Compound.

Compound V2 is built around a decentralized voting process. To understand this, it is important to know what upgradable proxies are, you can read about them here.

I am going to go through the most important aspects of the governance process, to simplify it as much as possible.

If we remember from the previous part, the Comptroller is the contract that basically does a bunch of safety checks for the cTokens.

The Comptroller is architected as an upgradable proxy, the name of the actual proxy is named the “Unitroller”, you can find the contract’s code here.

The Unitroller delegates all calls to the Comptroller singleton, but it also has some additional methods, primarily changing the implementation contract and changing the admin.

So there are a couple of important security things going on here.

First of all, if someone upgrades the implementation contract (we will do it later on as a poc) to a malicious address, and changes the admin, then all user’s funds will be lost as there is no way to get it back.

The process basically works by proposing a proposal, voting (favour or against) and executing the proposal if succeeded.

Let’s get into the low level process of how making changes to the contract works.

1. Propose

The first thing is to propose a proposal, and this is done on chain by calling the “propose” function from the GovernorBravoDelegate contract. You can find it here.

function propose(address[] memory targets, uint[] memory values, string[] memory signatures, bytes[] memory calldatas, string memory description) public returns (uint)

In order to be able to call the propose function, the proposer (msg.sender) should have at least x amount of COMP tokens or votes. This minimum amount of votes to propose a proposal is called the “proposalThreshold” and it is currently 25,000. This means that if you have less than 25,000 COMP tokens or votes, you are not able to be a proposer.

Once the proposal goes through, there is a voting delay of 13,140 blocks (around 2 days). This means that we need to wait 13,140 blocks to start the voting process .

2. Vote

Once the voting delay period has passed, the process of voting beginns.

*Users that have “votes” are the ones that are able to vote. For example, if you have 100 COMP tokens and you delegate them to yourself, then you have 100 votes. You can also delegate your 100 COMP tokens to someone else, deferring your votes.

The process is very simple, there is a function called “castVote” that voters call with their vote preference. (There are more voting functions but they are all pretty much the same).

function castVote(uint proposalId, uint8 support) external 

You just need to pass the id of the proposal and your vote support (0=against, 1=for, 2=abstain).

Once you vote, all the votes that your account owns will be summed up to the proposal’s state. For example, if you have 10,000 COMP tokens and you are the delegator of your own tokens, and vote in favour of a proposal, then that proposal will increase its “for” votes by 10,000.

The voting period currently lasts for 19,710 blocks (around 3 days).

Once the voting period ends, it is time to queue the proposal.

3. Queue

Once all the votes were gathered and the voting period ends, the proposal either “Succeeded” or got “Defeated”. If the proposal succeeded, then the next step can go through.

The proposal is successful if:

a) There were more votes in favour than against

b) The “for” votes are greater than the quorumVotes.

There is a minimum amount of “for” votes in order for the proposal to go through. Currently the minimum or "quorumVotes” is 400,000.

The next step (if the proposal succeeds) is to queue it to the Timelock contract. You can find the contract here.

Once the transaction has been queued to the Timelock contract there is a 172,800 seconds delay (2 days). Once the delay is over, the transaction can be executed.

4. Execute

After the 2 days Timelock delay has passed, the proposal can be executed.

This is simply done by calling the “execute” transaction from the GovernorBravoDelegate contract.

This function will execute the proposal from the context of the Timelock contract.

A more realistic architecture of how the governance contracts are implemented:

And visual representation of the proposal process:

If a protocol has a bad structured governance model (easy to manipulate), then the governance model becomes the security’s weakest link. As you can see from the previous explanation, the governance of a protocol like Compound has the power to make critical changes that affect (in a positive or negative way) all users.

In Compound’s case, the security of the protocol goes hand by hand with the COMP token valuation. If the total market cap is very low, the possibilities of someone taking control rise significantly.

Hands-On

For this next part, we are going to execute the most common operations in Compound.

You can find the github repo here (you should clone the repo to follow along).

NOTE: The examples are done by forking Ethereum mainnet at block 16401180 and using Foundry.

Governance (upgrading the Comptroller)

This is probably the most interesting example. We are going to go through the entire proposal lifecycle that we covered in the Governance section.

*The file is located at test/UpgradeComptroller.t.sol

In this example, we are going to create a proposal, vote, win it in our favour, and then execute it. The proposal is to change the Comptroller implementation to a malicious singleton.

Here is the code:

// SPDX-License-Identifier: MIT
pragma solidity >= 0.8.0;

import "forge-std/Test.sol";

import "../src/NewComptroller.sol";
import "./utils/TestUtils.sol";

/// @notice Example contract that upgrades the Comptroller.
/// This example also goes through the entire governance journey:
/// 1. Create the proposal
/// 2. Vote
/// 3. Queue it to the Timelock
/// 4. Execute the proposal
contract UpgradeComptrollerTest is Test, TestUtils {
    NewComptroller newComptroller;

    receive() external payable {}

    function setUp() public {
        // Fork mainnet at block 16_401_180.
        cheat.createSelectFork("mainnet", BLOCK_NUMBER);

        ///// We fund this test contract with 400K COMP tokens.
        uint256 TRANSFER_AMOUNT = 400_000 * 1e18;

        cheat.startPrank(0x2775b1c75658Be0F640272CCb8c72ac986009e38);
        comp.transfer(address(this), TRANSFER_AMOUNT);
        cheat.stopPrank();

        assertEq(comp.balanceOf(address(this)), TRANSFER_AMOUNT);
        /////

        ///// Now we delegate all votes to this address.
        comp.delegate(address(this));
        /////

        // We increase the block number by 1 so the votes are actionable.
        vm.roll(block.number + 1);
        assertEq(comp.getPriorVotes(address(this), block.number - 1), TRANSFER_AMOUNT);

        // We create the new singleton Comptroller.
        newComptroller = new NewComptroller();
    }

    /// @notice This test function goes through the complete governance model of Compound.
    /// It ends up upgrading the comptroller singleton.
    function testUpgradeComptroller() public {
        // 1. We CREATE and send the PROPOSAL.
        uint256 proposalId = propose();

        // We increase the block number by the voting delay.
        uint256 votingDelay = gBravo.votingDelay(); // 13140 blocks
        vm.roll(block.number + votingDelay + 1);

        // 2. We VOTE in favor of our proposal.
        gBravo.castVote(proposalId, 1); // 0=against, 1=for, 2=abstain

        // We increase the block number so it gets to the voting end.
        uint256 votingPeriod = gBravo.votingPeriod(); // 19710 blocks
        vm.roll(block.number + votingPeriod);

        // 3. We QUEUE the transaction to the timelock.
        gBravo.queue(proposalId);

        // We increase the timestamp number by the timelock delay.
        uint256 timelockDelay = timelock.delay();

        vm.warp(block.timestamp + timelockDelay);

        // 4. We EXECUTE the PROPOSAL.
        gBravo.execute(proposalId);

        // We accept the implementation.
        newComptroller.acceptImplementation(address(comptroller));

        // We check that the comptroller has been upgraded.
        (bool success, bytes memory data) =
            address(comptroller).staticcall(abi.encodeWithSignature("testImplementation()"));
        require(success);
        string memory result = abi.decode(data, (string));
        assertEq(result, "I am the new Comptroller");
    }

    function propose() internal returns (uint256) {
        address[] memory targets = new addressUnsupported embed;
        targets[0] = address(comptroller);

        uint256[] memory values = new uintUnsupported embed;
        values[0] = 0;

        string[] memory signatures = new stringUnsupported embed;
        signatures[0] = "";

        bytes[] memory calldatas = new bytesUnsupported embed;
        calldatas[0] = abi.encodeWithSignature("_setPendingImplementation(address)", address(newComptroller));

        string memory description = "Upgrades the Comptroller";

        uint256 proposalId = gBravo.propose(targets, values, signatures, calldatas, description);
        require(proposalId > 0, "Proposal failed");
        return proposalId;
    }
}
 

Supply & Redeem

In this example we are going to supply Eth to the CEth market and then redeem it.

*The file is located at test/SupplyAndRedeem.t.sol

The steps to supply to a Compound market and get a cToken in return are the following:

1. Deposit the underlying asset by calling the “mint()” function.

The mint function from the cToken will:

• Transfer the underlying token amount (mintAmount) to the cToken contract or msg.value for cEther.

• Mint the corresponding cTokens (depositAmount / exchangeRate).

We will be mainly interacting with the cEther contract, you can find it here.

Here is the complete test case for:

a) calculating the exchange rate

b) supplying

c) redeeming

// SPDX-License-Identifier: MIT
pragma solidity >= 0.8.0;

import "forge-std/Test.sol";

import "./utils/TestUtils.sol";

/// @notice Example contract that supplies an asset to Compound and redeems it.
contract SupplyAndRedeemTest is Test, TestUtils {
    receive() external payable {}

    function setUp() public {
        // Fork mainnet at block 16401180.
        cheat.createSelectFork("mainnet", BLOCK_NUMBER);
    }

    /// @dev Calculates the exchange rate between eth and cEther.
    function getExchangeRate() internal returns (uint256) {
        // exchangeRate = (totalCash + totalBorrows - totalReserves) / totalSupply.
        uint256 totalCash = cEther.getCash();
        assertEq(totalCash, address(cEther).balance);

        uint256 totalBorrows = cEther.totalBorrowsCurrent();
        assert(totalBorrows > 0);

        uint256 totalReserves = cEther.totalReserves();
        assert(totalReserves > 0);

        uint256 totalSupply = cEther.totalSupply();
        assert(totalSupply > 0);

        uint256 exchangeRate = 1e18 * (totalCash + totalBorrows - totalReserves) / totalSupply;
        return exchangeRate;
    }

    /// @notice Supplies Eth to Compound, checks balances, accrues interests, and redeems.
    function testSupplyAndRedeem() public {
        // We save the initial eth balance to compare it later on.
        uint256 initialEthBalance = address(this).balance;

        // Our initial cEther balance should be 0.
        assertEq(cEther.balanceOf(address(this)), 0);

        // We supply 1 ether.
        cEther.mint{value: 1 ether}();

        // We could get the exchange rate by calling "exchangeRateCurrent()" directly.
        // We calculate it ourselves for learning purposes.
        uint256 exchangeRate = getExchangeRate();

        // We get the balance of cEther after supplying.
        uint256 cEtherBalance = cEther.balanceOf(address(this));

        // We get the amount of cEther that we should have.
        uint256 mintTokens = 1 ether * 1e18 / exchangeRate;
        assertEq(cEtherBalance, mintTokens);

        // We incrase the block number by 1.
        vm.roll(block.number + 1);

        // We redeem all the cEther.
        require(cEther.redeem(cEther.balanceOf(address(this))) == 0, "redeem failed");

        // We should have 0 cEther.
        assertEq(cEther.balanceOf(address(this)), 0);

        // Eth + interests. We should have more eth with 1 block of interests.
        assert(address(this).balance > initialEthBalance);
    }
}
 

Borrow & Repay

In this example, we supply Eth as collateral, enter the markets, borrow Dai and then repay it.

*The file is located at test/BorrowAndRepay.t.sol

// SPDX-License-Identifier: MIT
pragma solidity >= 0.8.0;

import "forge-std/Test.sol";

import "./utils/TestUtils.sol";

/// @notice Example contract that borrows and repays from Compound.
contract BorrowAndRepayTest is Test, TestUtils {
    function setUp() public {
        // Fork mainnet at block 16401180.
        cheat.createSelectFork("mainnet", BLOCK_NUMBER);
    }

    /// @notice Supplies Eth to Compound, checks balances, accrues interest, and redeems.
    function testBorrowAndRepay() public {
        // We shouldn't have any Dai balance at this time.
        assertEq(dai.balanceOf(address(this)), 0);

        ///// We need to supply some eth for collateral.
        cEther.mint{value: 1 ether}();

        // We enter the markets.
        address[] memory cTokens = new addressUnsupported embed;
        cTokens[0] = address(cEther);
        comptroller.enterMarkets(cTokens); // <- we enter here

        // Checks
        address[] memory assetsIn = comptroller.getAssetsIn(address(this));
        assertEq(assetsIn[0], address(cEther));

        /////

        ///// Now we borrow some dai.
        uint256 borrowAmount = 500 * 1e18; // 500 dai
        cDai.borrow(borrowAmount);

        // Checks .. We should have 500 dai
        assertEq(dai.balanceOf(address(this)), borrowAmount);

        /////

        ///// We repay the dai.
        dai.approve(address(cDai), borrowAmount);
        cDai.repayBorrow(borrowAmount);

        assertEq(dai.balanceOf(address(this)), 0);
    }
}

References:

https://compound.finance/documents/Compound.Whitepaper.pdf

https://docs.compound.finance/v2/

Welcome to the in Depth DeFi series!

This series will be composed of several posts, each one will consist of the explanation of an individual protocol. The main purpose of this series is to understand from a first-principles approach how the top DeFi protocols work under the hood.

We will review them from a theoretical and practical level. This means that we will understand the theory behind the protocol, but we are also going to dive deep into the actual implementation (code).

Pre-Requisites:

In order to follow along, it is recommendable to have the following knowledge:

1. General understanding of the EVM

2. Comfortable with Solidity

3. Basic math (algebra)

4. General understanding of the fundamentals of blockchains and smart contract protocols built on top

UniSwap V2

The post is divided into two main parts. The first one “System’s Components Overview” explains the theory and practice behind the most important components that make the system work. The second part “System’s CORE Implementation” goes through the actual architectural implementation.

I believe that to truly understand a system in depth, you should be able to re-write it from scratch. Hopefully by the end of this post, you will be able to do that.

In order to start learning the system in a structured manner, it is important to ask ourselves some questions that are fundamental to the system:

• How does Uniswap’s pricing mechanism works ?

• Who provides liquidity to the system ?

• Why would someone provide liquidity to the system ?

• How does the system represents the liquidity ? etc..

Along the way, all the fundamental questions should be answered by understanding the protocol deeply.

Before starting, let’s quickly go to what Uniswap is:

Uniswap is a decentralized automated market maker protocol that allows anyone to swap token A for token B. The way automated market makers work is different from a traditional order book model. The core principle that differentiates an automated market maker (Uniswap) from a traditional centralized order book, is that the former runs permissionless code on the blockchain allowing anyone to participate.

Before moving on, there are a couple of things I want to say.

1. Uniswap V2 is decentralized: Decentralization is not binary, but from my point of view (and many others) a decentralized smart contract protocol is one in which no central party can access the user’s funds. In other words, no one has a special key that can modify the contracts.

2. There are 3 versions of Uniswap: For this post we will focus on V2 (we will do a V3 post in the future). But if you want to learn how Uniswap was created, I suggest watching this video.

3. A lot of AMM’s are a fork of Uniswap V2: Uniswap V2 is much simpler than V3, therefore, easier to maintain. So once you know how Uniswap V2 works, by default, you will know most of the AMM’s as well !

Let’s start !

System’s Components Overview

To start getting a feeling of how the protocol works, we need to ask ourselves what is really happening when you are doing a simple swap. Of course, the purpose of the entire post is to explain this.

But at a basic level, you are interacting with a smart contract (pool) that “holds” reserves of two different tokens. For example, if you are swapping some WETH for USDC, you are interacting with the WETH/USDC smart contract pair (we will go into detail as to how this works later on). If you are interested, here is the WETH/USDC smart contract pair on Etherscan.

So if you are buying USDC with WETH, you are increasing the supply of WETH in the pool and reducing the supply of USDC, therefore, increasing the relative price of USDC vs WETH.

In the following sections, we will understand how the pool works (math behind it).

One important thing to keep in mind, is that UniswapV1’s pools were always traded against Eth. In other words, every pool was ETH/xToken.

In Uniswap V2, every pool is ERC-20/ERC-20. This later approach provides more flexibility to liquidity providers as they don’t need to rely 100% on ETH. So every time you are swapping ETH for another token, in reality, your ETH gets converted to WETH first.

Protocol Participants

Uniswap works by providing incentives to different participants to work with the system in order for them to profit. The main participants of the system are:

1. Traders: Traders can perform several actions in the system, some of them are:

   • Speculating on the price of an asset.

   • Arbitrage software. For example, if the price of ETH in Uniswap is trading at $3,000 and in Coinbase is trading at $3,800, the arbitrageur would immediately buy ETH in Uniswap and resell-it in Coinbase for a profit.

   • Basic swap functionality (you want to change token x to token y) to use them in a Dapp. 2.

2. Liquidity Providers (LPs): LPs provide liquidity to the token pools. In rewards, they get the transaction fees.

3. Developers: Developers create the systems and applications that exist in the ecosystem. In Uniswap terms, they can be core protocol developers, third-party Dapp developers that integrate with Uniswap, wallet developers etc…

Before diving into the smart contracts, let’s understand the core concepts.

There are 3 basic components that we really need to understand in order to have a deep knowledge of Uniswap (and most of the DeFi protocols), they are the constant product formula, arbitrage and impermanent loss.

Fees

UniswapV2 charges a flat 0.3% fee per trade, we will see how this is calculated in future sections. The fee goes to the liquidity providers, this is to reward people for their liquidity. The protocol can also trigger a change that would give 0.05% to the Uniswap team, that part of the fee would be discounted from the LP’s instead of the traders.

Constant Product Formula in Depth

A lot of the automated market makers work thanks to the constant product formula. It is a very simple yet powerful algorithm.

The constant product formula is the automated market algorithm that powers the Uniswap protocol (and a lot more AMM’s).

This formula simply states that the invariant k must remain unchanged regarding of the outflow / inflow of x and y.

In other words, you can change the value of x and y to whatever you want, as long as k remains the same.

For example:

What are x and y ? x and y are the reserves of the tokens in the pool. For example, if you are swapping DAI for WETH, you are interacting with the DAI/WETH smart contract pool. The total amount of DAI that the contract holds would be x and the total amount of WETH would be y.

Simple enough, this is the algorithm that powers a lot of AMM’s.

In the actual implementation, the formula is a bit different.

Let’s see the real formula that Uniswap V2 uses.

Here you can find the full “swap” function implementation. But we are particularly interested in the following lines of code:

This piece of code is the real implementation of the constant product formula. Everything else you have read or seen, is just the theory. These lines of code are the bare metal implementation of the constant product formula.

There are 4 variables inside the require statement:

• balance0Adjusted: Reserves of x after the trader sends tokensX to the pool minus 0.3% of the amount sent.

• balance1Adjusted: Reserves of y after the tokensY are sent to the trader from the pool.

• _reserve0: Reserves of token x prior to the swap.

• _reserve1: Reserves of token y prior to the swap.

Of course, balance0Adjusted and balance1Adjusted can be treated inversely.

Let’s do an example to understand this better:

• There is a DAI/WETH pool in Uniswap.

• Current reserves are 20000DAI / 10 WETH and a trader wants to exchange 1 WETH for 1500 DAI:

As you can see, the trader sent 1 WETH to the pool in exchange of 1500 DAI. He could have gotten more DAI for his WETH ! but the point here is to illustrate two things:

1. The k never remains constant. It always increases due to the transaction fees, but it can also increase if people use the system inefficiently (like in our example, the trader could have gotten more DAI for his WETH).

2. The only check that the swap function really enforces, is that the new reserves (minus fees) are greater than or equal to previous reserves: newK ≥ oldK.

Here is actual code implementation of the previous example:

As you can see, things are multiplied by 1000. This is because there is no floating point numbers in Solidity, so this is necessary to represent the 0.3% fee. That is why the amount0In or amount1in are multiplied by 3 (to represent the 0.3%).

Getting the maximum amount out

A very important thing to understand, is the maximum amount of tokens that you can get for a given input. NOTE: In Uniswap V2 Periphery you have all the helper functions to implement this math.

Example:

We have a DAI /WETH pool with the following reserves:

• DAI: 100,000

• WETH: 20 We want to swap 1 WETH for the maximum amount of DAI.

The maximum amount of DAI that we would get for 1 WETH (for this pool) is 4748.29.

The math we just did can also be represented in code (this function is from V2 Periphery):

It is very important to always get this math right in order to avoid getting less output tokens.

As a final note on this topic, you maybe wondering, what determines the variable k?

K is determined when the pool is first created, and then it grows every time there is a new trade. If we go to our past example, if a trader executes a swap just after the one we did, the k for his trade is going to be the newK of the prior trade.

Arbitrage

Arbitrage is one of the most important concepts to understand how Uniswap works. Although, this concept is not unique to Uniswap, it applies to almost all of the DeFi projects. In order to understand this concept better, the first thing we need to ask ourselves is, how does Uniswap knows the price of a given token ?

For example, when you are swapping WETH for DAI in Uniswap, how does the protocol know that the price of WETH relative to DAI is x ?

The short answer is that Uniswap has no clue what the real price is. In reality, the price matches the outside world due to incentives.

The only thing that the protocol really enforces in order to make a successful swap, is the “constant product formula”.

Let’s go through an example.

Suppose there is a DAI/WETH pool in Uniswap. The price of WETH in Uniswap is trading at around 3000 DAI. We can get the price by dividing the amount of reserves of DAI by the amount of reserves of ETH (this is not the precise amount that you would get, we calculated that in the previous section).

Now, here comes the opportunity !

The price of WETH is trading at $3,200 at Coinbase. There is a difference of $200 usd between the WETH price of Uniswap and Coinbase. This will create an arbitrage opportunity, and immediately an arbitrageur (bot software) will buy WETH in Uniswap and sell it in Coinbase until the price matches.

This is how the prices in Uniswap are correlated with the outside world, by arbitrageurs that are constantly searching for an arbitrage opportunity. There are different types of arbitrage (we will not go into detail). But for the example shown, it is not an atomic arbitrage. In other words, the risks are higher because there is a probability that when the arbitrageur tries to earn a profit in Coinbase, the prices are already at par (because another arbitrageur did it first). That is why the safest arbitrage is done on-chain, because transactions are atomic, meaning, if something fails, the whole transaction reverts (minus gas fees).

So in conclusion, Uniswap does not know about the outside world prices, the prices are almost identical to the outside world thanks to the arbitrageurs.

Impermanent Loss

Impermanent loss for liquidity providers is the change in dollar terms of their total stake in a given pool at a given time vs just holding the assets.** **Let’s create an example to understand this better. Imagine that Alice has some tokens in her wallet, so she wants to become a liquidity provider to earn some yield. For our example, she is going to create a new DAI/WETH pool in Uniswap. The current market price of WETH is $3,000, so to avoid arbitrage, she will need to initiate the pool by putting 3000 DAI for every WETH. She will initiate the pool by putting 10 WETH and 30,000 DAI. With a total usd value of $60,000 (we need to keep this number in mind).

*To make it simple, we will not take into consideration the transaction fees.

Great, so now Alice became a LP of this DAI/WETH Uniswap pool. Now, let’s imagine that the price of WETH goes up to $4,687. As you should know by now, this will create a huge arbitrage opportunity, so immediately an arbitrageur will buy ETH in Alice’s pool until the price is at par with the outside market.

So after some arbitrage, Alice’s pool will look something like this (again, we are not considering the transaction fees):

As we can see, after some arbitrage now the pool has 8 WETH instead of 10 and 37,500 DAI instead of 30,000 (what Alice initially supplied). The total amount of the pool is now $75,000 ((8ETH * $4,687.5) + 37,500)).

Here comes the problem, if Alice would have just held the assets, she would have more money. Remember that initially she supplied the pool with 10 WETH and 30,000 DAI. So at the end, she had an impermanent loss of $1,875:

For this example we did not contemplate the profit from transaction fees (0.3%), but the concept remains unchanged.

The reason why it is called “impermanent” is because the loss only applies if the LPs sell at the present time, if the assets fluctuate, then that loss can be mitigated.

Hopefully the concept is clear by now! If still in doubts, I highly recommend watching this video.

Liquidity / LP Tokens

Big amounts of liquidity is what makes Uniswap an attractive system to use. Without enough liquidity, the system becomes inefficient particularly for big trades relative to the total liquidity of the pool.

Side Note*: For big trades (relative to the pool), it is better to use an aggregator to decrease slippage as much as possible.*

Ok! So the first thing we need to understand is, how are LP tokens minted and burned?

When a liquidity provider provides liquidity to a pool, it receives the pool’s LP tokens proportionally to the amount of liquidity he provided.

Let’s unpack this.

A Uniswap pool is just a smart contract that “holds” certain amount of reserves (token x and y), these reserves are provided by the liquidity providers. But, this pool also has an in-house token called “LP token”. This token is unique to each pool, and the main purpose is to keep track of the liquidity each liquidity provider has injected. You can think of this token as a certificate of your liquidity. This token also accrues the 0.3% fee that Uniswap charges.

The smart contract pool imports “UniswapV2ERC20.sol” (you can find it here), which is basically a contract that has basic ERC20 functionality (minting, burning, transfer, etc..).

The LP tokens are “stored” inside of this UniswapV2ERC20.sol. Every time a liquidity provider provides liquidity, some amount of tokens are minted to his address. Inversely, every time the liquidity provider takes liquidity out, the LP tokens are burned.

So, how does this work ?

If we think about it from a high-level, a liquidity provider can a) provide liquidity and b) take out the liquidity. Uniswap implements this mechanism in two functions: mint() and burn().

Let’s first go with the mint function, you can find the full function implementation here. In order to calculate the LP tokens that a liquidity provider receives, we first need to know if there is liquidity, or if it is the first time someone is providing liquidity.

Here is the piece of code (inside of the mint function) that we are interested in:

The MINIMUM_LIQUIDITY is a constant variable equal to 1000:

To understand this better, we are going to go through an example.

NOTE: In Ethereum, the currency for computation is WEI (ETH * 10 **18), this also applies to most of the ERC-20 tokens. For simplicity, we will write the numbers without the 18 zeroes, but every time there is a hardcoded number like MAXIMUM_LIQUIDITY = 1000, we will just accommodate that number instead.

Let’s suppose that Alice (a liquidity provider) just created a new DAI/WETH pool.

• She will supply 10,000 DAI and 2 WETH:

Before Alice, the total supply of the pool was 0, so the first thing that is going to happen is mint 1000 tokens to the address 0 (this is done to maintain a minimum liquidity):

Note: Every time there is a mint, the totalSupply variable gets updated:

We then get the amount of LP tokens that are going to be minted to the liquidity provider (Alice), for our example, the result was 141.42.. Again, this is the formula to determine that:

Great, so now our pool consists of the following:

Total supply means the total amount of LP tokens there are in circulation (do not confuse it with the x and y reserves).

Now, let’s imagine that Alice wants to withdraw every DAI and WETH she putted into the pool. For the sake of simplicity, let’s suppose that the reserves remain the same.

In order for Alice to remove her liquidity, she needs to call the burn function, but prior to that, she needs to transfer all her LP tokens to the pool’s address. Let’s understand how this works, here is the complete burn function implementation.

If we see line 187, the variable liquidity is the amount of LP tokens that the contract’s address hold. Hence, that is why I mentioned that Alice needs to transfer the LP tokens prior to the function call. Then, in line 191 and 192 are the amounts of token x and y to be transfered to Alice.

Following our example, let’s unpack this:

As you can see, amount0 = 10000 and amount1 = 2, that is the initial amount that Alice supplied !

After the amounts are calculated, they are transferred and then burned.

This is the magic behind LP tokens !

As a final note on this topic, if we remember, the protocol charges a 0.3% trading fee. This fee goes to the liquidity providers. The way the fee is technically accrued, is by increasing the reserves of x and y in every trade. This will positively impact the amount of LP tokens each liquidity provider holds (proportionally to their holdings).

If we go back to the burn function, these 2 lines of code are what calculate the amount of token x and y to send to the liquidity provider when he wants to exchange his LP tokens for the x and y tokens.

Every time a trader executes a swap, it needs to send a buffer of 0.3% relative to the size of the trade, that 0.3% increments the reserves of the pool. Therefore, increasing the value of balance0 and balance1 in the burn function.

System’s CORE Implementation

Now that we have a solid understanding of the individual components, let’s go to the actual implementation. This part will be much faster, as the core topics were already covered.

Protocol Architecture

Uniswap V2 is a binary smart contract system, it is composed of the V2-Core and V2-Periphery.

• V2-Core are the low-level base contracts. These smart contracts are responsible for the system’s functionality.

• V2-Periphery are helper contracts that allow front-end applications and developers integrate with the core contracts, by applying safety checks and abstracting away certain things.

In simpler terms, V2-Core is the part of the protocol that implements the core features (swapping, minting, burning etc..). In contrastV2-Periphery is one layer up. It is a set of contracts and libraries that make the integration easier for the developers.

The Uniswap team also architected this modular codebase approach to reduce security critical vulnerabilities by having the bare minimum in V2-Core. In other words, they only implemented what is necessary in V2-Core so there is less code to audit (therefore more secure). All the helper functions were thrown to V2-Periphery.

We will only focus on V2-Core. The simple reason, is that if you know how V2-Core works, by default you also know how V2-Periphery works (but not the other way around).

Again, you can find the V2-Core repo here.

There are 3 main contracts:

1. UniswapV2ERC20.sol: This contract is responsible for handling the LP tokens. It is a basic ERC20 contract, so we will not go over this.

2. UniswapV2Factory.sol: This is the factory that is responsible for deploying new pools (pairs) and also to keep track of them.

3. UniswapV2Pair.sol: This is where the action happens (the pool implementation).

Uniswap V2 Factory

Again, the factory contract is mainly responsible for creating new contract pairs (UniswapV2Pair.sol), here is the V2 factory contract on Etherscan.

In order to concentrate liquidity, there can only be one smart contract per pair. In other words, if there is a WETH/UNI pair contract already, the factory won’t allow to create the same pair. Of course, you can bypass that (by deploying the pair contract directly), but the core principle here is to concentrate liquidity as much as possible to avoid price slippage and have more liquidity.

Here is the function that creates pairs in UniswapV2Factory:

One thing that probably was still in question is, what determines the order of x and y ? The pairs are grouped by hexadecimal order as you can see in line 25:

In line 27 it checks that the pair is unique:

In line 30-32 it creates the pair (UniswapV2Pair.sol) using create2:

Then it initializes the contract with the address of each token and adds them to an array and mapping.

Another important point is that the factory can turn on a fee to charge a percentage per swap(you can check that yourself, it is pretty trivial).

That’s it for the factory. It is a very simple and straight-forward factory implementation, nothing complicated.

Uniswap V2 Pair

UniswapV2Pair.sol is the foundation of UniswapV2, here is the contract.

This contract is responsible for handling unique pools (each pool = one contract).

The basic functionality of this contract is to swap, mint and burn. We already went in detail as to how this components work, so we will just give them one quick brush.

Swap(): The swap function is the star of Uniswap. It is the function that gets called every time you want to trade one token for another. You can see the full function implementation here. The basic task of this function is to enforce that newK is greater than or equal to k:

Mint(): The mint function is responsible for minting LP tokens every time a liquidity provider provides liquidity, you can find it here.

Burn(): The burn function is responsible of burning LP tokens every time a liquidity provider wants to take his assets out of the pool, you can find it here.

Note on Flash Loans

Flash loans are a very important topic that we did not cover in this post. The reason why is because we are going to cover it in depth in the next post about AAVE.

Hopefully you enjoyed it !

Any comments are kindly welcomed.

References:

https://drive.google.com/viewerng/viewer?url=https://uniswap.org/whitepaper.pdf

https://drive.google.com/viewerng/viewer?url=https://uniswap.org/whitepaper.pdf

https://docs.uniswap.org/protocol/V2/concepts/protocol-overview/how-uniswap-works

https://docs.uniswap.org/protocol/V2/concepts/protocol-overview/how-uniswap-works

https://docs.uniswap.org/protocol/V2/concepts/protocol-overview/how-uniswap-works