Update 14/11/2024 Link to PR on GitHub
Update 18/11/2024 Revised to make it more straightforward design, moving away from a library-based structure
Update 20/11/2024 Update in section Security Considerations
Update 24/11/2024 Update change on Natspec
Update 27/11/2024 Update resolve some comments from EIP Editing Office Hour 47
Update 29/11/2024 Update specification interface and rationale
Update 30/11/2024 Update in section Motivation and fix typo
Simple Summary
An extended interface enables fungible tokens to possess expiration capabilities, allowing them to expire after a predetermined period.
Abstract
Introduces an extension for ERC-20 tokens, which facilitates the implementation of an expiration mechanism. Through this extension, tokens have a predetermined validity period, after which they become invalid and can no longer be transferred or used. This functionality proves beneficial in scenarios such as time-limited bonds, loyalty rewards, or game tokens necessitating automatic invalidation after a specific duration. The extension is crafted to seamlessly align with the existing ERC-20 standard, ensuring smooth integration with the prevailing token smart contract while introducing the capability to govern and enforce token expiration at the contract level.
Motivation
This extension facilitates the development of ERC-20 standard compatible tokens featuring expiration dates. This capability broadens the scope of potential applications, particularly those involving time-sensitive assets. Expirable tokens are well-suited for scenarios necessitating temporary validity, including
- Bonds or financial instruments with defined maturity dates
- Time-constrained assets within gaming ecosystems
- Next-gen loyalty programs incorporating expiring rewards or points
- Prepaid credits for utilities or services (e.g., cashback, data packages, fuel, computing resources) that expire if not used within a specified time frame
- Postpaid telecom data package allocations that expire at the end of the billing cycle, motivating users to utilize their data before it resets
- Tokenized e-Money for a closed-loop ecosystem, such as transportation, food court, and retail payments
- Insurance claim credits, which are time-sensitive credits issued to policyholders that can be used to offset deductibles or excess charges, and expire after a defined period (e.g., 6 months)
Specification
Epoch Mechanism
Epochs represent a specific period or block range during which certain tokens are valid. They can be categorized into two types
- block-based Defined by a specific number of blocks (e.g., 1000
blocks). - time-based Defined by a specific duration in seconds (e.g., 1000
seconds).
Tokens linked to an epoch remain valid as long as the epoch is active. Once the specified number of blocks or the duration in seconds has passed, the epoch expires, and any tokens associated with it are considered expired.
Balance Look Back Over Epochs
To retrieve the usable balance, tokens are checked from the current epoch against a past epoch (which can be any n epochs back). The past epoch can be set to any value n, allowing flexibility in tracking and summing tokens that are still valid from previous epochs, up to n epochs back.
The usable balance is the sum of tokens valid between the current epoch and the past epoch, ensuring that only non-expired tokens are considered.
Example Scenario
| epoch | balance |
|---|---|
| 1 | 100 |
| 2 | 150 |
| 3 | 200 |
- Current Epoch: 3
- Past Epoch: 1 epoch back
- Usable Balance: 350
Tokens from Epoch 2 and Epoch 3 are valid. The same logic applies for any n epochs back, where the usable balance includes tokens from the current epoch and all prior valid epochs.
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
Compatible implementations MUST inherit from ERC-20’s interface and MUST have all the following functions and all function behavior MUST meet the specification.
// SPDX-License-Identifier: CC0-1.0
pragma solidity >=0.8.0 <0.9.0;
/**
* @title ERC-7818 interface
* @dev Interface for adding expirable functionality to ERC20 tokens.
*/
import "./IERC20.sol";
interface IERC7818 is IERC20 {
/**
* @dev Enum represents the types of `epoch` that can be used.
* @notice The implementing contract may use one of these types to define how the `epoch` is measured.
*/
enum EPOCH_TYPE {
BLOCKS_BASED, // measured in the number of blocks (e.g., 1000 blocks)
TIME_BASED // measured in seconds (UNIX time) (e.g., 1000 seconds)
}
/**
* @dev Retrieves the balance of a specific `epoch` owned by an account.
* @param account The address of the account.
* @param epoch The `epoch for which the balance is checked.
* @return uint256 The balance of the specified `epoch`.
* @notice "MUST" return 0 if the specified `epoch` is expired.
*/
function balanceOfAtEpoch(
address account,
uint256 epoch
) external view returns (uint256);
/**
* @dev Retrieves the latest epoch currently tracked by the contract.
* @return uint256 The latest epoch of the contract.
*/
function currentEpoch() external view returns (uint256);
/**
* @dev Retrieves the duration of a single epoch.
* @return uint256 The duration of a single epoch.
* @notice The unit of the epoch length is determined by the `validityPeriodType()` function.
*/
function epochLength() external view returns (uint256);
/**
* @dev Returns the type of the epoch.
* @return EPOCH_TYPE Enum value indicating the unit of epoch.
*/
function epochType() external view returns (EPOCH_TYPE);
/**
* @dev Checks whether a specific `epoch` is expired.
* @param epoch The `epoch` to check.
* @return bool True if the token is expired, false otherwise.
* @notice Implementing contracts "MUST" define and document the logic for determining expiration,
* typically by comparing the latest epoch with the given `epoch` value,
* based on the `EPOCH_TYPE` measurement (e.g., block count or time duration).
*/
function isEpochExpired(uint256 epoch) external view returns (bool);
/**
* @dev Transfers a specific `epoch` and value to a recipient.
* @param to The recipient address.
* @param epoch The `epoch` for the transfer.
* @param value The amount to transfer.
* @return bool True if the transfer succeeded, otherwise false.
*/
function transferAtEpoch(
address to,
uint256 epoch,
uint256 value
) external returns (bool);
/**
* @dev Transfers a specific `epoch` and value from one account to another.
* @param from The sender's address.
* @param to The recipient's address.
* @param epoch The `epoch` for the transfer.
* @param value The amount to transfer.
* @return bool True if the transfer succeeded, otherwise false.
*/
function transferFromAtEpoch(
address from,
address to,
uint256 epoch,
uint256 value
) external returns (bool);
}
Behavior specification
balanceOfMUST return the total balance of tokens held by an account that are still valid (i.e., have not expired). This includes any tokens associated with specific epochs, provided they remain within their validity duration. Expired tokens MUST NOT be included in the returned balance, ensuring that only actively usable tokens are reflected in the result.balanceOfEpochreturns the balance of tokens held by an account at the specifiedepoch, If the specified epoch is expired, this function MUST return0.
For example, ifepoch5 has expired, callingbalanceOfByEpoch(address, 5)MUST return0even if there were tokens previously held in that epoch."transferandtransferFromMUST exclusively transfer tokens that remain non-expired at the time of the transaction. Attempting to transfer expired tokens MUST revert the transaction or return false. Additionally, implementations MAY include logic to prioritize the automatic transfer of tokens closest to expiration, ensuring that the earliest expiring tokens are used first, provided they meet the non-expired condition.transferByEpochandtransferFromByEpochMUST transfer the specified number of tokens held by an account at the specified epoch to the recipient, If the epoch has expired, the transaction MUSTrevertor returnfalsetotalSupplySHOULD be set to0ortype(uint256).maxdue to the challenges of tracking only valid (non-expired) tokens.- The implementation MAY use a standardized custom error, such as
ERC7818TransferredExpiredTokenorERC7818TransferredExpiredToken(address sender, uint256 epoch), to clearly indicate that the operation failed due to attempting to transfer expired tokens.
Aditional Potential Useful Function
These OPTIONAL functions provide additional functionality that might be useful depending on the specific use case.
epochInforeturns both the start and end of the specifiedepoch.remainingDurationBeforeEpochChangereturns the remaining time or blocks before the epoch change happens, based on the epoch type.
Rationale
Epochs for Flexible
Although the term epoch is an abstract concept, it leaves room for various implementations. For example, epochs can support more granular tracking of tokens within each epoch, allowing for greater control over when tokens are valid or expired on-chain. Alternatively, epochs can support bulk expiration, where all tokens within the same epoch expire simultaneously. This flexibility enables different methods of tracking token expiration, depending on the specific needs of the use case.
epoch also introduces a “lazy” way to simplify token expiration tracking in a flexible and gas-efficient manner. Instead of continuously updating the expiration state with write operations by the user or additional services, the current epoch can be calculated using a read operation.
Reference Implementation
For reference implementation can be found here, But in the reference implementation, we employ a sorted list to automatically select the token that nearest expires first with a First-In-First-Out (FIFO) and sliding window algorithm that operates based on the block.number as opposed to relying on block.timestamp, which has been criticized for its lack of security and resilience, particularly given the increasing usage of Layer 2 (L2) networks over Layer 1 (L1) networks. Many L2 networks exhibit centralization and instability, which directly impacts asset integrity, rendering them potentially unusable during periods of network halting, as they are still reliant on the timestamp.
Security Considerations
Denial Of Service
Run out of gas problem due to the operation consuming higher gas if transferring multiple groups of small tokens or loop transfer.
Gas Limit Vulnerabilities
Exceeds block gas limit if the blockchain has a block gas limit lower than the gas used in the transaction.
Block values as a proxy for time
if using block.timestamp for calculating epoch() and In rare network halts, block production stops, freezing block.timestamp and disrupting time-based logic. This risks asset integrity and inconsistent states.
Fairness Concerns
In a straightforward implementation, where all tokens within the same epoch share the same expiration (e.g., at epoch:x), bulk expiration occurs.
Risks in Liquidity Pools
When tokens with expiration dates are deposited into liquidity pools (e.g., in DEXs), they may expire while still in the pool.