pTokens

Introduction

Each asset supported by the DeFiPIE Protocol is integrated through a pToken contract, which is an EIP-20 compliant representation of balances supplied to the protocol. By minting pTokens, users (1) earn interest through the pToken's exchange rate, which increases in value relative to the underlying asset, and (2) gain the ability to use pTokens as collateral.

pTokens are the primary means of interacting with the DeFiPIE Protocol; when a user mints, redeems, borrows, repays a borrow, liquidates a borrow, or transfers pTokens, he/she will do so using the pToken contract.

There are currently two types of pTokens: PErc20 and PEther. Though both types expose the EIP-20 interface, PErc20 wraps an underlying ERC-20 asset, while PEther 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.

How do pTokens earn interest?

Each pool has its own Deposit interest rate (APR). Interest isn't distributed; instead, simply by holding pTokens, you'll earn interest.

pTokens accumulates interest through their exchange rate — over time, each pToken becomes convertible into an increasing amount of it's underlying asset, even while the number of pTokens in your wallet stays the same.

Do I need to calculate the pToken exchange rate?

When a pool is launched, the pToken exchange rate (how much ETH one cETH is worth) begins at 0.020000 — and increases at a rate equal to the compounding pool interest rate. For example, after one year, the exchange rate might equal 0.021591.

Each user has the same pToken exchange rate; there’s nothing unique to your wallet that you have to worry about.

Can you walk me through an example?

Let’s say you deposit 1,000 DAI to the DeFiPIE protocol, when the exchange rate is 0.020070; you would receive 49,825.61 pDAI (1,000/0.020070).

A few months later, you decide it’s time to withdraw your DAI from the protocol; the exchange rate is now 0.021591:

Your 49,825.61 cDAI is now equal to 1,075.78 DAI (49,825.61 * 0.021591)
You could withdraw 1,075.78 DAI, which would redeem all 49,825.61 pDAI
Or, you could withdraw a portion, such as your original 1,000 DAI, which would redeem 46,315.59 pDAI (keeping 3,510.01 pDAI in your wallet)

How do I view my pTokens?

Each pToken is visible on Etherscan, and you should be able to view them in the list of tokens associated with your address

You can add pToken by its address in any wallet (Metamask, Trust Wallet etc.) as a simple ERC-20 token.

Can I transfer pTokens?

Yes, but exercise caution! By transferring pTokens, you’re transferring your balance of the underlying asset inside the DeFiPIE protocol. If you send a pToken to your friend, your balance (viewable in the DeFiPIE Interface) will decline, and your friend will see their balance increase.

A pToken transfer will fail if the account has entered that pToken pool and the transfer would have put the account into a state of negative liquidity.

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 pTokens equal to the underlying tokens deposited, divided by the current Exchange Rate.

PErc20

function mint(uint mintAmount) returns (uint)

msg.sender: The account which shall deposit the asset, and own the minted pTokens.
mintAmount: The amount of the asset to be deposited, in units of the underlying asset.
RETURN: 0 on success, otherwise an Error code

Before depositing an asset, users must first approve the pToken to access their token balance.

PEther

function mint() payable

msg.value (payable): The amount of ether to be deposited, in wei.
msg.sender: The account which shall deposit the ether, and own the minted pTokens.
RETURN: No return, reverts on error.

Solidity

Erc20 underlying = Erc20(0xToken...);     // get a handle for the underlying asset contract
PErc20 pToken = PErc20(0x3FDA...);        // get a handle for the corresponding PToken contract
underlying.approve(address(pToken), 100); // approve the transfer
assert(pToken.mint(100) == 0);            // mint the pTokens and assert there is no error

Web3 1.0

const pToken = PEther.at(0x3FDB...);
await pToken.methods.mint().send({from: myAccount, value: 50});

Redeem

The redeem function converts a specified quantity of pTokens into the underlying asset, and returns them to the user. The amount of underlying tokens received is equal to the quantity of pTokens redeemed, multiplied by the current Exchange Rate. The amount redeemed must be less than the user's Account Liquidity and the pool's available liquidity.

