ERC-7498 NFT Redemption (Redeemable) Standard (NFT Redeemables)
Draft · NFTs & multi-token · created 2023-07-28
Creates redemption campaigns that let NFTs be exchanged for onchain tokens or physical goods in a standard way, so wallets and apps can automatically discover and use their conditions.
Why it is needed
Creators frequently use NFTs as redemption vouchers for digital or physical goods. For example, burning a specific NFT might grant a new NFT, or NFT holders might receive merchandise shipments. But without a common interface, wallets or marketplaces have no predictable way to discover whether such a redemption event exists, what must be given and received, or how long it will run. Each project's contract has to be analyzed individually, and users can only participate in redemptions by visiting the official website. Physical goods redemption is even harder: with no standard link connecting an onchain NFT burn to an offchain order (product selection, shipping address), a user could burn the NFT first and only later discover that the item can't be shipped to their region. This standard extends ERC-721 and ERC-1155 to define redemption campaign disclosure (events and query functions), onchain minting, and offchain order linkage within a single interface.
What to implement
event CampaignUpdated(uint256 indexed campaignId, Campaign campaign, string metadataURI);: An event fired when a campaign is created or modified. It serves as the basis for apps to discover campaign details.event Redemption(uint256 indexed campaignId, uint256 requirementsIndex, bytes32 redemptionHash, uint256[] considerationTokenIds, uint256[] traitRedemptionTokenIds, address redeemedBy);: An event fired every time a valid redemption occurs. It records who redeemed which tokens under which campaign.function getCampaign(uint256 campaignId) external view returns (Campaign memory campaign, string memory metadataURI, uint256 totalRedemptions);: Queries the campaign details, metadata URI, and the total number of redemptions so far.function createCampaign(Campaign calldata campaign, string calldata metadataURI) external returns (uint256 campaignId);: Creates a new campaign and returns the newly assigned campaignId.function updateCampaign(uint256 campaignId, Campaign calldata campaign, string calldata metadataURI) external;: Modifies an existing campaign. Only the manager address can call this.function redeem(uint256[] calldata considerationTokenIds, address recipient, bytes calldata extraData) external payable;: Executes a redemption by giving up the specified tokens. extraData carries the campaign number, requirements index, hash, signature, and so on.
In depth
Campaign structure: offer, consideration, traitRedemptions
A Campaign consists of params and a requirements array. CampaignParams includes startTime, endTime, maxCampaignRedemptions, a manager who can modify the campaign, and a signer that determines whether a signature is required. CampaignRequirements borrows Seaport's terminology and consists of offer (what is received in exchange), consideration (what must be given in exchange), and traitRedemptions (trait change conditions). A redemption is valid if any single entry in the requirements array is fully satisfied. The recipient of the consideration is the address that receives the token; for burns, send it to 0x000000000000000000000000000000000000dEaD, or if the token can handle its own burning and decrement totalSupply, burn it directly. Token implementations must return true for interfaceId 0x1ac61e13 in ERC-165 supportsInterface.
Campaign creation and modification rules
A new campaign must be created with createCampaign, which returns a new campaignId and must emit a CampaignUpdated event. campaignId is a counter that increments by 1 per campaign, and the first campaign must be 1. Modifications can use updateCampaign, which must also emit a CampaignUpdated event. If an address other than the manager attempts a modification, it must revert with NotManager(). To make a campaign permanently unmodifiable, set manager to the null address.
Offer tokens and IRedemptionMintable
If a token is specified in params' offer, that token must implement the IRedemptionMintable interface to support minting new items, and must return true for interfaceId 0x81fe13c2 in ERC-165 supportsInterface. When redeem is executed, mintRedemption() is called for every offer item, passing campaignId, recipient, offer, consideration, and traitRedemptions as arguments so the minting contract knows what was exchanged. When calling mintRedemption, it is recommended to replace the token identifiers of the consideration and trait redemptions with the actual items exchanged before passing them.
Redeem execution order and extraData layout
The redeem function must perform the prior transfer of consideration for the requirements determined by campaignId and requirementsIndex, the trait changes from traitRedemptions per ERC-7496, and mintRedemption() calls for every offer item, and must emit a Redemption event for each valid redemption. extraData consists of a 0-32 byte campaignId, 32-64 requirementsIndex, 64-96 redemptionHash (a hash of an off-chain order ID), uint256[] traitRedemptionTokenIds starting at byte 96, followed by salt and a signature (EIP-712 or ERC-1271) only if signer is not the null address. The order of traitRedemptionTokenIds must match the order of token addresses expected in the campaign requirement's TraitRedemption struct array. Whether a campaign is active is checked with the same boundary condition as Seaport, startTime <= block.timestamp < endTime, and must revert with NotActive() if inactive. Redemptions exceeding maxCampaignRedemptions must revert with MaxCampaignRedemptionsReached(uint256 total, uint256 max).
Trait redemption substandard
This also supports redemptions that change ERC-7496 dynamic trait values without burning or transferring the token. To use trait redemption, the token must implement ERC-7496. TraitRedemption has 4 substandards. 1 sets the trait value to traitValue (substandardValue is a value required in advance; if empty, already being in the state of traitValue is not allowed), 2 increases it by traitValue (substandardValue is the maximum), 3 decreases it by traitValue (substandardValue is the minimum), and 4 checks whether the value equals traitValue. This approach exists to let secondary market orders enforce trait values on-chain.
Signer and protection for off-chain redemptions
Specifying a signer for a campaign requires a signature to process redemptions. If signer is not the null address, the signature must be recoverable to the signer address via EIP-712 or ERC-1271. The EIP-712 signature struct is fixed as SignedRedeem(address owner,uint256[] considerationTokenIds,uint256[] traitRedemptionTokenIds,uint256 campaignId,uint256 requirementsIndex, bytes32 redemptionHash, uint256 salt). This mechanism mainly exists so a provider in an off-chain redemption can pre-approve a redemption before on-chain execution. For example, if a user's shipping country is not supported, withholding the signature prevents a situation where the NFT has already been burned or its trait changed before the shipping failure is discovered.
Metadata URI and ERC-1155 application
The campaign metadata URI must follow a defined JSON schema. Required fields are campaignId, name, description, imageUrls, and isBurn; it can also hold details, a banner image, FAQ, contentLocale, maxRedemptionsPerToken, productLimitForRedemption (the number of products selectable in a single redemption), and a products list. imageUrls allows up to 5 entries, with the first image used as the thumbnail. This standard can also be applied to ERC-1155, but a redemption applies to the entire quantity of a given token identifier. If all token quantities in an ERC-1155 contract are 1, the specification can be used as is.
Standard status: Draft
This proposal was created on July 28, 2023 and is currently in Draft status. Since it is still a draft stage whose content may change, the latest specification should be checked before implementation.
Things to watch out for
- Correct implementation of ERC-7496 dynamic traits: A token that wants to use the trait redemption feature must correctly implement ERC-7496 dynamic traits. An incorrect implementation can break redemption logic that depends on trait changes.
- Restricting who can call mintRedemption: The mintRedemption function of IRedemptionMintable, on a token minted via params' offer, must have restricted permissions so that only a designated address can call it. If anyone can call it, tokens could be minted without a redemption.