{"id":13470805,"url":"https://github.com/compound-finance/compound-protocol","last_synced_at":"2025-05-14T15:07:15.896Z","repository":{"id":37423168,"uuid":"200305501","full_name":"compound-finance/compound-protocol","owner":"compound-finance","description":"The Compound On-Chain Protocol","archived":false,"fork":false,"pushed_at":"2024-06-10T04:19:47.000Z","size":6325,"stargazers_count":1924,"open_issues_count":67,"forks_count":1223,"subscribers_count":79,"default_branch":"master","last_synced_at":"2025-04-10T04:53:20.415Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://compound.finance/developers","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/compound-finance.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-02T22:37:25.000Z","updated_at":"2025-04-09T11:48:07.000Z","dependencies_parsed_at":"2023-01-30T12:46:42.382Z","dependency_job_id":"73075e14-c5b2-4a9f-ae6c-2e39cd439e29","html_url":"https://github.com/compound-finance/compound-protocol","commit_stats":{"total_commits":73,"total_committers":20,"mean_commits":3.65,"dds":0.726027397260274,"last_synced_commit":"a3214f67b73310d547e00fc578e8355911c9d376"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compound-finance%2Fcompound-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compound-finance%2Fcompound-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compound-finance%2Fcompound-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/compound-finance%2Fcompound-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/compound-finance","download_url":"https://codeload.github.com/compound-finance/compound-protocol/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254169553,"owners_count":22026212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T16:00:36.144Z","updated_at":"2025-05-14T15:07:15.866Z","avatar_url":"https://github.com/compound-finance.png","language":"TypeScript","funding_links":[],"categories":["Resources","DEFI","TypeScript"],"sub_categories":[],"readme":"[![CircleCI](https://circleci.com/gh/compound-finance/compound-protocol.svg?style=svg\u0026circle-token=5ed19932325c559a06f71f87d69012aedd2cf3fb)](https://circleci.com/gh/compound-finance/compound-protocol) [![codecov](https://codecov.io/gh/compound-finance/compound-protocol/branch/master/graph/badge.svg?token=q4UvsvVzOX)](https://codecov.io/gh/compound-finance/compound-protocol)\n\nCompound Protocol\n=================\n\nThe 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.\n\nBefore getting started with this repo, please read:\n\n* The [Compound Whitepaper](https://compound.finance/documents/Compound.Whitepaper.pdf), describing how Compound works\n* The [Compound Protocol Specification](https://github.com/compound-finance/compound-protocol/tree/master/docs/CompoundProtocol.pdf), explaining in plain English how the protocol operates\n\nFor questions about interacting with Compound, please visit [our Discord server](https://compound.finance/discord).\n\nFor security concerns, please visit [https://compound.finance/security](https://compound.finance/security) or email [security@compound.finance](mailto:security@compound.finance).\n\nContributing\n============\n\nContributing to the Compound protocol is a bit different than most open-source projects -- check out the [community guide on Contributing](https://www.comp.xyz/t/contributing-to-compound-protocol/48).\n\nContracts\n=========\n\nWe detail a few of the core contracts in the Compound protocol.\n\n\u003cdl\u003e\n  \u003cdt\u003eCToken, CErc20 and CEther\u003c/dt\u003e\n  \u003cdd\u003eThe 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.\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eComptroller\u003c/dt\u003e\n  \u003cdd\u003eThe 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.\u003c/dd\u003e\n  \u003cul\u003e\n  \u003cem\u003eUpdating the Comptroller\u003c/em\u003e\n  \u003cli\u003eFollow the existing naming schema (ControllerGX)\u003c/li\u003e\n  \u003cli\u003eUpdate the scenario runner in scenario/src/Builder/ComptrollerImplBuilder.ts\u003c/li\u003e\n  \u003cli\u003eCreate unit tests and fork simulations as necessary\u003c/li\u003e\n  \u003cli\u003eCall \u003ccode\u003enpx saddle deploy Comptroller -n mainnet\u003c/code\u003e to deploy to mainnet and generate new ABI\u003c/li\u003e\n  \u003cul\u003e\n    \u003cli\u003eThe ABI can also be generated by deploying to mainnet in a fork simulation\u003c/li\u003e\n  \u003c/ul\u003e\n  \u003cli\u003eCall \u003ccode\u003enode script/comptroller-abi\u003c/code\u003e to merge the new Comptroller ABI with the Unitroller ABI\u003c/li\u003e\n  \u003cli\u003eEnsure that commit contains new generated Comptroller ABI\u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eComp\u003c/dt\u003e\n  \u003cdd\u003eThe Compound Governance Token (COMP). Holders of this token have the ability to govern the protocol via the governor contract.\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eGovernor Alpha\u003c/dt\u003e\n  \u003cdd\u003eThe administrator of the Compound timelock contract. Holders of Comp token may create and vote on proposals which will be queued into the Compound timelock and then have effects on Compound cToken and Comptroller contracts. This contract may be replaced in the future with a beta version.\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eInterestRateModel\u003c/dt\u003e\n  \u003cdd\u003eContracts 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).\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eCareful Math\u003c/dt\u003e\n  \u003cdd\u003eLibrary for safe math operations.\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eErrorReporter\u003c/dt\u003e\n  \u003cdd\u003eLibrary for tracking error codes and failure conditions.\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eExponential\u003c/dt\u003e\n  \u003cdd\u003eLibrary for handling fixed-point decimal numbers.\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eSafeToken\u003c/dt\u003e\n  \u003cdd\u003eLibrary for safely handling Erc20 interaction.\u003c/dd\u003e\n\u003c/dl\u003e\n\n\u003cdl\u003e\n  \u003cdt\u003eWhitePaperInterestRateModel\u003c/dt\u003e\n  \u003cdd\u003eInitial interest rate model, as defined in the Whitepaper. This contract accepts a base rate and slope parameter in its constructor.\u003c/dd\u003e\n\u003c/dl\u003e\n\nInstallation\n------------\nTo run compound, pull the repository from GitHub and install its dependencies. You will need [yarn](https://yarnpkg.com/lang/en/docs/install/) or [npm](https://docs.npmjs.com/cli/install) installed.\n\n    git clone https://github.com/compound-finance/compound-protocol\n    cd compound-protocol\n    yarn install --lock-file # or `npm install`\n\nREPL\n----\n\nThe 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`).\n\n    yarn repl -n development\n    yarn repl -n rinkeby\n\n    \u003e Read CToken cBAT Address\n    Command: Read CToken cBAT Address\n    AddressV\u003cval=0xAD53863b864AE703D31b819d29c14cDA93D7c6a6\u003e\n\nYou can read more about the scenario runner in the [Scenario Docs](https://github.com/compound-finance/compound-protocol/tree/master/scenario/SCENARIO.md) on steps for using the repl.\n\nTesting\n-------\nJest contract tests are defined under the [tests directory](https://github.com/compound-finance/compound-protocol/tree/master/tests). To run the tests run:\n\n    yarn test\n\nIntegration Specs\n-----------------\n\nThere are additional tests under the [spec/scenario](https://github.com/compound-finance/compound-protocol/tree/master/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.\n\nFormal Verification Specs\n-------------------------\n\nThe Compound Protocol has a number of formal verification specifications, powered by [Certora](https://www.certora.com/). You can find details in the [spec/formal](https://github.com/compound-finance/compound-protocol/tree/master/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.\n\nCode Coverage\n-------------\nTo run code coverage, run:\n\n    yarn coverage\n\nLinting\n-------\nTo lint the code, run:\n\n    yarn lint\n\nDocker\n------\n\nTo run in docker:\n\n    # Build the docker image\n    docker build -t compound-protocol .\n\n    # Run a shell to the built image\n    docker run -it compound-protocol /bin/sh\n\nFrom within a docker shell, you can interact locally with the protocol via ganache and truffle:\n\n```bash\n    /compound-protocol \u003e yarn console -n goerli\n    Using network goerli https://goerli-eth.compound.finance\n    Saddle console on network goerli https://goerli-eth.compound.finance\n    Deployed goerli contracts\n      comptroller: 0x627EA49279FD0dE89186A58b8758aD02B6Be2867\n      comp: 0xfa5E1B628EFB17C024ca76f65B45Faf6B3128CA5\n      governorAlpha: 0x8C3969Dd514B559D78135e9C210F2F773Feadf21\n      maximillion: 0x73d3F01b8aC5063f4601C7C45DA5Fdf1b5240C92\n      priceOracle: 0x9A536Ed5C97686988F93C9f7C2A390bF3B59c0ec\n      priceOracleProxy: 0xd0c84453b3945cd7e84BF7fc53BfFd6718913B71\n      timelock: 0x25e46957363e16C4e2D5F2854b062475F9f8d287\n      unitroller: 0x627EA49279FD0dE89186A58b8758aD02B6Be2867\n\n    \u003e await comp.methods.totalSupply().call()\n    '10000000000000000000000000'\n```\n\nConsole\n-------\n\nAfter you deploy, as above, you can run a truffle console with the following command:\n\n    yarn console -n goerli\n\nThis command will start a saddle console conencted to Goerli testnet (see [Saddle README](https://github.com/compound-finance/saddle#cli)):\n\n```javascript\n    Using network goerli https://goerli.infura.io/v3/e1a5d4d2c06a4e81945fca56d0d5d8ea\n    Saddle console on network goerli https://goerli.infura.io/v3/e1a5d4d2c06a4e81945fca56d0d5d8ea\n    Deployed goerli contracts\n      comptroller: 0x627EA49279FD0dE89186A58b8758aD02B6Be2867\n      comp: 0xfa5E1B628EFB17C024ca76f65B45Faf6B3128CA5\n      governorAlpha: 0x8C3969Dd514B559D78135e9C210F2F773Feadf21\n      maximillion: 0x73d3F01b8aC5063f4601C7C45DA5Fdf1b5240C92\n      priceOracle: 0x9A536Ed5C97686988F93C9f7C2A390bF3B59c0ec\n      priceOracleProxy: 0xd0c84453b3945cd7e84BF7fc53BfFd6718913B71\n      timelock: 0x25e46957363e16C4e2D5F2854b062475F9f8d287\n      unitroller: 0x627EA49279FD0dE89186A58b8758aD02B6Be2867\n    \u003e await comp.methods.totalSupply().call()\n    '10000000000000000000000000'\n```\n\nDeploying a CToken from Source\n------------------------------\n\nNote: you will need to set `~/.ethereum/\u003cnetwork\u003e` with your private key or assign your private key to the environment variable `ACCOUNT`.\n\nNote: for all sections including Etherscan verification, you must set the `ETHERSCAN_API_KEY` to a valid API Key from [Etherscan](https://etherscan.io/apis).\n\nTo deploy a new cToken, you can run the `token:deploy`. command, as follows. If you set `VERIFY=true`, the script will verify the token on Etherscan as well. The JSON here is the token config JSON, which should be specific to the token you wish to list.\n\n```bash\nnpx saddle -n rinkeby script token:deploy '{\n  \"underlying\": \"0x577D296678535e4903D59A4C929B718e1D575e0A\",\n  \"comptroller\": \"$Comptroller\",\n  \"interestRateModel\": \"$Base200bps_Slope3000bps\",\n  \"initialExchangeRateMantissa\": \"2.0e18\",\n  \"name\": \"Compound Kyber Network Crystal\",\n  \"symbol\": \"cKNC\",\n  \"decimals\": \"8\",\n  \"admin\": \"$Timelock\"\n}'\n```\n\nIf you only want to verify an existing token an Etherscan, make sure `ETHERSCAN_API_KEY` is set and run `token:verify` with the first argument as the token address and the second as the token config JSON:\n\n```bash\nnpx saddle -n rinkeby script token:verify 0x19B674715cD20626415C738400FDd0d32D6809B6 '{\n  \"underlying\": \"0x577D296678535e4903D59A4C929B718e1D575e0A\",\n  \"comptroller\": \"$Comptroller\",\n  \"interestRateModel\": \"$Base200bps_Slope3000bps\",\n  \"initialExchangeRateMantissa\": \"2.0e18\",\n  \"name\": \"Compound Kyber Network Crystal\",\n  \"symbol\": \"cKNC\",\n  \"decimals\": \"8\",\n  \"admin\": \"$Timelock\"\n}'\n```\n\nFinally, to see if a given deployment matches this version of the Compound Protocol, you can run `token:match` with a token address and token config:\n\n```bash\nnpx saddle -n rinkeby script token:match 0x19B674715cD20626415C738400FDd0d32D6809B6 '{\n  \"underlying\": \"0x577D296678535e4903D59A4C929B718e1D575e0A\",\n  \"comptroller\": \"$Comptroller\",\n  \"interestRateModel\": \"$Base200bps_Slope3000bps\",\n  \"initialExchangeRateMantissa\": \"2.0e18\",\n  \"name\": \"Compound Kyber Network Crystal\",\n  \"symbol\": \"cKNC\",\n  \"decimals\": \"8\",\n  \"admin\": \"$Timelock\"\n}'\n```\n\n## Deploying a CToken from Docker Build\n---------------------------------------\n\nTo deploy a specific version of the Compound Protocol, you can use the `token:deploy` script through Docker:\n\n```bash\ndocker run --env ETHERSCAN_API_KEY --env VERIFY=true --env ACCOUNT=0x$(cat ~/.ethereum/rinkeby) compoundfinance/compound-protocol:latest npx saddle -n rinkeby script token:deploy '{\n  \"underlying\": \"0x577D296678535e4903D59A4C929B718e1D575e0A\",\n  \"comptroller\": \"$Comptroller\",\n  \"interestRateModel\": \"$Base200bps_Slope3000bps\",\n  \"initialExchangeRateMantissa\": \"2.0e18\",\n  \"name\": \"Compound Kyber Network Crystal\",\n  \"symbol\": \"cKNC\",\n  \"decimals\": \"8\",\n  \"admin\": \"$Timelock\"\n}'\n```\n\nTo match a deployed contract against a given version of the Compound Protocol, you can run `token:match` through Docker, passing a token address and config:\n\n```bash\ndocker run --env ACCOUNT=0x$(cat ~/.ethereum/rinkeby) compoundfinance/compound-protocol:latest npx saddle -n rinkeby script token:match 0xF1BAd36CB247C82Cb4e9C2874374492Afb50d565 '{\n  \"underlying\": \"0x577D296678535e4903D59A4C929B718e1D575e0A\",\n  \"comptroller\": \"$Comptroller\",\n  \"interestRateModel\": \"$Base200bps_Slope3000bps\",\n  \"initialExchangeRateMantissa\": \"2.0e18\",\n  \"name\": \"Compound Kyber Network Crystal\",\n  \"symbol\": \"cKNC\",\n  \"decimals\": \"8\",\n  \"admin\": \"$Timelock\"\n}'\n```\n\nDiscussion\n----------\n\nFor any concerns with the protocol, open an issue or visit us on [Discord](https://compound.finance/discord) to discuss.\n\nFor security concerns, please email [security@compound.finance](mailto:security@compound.finance).\n\n_© Copyright 2020, Compound Labs_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcompound-finance%2Fcompound-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcompound-finance%2Fcompound-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcompound-finance%2Fcompound-protocol/lists"}