PErc20 / PEther

function redeem(uint redeemTokens) returns (uint)

msg.sender: The account to which redeemed funds shall be transferred.
redeemTokens: The number of pTokens to be redeemed.
RETURN: 0 on success, otherwise an Error code.

Solidity

PEther pToken = PEther(0x3FDB...);
require(pToken.redeem(7) == 0, "something went wrong");

Web3 1.0

const pToken = PErc20.at(0x3FDA...);
pToken.methods.redeem(1).send({from: ...});

Redeem Underlying

The redeem underlying function converts pTokens into a specified quantity of the underlying asset, and returns them to the user. The amount of pTokens 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 pool's available liquidity.

PErc20 / PEther

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.

Solidity

PEther pToken = PEther(0x3FDB...);
require(pToken.redeemUnderlying(50) == 0, "something went wrong");

Web3 1.0

const pToken = PErc20.at(0x3FDA...);
pToken.methods.redeemUnderlying(10).send({from: ...});

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 pool's available liquidity.

To borrow Ether, the borrower must be 'payable' (solidity).

PErc20 / PEther

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

Solidity

PErc20 pToken = PErc20(0x3FDA...);
require(pToken.borrow(100) == 0, "got collateral?");

Web3 1.0

const pToken = PEther.at(0x3FDB...);
await pToken.methods.borrow(50).send({from: 0xMyAccount});

Repay Borrow

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

PErc20

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. 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 pToken to access their token balance.

PEther

function repayBorrow() payable

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: No return, reverts on error.

Solidity

PEther pToken = PEther(0x3FDB...);
require(pToken.repayBorrow.value(100)() == 0, "transfer approved?");

Web3 1.0

const pToken = PErc20.at(0x3FDA...);
pToken.methods.repayBorrow(10000).send({from: ...});

Repay Borrow Behalf

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

PErc20

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. 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 pToken to access their token balance.

PEther

function repayBorrowBehalf(address borrower) payable

msg.value (payable): 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

PEther pToken = PEther(0x3FDB...);
require(pToken.repayBorrowBehalf.value(100)(0xBorrower) == 0, "transfer approved?");

Web3 1.0

const pToken = PErc20.at(0x3FDA...);
await pToken.methods.repayBorrowBehalf(0xBorrower, 10000).send({from: 0xPayer});

Transfer

Transfer is an ERC-20 method that allows accounts to send tokens to other Ethereum addresses. A pToken transfer will fail if the account has entered that pToken pool and the transfer would have put the account into a state of negative liquidity.

PErc20 / PEther

function transfer(address recipient, uint256 amount) returns (bool)

recipient: The transfer recipient address.
amount: The amount of pTokens to transfer.
RETURN: Returns a boolean value indicating whether or not the operation succeeded.

Solidity

PEther pToken = PEther(0x3FDB...);
pToken.transfer(0xABCD..., 100000000000);

Web3 1.0

const pToken = PErc20.at(0x3FDA...);
await pToken.methods.transfer(0xABCD..., 100000000000).send({from: 0xSender});

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. Liquidators must interact with each pToken contract in which they wish to repay a borrow and seize another asset as collateral. When collateral is seized, the liquidator is transferred pTokens, which they may redeem the same as if they had deposited the asset themselves. Users must approve each pToken contract before calling liquidate (i.e. on the borrowed asset which they are repaying), as they are transferring funds into the contract.

PErc20

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.
pTokenCollateral: The address of the pToken currently held as collateral by a borrower, that the liquidator shall seize.
RETURN: 0 on success, otherwise an Error code.

Before liquidating a loan, users must first approve the pToken to access their token balance.

PEther

function liquidateBorrow(address borrower, address pTokenCollateral) payable

msg.value (payable): 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.
pTokenCollateral: The address of the pToken currently held as collateral by a borrower, that the liquidator shall seize.
RETURN: No return, reverts on error.

Solidity

PEther pToken = PEther(0x3FDB...);
PErc20 pTokenCollateral = PErc20(0x3FDA...);
require(pToken.liquidateBorrow.value(100)(0xBorrower, pTokenCollateral) == 0, "borrower underwater??");

