iToken Introduction

Introduction

Each asset supported by Iron Bank is integrated through a iToken contract, which is an EIP-20 compliant representation of balances supplied to the protocol. By minting iTokens, users (1) earn interest through the iToken's exchange rate, which increases in value relative to the underlying asset, and (2) gain the ability to use iTokens as collateral.
iTokens are the primary means of interacting with Iron Bank; when user mints, redeems, borrows, repays a borrow, liquidates a borrow, or transfers iTokens, they will do so using the iToken contract.
There are currently two types of iTokens: 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 protocol, which begins accumulating interest based on the current Supply Rate for the asset. The user receives a quantity of iTokens equal to the underlying tokens supplied, divided by the current Exchange Rate.

CErc20

1
function mint(uint mintAmount) returns (uint)
Copied!
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 code
Before supplying an asset, users must first approve the iToken to access their token balance.

CEther

1
function mint() payable
Copied!
msg.valuepayable: 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

1
Erc20 underlying = Erc20(0xToken...); // get a handle for the underlying asset contract
2
CErc20 iToken = CErc20(0x3FDA...); // get a handle for the corresponding cToken contract
3
underlying.approve(address(cToken), 100); // approve the transfer
4
assert(iToken.mint(100) == 0); // mint the cTokens and assert there is no error
Copied!

Web3 1.0

1
const iToken = CEther.at(0x3FDB...);
2
await iToken.methods.mint().send({from: myAccount, value: 50});
Copied!

Redeem

The redeem function converts a specified quantity of iTokens into the underlying asset, and returns them to the user. The amount of underlying tokens received is equal to the quantity of iTokens redeemed, multiplied 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

1
function redeem(uint redeemTokens) returns (uint)
Copied!
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 code

Solidity

1
CEther iToken = CEther(0x3FDB...);
2
require(iToken.redeem(7) == 0, "something went wrong");
Copied!

Web3 1.0

1
const iToken = CErc20.at(0x3FDA...);
2
iToken.methods.redeem(1).send({from: ...});
Copied!

Redeem Underlying

The redeem underlying function converts iTokens into a specified quantity of the underlying asset, and returns them to the user. The amount of iTokens redeemed is equal to the quantity of underlying tokens received, 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

1
function redeemUnderlying(uint redeemAmount) returns (uint)
Copied!

Solidity

1
CEther iToken = CEther(0x3FDB...);
2
require(iToken.redeemUnderlying(50) == 0, "something went wrong");
Copied!

Web3 1.0

1
const iToken = CErc20.at(0x3FDA...);
2
iToken.methods.redeemUnderlying(10).send({from: ...});
Copied!

Borrow

The borrow function transfers an asset from the protocol 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 Account Liquidity and the market's available liquidity.
To borrow Ether, the borrower must be 'payable' (solidity).

CErc20 / CEther

1
function borrow(uint borrowAmount) returns (uint)
Copied!
msg.sender: The account to which redeemed funds shall be transferred.
borrowAmount: The number of iTokens to be borrowed
RETURN: 0 on success, otherwise an Error code

Solidity

1
CEther iToken = CEther(0x3FDB...);
2
require(iToken.redeemUnderlying(50) == 0, "got collateral?");
Copied!

Web3 1.0

1
const iToken = CEther.at(0x3FDA...);
2
await iToken.methods.borrow(50).send({from: 0xMyAccount});
Copied!

Repay Borrow

The repay function transfers an asset into the protocol, reducing the user's borrow balance.

CErc20

1
function repayBorrow(uint borrowAmount) returns (uint)
Copied!
msg.sender: The account to which borrowed the asset, and shall repay the borrow.
borrowAmount: The amount of the underlying borrowed asset to be repaid. A value of -1 (i.e. 2^256 - 1) can be used to repay the full amount.
RETURN: 0 on success, otherwise an Error code
Before repaying an asset, users must first approve the iToken to access their token balance.

CEther

1
function repayBorrow() payable
Copied!
msg.value payable: The amount of ether to be repaid, in wei.
msg.sender: The account which borrowed the asset, and shall repay the borrow
RETURN: 0 on success, otherwise an Error code

Solidity

