PaganoBarserker
/
DCIPs
forked from DecentralizedClimateFoundation/DCIPs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
DCIPs/EIPS/eip-5095.md

552 lines
23 KiB
Markdown
Raw Normal View History

Adding EIPs website fork with some Gem Updates
2023-04-05 16:02:54 +00:00
---
eip: 5095
title: Principal Token
description: Principal tokens (zero-coupon tokens) are redeemable for a single underlying EIP-20 token at a future timestamp.
author: Julian Traversa (@JTraversa), Robert Robbins (@robrobbins), Alberto Cuesta Cañada (@alcueca)
discussions-to: https://ethereum-magicians.org/t/eip-5095-principal-token-standard/9259
status: Stagnant
type: Standards Track
category: ERC
created: 2022-05-01
requires: 20, 2612
---
## Abstract
Principal tokens represent ownership of an underlying [EIP-20](./eip-20.md) token at a future timestamp.
This specification is an extension on the [EIP-20](./eip-20.md) token that provides basic functionality for depositing
and withdrawing tokens and reading balances and the [EIP-2612](./eip-2612.md) specification that provides
[EIP-712](./eip-712.md) signature based approvals.
## Motivation
Principal tokens lack standardization which has led to a difficult to navigate development space and diverse implementation
schemes.
The primary examples include yield tokenization platforms which strip future yield leaving a principal
token behind, as well as fixed-rate money-markets which utilize principal tokens as a medium
to lend/borrow.
This inconsistency in implementation makes integration difficult at the application layer as well as
wallet layer which are key catalysts for the space's growth.
Developers are currently expected to implement individual adapters for each principal token, as well as adapters for
their pool contracts, and many times adapters for their custodial contracts as well, wasting significant developer resources.
## Specification
All Principal Tokens (PTs) MUST implement [EIP-20](./eip-20.md) to represent ownership of future underlying redemption.
If a PT is to be non-transferrable, it MAY revert on calls to `transfer` or `transferFrom`.
The [EIP-20](./eip-20.md) operations `balanceOf`, `transfer`, `totalSupply`, etc. operate on the Principal Token balance.
All Principal Tokens MUST implement [EIP-20](./eip-20.md)'s optional metadata extensions.
The `name` and `symbol` functions SHOULD reflect the underlying token's `name` and `symbol` in some way, as well as the origination protocol, and in the case of yield tokenization protocols, the origination money-market.
All Principal Tokens MAY implement [EIP-2612](./eip-2612.md) to improve the UX of approving PTs on various integrations.
### Definitions:
- underlying: The token that Principal Tokens are redeemable for at maturity.
Has units defined by the corresponding [EIP-20](./eip-20.md) contract.
- maturity: The timestamp (unix) at which a Principal Token matures. Principal Tokens become redeemable for underlying at or after this timestamp.
- fee: An amount of underlying or Principal Token charged to the user by the Principal Token. Fees can exist on redemption or post-maturity yield.
- slippage: Any difference between advertised redemption value and economic realities of PT redemption, which is not accounted by fees.
### Methods
#### `underlying`
The address of the underlying token used by the Principal Token for accounting, and redeeming.
MUST be an EIP-20 token contract.
MUST _NOT_ revert.
```yaml
- name: underlying
type: function
stateMutability: view
inputs: []
outputs:
- name: underlyingAddress
type: address
```
#### `maturity`
The unix timestamp (uint256) at or after which Principal Tokens can be redeemed for their underlying deposit.
MUST _NOT_ revert.
```yaml
- name: maturity
type: function
stateMutability: view
inputs: []
outputs:
- name: timestamp
type: uint256
```
#### `convertToUnderlying`
The amount of underlying that would be exchanged for the amount of PTs provided, in an ideal scenario where all the conditions are met.
Before maturity, the amount of underlying returned is as if the PTs would be at maturity.
MUST NOT be inclusive of any fees that are charged against redemptions.
MUST NOT show any variations depending on the caller.
MUST NOT reflect slippage or other on-chain conditions, when performing the actual redemption.
MUST NOT revert unless due to integer overflow caused by an unreasonably large input.
MUST round down towards 0.
This calculation MAY NOT reflect the "per-user" price-per-principal-token, and instead should reflect the "average-user's" price-per-principal-token, meaning what the average user should expect to see when exchanging to and from.
```yaml
- name: convertToUnderlying
type: function
stateMutability: view
inputs:
- name: principalAmount
type: uint256
outputs:
- name: underlyingAmount
type: uint256
```
#### `convertToPrincipal`
The amount of principal tokens that the principal token contract would request for redemption in order to provide the amount of underlying specified, in an ideal scenario where all the conditions are met.
MUST NOT be inclusive of any fees.
MUST NOT show any variations depending on the caller.
MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.
MUST NOT revert unless due to integer overflow caused by an unreasonably large input.
MUST round down towards 0.
This calculation MAY NOT reflect the "per-user" price-per-principal-token, and instead should reflect the "average-user's" price-per-principal-token, meaning what the average user should expect to see when redeeming.
```yaml
- name: convertToPrincipal
type: function
stateMutability: view
inputs:
- name: underlyingAmount
type: uint256
outputs:
- name: principalAmount
type: uint256
```
#### `maxRedeem`
Maximum amount of principal tokens that can be redeemed from the `holder` balance, through a `redeem` call.
MUST return the maximum amount of principal tokens that could be transferred from `holder` through `redeem` and not cause a revert, which MUST NOT be higher than the actual maximum that would be accepted (it should underestimate if necessary).
MUST factor in both global and user-specific limits, like if redemption is entirely disabled (even temporarily) it MUST return 0.
MUST NOT revert.
```yaml
- name: maxRedeem
type: function
stateMutability: view
inputs:
- name: holder
type: address
outputs:
- name: maxPrincipalAmount
type: uint256
```
#### `previewRedeem`
Allows an on-chain or off-chain user to simulate the effects of their redeemption at the current block, given current on-chain conditions.
MUST return as close to and no more than the exact amount of underliyng that would be obtained in a `redeem` call in the same transaction. I.e. `redeem` should return the same or more `underlyingAmount` as `previewRedeem` if called in the same transaction.
MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the redemption would be accepted, regardless if the user has enough principal tokens, etc.
MUST be inclusive of redemption fees. Integrators should be aware of the existence of redemption fees.
MUST NOT revert due to principal token contract specific user/global limits. MAY revert due to other conditions that would also cause `redeem` to revert.
Note that any unfavorable discrepancy between `convertToUnderlying` and `previewRedeem` SHOULD be considered slippage in price-per-principal-token or some other type of condition.
```yaml
- name: previewRedeem
type: function
stateMutability: view
inputs:
- name: principalAmount
type: uint256
outputs:
- name: underlyingAmount
type: uint256
```
#### `redeem`
At or after maturity, burns exactly `principalAmount` of Principal Tokens from `from` and sends `underlyingAmount` of underlying tokens to `to`.
Interfaces and other contracts MUST NOT expect fund custody to be present. While custodial redemption of Principal Tokens through the Principal Token contract is extremely useful for integrators, some protocols may find giving the Principal Token itself custody breaks their backwards compatibility.
MUST emit the `Redeem` event.
MUST support a redeem flow where the Principal Tokens are burned from `holder` directly where `holder` is `msg.sender` or `msg.sender` has EIP-20 approval over the principal tokens of `holder`.
MAY support an additional flow in which the principal tokens are transferred to the Principal Token contract before the `redeem` execution, and are accounted for during `redeem`.
MUST revert if all of `principalAmount` cannot be redeemed (due to withdrawal limit being reached, slippage, the holder not having enough Principal Tokens, etc).
Note that some implementations will require pre-requesting to the Principal Token before a withdrawal may be performed. Those methods should be performed separately.
```yaml
- name: redeem
type: function
stateMutability: nonpayable
inputs:
- name: principalAmount
type: uint256
- name: to
type: address
- name: from
type: address
outputs:
- name: underlyingAmount
type: uint256
```
#### `maxWithdraw`
Maximum amount of the underlying asset that can be redeemed from the `holder` principal token balance, through a `withdraw` call.
MUST return the maximum amount of underlying tokens that could be redeemed from `holder` through `withdraw` and not cause a revert, which MUST NOT be higher than the actual maximum that would be accepted (it should underestimate if necessary).
MUST factor in both global and user-specific limits, like if withdrawals are entirely disabled (even temporarily) it MUST return 0.
MUST NOT revert.
```yaml
- name: maxWithdraw
type: function
stateMutability: view
inputs:
- name: holder
type: address
outputs:
- name: maxUnderlyingAmount
type: uint256
```
#### `previewWithdraw`
Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block, given current on-chain conditions.
MUST return as close to and no fewer than the exact amount of principal tokens that would be burned in a `withdraw` call in the same transaction. I.e. `withdraw` should return the same or fewer `principalAmount` as `previewWithdraw` if called in the same transaction.
MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though the withdrawal would be accepted, regardless if the user has enough principal tokens, etc.
MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.
MUST NOT revert due to principal token contract specific user/global limits. MAY revert due to other conditions that would also cause `withdraw` to revert.
Note that any unfavorable discrepancy between `convertToPrincipal` and `previewWithdraw` SHOULD be considered slippage in price-per-principal-token or some other type of condition.
```yaml
- name: previewWithdraw
type: function
stateMutability: view
inputs:
- name: underlyingAmount
type: uint256
outputs:
- name: principalAmount
type: uint256
```
#### `withdraw`
Burns `principalAmount` from `holder` and sends exactly `underlyingAmount` of underlying tokens to `receiver`.
MUST emit the `Redeem` event.
MUST support a withdraw flow where the principal tokens are burned from `holder` directly where `holder` is `msg.sender` or `msg.sender` has [EIP-20](./eip-20.md) approval over the principal tokens of `holder`.
MAY support an additional flow in which the principal tokens are transferred to the principal token contract before the `withdraw` execution, and are accounted for during `withdraw`.
MUST revert if all of `underlyingAmount` cannot be withdrawn (due to withdrawal limit being reached, slippage, the holder not having enough principal tokens, etc).
Note that some implementations will require pre-requesting to the principal token contract before a withdrawal may be performed. Those methods should be performed separately.
```yaml
- name: withdraw
type: function
stateMutability: nonpayable
inputs:
- name: underlyingAmount
type: uint256
- name: receiver
type: address
- name: holder
type: address
outputs:
- name: principalAmount
type: uint256
```
### Events
#### Redeem
`from` has exchanged `principalAmount` of Principal Tokens for `underlyingAmount` of underlying, and transferred that underlying to `to`.
MUST be emitted when Principal Tokens are burnt and underlying is withdrawn from the contract in the `EIP5095.redeem` method.
```yaml
- name: Redeem
type: event
inputs:
- name: from
indexed: true
type: address
- name: to
indexed: true
type: address
- name: amount
indexed: false
type: uint256
```
## Rationale
The Principal Token interface is designed to be optimized for integrators with a core minimal interface alongside optional interfaces to enable backwards compatibility. Details such as accounting and management of underlying are intentionally not specified, as Principal Tokens are expected to be treated as black boxes on-chain and inspected off-chain before use.
[EIP-20](./eip-20.md) is enforced as implementation details such as token approval and balance calculation directly carry over. This standardization makes Principal Tokens immediately compatible with all [EIP-20](./eip-20.md) use cases in addition to EIP-5095.
All principal tokens are redeemable upon maturity, with the only variance being whether further yield is generated post-maturity. Given the ubiquity of redemption, the presence of `redeem` allows integrators to purchase Principal Tokens on an open market, and them later redeem them for a fixed-yield solely knowing the address of the Principal Token itself.
This EIP draws heavily on the design of [EIP-4626](./eip-4626.md) because technically Principal Tokens could be described as a subset of Yield Bearing Vaults, extended with a `maturity` variable and restrictions on the implementation. However, extending [EIP-4626](./eip-4626.md) would force PT implementations to include methods (namely, `mint` and `deposit`) that are not necessary to the business case that PTs solve. It can also be argued that partial redemptions (implemented via `withdraw`) are rare for PTs.
PTs mature at a precise second, but given the reactive nature of smart contracts, there can't be an event marking maturity, because there is no guarantee of any activity at or after maturity. Emitting an event to notify of maturity in the first transaction after maturity would be imprecise and expensive. Instead, integrators are recommended to either use the first `Redeem` event, or to track themselves when each PT is expected to have matured.
## Backwards Compatibility
This EIP is fully backward compatible with the [EIP-20](./eip-20.md) specification and has no known compatibility issues with other standards.
For production implementations of Principal Tokens which do not use EIP-5095, wrapper adapters can be developed and used, or wrapped tokens can be implemented.
## Reference Implementation
```
// SPDX-License-Identifier: MIT
pragma solidity 0.8.14;
import {ERC20} from "yield-utils-v2/contracts/token/ERC20.sol";
import {MinimalTransferHelper} from "yield-utils-v2/contracts/token/MinimalTransferHelper.sol";
contract ERC5095 is ERC20 {
using MinimalTransferHelper for ERC20;
/* EVENTS
*****************************************************************************************************************/
event Redeem(address indexed from, address indexed to, uint256 underlyingAmount);
/* MODIFIERS
*****************************************************************************************************************/
/// @notice A modifier that ensures the current block timestamp is at or after maturity.
modifier afterMaturity() virtual {
require(block.timestamp >= maturity, "BEFORE_MATURITY");
_;
}
/* IMMUTABLES
*****************************************************************************************************************/
ERC20 public immutable underlying;
uint256 public immutable maturity;
/* CONSTRUCTOR
*****************************************************************************************************************/
constructor(
string memory name_,
string memory symbol_,
uint8 decimals_,
ERC20 underlying_,
uint256 maturity_
) ERC20(name_, symbol_, decimals_) {
underlying = underlying_;
maturity = maturity_;
}
/* CORE FUNCTIONS
*****************************************************************************************************************/
/// @notice Burns an exact amount of principal tokens in exchange for an amount of underlying.
/// @dev This reverts if before maturity.
/// @param principalAmount The exact amount of principal tokens to be burned.
/// @param from The owner of the principal tokens to be redeemed. If not msg.sender then must have prior approval.
/// @param to The address to send the underlying tokens.
/// @return underlyingAmount The total amount of underlying tokens sent.
function redeem(
uint256 principalAmount,
address from,
address to
) public virtual afterMaturity returns (uint256 underlyingAmount) {
_decreaseAllowance(from, principalAmount);
// Check for rounding error since we round down in previewRedeem.
require((underlyingAmount = _previewRedeem(principalAmount)) != 0, "ZERO_ASSETS");
_burn(from, principalAmount);
emit Redeem(from, to, principalAmount);
_transferOut(to, underlyingAmount);
}
/// @notice Burns a calculated amount of principal tokens in exchange for an exact amount of underlying.
/// @dev This reverts if before maturity.
/// @param underlyingAmount The exact amount of underlying tokens to be received.
/// @param from The owner of the principal tokens to be redeemed. If not msg.sender then must have prior approval.
/// @param to The address to send the underlying tokens.
/// @return principalAmount The total amount of underlying tokens redeemed.
function withdraw(
uint256 underlyingAmount,
address from,
address to
) public virtual afterMaturity returns (uint256 principalAmount) {
principalAmount = _previewWithdraw(underlyingAmount); // No need to check for rounding error, previewWithdraw rounds up.
_decreaseAllowance(from, principalAmount);
_burn(from, principalAmount);
emit Redeem(from, to, principalAmount);
_transferOut(to, underlyingAmount);
}
/// @notice An internal, overridable transfer function.
/// @dev Reverts on failed transfer.
/// @param to The recipient of the transfer.
/// @param amount The amount of the transfer.
function _transferOut(address to, uint256 amount) internal virtual {
underlying.safeTransfer(to, amount);
}
/* ACCOUNTING FUNCTIONS
*****************************************************************************************************************/
/// @notice Calculates the amount of underlying tokens that would be exchanged for a given amount of principal tokens.
/// @dev Before maturity, it converts to underlying as if at maturity.
/// @param principalAmount The amount principal on which to calculate conversion.
/// @return underlyingAmount The total amount of underlying that would be received for the given principal amount..
function convertToUnderlying(uint256 principalAmount) external view returns (uint256 underlyingAmount) {
return _convertToUnderlying(principalAmount);
}
function _convertToUnderlying(uint256 principalAmount) internal view virtual returns (uint256 underlyingAmount) {
return principalAmount;
}
/// @notice Converts a given amount of underlying tokens to principal exclusive of fees.
/// @dev Before maturity, it converts to principal as if at maturity.
/// @param underlyingAmount The total amount of underlying on which to calculate the conversion.
/// @return principalAmount The amount principal tokens required to provide the given amount of underlying.
function convertToPrincipal(uint256 underlyingAmount) external view returns (uint256 principalAmount) {
return _convertToPrincipal(underlyingAmount);
}
function _convertToPrincipal(uint256 underlyingAmount) internal view virtual returns (uint256 principalAmount) {
return underlyingAmount;
}
/// @notice Allows user to simulate redemption of a given amount of principal tokens, inclusive of fees and other
/// current block conditions.
/// @dev This reverts if before maturity.
/// @param principalAmount The amount of principal that would be redeemed.
/// @return underlyingAmount The amount of underlying that would be received.
function previewRedeem(uint256 principalAmount) external view afterMaturity returns (uint256 underlyingAmount) {
return _previewRedeem(principalAmount);
}
function _previewRedeem(uint256 principalAmount) internal view virtual returns (uint256 underlyingAmount) {
return _convertToUnderlying(principalAmount); // should include fees/slippage
}
/// @notice Calculates the maximum amount of principal tokens that an owner could redeem.
/// @dev This returns 0 if before maturity.
/// @param owner The address for which the redemption is being calculated.
/// @return maxPrincipalAmount The maximum amount of principal tokens that can be redeemed by the given owner.
function maxRedeem(address owner) public view returns (uint256 maxPrincipalAmount) {
return block.timestamp >= maturity ? _balanceOf[owner] : 0;
}
/// @notice Allows user to simulate withdraw of a given amount of underlying tokens.
/// @dev This reverts if before maturity.
/// @param underlyingAmount The amount of underlying tokens that would be withdrawn.
/// @return principalAmount The amount of principal tokens that would be redeemed.
function previewWithdraw(uint256 underlyingAmount) external view afterMaturity returns (uint256 principalAmount) {
return _previewWithdraw(underlyingAmount);
}
function _previewWithdraw(uint256 underlyingAmount) internal view virtual returns (uint256 principalAmount) {
return _convertToPrincipal(underlyingAmount); // should include fees/slippage
}
/// @notice Calculates the maximum amount of underlying tokens that can be withdrawn by a given owner.
/// @dev This returns 0 if before maturity.
/// @param owner The address for which the withdraw is being calculated.
/// @return maxUnderlyingAmount The maximum amount of underlying tokens that can be withdrawn by a given owner.
function maxWithdraw(address owner) public view returns (uint256 maxUnderlyingAmount) {
return _previewWithdraw(maxRedeem(owner));
}
}
```
## Security Considerations
Fully permissionless use cases could fall prey to malicious implementations which only conform to the interface in this EIP but not the specification, failing to implement proper custodial functionality but offering the ability to purchase Principal Tokens through secondary markets.
It is recommended that all integrators review each implementation for potential ways of losing user deposits before integrating.
The `convertToUnderlying` method is an estimate useful for display purposes,
and do _not_ have to confer the _exact_ amount of underlying assets their context suggests.
As is common across many standards, it is strongly recommended to mirror the underlying token's `decimals` if at all possible, to eliminate possible sources of confusion and simplify integration across front-ends and for other off-chain users.
## Copyright
Copyright and related rights waived via [CC0](../LICENSE.md).