Web3 1.0

const pToken = PErc20.at(0x3FDA...);
const pTokenCollateral = PEther.at(0x3FDB...);
await pToken.methods.liquidateBorrow(0xBorrower, 33, pTokenCollateral).send({from: 0xLiquidator});

Key Events

Event

Description

Mint(address minter,

uint mintAmount, uint mintTokens)

Emitted upon a successful .

Redeem(address redeemer,

uint redeemAmount, uint redeemTokens)

Emitted upon a successful .

Borrow(address borrower,

uint borrowAmount, uint accountBorrows,

uint totalBorrows)

Emitted upon a successful .

RepayBorrow(address payer,

address borrower, uint repayAmount,

uint accountBorrows, uint totalBorrows)

Emitted upon a successful .

LiquidateBorrow(address liquidator,

address borrower, uint repayAmount,

address pTokenCollateral,

uint seizeTokens)

Emitted upon a successful .

Error Codes

Code

Name

Description

NO_ERROR

Not a failure.

UNAUTHORIZED

The sender is not authorized to perform this action.

BAD_INPUT

An invalid argument was supplied by the caller.

CONTROLLER_REJECTION

The action would violate the controller policy.

CONTROLLER_CALCULATION_ERROR

An internal calculation has failed in the controller.

INTEREST_RATE_MODEL_ERROR

The interest rate model returned an invalid value.

INVALID_ACCOUNT_PAIR

The specified combination of accounts is invalid.

INVALID_CLOSE_AMOUNT_REQUESTED

The amount to liquidate is invalid.

INVALID_COLLATERAL_FACTOR

The collateral factor is invalid.

MATH_ERROR

A math calculation error occurred.

MARKET_NOT_FRESH

Interest has not been properly accrued.

MARKET_NOT_LISTED

The pool is not currently listed by its controller.

TOKEN_INSUFFICIENT_ALLOWANCE

ERC-20 contract must allow pToken contract to call transferFrom. The current allowance is either 0 or less than the requested deposit, repayBorrow or liquidate amount.

TOKEN_INSUFFICIENT_BALANCE

Caller does not have sufficient balance in the ERC-20 contract to complete the desired action.

TOKEN_INSUFFICIENT_CASH

The pool does not have a sufficient cash balance to complete the transaction. You may attempt this transaction again later.

TOKEN_TRANSFER_IN_FAILED

Failure in ERC-20 when transfering token into the pool.

TOKEN_TRANSFER_OUT_FAILED

Failure in ERC-20 when transfering token out of the pool.

Failure Info

Code

Name

ACCEPT_ADMIN_PENDING_ADMIN_CHECK

ACCRUE_INTEREST_ACCUMULATED_INTEREST_CALCULATION_FAILED

ACCRUE_INTEREST_BORROW_RATE_CALCULATION_FAILED

ACCRUE_INTEREST_NEW_BORROW_INDEX_CALCULATION_FAILED

ACCRUE_INTEREST_NEW_TOTAL_BORROWS_CALCULATION_FAILED

ACCRUE_INTEREST_NEW_TOTAL_RESERVES_CALCULATION_FAILED

ACCRUE_INTEREST_SIMPLE_INTEREST_FACTOR_CALCULATION_FAILED

BORROW_ACCUMULATED_BALANCE_CALCULATION_FAILED

BORROW_ACCRUE_INTEREST_FAILED

BORROW_CASH_NOT_AVAILABLE

BORROW_FRESHNESS_CHECK

BORROW_NEW_TOTAL_BALANCE_CALCULATION_FAILED

BORROW_NEW_ACCOUNT_BORROW_BALANCE_CALCULATION_FAILED

BORROW_MARKET_NOT_LISTED

BORROW_CONTROLLER_REJECTION

LIQUIDATE_ACCRUE_BORROW_INTEREST_FAILED

LIQUIDATE_ACCRUE_COLLATERAL_INTEREST_FAILED

LIQUIDATE_COLLATERAL_FRESHNESS_CHECK

