Introduction

Each asset supported by the Compound Protocol is integrated through a cToken contract, which is an EIP-20 compliant representation of balances supplied to the protocol. By minting cTokens, users (1) earn interest through the cToken's exchange rate, which increases in value relative to the underlying asset, and (2) gain the ability to use cTokens as collateral.

cTokens are the primary means of interacting with the Compound Protocol; when a user mints, redeems, borrows, repays a borrow, liquidates a borrow, or transfers cTokens, she will do so using the cToken contract.

There are currently two types of cTokens: CErc20 and CEther. Though both types expose the EIP-20 interface, CErc20 wraps an underlying ERC-20 asset, while CEther simply wraps Ether itself. As such, the core functions which involve transferring an asset into the protocol have slightly different interfaces depending on the type, each of which is shown below.

Mint

The mint function transfers an asset into the protocol, which begins accumulating interest based on the current Supply Rate for the asset. The user receives a quantity of cTokens equal to the underlying tokens supplied, divided by the current Exchange Rate.

CErc20

function mint(uint mintAmount) returns (uint)

Before supplying an asset, users must first approve the cToken to access their token balance.

CEther

function mint() payable

Solidity

Erc20 underlying = Erc20(0xToken...);     // get a handle for the underlying asset contract
CErc20 cToken = CErc20(0x3FDA...);        // get a handle for the corresponding cToken contract
underlying.approve(address(cToken), 100); // approve the transfer
assert(cToken.mint(100) == 0);            // mint the cTokens and assert there is no error

Web3 1.0

const cToken = CEther.at(0x3FDB...);
await cToken.methods.mint().send({from: myAccount, value: 50});

Redeem

The redeem function converts a specified quantity of cTokens into the underlying asset, and returns them to the user. The amount of underlying tokens received is equal to the quantity of cTokens redeemed, multiplied by the current Exchange Rate. The amount redeemed must be less than the user's Account Liquidity and the market's available liquidity.

CErc20 / CEther

function redeem(uint redeemTokens) returns (uint)

Solidity

CEther cToken = CEther(0x3FDB...);
require(cToken.redeem(7) == 0, "something went wrong");

Web3 1.0

const cToken = CErc20.at(0x3FDA...);
cToken.methods.redeem(1).send({from: ...});

Redeem Underlying

The redeem underlying function converts cTokens into a specified quantity of the underlying asset, and returns them to the user. The amount of cTokens redeemed is equal to the quantity of underlying tokens received, divided by the current Exchange Rate. The amount redeemed must be less than the user's Account Liquidity and the market's available liquidity.

CErc20 / CEther

function redeemUnderlying(uint redeemAmount) returns (uint)

Solidity

CEther cToken = CEther(0x3FDB...);
require(cToken.redeemUnderlying(50) == 0, "something went wrong");

Web3 1.0

const cToken = CErc20.at(0x3FDA...);
cToken.methods.redeemUnderlying(10).send({from: ...});

Borrow

The borrow function transfers an asset from the protocol to the user, and creates a borrow balance which begins accumulating interest based on the Borrow Rate for the asset. The amount borrowed must be less than the user's Account Liquidity and the market's available liquidity.

To borrow Ether, the borrower must be 'payable' (solidity).

CErc20 / CEther

function borrow(uint borrowAmount) returns (uint)

Solidity

CErc20 cToken = CErc20(0x3FDA...);
require(cToken.borrow(100) == 0, "got collateral?");

Web3 1.0

const cToken = CEther.at(0x3FDB...);
await cToken.methods.borrow(50).send({from: 0xMyAccount});

Repay Borrow

The repay function transfers an asset into the protocol, reducing the user's borrow balance.

CErc20

function repayBorrow(uint repayAmount) returns (uint)

Before repaying an asset, users must first approve the cToken to access their token balance.

CEther

function repayBorrow() payable

Solidity

CEther cToken = CEther(0x3FDB...);
require(cToken.repayBorrow.value(100)() == 0, "transfer approved?");

Web3 1.0

const cToken = CErc20.at(0x3FDA...);
cToken.methods.repayBorrow(10000).send({from: ...});

Repay Borrow Behalf

The repay function transfers an asset into the protocol, reducing the target user's borrow balance.

CErc20

function repayBorrowBehalf(address borrower, uint repayAmount) returns (uint)

Before repaying an asset, users must first approve the cToken to access their token balance.

CEther

function repayBorrowBehalf(address borrower) payable

Solidity

CEther cToken = CEther(0x3FDB...);
require(cToken.repayBorrowBehalf.value(100)(0xBorrower) == 0, "transfer approved?");

Web3 1.0

const cToken = CErc20.at(0x3FDA...);
await cToken.methods.repayBorrowBehalf(0xBorrower, 10000).send({from: 0xPayer});

Transfer

Transfer is an ERC-20 method that allows accounts to send tokens to other Ethereum addresses. A cToken transfer will fail if the account has entered that cToken market and the transfer would have put the account into a state of negative liquidity.

CErc20 / CEther

function transfer(address recipient, uint256 amount) returns (bool)

Solidity

