Principal Token
The Principal Token is the main contract of Spectra. It is EIP 5095, and 2612 compliant.
Users deposit the IBT (or underlying token of the IBT) and receive the Principal Token (PT) and the Yield Token (YT) in return. For example, user deposits aDAI (or DAI) and receives the PT and YT of the aDAI position with a certain expiry.
The user can also withdraw and redeem after and before expiry. For more information, see the Tokenising Yield guide.
Code for PrincipalToken.sol can be found on GitHub.
Methods
deposit
Deposits the amount of the underlying assets
(e.g. DAI or USDC etc) and mints an amount of shares
(i.e. Principal Tokens) and Yield Tokens for the receiver
.
msg.sender
must approve the relevant allowance of the underlying asset before calling this method.
deposit
must be called before the expiry
of the Principal Token.
assets
uint256
The amount of the underlying assets to deposit.
receiver
address
shares
uint256
deposit
Deposits amount of assets
in the PT vault specifying the PT receiver (ptReceiver
) and the YT receiver (ytReceiver
).
msg.sender
must approve the relevant allowance of the underlying asset before calling this method.
deposit
must be called before the expiry
of the Principal Token.
assets
uint256
The amount of the underlying assets to deposit.
ptReceiver
address
ytReceiver
address
shares
uint256
deposit
Deposits amount of assets
with a lower bound on shares received (minShares
).
msg.sender
must approve the relevant allowance of the underlying asset before calling this method.
deposit
must be called before the expiry
of the Principal Token.
assets
uint256
The amount of the underlying assets to deposit.
ptReceiver
address
ytReceiver
address
minShares
uint256
The minimum amount of shares the caller expect to receive from the posit
shares
uint256
depositIBT
Deposits the ibts
of the Interest Bearing Token (e.g. aDAI or aUSDC etc) and mints an amount of shares
(i.e. Principal Tokens) and Yield Tokens for the receiver
.
msg.sender
must approve the relevant allowance of the IBT before calling this method.
deposit
must be called before the expiry
of the Principal Token.
ibts
uint256
The amount of the PrincipalToken's IBT assets to deposit.
receiver
address
shares
uint256
depositIBT
Deposits the ibts
of the Interest Bearing Token (e.g. aDAI or aUSDC etc) and mints an amount of shares
(i.e. Principal Tokens) for the ptReceiver
and Yield Tokens for the ytReceiver
.
msg.sender
must approve the relevant allowance of the IBT before calling this method.
deposit
must be called before the expiry
of the Principal Token.
ibts
uint256
The amount of the PrincipalToken's IBT assets to deposit.
ptReceiver
address
ytReceiver
address
shares
uint256
depositIBT
Deposits the ibts
of the Interest Bearing Token (e.g. aDAI or aUSDC etc) and mints an amount of shares
(i.e. Principal Tokens) for the ptReceiver
and Yield Tokens for the ytReceiver
.
msg.sender
must approve the relevant allowance of the IBT before calling this method.
deposit
must be called before the expiry
of the Principal Token.
ibts
uint256
The amount of the PrincipalToken's IBT assets to deposit.
ptReceiver
address
ytReceiver
address
minShares
uint256
The minimum amount of shares the caller expect to receive from the posit
shares
uint256
redeem
Redeems (by burning tokens) the amount of shares
(i.e. Principal Tokens) from owner
, redeeming an amount of assets
of the underlying asset.
The first caller to Redeem after expiry will make an implicit call to StoreRatesAtExpiry()
to store the rates after expiry. This is done only once for all.
shares
uint256
receiver
address
owner
address
assets
uint256
Conforms to ERC-5095 standards.
redeem
Redeems (by burning tokens) the amount of shares
(i.e. Principal Tokens) from owner
, redeeming an amount of assets
of the underlying asset, while also specifying the minimum asset (minAssets
) amount that the caller expects the receiver
to receive.
I.e. converts PT to the underlying asset, using the number of PT to burn, after expiry.
The first caller to Redeem after expiry will make an implicit call to StoreRatesAtExpiry()
to store the rates after expiry. This is done only once for all.
shares
uint256
receiver
address
owner
address
minAssets
uint256
The minimum asset amount that the caller expects the receiver
to receive.
assets
uint256
redeemForIBT
Redeems (by burning tokens) the amount of shares
(i.e. Principal Tokens) from owner
, redeeming an amount of ibts
of the IBT.
The first caller to Redeem after expiry will make an implicit call to StoreRatesAtExpiry()
to store the rates after expiry. This is done only once for all.
shares
uint256
receiver
address
The address that will receive the redeemed tokens.
owner
address
ibts
uint256
redeemForIBT
Redeems (by burning tokens) the amount of shares
(i.e. Principal Tokens) from owner
, redeeming an amount of ibts
of the IBT, while also specifying the minimum asset (minIbts
) amount that the caller expects the receiver
to receive.
The first caller to Redeem after expiry will make an implicit call to StoreRatesAtExpiry()
to store the rates after expiry. This is done only once for all.
shares
uint256
receiver
address
The address that will receive the redeemed tokens.
owner
address
minIbts
uint256
The minimum asset amount that the caller expects the receiver
to receive.
ibts
uint256
withdraw
Withdraws the amount of underlying assets
of a position of owner
, withdrawing those assets
to receiver
. This is done by burning shares
(i.e. Principal Tokens) and remaining Yield Tokens of owner
.
assets
uint256
receiver
address
owner
address
shares
uint256
Conforms to ERC-5095 standards.
withdraw
Withdraws the amount of underlying assets
of a position of owner
, withdrawing those assets
to receiver
. This is done by burning shares
(i.e. Principal Tokens) and remaining Yield Tokens of owner
, while specifying the maximum amount (maxShares
) of shares to withdraw.
I.e. converts PT and YT to the underlying asset, using the number of underlying assets to withdraw, before expiry.
assets
uint256
receiver
address
owner
address
maxShares
uint256
The maximum amount of shares allowed to be burnt
shares
uint256
withdrawIBT
Withdraws the amount of IBTs of a position of owner
, withdrawing those ibts
to receiver
. This is done by burning shares
(i.e. Principal Tokens) and remaining Yield Tokens of owner
.
ibts
uint256
receiver
address
The address that will receive the withdrawn tokens.
owner
address
shares
uint256
withdrawIBT
Withdraws the amount of IBTs of a position of owner
, withdrawing those ibts
to receiver
. This is done by burning shares
(i.e. Principal Tokens) and remaining Yield Tokens of owner
, while specifying the maximum amount (maxShares
) of shares to withdraw.
ibts
uint256
receiver
address
The address that will receive the withdrawn tokens.
owner
address
maxShares
uint256
The maximum amount of shares allowed to be burnt
shares
uint256
claimYield
Claims the yield of msg.sender
based on their current balance of YT. Send the yield as underlying tokens.
_receiver
address
The address that will receive the yield.
yieldInAsset
uint256
claimYieldInIBT
Claims the yield of msg.sender
based on their current balance of YT. Send the yield as IBT tokens.
_receiver
address
The address that will receive the yield.
yieldInIBT
uint256
updateYield
Updates _user
yield with the latest yield in IBT generated since the previous update.
This method should not be used by users. This method is called implicitely before each action to deposit, redeem, withdraw and sending receiving YT tokens.
_user
address
The address of the user to compute the yield
updatedUserYieldInRay
uint256
flashLoan
The flashLoan method is used to swap PT for YT tokens by borrowing the IBT of the PT contract to swap PT for YTs.
The transaction reverts if the trade is not profitable and the borrower is unable to repay the loan.
_receiver
IERC3156FlashBorrower
The receiver of the tokens in the loan, and the receiver of the callback.
_token
address
The loan currency.
_amount
uint256
The amount of tokens lent.
_data
bytes calldata
Arbitrary data structure, intended to contain user-defined parameters.
bool
If successful, flashLoan
return true
.
Conforms to EIP-3156 standards.
StoreRatesAtExpiry
Store the rates at the time of expiry.
View Methods
previewDeposit
Calculates the amount of shares
(i.e. Principal Tokens) and Yield Tokens that would be minted for depositing amount of assets.
Only available if position is not expired/reached maturity.
maxDeposit
This function returns the maximum amount of underlying assets that can be deposited in a single deposit
call by the receiver
.
previewDepositIBT
Calculates the amount of shares
(i.e. Principal Tokens) and Yield Tokens that would be minted for depositing amount of ibts.
Only available if position is not expired/reached maturity.
previewWithdraw
Calculates the amount of shares
(i.e. Principal Tokens) that would be burned for withdrawing an amount of assets
.
Conforms to ERC-5095 standards.
previewWithdrawIBT
Calculates the amount of shares
(i.e. Principal Tokens) that would be burned for withdrawing an amount of ibts
.
maxWithdraw
Calculates the maximum amount of underlying assets that can withdrawn by the owner
.
Conforms to ERC-5095 standards.
maxWithdrawIBT
Calculates the maximum amount of IBTs that can withdrawn by the owner
.
previewRedeem
Calculates the amount of assets that would be redeemed for an amount of shares
(i.e. Principal Tokens).
Conforms to ERC-5095 standards.
previewRedeemForIBT
Calculates the amount of IBTs that would be redeemed for an amount of shares
(i.e. Principal Tokens).
maxRedeem
Calculations the maximum amount of shares (i.e. Principal Tokens) that the owner
can currently redeem/burn.
Conforms to ERC-5095 standards.
convertToPrincipal
Calculates the amount of principal tokens that are equivalent to the amount of underlyingAmount
.
Conforms to EIP-5095 standard.
convertToUnderlying
Same as convertToAssets()
.
Conforms to ERC-5095 standard.
underlying
Returns the address of the underlying ERC20 or ERC777 asset.
E.g. if the IBT is aDAI, then the asset is DAI. If the IBT is cUSDC, then the asset is USDC.
Conforms to ERC-5095 standard.
totalAssets
Returns the total balance of the underlying assets in the Principal Token. Useful for TVL calculations.
decimals
Returns the decimals of the IBT.
maturity
Returns the expiry/maturity of the position in unix timestamp, at or after which the Principal Tokens can be redeemed for their underlying asset.
Conforms to ERC-5095 standard.
getDuration
Returns the total duration of the principal token period in seconds.
getIBT
Returns the address of the IBT (Interest Bearing Token).
E.g. if the underlying asset is DAI, the IBT could be aDAI (for Aave deposited DAI) or cDAI (for Compound deposited DAI), etc.
getYT
Returns the address of the YT (Yield Token).
getIBTRate
Returns the ibtRate.
getPTRate
Returns the ptRate.
getIBTUnit
Returns the number used for one unit (10^decimals) of the IBT.
getAssetUnit
Returns the number used for one unit (10^decimals) of the asset.
getIBTRateAtExpiry
Returns the IBT rate at expiry. Only valid after maturity.
getPTRateAtExpiry
Returns the PT rate at expiry. Only valid after maturity.
getCurrentYieldOfUserInIBT
Returns the yield of _user
in IBT tokens.
Internal Methods
_computeYield
Computes the yield generated by a user given old and new rates. For more information, see the Yield Calculations page.
Last updated