Compound Presidio

Compound v2 (a.k.a. Presidio) is a set of smart contracts deployed on the Ethereum blockchain, which allows supplying and borrowing of ERC-20 tokens. This page details the on-chain function 'ABI' for developing smart contracts or building Web3-enabled dApps.

For information on the Compound API, please visit the Compound API docs.

Getting Started

The Compound Protocol v2 is currently deployed on the following networks:

cTokens

Every asset supported by the Compound Protocol is now integrated through a cToken smart contract, which is an EIP-20 compliant representation of balances supplied to the protocol. Users supply to the protocol by minting tokens (cTokens), which strictly increase in value relative to their underlying asset.

cTokens are the primary way of interacting with the Compound Protocol. Each cToken contract creates its own money market. 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 money market, which begins accumulating interest based on the current supply rate for the asset. The number of tokens minted is the amount of underlying asset being provided divided by the current exchange rate

Mint is analagous to supply from the Compound v1 Protocol.

CErc20

• msg.sender - The account which shall supply the asset, and own the minted cTokens.
• mintAmount - The amount of the asset to be supplied, in units of the underlying asset.
• RETURN - 0 on success, otherwise an Error codes

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

CEther

• msg.value - The amount of ether to be supplied, in wei.
• msg.sender - The account which shall supply the ether, and own the minted cTokens.
• RETURN - No return, reverts on error.

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 transfers the underlying asset from the money market to the user in exchange for previously minted cTokens. The amount of underlying redeemed is the number of cTokens multiplied by the current Exchange Rate. The amount redeemed must be less than the user's account liquidity and the market's available liquidity.

Redeem is analagous to withdraw from the Compound v1 Protocol.

CErc20 / CEther

• msg.sender - The account to which redeemed funds shall be transferred.
• redeemTokens - The number of cTokens to be redeemed.
• RETURN - 0 on success, otherwise an Error codes

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 transfers the underlying asset from the money market to the user in exchange for previously minted cTokens. The number of cTokens redeemed is the amount of underlying 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

• msg.sender - The account to which redeemed funds shall be transferred.
• redeemAmount - The amount of underlying to be redeemed.
• RETURN - 0 on success, otherwise an Error codes

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 money market 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 borrow capacity and the market's available liquidity. Users must maintain a collateral requirement to avoid liquidation.

Note that the borrower will receive a transfer of the underlying asset. For CEther, this will be ether and thus the borrower must be payable (for Solidity).

CErc20 / CEther

• msg.sender - The account to which borrowed funds shall be transferred.
• borrowAmount - The amount of the underlying asset to be borrowed.
• RETURN - 0 on success, otherwise an Error codes

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 money market, reducing the user's borrow balance.

CErc20

• msg.sender - The account which borrowed the asset, and shall repay the borrow.
• repayAmount - The amount of the underlying borrowed asset to be repaid. A value of -1 (i.e. 2²⁵⁶ - 1) can be used to repay the full amount.
• RETURN - 0 on success, otherwise an Error codes

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

CEther

• msg.value - The amount of ether to be repaid, in wei.
• msg.sender - The account which borrowed the asset, and shall repay the borrow.
• RETURN - No return, reverts on error.

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 money market, reducing the user's borrow balance.

CErc20

• msg.sender - The account which shall repay the borrow.
• borrower - The account which borrowed the asset to be repaid.
• repayAmount - The amount of the underlying borrowed asset to be repaid. A value of -1 (i.e. 2²⁵⁶ - 1) can be used to repay the full amount.
• RETURN - 0 on success, otherwise an Error codes

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

CEther

• msg.value - The amount of ether to be repaid, in wei.
• msg.sender - The account which shall repay the borrow.
• borrower - The account which borrowed the asset to be repaid.
• RETURN - No return, reverts on error.

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});

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

• msg.sender - The account which shall liquidate the borrower by repaying their debt and seizing their collateral.
• borrower - The account with negative account liquidity that shall be liquidated.
• repayAmount - The amount of the borrowed asset to be repaid and converted into collateral, specified in units of the underlying borrowed asset.
• cTokenCollateral - The address of the cToken currently held as collateral by a borrower, that the liquidator shall seize.
• RETURN - 0 on success, otherwise an Error codes

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

