ERC-7590 ERC-20 Holding Extension for NFTs (ERC-20 Holder Extension for NFTs)

Review · NFTs & multi-token · created 2024-01-05

An extension standard that allows a single NFT (ERC-721) to receive and hold ERC-20 tokens, letting the NFT owner withdraw and send those tokens.

Why it is needed

An NFT is originally meant to represent only a single unique asset, such as an artwork or game item, and there was no standard way to hold other tokens inside it. As a result, services that need to handle a unique asset bundled together with a fungible token, such as games, had to invent project-specific methods. Additionally, ERC-20 tokens have no standard way to notify the recipient of an incoming transfer, so simply sending tokens to an NFT contract address leaves no way to know which NFT they were intended for. Furthermore, there was no common mechanism to prevent a seller of a token-holding NFT from secretly withdrawing the tokens inside it right before a sale closes. This standard aims to solve these problems by defining common functions for depositing and withdrawing ERC-20 tokens from a specific NFT, along with a counter (nonce) that increments with every withdrawal.

In depth

Why a Pull-Based Deposit Model Was Chosen

Rather than sending tokens directly to the NFT contract, this standard uses a pull model where the NFT contract draws tokens from the caller. There are two reasons for this. First, since the contract initiates the transfer itself, developers can insert desired logic (hooks) before and after the transfer. Second, ERC-20 has no standardized transfer method with a callback, unlike ERC-721's safeTransfer, so there is no reliable way to notify the recipient of a successful transfer or convey which NFT is the destination. The tradeoff of this approach is that the token must first be approved for the NFT contract before depositing.

Rules for the Deposit Function transferERC20ToToken

transferERC20ToToken deposits amount of the token at erc20Contract into the NFT indicated by tokenId. The balance MUST be moved from msg.sender, which requires that this contract be approved to move tokens on that ERC-20 contract beforehand. The data field is unformatted additional data for implementations to attach their own logic. Upon receipt, a ReceivedERC20 event announces which ERC-20 token, from whom, into which NFT, and how much was received.

Rules for the Withdrawal Function transferHeldERC20FromToken

transferHeldERC20FromToken sends amount of the ERC-20 token held by tokenId to the to address. The balance MUST be moved from this contract, the transfer-out-nonce for that tokenId MUST be incremented on every call, and it MUST revert if msg.sender is neither the NFT's owner nor an approved operator. Once the transfer occurs, a TransferredERC20 event is emitted.

erc20TransferOutNonce and Preventing Pre-Sale Withdrawal

erc20TransferOutNonce is a value that increments by 1 each time an ERC-20 token leaves that NFT. It is a mechanism to prevent front-running, where a seller lists an NFT holding tokens on a marketplace and withdraws the tokens inside right before the sale closes. A marketplace should record the nonce at listing time, and MUST revert the transaction if the nonce has changed by the time the sale is executed.

Why a Granular Design by Token Type Was Chosen

During the design process, two approaches were compared: a granular design with separate interfaces per token type, and a universal design covering ERC-721 and ERC-1155 as well. The granular implementation is slightly cheaper in gas and produces a smaller contract when only one or two types are used. The universal design has a smaller overall footprint and only one function each for sending and receiving, but it becomes more complex because it always requires an id, which ERC-20 doesn't need, and an amount, which ERC-721 doesn't need. Also, ERC-721 and ERC-1155 already have receiving interfaces such as safe transfer, IERC721Receiver, and IERC1155Receiver, so an additional interface isn't particularly necessary for them, whereas ERC-20 has no callback to notify the recipient. For these reasons, the granular design was chosen.

A Proposal Still in Review Status

This proposal's status is Review, meaning it is not yet finalized and its content may change. Test code and a reference implementation (ERC7590Mock.sol) are provided alongside the proposal, and it requires ERC-20, ERC-165, and ERC-721. Checking the latest original text before actual adoption is recommended.

Things to watch out for

Original ERC · ← ERCs