1
CEther iToken = CEther(0x3FDB...);
2
require(iToken.repayBorrow.value(100() == 0, "transfer approved?");const iToken = CErc20.at(0x3FDA...);
3
iToken.methods.repayBorrow(10000).send({from: ...});
Copied!

Web3 1.0

1
const iToken = CEther.at(0x3FDA...);
2
await iToken.methods.borrow(50).send({from: 0xMyAccount});
Copied!

Repay Borrow Behalf

The repay function transfers an asset into the protocol, reducing the target user's borrow balance.

CErc20

1
function repayBorrowBehalf(address borrower, uint repayAmount) returns (uint)
Copied!
msg.sender: The account to which shall repay the borrow
borrowAmount: 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^256 - 1) can be used to repay the full amount.
RETURN: 0 on success, otherwise an Error code
Before repaying an asset, users must first approve the iToken to access their token balance.

CEther

1
function repayBorrowBehalf(address borrower) payable
Copied!
msg.valuepayable: 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

1
CEther iToken = CEther(0x3FDB...);
2
require(iToken.repayBorrowBehalf.value(100)(0xBorrower) == 0, "transfer approved?");
Copied!

Web3 1.0

1
const iToken = CErc20.at(0x3FDA...);
2
await iToken.methods.repayBorrowBehalf(0xBorrower, 10000).send({from: 0xPayer});
Copied!

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. When collateral is seized, the liquidator is transferred iTokens which they may redeem the same as if they had supplied the asset themselves. Users must approve each iToken contract before calling liquidate (i.e. on the borrowed asset which they are repaying), as they are transferring funds into the contract.

CErc20

1
function liquidateBorrow(address borrower, uint amount, address collateral) returns (uint)
Copied!
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 iToken currently held as collateral by a borrower, that the liquidator shall seize.
RETURN: 0 on success, otherwise an Error code
Before supplying an asset, users must first approve the iToken to access their token balance.

CEther

1
function liquidateBorrow(address borrower, address iTokenCollateral) payable
Copied!
msg.valuepayable: 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.
iTokenCollateral: The address of the iToken currently held as collateral by a borrower, that the liquidator shall seize.
RETURN: No return, reverts on error.

Solidity

1
CEther iToken = CEther(0x3FDB...);
2
CErc20 iTokenCollateral = CErc20(0x3FDA...);
3
require(iToken.liquidateBorrow.value(100)(0xBorrower, iTokenCollateral) == 0, "borrower underwater??");
Copied!

Web3 1.0

1
const iToken = CErc20.at(0x3FDA...);
2
const iTokenCollateral = CEther.at(0x3FDB...);
3
await iToken.methods.liquidateBorrow(0xBorrower, 33, iTokenCollateral).send({from: 0xLiquidator});
Copied!

Exchange Rate

Each iToken is convertible into an ever increasing quantity of the underlying asset, as interest accrues in the market. The exchange rate between a iToken and the underlying asset is equal to:
1
exchangeRate = (getCash() + totalBorrows() - totalReserves()) / totalSupply()
Copied!

CErc20/CEther

1
function exchangeRateCurrent() returns (uint)
Copied!

Solidity

1
CErc20 iToken = iToken(0x3FDA...);
2
uint exchangeRateMantissa = iToken.exchangeRateCurrent();
Copied!

Web3 1.0

1
const iToken = CEther.at(0x3FDB...);
2
const exchangeRate = (await iToken.methods.exchangeRateCurrent().call()) / 1e18;
Copied!
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 iToken contract. One may query the total amount of cash currently available to this market.

CErc20/CEther

1
function getCash() returns (unit)
Copied!
RETURN: The quantity of underlying asset owned by the contract.

Solidity

1
CErc20 iToken = iToken(0x3FDA...);
2
uint cash = iToken.getCash();
Copied!

Web3 1.0

1
const iToken = CEther.at(0x3FDB...);
2
const cash = (await iToken.methods.getCash().call());
Copied!

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

1
function totalBorrowCurrent() returns (unit)
Copied!
RETURN: The total amount of borrowed underlying, with interest.

Solidity

1
CErc20 iToken = CToken(0x3FDA...);
2
uint borrows = iToken.totalBorrowsCurrent();
Copied!

Web3 1.0

