Published in


Ethereum NFT token-to-asset mappings are off-chain and nobody cares

The integrity of NFT art is being defeated by project designers who leave essential token → asset mappings off-chain

Example of a NFT from a popular collection called Hashmasks

Non-fungible tokens (NFTs) on the Ethereum blockchain are spearheading the next wave of innovation following the massive Decentralized Finance (DeFi) wave. The typical use-case for NFTs is mapping ownership of a digital asset to the holding of a unique token on chain. NFT-represented assets don’t necessarily need to be digital, although it’s a more natural fit than representation of physical assets. Representing digital assets on the blockchain is natural because the bits that compose the digital file can be hashed to a shorter representation of the file which is cheaper to store on chain.

The first NFT-type project on Ethereum was Cryptopunks. The mechanics behind it are fairly simple — a 100x100 grid of unique cryptopunk images were stitched together to form a larger image which was then hashed and stored on the blockchain. The Cryptopunks project released 10,000 unique tokens that represented each cryptopunk. The tokens were initially given away for free, but are now traded for Ether; some being valued at over $1,000,000.

Fast-forward 3.5 years to the arrival of Hashmasks, a highly innovative project which one-uped Cryptopunks. In the Hashmasks project, greater attention to detail went in to the generation of the artwork, with over 70 artists participating in the highly iterative process that generated 16,384 unique pieces of digital art. Each Hashmask has a unique set of explicit traits, some rarer than others. In addition to the explicit ones, hidden traits make some masks even rarer. Hashmasks are represented by NFTs, following the ERC-721 standard. Furthermore, the Hashmasks project introduced Name Change Tokens (NCTs), which accumulate as time passes and give artwork owners the right to change the piece’s name, thus allowing them to add the finishing touch.

Distribution launched on January 28th of this year and was an instant success, creating a dedicated following along with it. During the token distribution period, NFT purchasers knew that every NFT would eventually map to a Hashmask image hosted on IPFS, but at the moment were blind to which one. Once all NFTs were distributed, the NFT → image mapping was revealed. Extensive media coverage followed, bringing blockchain collectibles back into the limelight. Next came Twitter trends, Discord servers, image analyses, dozens of websites, hidden trait searching, emerging patterns, price discovery, and what appears to be a culture developing around the project.

How does Hashmasks ownership and token → image mapping work?

The Hashmasks team generated a hash of every one of 16,384 images and assigned an index to each one, from 0 to 16,383. Next the image hashes were concatenated in the order of their indices and all hashed together to generate a provenance record, as the team explains here. The provenance record was stored immutably in the Hashmasks Ethereum contract. During the token distribution phase, tokens were still not mapped to these images.

Provenance record definition as seen here

How were the tokens mapped to the images?

After the token distribution concluded, a so called startingIndex was randomly generated within the contract. The startingIndex’s purpose was to establish that the image in the original sequence with index = startingIndex would correspond to the token with tokenId = 0. Then, every subsequent tokenId after 0, mapped to the next image in the original sequence (mod 16,384, in order to loop back to the images sequenced before the “starting image”).

So, what’s the problem with this formulation?

At first glance, the definition seems sensible, secure, immutable, and it clearly provides enough confidence to the audience and market, as evidenced in the extensive adoption and hundred-of-thousands of dollar price-tags on some of the rare pieces currently being traded.

So, what is the problem?

I claim that the definition is incomplete because it relies on off-chain information, causing the NFTs to be decoupled from the artwork they are intended to represent ownership of. This defeats the very essence of decentralizing digital art ownership.

How so?

Well, let’s first take a look at what can be proven, which reveals what cannot. It can be proven that only the sequence of images in the original order can generate the provenance record hash. Any modification to the order or to a single bit in a single image, would change the provenance record to something completely different. What else can we prove? We also know that the startingIndex is provably random-generated by the smart contract. And that’s all we know. In other words, there isn’t enough on-chain, immutable information which undeniably maps a particular token to a particular image. Furthermore, the instructions to realize the intended mapping live off-chain, on the Hashmasks website. This implies that, in theory, if the mapping definition on the Hashmasks website were to change, the token → image mappings could change and Hashmask owners would no longer own the Hashmask they thought they did.

What’s an example of such a change in definition that would modify ownership?

  1. The Hashmasks website definition could ignore startingIndex altogether, and simply define that every NFT maps to the image with index equal to its tokenId in the original sequence (i.e. the sequence represented by the provenance record). This scenario would be equivalent to having made the NFT distribution non-blind to the artwork that was being purchased.
  2. The Hashmasks website definition could change how the startingIndex is used in the off-chain mapping formula to: (startingIndex - tokenId) % 16384. This would be like flipping ownership around the image at index equal to startingIndex in the original sequence.

What could the Hashmasks team had done different?

There are two simple solutions that come to mind that would still have kept token distribution blind to artwork ownership, which was clearly one of the project’s objectives.

  1. Once token distribution was over and the startingIndex was randomly chosen, the image hashes could be re-ordered based on the intended mapping formula: (tokenId + startingIndex) % 16384. Then the contract provenance record would be set to the hash of the image-hashes in this final order. Under this definition, artwork ownership would be clearly defined, because every tokenId would correspond to the image with index equal to tokenId in the provenance record.
  2. A more straight-forward and elegant solution would be to generate the startingIndex at random as originally intended, but also provide a contract method which takes as input the tokenId and outputs the artwork image hash that corresponds to that token, thus perfectly coupling the token to the image on-chain.

Both solutions come at a higher expense to the project as the first solution requires calculation of a hash of 16,384 hashes within the contract, or storing 16,384 previously calculated hashes in contract storage; and the second solution requires storing 16,384 image hashes in contract storage as well. I suppose these expenses has something to do with why the Hashmasks team decided to leave the mapping definition off-chain. The decision is surprising given that the expense would have been insignificant for a project that generated over 14 million dollars in income during token distribution. It’s possible the team didn’t want to put up such a big upfront cost in case the project didn’t turn out successful.

Another cheaper idea worth experimenting with is to store the provenance record in the contract just as the Hashmasks team did, but randomize tokenId assignments once token distribution is finalized.


The Hashmasks team did a great, beautiful, and meticulous job designing a project that had enough innovative ingredients to bring NFT art back into the limelight, hopefully to stay. The entire collection is currently valued (just taking into account floor-mask value) upwards of 50 million dollars. I actually own a couple Hashmasks albeit the described shortcomings.

However, I believe the community must arrive at consensus that current artwork ownership models come with key logic gaps that the industry should learn from so that the mistakes aren’t repeated, thus keeping the integrity of decentralized art.

I don’t believe it’s likely that the Hashmasks team will ever change the ownership definition on their site, but that’s beside the point — they shouldn’t even be able to. The objective of all the infrastructure being built on Ethereum is to avoid needing trust, even when it’s probably OK to trust.



Coinmonks ( is a non-profit Crypto Educational Publication. Follow us on Twitter @coinmonks and Our other project —, Email  —

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Adam Ξisenman | DigitalOil.nftr

Early. Ethereum dev and founder @nft_registry . Podcast host @0xCryptoLatinos . Business director. Former ios dev & satcom engineer. @GeorgiaTech ee & @mit