LIQUIDATE_CONTROLLER_REJECTION

LIQUIDATE_CONTROLLER_CALCULATE_AMOUNT_SEIZE_FAILED

LIQUIDATE_CLOSE_AMOUNT_IS_UINT_MAX

LIQUIDATE_CLOSE_AMOUNT_IS_ZERO

LIQUIDATE_FRESHNESS_CHECK

LIQUIDATE_LIQUIDATOR_IS_BORROWER

LIQUIDATE_REPAY_BORROW_FRESH_FAILED

LIQUIDATE_SEIZE_BALANCE_INCREMENT_FAILED

LIQUIDATE_SEIZE_BALANCE_DECREMENT_FAILED

LIQUIDATE_SEIZE_CONTROLLER_REJECTION

LIQUIDATE_SEIZE_LIQUIDATOR_IS_BORROWER

LIQUIDATE_SEIZE_TOO_MUCH

MINT_ACCRUE_INTEREST_FAILED

MINT_CONTROLLER_REJECTION

MINT_EXCHANGE_CALCULATION_FAILED

MINT_EXCHANGE_RATE_READ_FAILED

MINT_FRESHNESS_CHECK

MINT_NEW_ACCOUNT_BALANCE_CALCULATION_FAILED

MINT_NEW_TOTAL_SUPPLY_CALCULATION_FAILED

MINT_TRANSFER_IN_FAILED

MINT_TRANSFER_IN_NOT_POSSIBLE

REDEEM_ACCRUE_INTEREST_FAILED

REDEEM_CONTROLLER_REJECTION

REDEEM_EXCHANGE_TOKENS_CALCULATION_FAILED

REDEEM_EXCHANGE_AMOUNT_CALCULATION_FAILED

REDEEM_EXCHANGE_RATE_READ_FAILED

REDEEM_FRESHNESS_CHECK

REDEEM_NEW_ACCOUNT_BALANCE_CALCULATION_FAILED

REDEEM_NEW_TOTAL_SUPPLY_CALCULATION_FAILED

REDEEM_TRANSFER_OUT_NOT_POSSIBLE

REDUCE_RESERVES_ACCRUE_INTEREST_FAILED

REDUCE_RESERVES_ADMIN_CHECK

REDUCE_RESERVES_CASH_NOT_AVAILABLE

REDUCE_RESERVES_FRESH_CHECK

REDUCE_RESERVES_VALIDATION

REPAY_BEHALF_ACCRUE_INTEREST_FAILED

REPAY_BORROW_ACCRUE_INTEREST_FAILED

REPAY_BORROW_ACCUMULATED_BALANCE_CALCULATION_FAILED

REPAY_BORROW_CONTROLLER_REJECTION

REPAY_BORROW_FRESHNESS_CHECK

REPAY_BORROW_NEW_ACCOUNT_BORROW_BALANCE_CALCULATION_FAILED

REPAY_BORROW_NEW_TOTAL_BALANCE_CALCULATION_FAILED

REPAY_BORROW_TRANSFER_IN_NOT_POSSIBLE

SET_COLLATERAL_FACTOR_OWNER_CHECK

SET_COLLATERAL_FACTOR_VALIDATION

SET_CONTROLLER_OWNER_CHECK

SET_INTEREST_RATE_MODEL_ACCRUE_INTEREST_FAILED

SET_INTEREST_RATE_MODEL_FRESH_CHECK

SET_INTEREST_RATE_MODEL_OWNER_CHECK

SET_MAX_ASSETS_OWNER_CHECK

SET_ORACLE_MARKET_NOT_LISTED

SET_PENDING_ADMIN_OWNER_CHECK

SET_RESERVE_FACTOR_ACCRUE_INTEREST_FAILED

SET_RESERVE_FACTOR_ADMIN_CHECK

SET_RESERVE_FACTOR_FRESH_CHECK

SET_RESERVE_FACTOR_BOUNDS_CHECK

TRANSFER_CONTROLLER_REJECTION

TRANSFER_NOT_ALLOWED

TRANSFER_NOT_ENOUGH

TRANSFER_TOO_MUCH

