Cauldron V4

Forth version of the cauldrons, implementing the following changes:

  • Blacklisted Callees, allowing owner to block cauldron calls to some specific addresses.

  • RepayForAll, allowing the repayment of debt to all user proportionally to the borrowPart owned.

  • Ability to release funds from Strategy and redeposit them afterwards. (if bentoBox is owned by bentoBoxOwner contract)

  • Liquidations can happen as part of cook().

Functions starting with '✨' are new in V4.

It is deployed directly and then used as a masterContract to deploy each market, as clones, following the minimal proxy pattern.

You can find the full contract here.

constructor nonpayable (address)

This will create the masterContract that will be used by all the clones (markets).

ParameterDescription

bentoBox_

The address of the BentoBox

magicInternetMoney_

The address of MIM.

Write Functions

accrue

function accrue() public

Accrues the interest on the borrowed tokens and handles the accumulation of fees.

updateExchangeRate

function updateExchangeRate() public returns (bool updated, uint256 rate)

Gets the exchange rate, ie how much collateral to buy 1e18 asset. Invoked if needed since Oracle queries can be expensive.

Returns

NameTypeDescription

updated

bool

boolean determining if the exchange rate has been updated yet or not

rate

uint256

the new exchange rate that was fetched

addCollateral

function addCollateral(
        address to,
        bool skim,
        uint256 share
    ) public

Adds share amount of collateral from msg.sender to the account to.

Parameters

NameTypeDescription

to

address

receiver of the tokens

skim

bool

True if the amount should be skimmed from the deposit balance of msg.sender. False if tokens from msg.sender in bentoBox should be transferred.

share

uint256

amount of shares to add for to

removeCollateral

function removeCollateral(address to, uint256 share) public solvent

Calls _removeCollateral, which removes the amount share of collateral and transfers it to the account to.

Parameters

NameTypeDescription

to

address

receiver of the shares

share

uint256

amount of shares to send

borrow

function borrow(address to, uint256 amount) public solvent returns (uint256 part, uint256 share)

Calls _borrow, which allows the sender to borrow amount and transfer to to.

Parameters

NameTypeDescription

to

address

receiver of the borrowed assets

amount

uint256

amount of assets to borrow

Returns

NameTypeDescription

part

uint256

total part of debt held by borrowers

share

uint256

total amount in shares borrowed

repay

function repay(
        address to,
        bool skim,
        uint256 part
    ) public returns (uint256 amount)

Calls _repay, which repays a loan.

Parameters

NameTypeDescription

to

address

address of user payment should go to

skim

bool

true if amount should be skimmed from the deposit balance of msg.sender

part

uint256

amount to repay

Returns

NameTypeDescription

amount

uint256

total amount repayed

changeBorrowLimit

