# eTokens Each asset supported by the Eco DeFi Protocol is integrated through a eToken contract, which is an EIP-20 compliant representation of balances supplied to the protocol. By minting eTokens, users (1) earn interest through the eToken's exchange rate, which increases in value relative to the underlying asset, and (2) gain the ability to use eTokens as collateral. eTokens are the primary means of interacting with the Eco DeFi Protocol; when a user mints, redeems, borrows, repays a borrow, liquidates a borrow, or transfers eTokens, he/she will do so using the eToken contract. There are currently two types of eTokens: EBEP20 and EBNB. Though both types expose the EIP-20 interface, EBEP20 wraps an underlying BEP-20 asset, while BNB 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. ### Redeem The redeem function converts a specified quantity of eTokens into the underlying asset, and returns them to the user. The amount of underlying tokens received is equal to the quantity of eTokens 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 #### EBEP20 / EBNB ``` function redeem(uint redeemTokens) returns (uint) ``` * `msg.sender`: The account to which redeemed funds shall be transferred * `redeemTokens`: The number of eTokens to be redeemed * `RETURN`: 0 on success, otherwise an Error code {% tabs %} {% tab title="Solidity" %} ``` EToken eToken = EToken (0x3FDB...); require(eToken.redeem(7) == 0, "something went wrong"); ``` {% endtab %} {% tab title="Web3 1.0" %} ``` const eToken = EBEP20.at(0x3FDA...); eToken.methods.redeemUnderlying(10).send({from: ...}); ``` {% endtab %} {% endtabs %} ### Redeem Underlying The redeem underlying function converts eTokens into a specified quantity of the underlying asset, and returns them to the user. The amount of eTokens 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. #### EBEP20 / EBNB ``` function redeemUnderlying(uint redeemAmount) returns (uint) ``` * msg.sender: The account to which redeemed funds shall be transferred * redeemAmount: The amount of underlying to be redeemed * RETURN: 0 on success, otherwise an Error code {% tabs %} {% tab title="Solidity" %} ``` EToken eToken = EToken (0x3FDB...); require(eToken.redeemUnderlying(50) == 0, "something went wrong"); ``` {% endtab %} {% tab title="Web3 1.0" %} ``` const eToken = EBEP20.at(0x3FDA...); eToken.methods.redeemUnderlying(10).send({from: ...}); ``` {% endtab %} {% endtabs %} ### 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 EBNB, the borrower must be 'payable' (solidity). #### EBEP20 / EBNB ``` function borrow(uint borrowAmount) returns (uint) ``` * msg.sender: The account to which borrowed funds shall be transferred. * borrowAmount : The amount of the underlying asset to be borrowed. * RETURN: 0 on success, otherwise an Error code {% tabs %} {% tab title="Solidity" %} ``` EToken eToken = EToken (0x3FDB...); require(eToken.borrow(100) == 0, "got collateral?"); ``` {% endtab %} {% tab title="Second Tab" %} ``` const eToken = EBEP20.at(0x3FDB...); await eToken.methods.borrow(50).send({from: 0xMyAccount}); ``` {% endtab %} {% endtabs %} ### Repay Borrow The repay function transfers an asset into the protocol, reducing the user's borrow balance. #### EBEP20 ``` function repayBorrow(uint repayAmount) returns (uint) ``` * msg.sender: The account which borrowed the asset, and shall repay the borrow. * repayAmount: The amount of the underlying borrowed asset to be repaid. A value of -1 (i.e. 2256 - 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 eToken to access their token balance. #### EBNB ```actionscript function repayBorrow() payable ``` * msg.valuepayable: The amount of BNB to be repaid, in wei. * msg.sender: The account which borrowed the asset, and shall repay the borrow. * RETURN: No return, reverts on error. {% tabs %} {% tab title="Solidity" %} ```lisp EToken eToken = EToken (0x3FDB...); require(eToken.repayBorrow.value(100)() == 0, "transfer approved?"); ``` {% endtab %} {% tab title="Second Tab" %} ``` const eToken = EBEP20.at(0x3FDA...); eToken.methods.repayBorrow(10000).send({from: ...}); ``` {% endtab %} {% endtabs %} ### Repay Borrow Behalf The repay function transfers an asset into the protocol, reducing the target user's borrow balance. #### EBEP20 ``` function repayBorrowBehalf(address borrower, uint repayAmount) returns (uint) ``` * msg.sender: The account which shall repay the borrow. * borrower: 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. 2256 - 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 eToken to access their token balance. #### EBNB ``` function repayBorrowBehalf(address borrower) payable ``` * msg.valuepayable: The amount of bnb 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. {% tabs %} {% tab title="Solidity" %} ``` EToken eToken = EToken(0x3FDB...); require(eToken.repayBorrowBehalf.value(100)(0xBorrower) == 0, "transfer approved?"); ``` {% endtab %} {% tab title="Second Tab" %} ``` const eToken = EBEP20.at(0x3FDA...); await eToken.methods.repayBorrowBehalf(0xBorrower, 10000).send({from: 0xPayer}); ``` {% endtab %} {% endtabs %} ### Transfer Transfer is BEP20 method that allows accounts to send tokens to other BNB addresses. eToken transfer will fail if the account has entered that eToken market and the transfer would have put the account into a state of negative liquidity. #### EBEP20 / EBNB ```php function transfer(address recipient, uint256 amount) returns (bool) ``` * recipient: The transfer recipient address. * amount: The amount of eTokens to transfer. * RETURN: Returns a boolean value indicating whether or not the operation succeeded. {% tabs %} {% tab title="Solidity" %} ``` EToken eToken = EToken(0x3FDB...); eToken.transfer(0xABCD..., 100000000000); ``` {% endtab %} {% tab title="Web3 1.0" %} ``` const eToken = EBEP20.at(0x3FDA...); await eToken.methods.transfer(0xABCD..., 100000000000).send({from: 0xSender}); ``` {% endtab %} {% endtabs %} ### 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 transferes eTokens, which may redeem the same as if they had supplied the asset themselves. Users must approve each eToken contract before calling liquidate (i.e. on the borrowed asset which they are repaying), as they are transferring funds into the contract. #### EBEP20 ``` function liquidateBorrow(address borrower, uint amount, address collateral) returns (uint) ``` * 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. * eTokenCollateral: The address of the eToken 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 eToken to access their token balance. #### EBNB ``` function liquidateBorrow(address borrower, address eTokenCollateral) payable ``` * 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. * eTokenCollateral: The address of the eToken currently held as collateral by a borrower, that the liquidator shall seize. * RETURN: No return, reverts on error. {% tabs %} {% tab title="Solidity" %} ``` EToken eToken = EToken(0x3FDB...); EBEP20 eTokenCollateral = EBEP20(0x3FDA...); require(eToken.liquidateBorrow.value(100)(0xBorrower, eTokenCollateral) == 0, "borrower underwater??"); ``` {% endtab %} {% tab title="Web3 1.0" %} ``` const eToken = EBEP20.at(0x3FDA...); const eTokenCollateral = EBNB.at(0x3FDB...); await eToken.methods.liquidateBorrow(0xBorrower, 33, eTokenCollateral).send({from: 0xLiquidator}); ``` {% endtab %} {% endtabs %} ### Key Events | **Event** | **Description** | | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | Mint(address minter, uint mintAmount, uint mintTokens) | Emitted upon a successful Mint. | | Redeem(address redeemer, uint redeemAmount, uint redeemTokens) | Emitted upon a successful Redeem. | | Borrow(address borrower, uint borrowAmount, uint accountBorrows, uint totalBorrows) | Emitted upon a successful Borrow. | | RepayBorrow(address payer, address borrower, uint repayAmount, uint accountBorrows, uint totalBorrows) | Emitted upon a successful Repay Borrow. | | LiquidateBorrow(address liquidator, address borrower, uint repayAmount, address cTokenCollateral, uint seizeTokens) | Emitted upon a successful Liquidate Borrow. | ### Error Codes
NameDescriptionCode
NO_ERRORNot a failure.0
UNAUTHORIZEDThe sender is not authorized to perform this action.1
BAD_INPUTAn invalid argument was supplied by the caller.2
ESGTROLLER_REJECTIONThe action would violate the esgtroller policy.3
ESGTROLLER_CALCULATION_ERRORAn internal calculation has failed in the esgtroller.4
INTEREST_RATE_MODEL_ERRORThe interest rate model returned an invalid value.5
INVALID_ACCOUNT_PAIRThe specified combination of accounts is invalid.6
INVALID_CLOSE_AMOUNT_REQUESTEDThe amount to liquidate is invalid.7
INVALID_COLLATERAL_FACTORThe collateral factor is invalid.8
MATH_ERRORA math calculation error occurred.9
MARKET_NOT_FRESHInterest has not been properly accrued.10
MARKET_NOT_LISTEDThe market is not currently listed by its esgtroller.11
TOKEN_INSUFFICIENT_ALLOWANCEBEP-20 contract must allow Money Market contract to call transferFrom. The current allowance is either 0 or less than the requested supply, repayBorrow or liquidate amount.12
TOKEN_INSUFFICIENT_BALANCECaller does not have sufficient balance in the BEP-20 contract to complete the desired action.13
TOKEN_INSUFFICIENT_CASHThe market does not have a sufficient cash balance to complete the transaction. You may attempt this transaction again later.14
TOKEN_TRANSFER_IN_FAILEDFailure in BEP-20 when transfering token into the market.15
TOKEN_TRANSFER_OUT_FAILEDFailure in BEP-20 when transfering token out of the market.16
### Failure Info
NameCode
ACCEPT_ADMIN_PENDING_ADMIN_CHECK0
ACCRUE_INTEREST_ACCUMULATED_INTEREST_CALCULATION_FAILED1
ACCRUE_INTEREST_BORROW_RATE_CALCULATION_FAILED2
ACCRUE_INTEREST_NEW_BORROW_INDEX_CALCULATION_FAILED3
ACCRUE_INTEREST_NEW_TOTAL_BORROWS_CALCULATION_FAILED4
ACCRUE_INTEREST_NEW_TOTAL_RESERVES_CALCULATION_FAILED5
ACCRUE_INTEREST_SIMPLE_INTEREST_FACTOR_CALCULATION_FAILED6
BORROW_ACCUMULATED_BALANCE_CALCULATION_FAILED7
BORROW_ACCRUE_INTEREST_FAILED8
BORROW_CASH_NOT_AVAILABLE9
BORROW_FRESHNESS_CHECK10
BORROW_NEW_TOTAL_BALANCE_CALCULATION_FAILED11
BORROW_NEW_ACCOUNT_BORROW_BALANCE_CALCULATION_FAILED12
BORROW_MARKET_NOT_LISTED13
BORROW_ETROLLER_REJECTION14
LIQUIDATE_ACCRUE_BORROW_INTEREST_FAILED15
LIQUIDATE_ACCRUE_COLLATERAL_INTEREST_FAILED16
LIQUIDATE_COLLATERAL_FRESHNESS_CHECK17
LIQUIDATE_ESGTROLLER_REJECTION18
LIQUIDATE_E SGTROLLER_CALCULATE_AMOUNT_SEIZE_FAILED19
LIQUIDATE_CLOSE_AMOUNT_IS_UINT_MAX20
LIQUIDATE_CLOSE_AMOUNT_IS_ZERO21
LIQUIDATE_FRESHNESS_CHECK22
LIQUIDATE_LIQUIDATOR_IS_BORROWER23
LIQUIDATE_REPAY_BORROW_FRESH_FAILED24
LIQUIDATE_SEIZE_BALANCE_INCREMENT_FAILED25
LIQUIDATE_SEIZE_BALANCE_DECREMENT_FAILED26
LIQUIDATE_SEIZE_ESGTROLLER_REJECTION27
LIQUIDATE_SEIZE_LIQUIDATOR_IS_BORROWER28
LIQUIDATE_SEIZE_TOO_MUCH29
MINT_ACCRUE_INTEREST_FAILED30
MINT_ESGTROLLER_REJECTION31
MINT_EXCHANGE_CALCULATION_FAILED32
MINT_EXCHANGE_RATE_READ_FAILED33
MINT_FRESHNESS_CHECK34
MINT_NEW_ACCOUNT_BALANCE_CALCULATION_FAILED35
MINT_NEW_TOTAL_SUPPLY_CALCULATION_FAILED36
MINT_TRANSFER_IN_FAILED37
MINT_TRANSFER_IN_NOT_POSSIBLE38
REDEEM_ACCRUE_INTEREST_FAILED39
REDEEM_ESGTROLLER_REJECTION40
REDEEM_EXCHANGE_TOKENS_CALCULATION_FAILED41
REDEEM_EXCHANGE_AMOUNT_CALCULATION_FAILED42
REDEEM_EXCHANGE_RATE_READ_FAILED43
REDEEM_FRESHNESS_CHECK44
REDEEM_NEW_ACCOUNT_BALANCE_CALCULATION_FAILED45
REDEEM_NEW_TOTAL_SUPPLY_CALCULATION_FAILED46
REDEEM_TRANSFER_OUT_NOT_POSSIBLE47
REDUCE_RESERVES_ACCRUE_INTEREST_FAILED48
REDUCE_RESERVES_ADMIN_CHECK49
REDUCE_RESERVES_CASH_NOT_AVAILABLE50
REDUCE_RESERVES_FRESH_CHECK51
REDUCE_RESERVES_VALIDATION52
REPAY_BEHALF_ACCRUE_INTEREST_FAILED53
REPAY_BORROW_ACCRUE_INTEREST_FAILED54
REPAY_BORROW_ACCUMULATED_BALANCE_CALCULATION_FAILED55
REPAY_BORROW_ESGTROLLER_REJECTION56
REPAY_BORROW_FRESHNESS_CHECK57
REPAY_BORROW_NEW_ACCOUNT_BORROW_BALANCE_CALCULATION_FAILED58
REPAY_BORROW_NEW_TOTAL_BALANCE_CALCULATION_FAILED59
REPAY_BORROW_TRANSFER_IN_NOT_POSSIBLE60
SET_COLLATERAL_FACTOR_OWNER_CHECK61
SET_COLLATERAL_FACTOR_VALIDATION62
SET_ESGTROLLER_OWNER_CHECK63
SET_INTEREST_RATE_MODEL_ACCRUE_INTEREST_FAILED64
SET_INTEREST_RATE_MODEL_FRESH_CHECK65
SET_INTEREST_RATE_MODEL_OWNER_CHECK66
SET_MAX_ASSETS_OWNER_CHECK67
SET_ORACLE_MARKET_NOT_LISTED68
SET_PENDING_ADMIN_OWNER_CHECK69
SET_RESERVE_FACTOR_ACCRUE_INTEREST_FAILED70
SET_RESERVE_FACTOR_ADMIN_CHECK71
SET_RESERVE_FACTOR_FRESH_CHECK72
SET_RESERVE_FACTOR_BOUNDS_CHECK73
TRANSFER_ESGTROLLER_REJECTION74
TRANSFER_NOT_ALLOWED75
TRANSFER_NOT_ENOUGH76
TRANSFER_TOO_MUCH77
### Exchange Rate Each eToken is convertible into an ever increasing quantity of the underlying asset, as interest accrues in the market. The exchange rate between a eToken and the underlying asset is equal to: ``` exchangeRate = (getCash() + totalBorrows() - totalReserves()) / totalSupply() ``` #### EBEP20 / EBNB ``` function exchangeRateCurrent() returns (uint) ``` * RETURN: The current exchange rate as an unsigned integer, scaled by 1 \* 10^(18 - 8 + Underlying Token Decimals). {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint exchangeRateMantissa = eToken.exchangeRateCurrent(); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const exchangeRate = (await eToken.methods.exchangeRateCurrent().call()) / 1e18; ``` {% endtab %} {% endtabs %} 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 eToken contract. One may query the total amount of cash currently available to this market. #### EBEP20 / EBNB ``` function getCash() returns (uint) ``` * RETURN: The quantity of underlying asset owned by the contract. {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint cash = eToken.getCash(); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const cash = (await eToken.methods.getCash().call()); ``` {% endtab %} {% endtabs %} ### Total Borrows 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. #### EBEP20 / EBNB ``` function totalBorrowsCurrent() returns (uint) ``` * RETURN: The total amount of borrowed underlying, with interest. {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint borrows = eToken.totalBorrowsCurrent(); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const borrows = (await eToken.methods.totalBorrowsCurrent().call()); ``` {% endtab %} {% endtabs %} ### 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. #### EBEP20 / EBNB ``` function borrowBalanceCurrent(address account) returns (uint) ``` * account: The account which borrowed the assets. * RETURN: The user's current borrow balance (with interest) in units of the underlying asset {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint borrows = eToken.borrowBalanceCurrent(msg.caller); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const borrows = await eToken.methods.borrowBalanceCurrent(account).call(); ``` {% endtab %} {% endtabs %} ### Borrow Rate At any point in time one may query the contract to get the current borrow rate per block. #### EBEP20 / EBNB ``` function borrowRatePerBlock() returns (uint) ``` * RETURN: The current borrow rate as an unsigned integer, scaled by 1e18. {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint borrowRateMantissa = eToken.borrowRatePerBlock(); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const borrowRate = (await eToken.methods.borrowRatePerBlock().call()) / 1e18; ``` {% endtab %} {% endtabs %} ### Total Supply Total Supply is the number of tokens currently in circulation in this eToken market. It is part of the EIP-20 interface of the eToken contract. #### EBEP20 / EBNB ``` function totalSupply() returns (uint) ``` * RETURN: The total number of tokens in circulation for the market. {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint tokens = eToken.totalSupply(); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const tokens = (await eToken.methods.totalSupply().call()); ``` {% endtab %} {% endtabs %} ### Underlying Balance The user's underlying balance, representing their assets in the protocol, is equal to the user's eToken balance multiplied by the Exchange Rate. #### EBEP20 / EBNB ``` function balanceOfUnderlying(address account) returns (uint) ``` * account: The account to get the underlying balance. * RETURN: The amount of underlying currently owned by the account. {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint tokens = eToken.balanceOfUnderlying(msg.caller); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const tokens = await eToken.methods.balanceOfUnderlying(account).call(); ``` {% endtab %} {% endtabs %} ### 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. #### EBEP20 / EBNB ``` function supplyRatePerBlock() returns (uint) ``` * RETURN: The current supply rate as an unsigned integer, scaled by 1e18. {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint supplyRateMantissa = eToken.supplyRatePerBlock(); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const supplyRate = (await eToken.methods.supplyRatePerBlock().call()) / 1e18; ``` {% endtab %} {% endtabs %} ### Total Reserves Reserves are an accounting entry in each eToken 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. #### EBEP20 / EBNB ``` function totalReserves() returns (uint) ``` * RETURN: The total amount of reserves held in the market. {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint reserves = eToken.totalReserves(); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const reserves = (await eToken.methods.totalReserves().call()); ``` {% endtab %} {% endtabs %} ### Reserve Factor The reserve factor defines the portion of borrower interest that is converted into reserves. #### EBEP20 / EBNB ``` function reserveFactorMantissa() returns (uint) ``` * RETURN: The current reserve factor as an unsigned integer, scaled by 1e18. {% tabs %} {% tab title="Solidity" %} ```abnf EBEP20 eToken = EToken(0x3FDA...); uint reserveFactorMantissa = eToken.reserveFactorMantissa(); ``` {% endtab %} {% tab title="Web3 1.0" %} ```abnf const eToken = EToken.at(0x3FDB...); const reserveFactor = (await eToken.methods.reserveFactorMantissa().call()) / 1e18; ``` {% endtab %} {% endtabs %}