Author: 0xEstarriol, harry //

FPE Map is released under the MIT open-source license and free to use. If you're looking for commercial support, it's available at ctor.xyz

• We create an innovative metadata shuffling framework, FPE Map, for revealing NFT mystery boxes in a fair and gas-efficient manner.

• FPE Map requires storing only one random number on-chain, regardless of the size of the NFT collection. This makes it extremely gas efficient. (20000x cheaper than Clone X's method)

• Powered by the encryption algorithm, any small change in the random number results in a drastically different mapping, making rarity snipping impossible.

• In combination with Chainlink VRF V2, users are able to create a fair mystery box revealing process without setting up a custom backend.

• The code has been used in production (ZombiePod Genesis, Godpod) and is available through github or npm.

NFT revealing is undoubtedly one of the most exciting moments of an NFT project. This is the moment that holders can finally see what their NFT looks like, and some holders can potentially profit a lot from getting an NFT with rare traits. As it attracts all the attention, NFT reveal also becomes a popular way to increase sales and build hype around a project.

Since it is such an important moment, the revealing process has to be carefully catered to. In Particular, fairness and security may be important factors to be taken into account as there may be a huge economic benefit by getting an NFT with rare attributes.

The most naive method for designing mystery boxes is having a backend that serves the metadata when the tokens are revealed.

However, without a transparent process for shuffling the metadata to guarantee the fairness and randomness of the metadata distribution, it can be a problem for both creators and buyers. One of the most notable controversial events regarding the fair reveal is MecaVerse. One of the team members is accused of profiting from leaked metadata info.

As for how the metadata is shuffled, let’s have a quick dive into some noticeable NFT projects.

• Hashmask: Hashmask uses a randomly generated starting index. For example, if the starting index is 5000, #0 Hashmask would get the image of the 5000th from the initial sequence, and #1 Hashmask would get the 5001st image. However, this doesn’t change the order of the sequence. Therefore, it is possible for someone to snipe the rare ones by buying a set of tokens with consecutive token IDs.

• Clone X: On the other hand, Clone X scrambled the metadata through a more sophisticated algorithm. However, the shuffling process is performed off-chain written back. This method came with a few drawbacks. The first one is that it requires writing the full sequence of the shuffled IDs back to the chain. It costs the Clone X team more than 30 eths to do so! Apart from that, it requires a backend server holding special privileges to perform the shuffling. Some people may question its fairness. (Don't get it wrong. We love Clone X!)

An ideal solution should satisfy three criterias:

• Only store the randomness factor on the chain. The gas consumption doesn’t scale with the size of the NFT collection.

• The mapping between the token ID and the metadata ID should be unpredictable.

• The mapping has to be a one-to-one mapping. Namely, every metadata ID is corresponding to one and only one token ID, so there won’t be two NFTs having exactly the same attributes.

Is there anything that creates unpredictable one-to-one mappings? Yes, that is encryption!

For an encryption algorithm, the plain text and the cipher should have an one-to-one relation, so the information is not lost and the cipher can be decrypted. Also, without knowing the key, the relation between the plain text and the cipher cannot be predicted for a good encryption algorithm.

More specifically, the encryption method we are using here is format-preserved algorithm (FPE), a special type of encryption algorithm. With format-preserved encryption (FPE), one can make the encrypted cipher and the plain text have the same format. For instance, one can use FPE to encrypt a credit card number and have the encrypted cipher still be a valid credit card number.

The property of preserving the format is a huge benefit for NFT applications. We can set the metadata ID to have the same range of the NFT token NFT IDs. Taking Clone X as an example again, with the token ID ranging from 1~20000, we can also have the metadata ID also range from 1~20000, too. As a result, the FPE Map we developed can be used as a drop-in replacement for the mapping array of CloneX and could potentially save 30 eths without any downside.

The FPE Map is realized through an encryption core and a conditional circuit. The encryption core is a block cipher that takes the token ID as the input. The operating domain of the encryption doesn’t have to be the same as the range of the token IDs. However, it requires the operating domain to cover all the possible token IDs. At the output of the encryption core, there will be a conditional circuit that checks whether the output is a valid token ID. If the output doesn’t fit the format of the token ID, it will be fed to the encryption core again until the output has the valid format. In our implementation, we implement the block cipher with a Feistel network as its block size which affects the operating domain of the Feistel network can be easily adjusted. In our implementation, we also implement functions to automatically configure the block size of the Feistel network based on the range of the token IDs.

To make the whole process secure, it is also important to have a reliable randomness source. The blockhash based randomness source that has been used in multiple projects due to its simplicity is vulnerable to flashbot attack. With flashbot, attackers can engineer the supplied randomness and potentially profit from it. We use Chainlink’s VRF V2, as it offers cryptographically verifiable randomness. Combining Chainlink VRF V2 with the FPE Map, we are able to construct a cost-efficient yet secure NFT reveal process without the need of maintaining a custom backend.

The source code of FPE Map is available on both github and npm and has been used in the production environment. The first project that adopts this innovative revealing method is ZombieClub’s ZombiePod Genesis NFT.

Author: 0xEstarriol, harry //

FPE Map is released under the MIT open-source license and free to use. If you're looking for commercial support, it's available at ctor.xyz

• We create an innovative metadata shuffling framework, FPE Map, for revealing NFT mystery boxes in a fair and gas-efficient manner.

• FPE Map requires storing only one random number on-chain, regardless of the size of the NFT collection. This makes it extremely gas efficient. (20000x cheaper than Clone X's method)

• Powered by the encryption algorithm, any small change in the random number results in a drastically different mapping, making rarity snipping impossible.

• In combination with Chainlink VRF V2, users are able to create a fair mystery box revealing process without setting up a custom backend.

• The code has been used in production (ZombiePod Genesis, Godpod) and is available through github or npm.

NFT revealing is undoubtedly one of the most exciting moments of an NFT project. This is the moment that holders can finally see what their NFT looks like, and some holders can potentially profit a lot from getting an NFT with rare traits. As it attracts all the attention, NFT reveal also becomes a popular way to increase sales and build hype around a project.

Since it is such an important moment, the revealing process has to be carefully catered to. In Particular, fairness and security may be important factors to be taken into account as there may be a huge economic benefit by getting an NFT with rare attributes.

The most naive method for designing mystery boxes is having a backend that serves the metadata when the tokens are revealed.

However, without a transparent process for shuffling the metadata to guarantee the fairness and randomness of the metadata distribution, it can be a problem for both creators and buyers. One of the most notable controversial events regarding the fair reveal is MecaVerse. One of the team members is accused of profiting from leaked metadata info.

As for how the metadata is shuffled, let’s have a quick dive into some noticeable NFT projects.

• Hashmask: Hashmask uses a randomly generated starting index. For example, if the starting index is 5000, #0 Hashmask would get the image of the 5000th from the initial sequence, and #1 Hashmask would get the 5001st image. However, this doesn’t change the order of the sequence. Therefore, it is possible for someone to snipe the rare ones by buying a set of tokens with consecutive token IDs.

• Clone X: On the other hand, Clone X scrambled the metadata through a more sophisticated algorithm. However, the shuffling process is performed off-chain written back. This method came with a few drawbacks. The first one is that it requires writing the full sequence of the shuffled IDs back to the chain. It costs the Clone X team more than 30 eths to do so! Apart from that, it requires a backend server holding special privileges to perform the shuffling. Some people may question its fairness. (Don't get it wrong. We love Clone X!)

An ideal solution should satisfy three criterias:

• Only store the randomness factor on the chain. The gas consumption doesn’t scale with the size of the NFT collection.

• The mapping between the token ID and the metadata ID should be unpredictable.

• The mapping has to be a one-to-one mapping. Namely, every metadata ID is corresponding to one and only one token ID, so there won’t be two NFTs having exactly the same attributes.

Is there anything that creates unpredictable one-to-one mappings? Yes, that is encryption!

For an encryption algorithm, the plain text and the cipher should have an one-to-one relation, so the information is not lost and the cipher can be decrypted. Also, without knowing the key, the relation between the plain text and the cipher cannot be predicted for a good encryption algorithm.

More specifically, the encryption method we are using here is format-preserved algorithm (FPE), a special type of encryption algorithm. With format-preserved encryption (FPE), one can make the encrypted cipher and the plain text have the same format. For instance, one can use FPE to encrypt a credit card number and have the encrypted cipher still be a valid credit card number.

The property of preserving the format is a huge benefit for NFT applications. We can set the metadata ID to have the same range of the NFT token NFT IDs. Taking Clone X as an example again, with the token ID ranging from 1~20000, we can also have the metadata ID also range from 1~20000, too. As a result, the FPE Map we developed can be used as a drop-in replacement for the mapping array of CloneX and could potentially save 30 eths without any downside.

The FPE Map is realized through an encryption core and a conditional circuit. The encryption core is a block cipher that takes the token ID as the input. The operating domain of the encryption doesn’t have to be the same as the range of the token IDs. However, it requires the operating domain to cover all the possible token IDs. At the output of the encryption core, there will be a conditional circuit that checks whether the output is a valid token ID. If the output doesn’t fit the format of the token ID, it will be fed to the encryption core again until the output has the valid format. In our implementation, we implement the block cipher with a Feistel network as its block size which affects the operating domain of the Feistel network can be easily adjusted. In our implementation, we also implement functions to automatically configure the block size of the Feistel network based on the range of the token IDs.

To make the whole process secure, it is also important to have a reliable randomness source. The blockhash based randomness source that has been used in multiple projects due to its simplicity is vulnerable to flashbot attack. With flashbot, attackers can engineer the supplied randomness and potentially profit from it. We use Chainlink’s VRF V2, as it offers cryptographically verifiable randomness. Combining Chainlink VRF V2 with the FPE Map, we are able to construct a cost-efficient yet secure NFT reveal process without the need of maintaining a custom backend.

The source code of FPE Map is available on both github and npm and has been used in the production environment. The first project that adopts this innovative revealing method is ZombieClub’s ZombiePod Genesis NFT.