ERC-6806 ERC-721 holding time tracking

Draft · NFTs & multi-token · created 2023-03-30

A standard that extends ERC-721 so that the current account's holding time for an NFT (non-fungible token) can be queried in seconds.

Why it is needed

The existing ERC-721 standard has no mechanism for recording how long an account has held an NFT. However, this information is essential for services that want to reward long-term holders, unlock special content only for those who have held an NFT past a certain period, or apply different business logic based on holding duration. Without a standard, every project ends up recording holding time differently, and external apps or contracts have to read the data using a different method for each implementation. This proposal adds a single common function to ERC-721 for querying holding time, so that any contract can provide and read holding time information the same way.

What to implement

In depth

The getHoldingInfo function specification

This standard's interface, IERC6806, defines a single function. getHoldingInfo takes tokenId (the NFT's unique identifier) and returns a tuple of the current holder's address (holder) and how long (holdingTime) the current account has held this NFT. Holding time is measured in seconds. The original text cites precision and compatibility with other time-based functions in smart contracts as the reasons for using seconds.

Why holder is returned alongside holding time

getHoldingInfo returns holder along with holdingTime so that implementations can exclude certain token owners, as defined by the implementation, from the holding time calculation. For example, if a contract takes custody of an NFT as loan collateral, excluding that loan contract lets the actual owner's holding time keep increasing without interruption.

How the reference implementation behaves

The reference implementation stores the holder per token (_holder), the holding start time (_holdStart), and a per-address whitelist (_holdingTimeWhitelist). In _afterTokenTransfer, called after a transfer, if either from or to is on the whitelist, nothing happens. Otherwise, if the holder changes, _holder is updated to the new address and _holdStart is updated to the current block.timestamp. getHoldingInfo returns the holding time as block.timestamp minus _holdStart. Whitelist registration is done through the setHoldingTimeWhitelistedAddress function, which is restricted with onlyOwner so only the contract owner can call it.

Compatibility with existing ERC-721

This proposal adds new functions that do not affect core functionality, so it is fully backward compatible with the existing ERC-721 standard. It is an extension that adds functionality for new use cases while maintaining compatibility with already deployed ERC-721 implementations.

Proposal status

This document is a proposal in Draft status, created on March 30, 2023. Its contents may change or progress may stall, so it is advisable to check the latest status before implementing.

Things to watch out for

Original ERC · ← ERCs