ERC-7631: Dual Nature Token Pair

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


Metadata
Status: ReviewStandards Track: ERCCreated: 2024-02-21
Authors
vectorized (@vectorized), Thomas (@0xth0mas), Quit (@quitcrypto), Michael Amadi (@AmadiMichael), cygaar (@cygaar), Harrison (@pop-punk)
Requires

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.


The ERC-20 contract MAY implement the following interface.


ERC-721 Extension Interface

The ERC-721 contract MUST implement the following interface.


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.