ERC-7631: Dual Nature Token Pair

A specification for a co-joined fungible and non-fungible token pair

Abstract

A fungible ERC-20 token contract and non-fungible ERC-721 token contract can be interlinked, allowing actions performed on one contract to be reflected on the other. This proposal defines how the relationship between the two token contracts can be queried. It also enables accounts to configure whether ERC-721 mints and transfers should be skipped during ERC-20 to ERC-721 synchronization.

Motivation

The ERC-20 fungible and ERC-721 non-fungible token standards offer sufficient flexibility for a co-joined, dual nature token pair. Transfers on the ERC-20 token can automatically trigger transfers on the ERC-721 token, and vice-versa. This enables applications such as native ERC-721 fractionalization, wherein acquiring ERC-20 tokens leads to the automatic issuance of ERC-721 tokens, proportional to the ERC-20 balance.

Dual nature token pairs maintain full compliance with both ERC-20 and ERC-721 token standards. This proposal aims to enhance the functionality of dual nature token pairs.

To facilitate querying the relationship between the tokens, extension interfaces are proposed for the ERC-20 and ERC-721 tokens respectively. This enables various quality of life improvements such as allowing decentralized exchanges and NFT marketplaces to display the relationship between the tokens.

Additionally, users can configure whether they want to skip ERC-721 mints and transfers during ERC-20 to ERC-721 synchronization.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Overview

A dual nature token pair comprises of an ERC-20 contract and an ERC-721 contract.

For convention, the ERC-20 contract is designated as the base contract, and the ERC-721 contract is designated as the mirror contract.

ERC-20 Extension Interface

The ERC-20 contract MUST implement the following interface.

interface IERC7631Base {
    /// @dev Returns the address of the mirror ERC-721 contract.
    ///
    /// This method MAY revert or return the zero address
    /// to denote that a mirror ERC-721 contract has not been linked.
    ///
    /// If a non-zero address is returned, the returned address MUST
    /// implement `IERC7631Mirror` and its `baseERC20()` method MUST
    /// return the address of this contract.
    ///
    /// Once a non-zero address has been returned, this method
    /// MUST NOT revert and the returned value MUST NOT change.
    function mirrorERC721() external view returns (address);
}

The ERC-20 contract MAY implement the following interface.

interface IERC7631BaseNFTSkippable {
    /// @dev Implementations SHOULD emit this event when the skip NFT status
    /// of `owner` is updated to `status`.
    ///
    /// The purpose of this event is to signal to indexers that the
    /// skip NFT status has been changed.
    ///
    /// For simplicity of implementation,
    /// this event MAY be emitted even if the status is unchanged.
    event SkipNFTSet(address indexed owner, bool status);

    /// @dev Returns true if ERC-721 mints and transfers to `owner` SHOULD be
    /// skipped during ERC-20 to ERC-721 synchronization.
    /// Otherwise, returns false.
    /// 
    /// This method MAY revert
    /// (e.g. contract not initialized, method not supported).
    ///
    /// If this method reverts:
    /// - Interacting code SHOULD interpret `setSkipNFT` functionality as
    ///   unavailable and hide any functionality to call `setSkipNFT`.
    /// - The skip NFT status for `owner` SHOULD be interpreted as undefined.
    ///
    /// Once a true or false value has been returned for a given `owner`,
    /// this method MUST NOT revert for the given `owner`.
    function getSkipNFT(address owner) external view returns (bool);

    /// @dev Sets the caller's skip NFT status.
    ///
    /// This method MAY revert
    /// (e.g. insufficient permissions, method not supported).
    ///
    /// It is RECOMMENDED to keep this method permissionless.
    ///
    /// Emits a {SkipNFTSet} event.
    function setSkipNFT(bool status) external;
}

ERC-721 Extension Interface

The ERC-721 contract MUST implement the following interface.