CEther

• msg.value - The amount of ether to be repaid and converted into collateral, in wei.
• msg.sender - The account which shall liquidate the borrower by repaying their debt and seizing their collateral.
• borrower - The account with negative account liquidity that shall be liquidated.
• cTokenCollateral - The address of the cToken currently held as collateral by a borrower, that the liquidator shall seize.
• RETURN - No return, reverts on error.

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

cToken Helpers

In addition to the core market functions, the cToken contracts implement a number of helper functions to aid developers in building on top of the protocol.

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:

CErc20 / CEther

• RETURN - The current exchange rate as an unsigned integer, scaled by 1e18.

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

• RETURN - The quantity of underlying asset owned by the contract.

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

• RETURN - The total amount of borrowed underlying, with interest.

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

• account - The account which borrowed the assets.
• RETURN - The user's current borrow balance (with interest) in units of the underlying asset.

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

• RETURN - The current borrow rate as an unsigned integer, scaled by 1e18.

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

• RETURN - The total number of tokens in circulation for the market.

Solidity

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

Web3 1.0

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

Supply Balance

A user who supplies assets to the protocol receives tokens which accumulate interest based on the current supply rate. At any given time, the value of a token with interest may be queried via the exchange rate. The number of tokens owned by a particular user may also be queried, which is part of the EIP-20 interface of the cToken contract.

CErc20 / CEther

• account - The account to get the token balance of.
• RETURN - The number of tokens currently owned by the account.

Solidity

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

Web3 1.0

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

Supply Balance Underlying

CTokens also have a convenience method for determining the supply balance in terms of the amount of underlying (i.e. supply balance multiplied by the exchange rate).

CErc20 / CEther

function balanceOfUnderlying(address account) returns (uint)

• account - The account to get the underlying balance of.
• RETURN - The amount of underlying currently owned by the account.

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

• RETURN - The current supply rate as an unsigned integer, scaled by 1e18.

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 the equity accrued to the protocol itself, in order to fund its operation. Reserves also form part of the cash which may be loaned out to borrowers in the market. A small portion of borrower interest accrues into the protocol, determined by the reserve factor.

CErc20 / CEther

• RETURN - The total amount of reserves held by the protocol.

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 small slice of interest that is accrued into reserves.

CErc20 / CEther

• RETURN - The current reserve factor as an unsigned integer, scaled by 1e18.

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;

Comptroller

The comptroller contract manages the risk associated with the Compound Protocol v2. It is responsible for determining when account's are underwater and can be liquidated. It determines how much collateral can be seized in exchange for liquidating an underwater account. It also provides a defense mechanism to protect the protocol against unforeseen future attacks on the market.

In order to borrow from a market, users are required to supply collateral in some other market(s). Collateral protects the borrowed market, by incentivizing the borrower and/or a liquidator to repay debt. In v1, all markets had the same collateral factor. In addition, any market an account supplied to automatically became collateral for any borrows opened by that account.

In v2, we open the door for each market to determine what is sufficient collateral for a borrow of its asset. We also require that users explicitly enter the markets which they wish to either use as collateral or borrow from. This cuts down on the cost of supporting a large number of markets, while giving users the choice to not use all of their assets as collateral. The cost is a small bit of management overhead for users wishing to borrow, since they must now enter and exit markets.

Enter Markets

Enter into a list of markets - it is not an error to enter the same market more than once. In order to supply collateral or borrow in a market, it must be entered first.

Comptroller

• msg.sender - The account which shall enter the given markets.
• cTokens - The addresses of the cToken markets to enter.
• RETURN - For each market, returns an error code indicating whether or not it was entered. Each is 0 on success, otherwise an Error codes.

Solidity

Comptroller troll = Comptroller(0xABCD...);
CToken[] memory cTokens = new CToken[](2);
cTokens[0] = CErc20(0x3FDA...);
cTokens[1] = CEther(0x3FDB...);
uint[] memory errors = troll.enterMarkets(cTokens);

Web3 1.0