1
iToken = CEther.at(0x3FDB...);
2
const borrows = (await iToken.methods.totalBorrowsCurrent().call());
Copied!

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

1
function borrowBalanceCurrent(addressacount) returns (unit)
Copied!
RETURN: The total amount of borrowed underlying, with interest.

Solidity

1
CErc20 iToken = CToken(0x3FDA...);
2
uint borrows = iToken.borrowBalanceCurrent(msg.caller);
Copied!

Web3 1.0

1
iToken = CEther.at(0x3FDB...);
2
const borrows = await iToken.methods.totalBorrowsCurrent(account).call();
Copied!

Borrow Rate

At any point in time one may query the contract to get the current borrow rate per block.

CErc20/CEther

1
function borrowRatePerBlock() returns (unit)
Copied!
RETURN: The total amount of borrowed underlying, with interest.

Solidity

1
CErc20 iToken = CToken(0x3FDA...);
2
uint borrowRateMantissa = iToken.borrowRatePerBlock();
Copied!

Web3 1.0

1
iToken = CEther.at(0x3FDB...);
2
const borrowRate = (await iToken.methods.borrowRatePerBlock().call());
Copied!

Total Supply

Total Supply is the number of tokens currently in circulation in this iToken market. It is part of the EIP-20 interface of the iToken contract.

CErc20/CEther

1
function totalSupply() returns (unit)
Copied!
RETURN: The total number of tokens in circulation for the market.

Solidity

1
CErc20 iToken = CToken(0x3FDA...);
2
uint tokens = iToken.totalSupply();
Copied!

Web3 1.0

1
iToken = CEther.at(0x3FDB...);
2
const tokens = (await iToken.methods.totalSupply().call());
Copied!

Underlying Balance

The user's underlying balance, representing their assets in the protocol, is equal to the user's iToken balance multiplied by the Exchange Rate.

CErc20/CEther

1
function balanceOfUnderlying(address account) returns (unit)
Copied!
account: The account to get the underlying balance of.
RETURN: The amount of underlying currently owned by the account.

Solidity

1
CErc20 iToken = CToken(0x3FDA...);
2
uint tokens = iToken.balanceOfUnderlying(msg.caller);
Copied!

Web3 1.0

1
iToken = CEther.at(0x3FDB...);
2
const tokens = await iToken.methods.balanceOfUnderlying(account).call();
Copied!

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

1
function supplyRatePerBlock() returns (unit)
Copied!
RETURN: The current supply rate as an unsigned integer, scaled by 1e18.

Solidity

1
CErc20 iToken = CToken(0x3FDA...);
2
uint supplyRateMantissa = iToken.supplyRatePerBlock();
Copied!

Web3 1.0

1
const cToken = CEther.at(0x3FDB...);
2
const supplyRate = (await cToken.methods.supplyRatePerBlock().call()) / 1e18;
Copied!

Total Reserves

Reserves are an accounting entry in each iToken contract that represents a portion of historical interest set aside as cash which can be withdrawn or transferred through the protocol's governance. A small portion of borrower interest accrues into the protocol, determined by the reserve factor.

CErc20/CEther

1
function totalReserves() returns (unit)
Copied!
RETURN: The total amount of reserves held in the market

Solidity

1
CErc20 iToken = CToken(0x3FDA...);
2
uint reserves = iToken.totalReserves();
Copied!

Web3 1.0

1
const iToken = CEther.at(0x3FDB...);
2
const reserves = (await iToken.methods.totalReserves().call());
Copied!

Reserve Factor

The reserve factor defines the portion of borrower interest that is converted into reserves.

CErc20/CEther

1
function reserveFactorMantissa() returns (unit)
Copied!
RETURN: The current reserve factor as an unsigned itneger, scaled by 1e18.

Solidity

1
CErc20 iToken = CToken(0x3FDA...);
2
uint reserveFactorMantissa = crconst cToken = CEther.at(0x3FDB...);
3
const reserveFactor = (await cToken.methods.reserveFactorMantissa().call()) / 1e18;Token.reserveFactorMantissa();
Copied!

Web3 1.0

1
const iToken = CEther.at(0x3FDB...);
2
const reserves = (await iToken.methods.totalReserves().call());
Copied!