Introduction
The Compound protocol is based on the Compound Whitepaper (2019); the codebase is open-source, and maintained by the community.
The app.compound.finance interface is open-source, and maintained by the community.
Please join the #development room in the Compound community Discord server; Compound Labs and members of the community look forward to helping you build an application on top of Compound. Your questions help us improve, so please don't hesitate to ask if you can't find what you are looking for here.
Guides
Setting up an Ethereum Development Environment
Supplying Assets to the Compound Protocol
Borrowing Assets from the Compound Protocol
Create a Compound API with Infura
Building a Governance Interface
Delegation & Voting
Contributing to the Protocol
Networks
The Compound Protocol is currently deployed on the following networks:
| Contract | ABI | Address |
|---|---|---|
| cAAVE cToken | JSON | |
| cBAT cToken | JSON | |
| cCOMP cToken | JSON | |
| cDAI cToken | JSON | |
| cETH cEther | JSON | |
| cFEI cToken | JSON | |
| cLINK cToken | JSON | |
| cMKR cToken | JSON | |
| cREP cToken | JSON | |
| cSAI cToken | JSON | |
| cSUSHI cToken | JSON | |
| cTUSD cToken | JSON | |
| cUNI cToken | JSON | |
| cUSDC cToken | JSON | |
| cUSDP cToken | JSON | |
| cUSDT cToken | JSON | |
| cWBTC cToken | JSON | |
| cWBTC2 cToken | JSON | |
| cYFI cToken | JSON | |
| cZRX cToken | JSON | |
| COMP | JSON | |
| Comptroller | JSON | |
| Governance | JSON | |
| Timelock | JSON |
You can also see a full list of all deployed contract addresses here.
Protocol Math
The Compound protocol contracts use a system of exponential math, Exponential.sol, in order to represent fractional quantities with sufficient precision.
Most numbers are represented as a mantissa, an unsigned integer scaled by 1 * 10 ^ 18, in order to perform basic math at a high level of precision.
cToken and Underlying Decimals
Prices and exchange rates are scaled by the decimals unique to each asset; cTokens are ERC-20 tokens with 8 decimals, while their underlying tokens vary, and have a public member named decimals.
| cToken | cToken Decimals | Underlying | Underlying Decimals |
|---|---|---|---|
| cETH | 8 | ETH | 18 |
| cAAVE | 8 | AAVE | 18 |
| cBAT | 8 | BAT | 18 |
| cCOMP | 8 | COMP | 18 |
| cDAI | 8 | DAI | 18 |
| cFEI | 8 | FEI | 18 |
| cLINK | 8 | LINK | 18 |
| cMKR | 8 | MKR | 18 |
| cSUSHI | 8 | SUSHI | 18 |
| cTUSD | 8 | TUSD | 18 |
| cUNI | 8 | UNI | 18 |
| cUSDC | 8 | USDC | 6 |
| cUSDP | 8 | USDP | 18 |
| cUSDT | 8 | USDT | 6 |
| cWBTC | 8 | WBTC | 8 |
| cYFI | 8 | YFI | 18 |
| cZRX | 8 | ZRX | 18 |
Interpreting Exchange Rates
The cToken Exchange Rate is scaled by the difference in decimals between the cToken and the underlying asset.
oneCTokenInUnderlying = exchangeRateCurrent / (1 * 10 ^ (18 + underlyingDecimals - cTokenDecimals))Here is an example of finding the value of 1 cBAT in BAT with Web3.js JavaScript.
const cTokenDecimals = 8; // all cTokens have 8 decimal places
const underlying = new web3.eth.Contract(erc20Abi, batAddress);
const cToken = new web3.eth.Contract(cTokenAbi, cBatAddress);
const underlyingDecimals = await underlying.methods.decimals().call();
const exchangeRateCurrent = await cToken.methods.exchangeRateCurrent().call();
const mantissa = 18 + parseInt(underlyingDecimals) - cTokenDecimals;
const oneCTokenInUnderlying = exchangeRateCurrent / Math.pow(10, mantissa);
console.log('1 cBAT can be redeemed for', oneCTokenInUnderlying, 'BAT');There is no underlying contract for ETH, so to do this with cETH, set underlyingDecimals to 18.
To find the number of underlying tokens that can be redeemed for cTokens, multiply the number of cTokens by the above value oneCTokenInUnderlying.
underlyingTokens = cTokenAmount * oneCTokenInUnderlyingCalculating Accrued Interest
Interest rates for each market update on any block in which the ratio of borrowed assets to supplied assets in the market has changed. The amount interest rates are changed depends on the interest rate model smart contract implemented for the market, and the amount of change in the ratio of borrowed assets to supplied assets in the market.
See the interest rate data visualization notebook on Observable to visualize which interest rate model is currently applied to each market.
Historical interest rates can be retrieved from the MarketHistoryService API.
Interest accrues to all suppliers and borrowers in a market when any Ethereum address interacts with the market’s cToken contract, calling one of these functions: mint, redeem, borrow, or repay. Successful execution of one of these functions triggers the accrueInterest method, which causes interest to be added to the underlying balance of every supplier and borrower in the market. Interest accrues for the current block, as well as each prior block in which the accrueInterest method was not triggered (no user interacted with the cToken contract). Interest compounds only during blocks in which the cToken contract has one of the aforementioned methods invoked.
Here is an example of supply interest accrual:
Alice supplies 1 ETH to the Compound protocol. At the time of supply, the supplyRatePerBlock is 37893605 Wei, or 0.000000000037893605 ETH per block. No one interacts with the cEther contract for 3 Ethereum blocks. On the subsequent 4th block, Bob borrows some ETH. Alice’s underlying balance is now 1.000000000151574420 ETH (which is 37893605 Wei times 4 blocks, plus the original 1 ETH). Alice’s underlying ETH balance in subsequent blocks will have interest accrued based on the new value of 1.000000000151574420 ETH instead of the initial 1 ETH. Note that the supplyRatePerBlock value may change at any time.
Calculating the APY Using Rate Per Block
The Annual Percentage Yield (APY) for supplying or borrowing in each market can be calculated using the value of supplyRatePerBlock (for supply APY) or borrowRatePerBlock (for borrow APY) in this formula:
Rate = cToken.supplyRatePerBlock(); // Integer
Rate = 37893566
ETH Mantissa = 1 * 10 ^ 18 (ETH has 18 decimal places)
Blocks Per Day = 7200 (12 seconds per block)
Days Per Year = 365
APY = ((((Rate / ETH Mantissa * Blocks Per Day + 1) ^ Days Per Year)) - 1) * 100Here is an example of calculating the supply and borrow APY with Web3.js JavaScript:
const ethMantissa = 1e18;
const blocksPerDay = 7200; // 12 seconds per block
const daysPerYear = 365;
const cToken = new web3.eth.Contract(cEthAbi, cEthAddress);
const supplyRatePerBlock = await cToken.methods.supplyRatePerBlock().call();
const borrowRatePerBlock = await cToken.methods.borrowRatePerBlock().call();
const supplyApy = (((Math.pow((supplyRatePerBlock / ethMantissa * blocksPerDay) + 1, daysPerYear))) - 1) * 100;
const borrowApy = (((Math.pow((borrowRatePerBlock / ethMantissa * blocksPerDay) + 1, daysPerYear))) - 1) * 100;
console.log(`Supply APY for ETH ${supplyApy} %`);
console.log(`Borrow APY for ETH ${borrowApy} %`);Gas Costs
The gas usage of the protocol functions may fluctuate by market and user. External calls, such as to underlying ERC-20 tokens, may use an arbitrary amount of gas. Any calculations that involve checking account liquidity, have gas costs that increase with the number of entered markets. Thus, while it can be difficult to provide any guarantees about costs, we provide the table below for guidance:
| Function | Typical Gas Cost |
|---|---|
| Mint | < 150K, cDAI < 300k |
| Redeem, Transfer | < 250K if borrowing, otherwise < 90K |
| Borrow | < 300K |
| Repay Borrow | < 90K |
| Liquidate Borrow | < 400K |