CEther cToken = CEther(0x3FDB...);
cToken.transfer(0xABCD..., 100000000000);

Web3 1.0

const cToken = CErc20.at(0x3FDA...);
await cToken.methods.transfer(0xABCD..., 100000000000).send({from: 0xSender});

Liquidate Borrow

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 liquidator may close up to a certain fixed percentage (i.e. close factor) of any individual outstanding borrow of the underwater account. Unlike in v1, liquidators must interact with each cToken contract in which they wish to repay a borrow and seize another asset as collateral. When collateral is seized, the liquidator is transferred cTokens, which they may redeem the same as if they had supplied the asset themselves. Users must approve each cToken contract before calling liquidate (i.e. on the borrowed asset which they are repaying), as they are transferring funds into the contract.

CErc20

function liquidateBorrow(address borrower, uint amount, address collateral) returns (uint)

Before supplying an asset, users must first approve the cToken to access their token balance.

CEther

function liquidateBorrow(address borrower, address cTokenCollateral) payable

Solidity

CEther cToken = CEther(0x3FDB...);
CErc20 cTokenCollateral = CErc20(0x3FDA...);
require(cToken.liquidateBorrow.value(100)(0xBorrower, cTokenCollateral) == 0, "borrower underwater??");

Web3 1.0

const cToken = CErc20.at(0x3FDA...);
const cTokenCollateral = CEther.at(0x3FDB...);
await cToken.methods.liquidateBorrow(0xBorrower, 33, cTokenCollateral).send({from: 0xLiquidator});

Key Events

Error Codes

Failure Info

Exchange Rate

Each cToken is convertible into an ever increasing quantity of the underlying asset, as interest accrues in the market. The exchange rate between a cToken and the underlying asset is equal to:

exchangeRate = (getCash() + totalBorrows() - totalReserves()) / totalSupply()

CErc20 / CEther

function exchangeRateCurrent() returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint exchangeRateMantissa = cToken.exchangeRateCurrent();

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const exchangeRate = (await cToken.methods.exchangeRateCurrent().call()) / 1e18;

Tip: note the use of call vs. send to invoke the function from off-chain without incurring gas costs.

Get Cash

Cash is the amount of underlying balance owned by this cToken contract. One may query the total amount of cash currently available to this market.

CErc20 / CEther

function getCash() returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint cash = cToken.getCash();

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const cash = (await cToken.methods.getCash().call());

Total Borrow

Total Borrows is the amount of underlying currently loaned out by the market, and the amount upon which interest is accumulated to suppliers of the market.

CErc20 / CEther

function totalBorrowsCurrent() returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint borrows = cToken.totalBorrowsCurrent();

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const borrows = (await cToken.methods.totalBorrowsCurrent().call());

Borrow Balance

A user who borrows assets from the protocol is subject to accumulated interest based on the current borrow rate. Interest is accumulated every block and integrations may use this function to obtain the current value of a user's borrow balance with interest.

CErc20 / CEther

function borrowBalanceCurrent(address account) returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint borrows = cToken.borrowBalanceCurrent(msg.caller);

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const borrows = await cToken.methods.borrowBalanceCurrent(account).call();

Borrow Rate

At any point in time one may query the contract to get the current borrow rate per block.

CErc20 / CEther

function borrowRatePerBlock() returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint borrowRateMantissa = cToken.borrowRatePerBlock();

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const borrowRate = (await cToken.methods.borrowRatePerBlock().call()) / 1e18;

Total Supply

Total Supply is the number of tokens currently in circulation in this cToken market. It is part of the EIP-20 interface of the cToken contract.

CErc20 / CEther

function totalSupply() returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint tokens = cToken.totalSupply();

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const tokens = (await cToken.methods.totalSupply().call());

Underlying Balance

The user's underlying balance, representing their assets in the protocol, is equal to the user's cToken balance multiplied by the Exchange Rate.

CErc20 / CEther

function balanceOfUnderlying(address account) returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint tokens = cToken.balanceOfUnderlying(msg.caller);

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const tokens = await cToken.methods.balanceOfUnderlying(account).call();

Supply Rate

At any point in time one may query the contract to get the current supply rate per block. The supply rate is derived from the borrow rate, reserve factor and the amount of total borrows.

CErc20 / CEther

function supplyRatePerBlock() returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint supplyRateMantissa = cToken.supplyRatePerBlock();

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const supplyRate = (await cToken.methods.supplyRatePerBlock().call()) / 1e18;

Total Reserves

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. A small portion of borrower interest accrues into the protocol, determined by the reserve factor.

CErc20 / CEther

function totalReserves() returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint reserves = cToken.totalReserves();

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const reserves = (await cToken.methods.totalReserves().call());

Reserve Factor

The reserve factor defines the portion of borrower interest that is converted into reserves.

CErc20 / CEther

function reserveFactorMantissa() returns (uint)

Solidity

CErc20 cToken = CToken(0x3FDA...);
uint reserveFactorMantissa = cToken.reserveFactorMantissa();

Web3 1.0

const cToken = CEther.at(0x3FDB...);
const reserveFactor = (await cToken.methods.reserveFactorMantissa().call()) / 1e18;