Comptroller

Each time a user interacts with a caToken, the Comptroller is asked to approve or deny the transaction. The Comptroller maps user balances to prices (via the Price Oracle) to risk weights (called Collateral Factors) to make its determinations.

Users explicitly list which assets they would like included in their risk scoring, by calling Enter Markets and Exit Market.

The Comptroller is implemented as an upgradeable proxy. The Unitroller proxies all logic to the Comptroller implementation, but storage values are set on the Unitroller. To call Comptroller functions, use the Comptroller ABI on the Unitroller address.

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 troll = Comptroller(0xABCD...);
CToken[] memory cTokens = new CToken[](2);
cTokens[0] = CErc20(0x3FDA...);
cTokens[1] = CEther(0x3FDB...);
uint[] memory errors = troll.enterMarkets(cTokens);

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

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 troll = Comptroller(0xABCD...);
uint error = troll.exitMarket(CToken(0x3FDA...));

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

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 troll = Comptroller(0xABCD...);
address[] memory markets = troll.getAssetsIn(0xMyAccount);

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

A caToken's collateral factor can range from 0-90%, and represents the proportionate increase in liquidity (borrow limit) that an account receives by minting the caToken. Generally, large or liquid assets have high collateral factors, while small or illiquid assets have low collateral factors.

If an asset has a 0% collateral factor, it can't be used as collateral (or seized in liquidation), though it can still be borrowed. Collateral factors can be increased (or decreased) through protocol governance, as market conditions change.

Comptroller troll = Comptroller(0xABCD...);
(bool isListed, uint collateralFactorMantissa, bool isComped) = troll.markets(0x3FDA...);

const troll = Comptroller.at(0xABCD...);
const result = await troll.methods.markets(0x3FDA...).call();
const {0: isListed, 1: collateralFactorMantissa, 2: isComped} = result;

Account Liquidity represents the USD value borrowable by a user, before it reaches liquidation. Users with a shortfall (negative liquidity) are subject to liquidation, and can't withdraw or borrow assets until Account Liquidity is positive again.

For each market the user has entered into, their supplied balance is multiplied by the market's collateral factor, and summed; borrow balances are then subtracted, to equal Account Liquidity. Borrowing an asset reduces Account Liquidity for each USD borrowed; withdrawing an asset reduces Account Liquidity by the asset's collateral factor times each USD withdrawn.

Because the CapyFi Protocol exclusively uses unsigned integers, Account Liquidity returns either a surplus or shortfall.

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

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

The percent, ranging from 0% to 100%, of a liquidatable account's borrow that can be repaid in a single liquidate transaction. If a user has multiple borrowed assets, the closeFactor applies to any single borrowed asset, not the aggregated value of a user's outstanding borrowing.

Comptroller troll = Comptroller(0xABCD...);
uint closeFactor = troll.closeFactorMantissa();

const troll = Comptroller.at(0xABCD...);
const closeFactor = await troll.methods.closeFactorMantissa().call();

The liquidation incentive is the additional collateral given to liquidators as a reward for liquidating undercollateralized accounts. This incentive ensures that liquidators are compensated for their service and helps maintain the health of the protocol.

Comptroller troll = Comptroller(0xABCD...);
uint liquidationIncentive = troll.liquidationIncentiveMantissa();

const troll = Comptroller.at(0xABCD...);
const liquidationIncentive = await troll.methods.liquidationIncentiveMantissa().call();

The Comptroller contract has an array called `getAllMarkets` that contains the addresses of each caToken contract. Each address in the `getAllMarkets` array can be used to fetch a metadata struct in the Comptroller's markets constant.

Comptroller troll = Comptroller(0xABCD...);
CToken cTokens[] = troll.getAllMarkets();

const comptroller = new web3.eth.Contract(comptrollerAbi, comptrollerAddress);
const cTokens = await comptroller.methods.getAllMarkets().call();
const cToken = cTokens[0]; // address of a cToken