ERC-5095: Principal Token

Principal tokens (zero-coupon tokens) are redeemable for a single underlying EIP-20 token at a future timestamp.


Metadata
Status: StagnantStandards Track: ERCCreated: 2022-05-01
Authors
Julian Traversa (@JTraversa), Robert Robbins (@robrobbins), Alberto Cuesta Cañada (@alcueca)
Requires

Abstract


Principal tokens represent ownership of an underlying EIP-20 token at a future timestamp.

This specification is an extension on the EIP-20 token that provides basic functionality for depositing and withdrawing tokens and reading balances and the EIP-2612 specification that provides EIP-712 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 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 operations balanceOf, transfer, totalSupply, etc. operate on the Principal Token balance.

All Principal Tokens MUST implement EIP-20'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 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 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.


maturity

The unix timestamp (uint256) at or after which Principal Tokens can be redeemed for their underlying deposit.

MUST NOT revert.


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.


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.


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.


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.


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.


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.


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.


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 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.


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.


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 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 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 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 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 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



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.