ADD_RESERVES_ACCRUE_INTEREST_FAILED

ADD_RESERVES_FRESH_CHECK

ADD_RESERVES_TRANSFER_IN_NOT_POSSIBLE

SET_NEW_IMPLEMENTATION

Exchange Rate

Each pToken is convertible into an ever-increasing quantity of the underlying asset, as interest accrues in the pool. The exchange rate between a pToken and the underlying asset is equal to:

exchangeRate = (getCash() + totalBorrows() - totalReserves()) / totalSupply()

PErc20 / PEther

function exchangeRateCurrent() returns (uint)

RETURN: The current exchange rate as an unsigned integer, scaled by 1e18.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint exchangeRateMantissa = pToken.exchangeRateCurrent();

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const exchangeRate = (await pToken.methods.exchangeRateCurrent().call()) / 1e18;

Tip: note the use of callvs. send to invoke the function from off-chain without incurring gas costs.

Get Cash

Cash is the amount of underlying balance owned by this pToken contract. One may query the total amount of cash currently available to this pool.

PErc20 / PEther

function getCash() returns (uint)

RETURN: The quantity of underlying asset owned by the contract.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint cash = pToken.getCash();

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const cash = (await pToken.methods.getCash().call());

Total Borrow

Total Borrows is the amount of underlying currently loaned out by the pool, and the amount upon which interest is accumulated to suppliers of the pool.

PErc20 / PEther

function totalBorrowsCurrent() returns (uint)

RETURN: The total amount of borrowed underlying, with interest.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint borrows = pToken.totalBorrowsCurrent();

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const borrows = (await pToken.methods.totalBorrowsCurrent().call());

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.

PErc20 / PEther

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.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint borrows = pToken.borrowBalanceCurrent(msg.caller);

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const borrows = await pToken.methods.borrowBalanceCurrent(account).call();

Borrow Rate

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

PErc20 / PEther

function borrowRatePerBlock() returns (uint)

RETURN: The current borrow rate as an unsigned integer, scaled by 1e18.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint borrowRateMantissa = pToken.borrowRatePerBlock();

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const borrowRate = (await pToken.methods.borrowRatePerBlock().call()) / 1e18;

Total Supply

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

PErc20 / PEther

function totalSupply() returns (uint)

RETURN: The total number of tokens in circulation for the market.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint tokens = pToken.totalSupply();

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const tokens = (await pToken.methods.totalSupply().call());

Underlying Balance

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

PErc20 / PEther

function balanceOfUnderlying(address account) returns (uint)

account: The account to get the underlying balance of.
RETURN: The amount of underlying currently owned by the account.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint tokens = pToken.balanceOfUnderlying(msg.caller);

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const tokens = await pToken.methods.balanceOfUnderlying(account).call();

Supply Rate

At any point in time one may query the contract to get the current supply (deposit) rate per block. The supply rate is derived from the borrow rate, reserve factor and the amount of total borrows.

PErc20 / PEther

function supplyRatePerBlock() returns (uint)

RETURN: The current supply rate as an unsigned integer, scaled by 1e18.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint supplyRateMantissa = pToken.supplyRatePerBlock();

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const supplyRate = (await pToken.methods.supplyRatePerBlock().call()) / 1e18;

Total Reserves

Reserves are an accounting entry in each pToken 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.

PErc20 / PEther

function totalReserves() returns (uint)

RETURN: The total amount of reserves held in the pool.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint reserves = pToken.totalReserves();

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const reserves = (await pToken.methods.totalReserves().call());

Reserve Factor

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

PErc20 / PEther

function reserveFactorMantissa() returns (uint)

RETURN: The current reserve factor as an unsigned integer, scaled by 1e18.

Solidity

PErc20 pToken = PToken(0x3FDA...);
uint reserveFactorMantissa = pToken.reserveFactorMantissa();

Web3 1.0

const pToken = PEther.at(0x3FDB...);
const reserveFactor = (await pToken.methods.reserveFactorMantissa().call()) / 1e18;

PreviousGetting Started NextController

Last updated 3 years ago