const troll = Comptroller.at(0xABCD...);
const cTokens = [CErc20.at(0x3FDA...), CEther.at(0x3FDB...)];
const errors = await troll.methods.enterMarkets(cTokens).send({from: ...});

Exit Market

Exit a market - it is not an error to exit a market which is not currently entered. Exited markets will not count towards account liquidity calculations.

Comptroller

• msg.sender - The account which shall exit the given market.
• cTokens - The addresses of the cToken market to exit.
• RETURN - 0 on success, otherwise an Error codes.

Solidity

Comptroller troll = Comptroller(0xABCD...);
uint error = troll.exitMarket(CToken(0x3FDA...));

Web3 1.0

const troll = Comptroller.at(0xABCD...);
const errors = await troll.methods.exitMarket(CEther.at(0x3FDB...)).send({from: ...});

Get Assets In

Get the list of markets an account is currently entered into. In order to supply collateral or borrow in a market, it must be entered first. Entered markets count towards account liquidity calculations.

Comptroller

• account - The account whose list of entered markets shall be queried.
• RETURN - The address of each market which is currently entered into.

Solidity

"Comptroller troll = Comptroller(0xABCD...);
address[] memory markets = troll.getAssetsIn(0xMyAccount);

Web3 1.0

const troll = Comptroller.at(0xABCD...);
const markets = await troll.methods.getAssetsIn(cTokens).call();

Get Assets In

Within the Compound Protocol, account liquidity is defined as the total estimated ether value of an account's collateral (supply balances multiplied by the protocol collateral factor, minus the total value of that account's borrow balances. These values are calculated using only the markets which the account has entered into.

Users who do not have positive account liquidity do not have the ability to withdraw or borrow any assets until they bring their account liquidity back positive by supplying more assets or paying back outstanding borrows.

Sometimes account liquidity refers to a single signed value, rather than two unsigned values - however the Compound Protocol only deals with unsigned integers. A negative value for account liquidity also means the user is subject to liquidation to bring their account liquidity back to zero.

• account - The account whose liquidity shall be calculated.
• RETURN - Tuple of values (error, liquidity, shortfall). The error shall be 0 on success, otherwise an error code. A non-zero liquidity value indicates the account has available account liquidity. A non-zero shortfall value indicates the account is currently below his/her collateral requirement and is subject to liquidation. At most one of liquidity or shortfall shall be non-zero.

Solidity

Comptroller troll = Comptroller(0xABCD...);
(uint error, uint liquidity, uint shortfall) = troll.getAccountLiquidity(msg.caller);
require(error == 0, "join the Discord");
require(shortfall == 0, "account underwater");
require(liquidity > 0, "account has excess collateral");

Web3 1.0

const troll = Comptroller.at(0xABCD...);
const result = await troll.methods.getAccountLiquidity(0xBorrower).call();
const {0: error, 1: liquidity, 2: shortfall} = result;

Key Events

Error Codes

Failure Info

Appendix

Supplementary discussion of some considerations for using the protocol. If you have other questions which are not answered here, please feel free to reach out for support.

Collateral

In order to borrow from the protocol, accounts must provide enough collateral. One of the greatest motivating factors for Compound v2: Presidio was the ability to set different collateral requirements, depending on the asset being borrowed. With Presidio, the protocol no longer has a global collateral requirement and instead opens it up to individual asset communities to determine what is sufficient collateral in order to borrow their asset.

More details about how this works now and how it will evolve will be coming in the next few weeks as we prepare for mainnet launch.

Exponential Math

The Compound smart contracts use a system of exponential math in order to represent fractional quantities with sufficient precision. Throughout the documentation and code we make reference to mantissas, which are unsigned integers scaled up by a factor of 1e18 from their nominal value. By using mantissas within our contracts, we may perform basic mathematical operations like multiplication and division at a higher resolution than working with the unscaled quantities directly as integers. To gain a better understanding of how this works, see Exponential.sol.

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:

Glossary

Support

For support requests, please reach out to us in the #development channel in our Discord. We're happy to help out and grow the Compound community. Your questions help us improve, so please don't hesitate to ask if you can't find what you are looking for here.