function changeBorrowLimit(
        uint128 newBorrowLimit, 
        uint128 perAddressPart
    ) public onlyMasterContractOwner {

Allows MasterContractOwner to change the borrow limits of the cauldron, both globally and per user.

Parameters

NameType

newBorrowLimit

uint128

perAddressPart

uint128

changeInterestRate

function changeInterestRate(uint64 newInterestRate) public onlyMasterContractOwner {

Allows MasterContractOwner to change the interest rate of the Cauldron. The rate can only be change every 3 days The newInterestRate can't be bigger than 175% of the old rate (the rate can't increase by more than 75% at the time) If rate was 0%, the rate can be increased to 1%, the previous rule then applies.

Parameters

NameTypeDescription

newInterestRate

uint64

New Interest rate

cook

function cook(
        uint8[] calldata actions,
        uint256[] calldata values,
        bytes[] calldata datas
    ) external payable returns (uint256 value1, uint256 value2)

Executes a set of actions and allows composability (contract calls) to other contracts.

The cook function allows to bundle functionality within one contract call while passing return values from one call to the next one. Actions are defined by a numeric identifier and can return two values, value1 and value2 to the next function. The input arrays actions, values and datas define the sequential actions. In the Value array the ether value of a call may be defined.

Whereas calling functions like borrow that have the solvent modifier requires solvency at the end of the function, solvency only needs to be guaranteed at the end of the cook function, thereby allowing more complicated operations such as leveraging within one call.

For certain parameters either an external value can be passed in or the identifier USEVALUE1 (-1) or USE_VALUE2 (-2) to access either of the local variables. The following variables are marked in bold italic in the table below. If an action returns one value it is saved as value1, if two are returned they are saved as value1 and value2 respectively. Any action can access these values during the whole duration of the cook call.

The call data for the actions is ABI encoded as listed below.

Action NameIDparameter namesABI encodingreturnValues

ACTION_REPAY

2

share, to, skim

int256, address, bool

ACTION_REMOVE_COLLATERAL

4

fraction, to

int256, address

ACTION_BORROW

5

amount, to

int256, address

part, share

ACTION_GET_REPAY_SHARE

6

part

int256

ACTION_GET_REPAY_PART

7

amount

int256

ACTION_ACCRUE

8

ACTION_ADD_COLLATERAL

10

share, to, skim

int256, address, bool

ACTION_UPDATE_EXCHANGE_RATE

11

must_update, minRate, maxRate

bool, uint256, uint256

ACTION_BENTO_DEPOSIT

20

token, to, amount, share

IERC20, address, int256, int256

amountOut, shareOut

ACTION_BENTO_WITHDRAW

21

token, to, amount, share

IERC20, address, int256, int256

amountOut, shareOut

ACTION_BENTO_TRANSFER

22

token, to, share

IERC20, address, int256

ACTION_BENTO_TRANSFER_MULTIPLE

23

token, tos, shares

IERC20, address[], uint256[]

ACTION_BENTO_SETAPPROVAL

24

user, _masterContract, approved, v, r, s

address, address, bool, uint8, bytes32, bytes32

ACTION_CALL

30

callee, callData, useValue1, useValue2, returnValues

address, bytes, bool, bool, uint8

ACTION_LIQUIDATE

31

users, maxBorrowParts, to, swapper, swapperData

address[], uint265[], address, ISwapperV2, bytes

ACTION_RELEASE_COLLATERAL_FROM_STRATEGY

33

Available actions and their ID:

// Functions that need accrue to be called
    uint8 internal constant ACTION_REPAY = 2;
    uint8 internal constant ACTION_REMOVE_COLLATERAL = 4;
    uint8 internal constant ACTION_BORROW = 5;
    uint8 internal constant ACTION_GET_REPAY_SHARE = 6;
    uint8 internal constant ACTION_GET_REPAY_PART = 7;
    uint8 internal constant ACTION_ACCRUE = 8;

    // Functions that don't need accrue to be called
    uint8 internal constant ACTION_ADD_COLLATERAL = 10;
    uint8 internal constant ACTION_UPDATE_EXCHANGE_RATE = 11;

    // Function on BentoBox
    uint8 internal constant ACTION_BENTO_DEPOSIT = 20;
    uint8 internal constant ACTION_BENTO_WITHDRAW = 21;
    uint8 internal constant ACTION_BENTO_TRANSFER = 22;
    uint8 internal constant ACTION_BENTO_TRANSFER_MULTIPLE = 23;
    uint8 internal constant ACTION_BENTO_SETAPPROVAL = 24;

    // Any external call (except to BentoBox)
    uint8 internal constant ACTION_CALL = 30;
    uint8 internal constant ACTION_LIQUIDATE = 31;
    uint8 internal constant ACTION_RELEASE_COLLATERAL_FROM_STRATEGY = 33;

    int256 internal constant USE_VALUE1 = -1;
    int256 internal constant USE_VALUE2 = -2;

Parameters

NameTypeDescription

actions

uint8[]

array with sequence of actions to execute

values

uint256[]

one-to-one mapped array to actions, ETH amounts to send along with the actions

datas

bytes[]

one-to-one mapped array to actions, contains abi encoded data of function arguments

Returns

NameTypeDescription

value1

uint256

may contain first positioned return value of last executed action (if applicable)

value2

uint256

may contain second positioned return value of last executed action which returns 2 values (if applicable)

liquidate

function liquidate(
        address[] calldata users,
        uint256[] calldata maxBorrowParts,
        address to,
        ISwapper swapper,
    ) public

Handles the liquidation of users' balances once the users' amount of collateral is too low.

Parameters

NameTypeDescription

users

address[]

Array of user addresses

maxBorrowParts

uint256[]

one-to-one mapping to users, contains maximum (partial) borrow amounts (to liquidate) of the respective user

to

address

address of the receiver in open liquidations if swapper is zero

swapper

ISwapper

contract address of the ISwapper implementation, swappers are restricted for closed liquidations

withdrawFees

function withdrawFees() public

Withdraw the fees accumulated to the feeTo address.

setFeeTo

function setFeeTo(address newFeeTo) public onlyOwner

Sets the beneficiary of fees accrued in liquidations. Can only be called by the owner of the contract.

Parameters

NameTypeDescription

newFeeTo

address

address of the beneficiary

reduceSupply

function reduceSupply(uint256 amount) public 

Reduces the supply of MIM

Parameters

NameTypeDescription

amount

uint256

amount to reduce supply by (in native representation)

✨ repayForAll​ | New in V4

Parameters

NameType

amount

uint128

Amount of MIM to repay.

skim

bool

Ignore amount and take every mim in this contract.

Return values

NameTypeDescription

/

uint128

Amount repaid.

✨ setBlacklistedCallee | New in V4

Parameters

NameTypeDescription

callee

address

Address of the callee

blacklisted

bool

new blacklist status. True if blacklisted.

View Functions

BORROW_OPENING_FEE

Returns the opening fee (charged instantly, added to user debt upon borrowing) in Basis Points.

COLLATERIZATION_RATE

Returns the Collateralization Rate (maximum % borrowable with this collateral) in Basis Points. eg: 75000 = 75%

LIQUIDATION_MULTIPLIER

Returns the liquidation fee in Basis Points. eg: 112000 would add 12% (it's a multiplier, so the value is 112%)

accrueInfo

Return values

NameTypeDescription

lastAccrued

uint64

Timestamp of the last accrue() call.

feesEarned

uint128

Fees accrue between the last withdrawal and the last accrue.

INTEREST_PER_SECOND

uint64

bentoBox

Return values

NameTypeDescription

/

address

Address of the bentoBox the cauldron is deployed on. Set by constructor of masterContract

✨ blacklistedCallees | New in V4

Parameters

NameTypeDescription

/

address

Address of the callee

Return values

NameTypeDescription

/

bool

Blacklist status. True if blacklisted.

borrowLimit

Returns the current borrowLimit, expressed in borrowParts at the cauldron level and at the address level.

Return values

NameTypeDescription

total

uint128

Max total borrow parts for the cauldron.

borrowPartPerAddress

uint128

Max total borrow parts per user.

collateral

Return values

NameTypeDescription

/

address

Address of the collateral used by this cauldron.

exchangeRate

Return values

NameTypeDescription

/

uint256

Current cached exchange rate.

feeTo

Return values

NameType

/

address

Recipient of the Fees (controlled by masterContract, which is why regular cauldrons have a feeTo zero address)

magicInternetMoney

Return values

NameTypeDescription

/

address

Address of MIM, set by constructor of masterContract

masterContract

Return values

NameTypeDescription

/

address

masterContract address.

oracle

Return values

NameTypeDescription

/

address

Oracle Address.

oracleData

Return values

NameTypeDescription

/

bytes

Oracle data used to query it.

owner

Return values

NameType

/

address

Owner of the Cauldron (controlled by masterContract, which is why regular cauldrons have zeroAddress as an owner).

pendingOwner

When transferring ownership, the future owner is pending until they claims ownership.

Return values

NameTypeDescription

/

address

Address of the pending owner.

totalBorrow

Returns the total amounts borrowed from the cauldron.

Return values

NameTypeDescription

elastic

uint128

Amount of MIM borrowed by users.

base

uint128

Amount of borrowParts held by users.

totalCollateralShare

Returns the amount (in shares) of the token collateral used as collateral in this cauldron.

Return values

NameTypeDescription

/

uint256

Amount of shares of collateral deposited into the Cauldron.

userBorrowPart

Returns the amount of borrowParts held by a user. To convert that amount into a numerical MIM debt amount, you must do totalBorrow.elastic / totalBorrow.base * borrowParts.

Parameters

NameTypeDescription

/

address

User address.

Return values

NameTypeDescription

/

uint256

Amount of borrowParts held.

userCollateralShare

Amount (in shares) of the token collateral used as collateral by the user.

Parameters

NameTypeDescription

/

address

User address.

Return values

NameTypeDescription

/

uint256

Shares of collateral deposited.

Last updated