interface IERC7631Mirror {
    /// @dev Returns the address of the base ERC-20 contract.
    ///
    /// This method MAY revert or return the zero address
    /// to denote that a base ERC-20 contract has not been linked.
    ///
    /// If a non-zero address is returned, the returned address MUST
    /// implement `IERC7631Base` and its `mirrorERC721()` method MUST
    /// return the address of this contract.
    ///
    /// Once a non-zero address has been returned, this method
    /// MUST NOT revert and the returned value MUST NOT change.
    function baseERC20() external view returns (address);
}

Rationale

Implementation Detection

The mirrorERC721 and baseERC20 methods returning non-zero addresses signal that the ERC-20 and ERC-721 contracts implement the required interfaces respectively. As such, ERC-165 is not required.

The getSkipNFT and setSkipNFT methods MAY revert. As contracts compiled with Solidity or Vyper inherently revert on calls to undefined methods, a typical IERC7631Base implementation lacking explicit getSkipNFT and setSkipNFT definitions still complies with IERC7631BaseNFTSkippable.

NFT Skipping

The skip NFT methods allow accounts to avoid having ERC-721 tokens automatically minted to it whenever there is an ERC-20 transfer.

They are helpful in the following situations:

• Loading vesting contracts with large amounts ERC-20 tokens to be vested to many users.
• Loading candy machine contracts with large amounts of ERC-20 tokens to sell ERC-721 tokens to customers.
• Transferring large amounts of ERC-20 tokens in / out of a liquidity pool.
• Transferring large amounts of ERC-20 tokens between admin accounts.

Including the skip NFT methods in the standard will:

• Enable applications to conveniently display the option for users to skip NFTs.
• Enable applications to transfer any amount of ERC-20 tokens without the O(n) gas costs associated with minting multiple ERC-721 tokens, which can surpass the block gas limit.

These methods are recommended even on EVM chains with low gas costs, because bulk automatic ERC-721 transfers can still surpass the block gas limit.

A useful pattern is to make getSkipNFT return true by default if owner is a smart contract.

The choice of getSkipNFT returning a boolean value is for simplicity. If more complex behavior is needed, developers may add in extra methods of their own.

Implementation Conventions

The ERC-20 contract is designated as the base contract for convention, as a typical implementation can conveniently derive ERC-721 balances from the ERC-20 balances. This does not prohibit one from implementing most of the logic in the ERC-721 contract if required.

This proposal does not cover the token synchronization logic. This is to leave flexibility for various implementation patterns and novel use cases (e.g. automatically rebased tokens).

Linking Mechanism

The linking process is omitted for flexibility purposes. Developers can use any desired mechanism (e.g. linking in constructor, initializer, or via custom admin-only public methods on the two contracts). The only restriction is that the pairing must be immutable once established (to simplify indexing logic).

Backwards Compatibility

No backward compatibility issues found.

Security Considerations

Synchronization Access Guards

External methods for synchronization logic must be guarded such that only the other contract is authorized to call them.

Rare NFT Sniping

For dual nature collections that offer ERC-721 tokens with differing rarity levels, the ERC-721 metadata should be revealed in a way that is not easily gameable with metadata scraping and ERC-20 token transfers. A recommendation is to require that an ERC-721 token is held by the same account for some time before revealing its metadata.

Out-of-gas Denial of Service

Transferring ERC-20 tokens can automatically initiate the minting, transferring, or burning of multiple ERC-721 tokens. This can incur O(n) gas costs instead of the typical O(1) gas costs for ERC-20 tokens transfers. Logic for selecting ERC-721 token IDs can also incur additional gas costs. Synchronization logic must consider ERC-721 related gas costs to prevent out-of-gas denial of service issues.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

vectorized (@vectorized), Thomas (@0xth0mas), Quit (@quitcrypto), Michael Amadi (@AmadiMichael), cygaar (@cygaar), Harrison (@pop-punk), "ERC-7631: Dual Nature Token Pair [DRAFT]," Ethereum Improvement Proposals, no. 7631, February 2024. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7631.