/compound-protocol

The Compound On-Chain Protocol

Primary LanguageTypeScriptOtherNOASSERTION

CircleCI codecov

Compound Protocol

The Compound Protocol is an Ethereum smart contract for supplying or borrowing assets. Through the cToken contracts, accounts on the blockchain supply capital (Ether or ERC-20 tokens) to receive cTokens or borrow assets from the protocol (holding other assets as collateral). The Compound cToken contracts track these balances and algorithmically set interest rates for borrowers.

Before getting started with this repo, please read:

For questions about interacting with Compound, please visit our Discord server.

For security concerns, please visit https://compound.finance/security or email security@compound.finance.

Contracts

We detail a few of the core contracts in the Compound protocol.

CToken, CErc20 and CEther
The Compound cTokens, which are self-contained borrowing and lending contracts. CToken contains the core logic and CErc20 and CEther add public interfaces for Erc20 tokens and ether, respectively. Each CToken is assigned an interest rate and risk model (see InterestRateModel and Comptroller sections), and allows accounts to *mint* (supply capital), *redeem* (withdraw capital), *borrow* and *repay a borrow*. Each CToken is an ERC-20 compliant token where balances represent ownership of the market.
Comptroller
The risk model contract, which validates permissible user actions and disallows actions if they do not fit certain risk parameters. For instance, the Comptroller enforces that each borrowing user must maintain a sufficient collateral balance across all cTokens.
InterestRateModel
Contracts which define interest rate models. These models algorithmically determine interest rates based on the current utilization of a given market (that is, how much of the supplied assets are liquid versus borrowed).
Careful Math
Library for safe math operations.
ErrorReporter
Library for tracking error codes and failure conditions.
Exponential
Library for handling fixed-point decimal numbers.
SafeToken
Library for safely handling Erc20 interaction.
WhitePaperInterestRateModel
Initial interest rate model, as defined in the Whitepaper. This contract accepts a base rate and slope parameter in its constructor.

Installation

To run compound, pull the repository from GitHub and install its dependencies. You will need yarn or npm installed.

git clone https://github.com/compound-finance/compound-protocol
cd compound-protocol
yarn # or `npm install`

You can then compile and deploy the contracts with:

yarn run deploy

Note: this project does not use truffle migrations. The command above is the best way to deploy contracts. To view the addresses of contracts, please inspect the networks/development.json file that is produced as an artifact of that command.

Console

After you deploy, as above, you can run a truffle console with the following command:

yarn run console

This command will create a truffle-like build directory and start a truffle console, thus you can then run:

truffle(rinkeby)> cDAI.deployed().then((cdai) => cdai.borrowRatePerBlock.call())
<BN: 7699bf9dd>

You can also specify a network (rinkeby, ropsten, kovan, goerli or mainnet):

yarn run console rinkeby

REPL

The Compound Protocol has a simple scenario evaluation tool to test and evaluate scenarios which could occur on the blockchain. This is primarily used for constructing high-level integration tests. The tool also has a REPL to interact with local the Compound Protocol (similar to truffle console).

yarn run repl

> Read CToken cBAT Address
Command: Read CToken cBAT Address
AddressV<val=0xAD53863b864AE703D31b819d29c14cDA93D7c6a6>

You can read more about the scenario runner in the Scenario Docs on steps for using the repl.

Deployment

The easiest way to deploy some Erc20 tokens, cTokens and a Comptroller is through scenario scripts.

# run ganache locally
script/ganache # or `ganache-cli`

# ensure development files don't exist as
# new ganache instances invalidate old deployed contracts
rm networks/development*

# run deployment script
yarn run deploy -v

After that, you'll have a full set of contracts deployed locally. Look in networks/development.json for the addresses for those deployed contracts. You can use the yarn run console command above to interact with the contracts (or the scenario REPL, if you prefer).

Testing

Mocha contract tests are defined under the test directory. To run the tests run:

yarn run test

or with inspection (visit chrome://inspect) and look for a remote target after running:

node --inspect node_modules/truffle-core/cli.js test

Assertions used in our tests are provided by ChaiJS.

Integration Specs

There are additional tests under the spec/scenario folder. These are high-level integration tests based on the scenario runner depicted above. The aim of these tests is to be highly literate and have high coverage in the interaction of contracts.

Formal Verification Specs

The Compound Protocol has a number of formal verification specifications, powered by Certora. You can find details in the spec/formal folder. The Certora Verification Language (CVL) files included are specifications, which when with the Certora CLI tool, produce formal proofs (or counter-examples) that the code of a given contract exactly matches that specification.

Code Coverage

To run code coverage, run:

scripts/ganache-coverage # run ganache in coverage mode
yarn run coverage

Linting

To lint the code, run:

yarn run lint

Docker

To run in docker:

# Build the docker image
docker build -t compound-protocol .

# Run a shell to the built image
docker run -it compound-protocol /bin/sh

From within a docker shell, you can interact locally with the protocol via ganache and truffle:

> ganache-cli &
> yarn run deploy
> yarn run console
truffle(development)> cDAI.deployed().then((contract) => cdai = contract);
truffle(development)> cdai.borrowRatePerBlock.call().then((rate) => rate.toNumber())
20

Discussion

For any concerns with the protocol, visit us on Discord to discuss.

© Copyright 2019, Compound Labs, Inc.