Spatializes

Hacking on Farcaster Frames

spat.eth — Thu, 01 Feb 2024 21:06:31 GMT

Getting started with your first Frame? Here’s all the info you need to get rolling.

I’ll be building a Frame to airdrop tokens, but for now lets get started with the basics. The code is all posted here on GitHub if you want to follow along.

Farcaster frames were released just last week in Farcaster’s Feature Friday. A bunch have been built already, check out the list below the see some examples. Here’s a Nouns frame where you can see the current Noun up for auction and bid.

So what is a Farcaster Frame? It’s a little app in your feed. They’re very simple at this point, an image with a few buttons. Click a button and get a callback to update the image. But the best part? The simplicity of building one!

Frame dev

Frames are based on the OpenGraph standard, the thing that enables link previews in social feeds. So we’re really just working with a fancy link preview! Genius idea by the Farcaster team.

But instead of only the image, description, and title, we bring in a few extra tags. Let’s see the core basics of a Frame in a NextJS app. Throw this into your page.tsx and deploy it to Vercel.

import { Metadata } from "next";

const frameMetadata = {
  "fc:frame": "vNext",
  "fc:frame:image": "https://blocklive.io/util/logo.png",
  "fc:frame:button:1": "$ETH",
  "fc:frame:button:2": "$BTC",
};

export const metadata: Metadata = {
  title: "Frame Airdrop",
  description: "Generated by create next app",
  other: {
    ...frameMetadata,
  },
};

export default function Home() {
  return (
    <>
      Frame Airdrop!
    
  );
}

Head over to the Frame Validator with your Vercel link and run it!

We have a frame!

Now the buttons don’t do anything. Let’s hook them up. This will be as easy as creating an API route in our NextJS and and returning a new HTML response on button click. Add a route at app/api/frame called route.ts

import { NextRequest, NextResponse } from "next/server";

const POST_URL = "https://frame-airdrop.vercel.app/api/frame";

export async function POST(req: NextRequest, res: NextResponse) {

  const NEW_IMAGE_URLimage =
    "https://assets.blocklive.io/events/2bfb5de2-cd38-49d5-bb3b-1834dfc66380/58662d9d-303b-4c72-b3cd-92207ca8b91b_dall_e_2024_01_28_23_08_18___design_a_banner_image__size_936px_x_468px__that_looks_like_an_entrance_ticket_to_an_event_for_the__frames__feature_on_a_social_media_platform_resembli.png";

  let html =
    `` +
    `` +
    `` +
    `` +
    `` +
    `` +
    ``;

  return new Response(html, { headers: { "Content-Type": "text/html" } });
}

export const dynamic = "force-dynamic";

Checkout the repo where we do some fancy validation to ensure the button click comes from our Frame and take action based on which button is clicked. This just returns a new image and button set to get you across the line.

Helpers

Embed validator

Frame validator

Trending frames

Farcaster Frames spec

Pimlico sponsored gas for frames

Awesome Frames (big list of Frame resources)

Examples In The Wild

Base mint for physical claim

Example Code

https://warpcast.notion.site/Farcaster-Frames-4bd47fe97dc74a42a48d3a234636d8c5

https://github.com/farcasterxyz/fc-polls/blob/main/app/polls/%5Bid%5D/page.tsx

Hackathon Ideas

Powerball for Farcasters
One-click checkouts
Prediction markets from Polymarket
Governance voting
Show the user’s connected wallet address
Meme bot

$$$

Bountycaster

Aztec is doing $25,000 in bounties for the top 5 Farcaster applications (frames or otherwise) built using Noir

In Austin? Stop by for our Farcaster Frames Hackathon on Blocklive hosted by citydao.network, Base, and ATX DAO. Follow me on X and Farcaster!

First Time Experience Joining and Gaming with Cyberkongz Play & Kollect

spat.eth — Tue, 10 May 2022 18:27:28 GMT

We've discussed Cyberkongz in previous posts here, diving into smart contracts and metaverse concepts, because Cyberkongz is the OG PFP and VX project. So of course, they are also leading the way in pure on-chain gaming.

At a high level for Play & Kollect, holders of the Cyberkongz VX NFT collection play text-based games to collect a variety of tokens and NFTs. Gaming is done on the Polygon network.

How does it really work?

1. Buy a Cyberkongz VX

To play, I needed to acquire 1 Cyberkongz VX NFT. These are currently trading at a ~0.9 eth floor.

2. Deposit the Cyberkongz VX to Polygon

Once we have the NFT, all gaming is done on the Cyberkongz website. Go to the website, and deposit the Cyberkongz VX onto the Polygon network.

Do this by clicking on the 'Jungle' tab in the top menu. On the map, click the 'Polygon Bridge' icon.

This took two transactions ($5 and $20 with gas at 30gwei). At the cost of a traditional PC game, this is not cheap to get started playing. Though at a 1.1 eth entry point ($3.3k), this is no kid’s game! Maybe someday, although gas at today's 30gwei is the lowest we've seen all year. 2021 had us at 100+ gwei for the majority of the year.

Now that my Cyberkongz VX is locked, one step closer to Adventure. Interesting to note, when we look at our OpenSea profile, the VX is still in our wallet but it's technically on the Polygon network now, not Ethereum L1. When I search for my VX in the CyberKongz VX collection, it was no longer owned by me! It's now owned by a shared wallet (0xE6F45376f64e1F568BD1404C155e5fFD2F80F7AD) which owns a huge pile of other Kongz and Kongz accessories. So I own the corresponding VX now in a separate VX Polygon collection. Under the hood, what happened? A new NFT was minted on Polygon. I transferred my mainnet NFT to Cyberkongz. I was airdropped this Polygon representation, which trades at about the same floor price.

Airdropped when you bridge your eth mainnet Kong to Polygon.

3. Build your crew

Head back to the Jungle tab. Click on the MS Kongz ship icon.

Switch to the Polygon network. Create a crew. I tried this right after Depositing my VX and it wasn't available yet. The docs say it will take 7-30 minutes to show up on Polygon. After 25 minutes, the VX has landed.

Add the VX and click Create Crew! Ooh! I have 0 MATIC. Head over to the Cyberkongz Discord, in the polygon-faucet channel, type !faucet, and get 2.2 Polygon. Very convenient. Otherwise, I'd be headed to a dex to swap for MATIC.

Send a DM to tip.cc, and say $withdraw matic.

Type in your Polygon address (same as the ethereum address you had your VX in).

Type all and confirm, boom we've got Matic to play with.

Now we click Create Crew and for only 0.01 Matic we make the transaction. Ok, now compared to our $25 spend on eth transactions, it makes a lot of sense why we'd want to be on the Polygon network.

Our 1 man crew is ready for adventures!

4. Adventure!

We still don't have any banana or fuel rods though. $BANANA we'll never get, unless we buy some. $BANANA is only accumulated, 10 per day, by a genesis kong. The floor for a genesis is a mere 47eth. Lower than I've seen in the past at 100+, but still out of our budget. But we will acquire 1 fuel rod per day our VX is locked up in the Polygon Deposit. It looks to accumulate over 24 hours, so after half a day, we'll have 0.5 fuel rod.

But I’m impatient and I don't want to wait that long, so I'll pick up some $BANANA.

5. Get Banana

This ended up being an entire adventure on Polygon network.

In the name of science, I'll investigate a few routes for crytpo transactions on various networks. This will look at the state of movement of funds around exchanges and the Polygon network.

Eth to $BANANA

Jump to the Discord to grab a link to a DEX from the official links section. I'll use the Uniswap link: https://app.uniswap.org/#/swap?inputCurrency=0x94e496474f1725f1c1824cb5bdb92d7691a4f03a&chain=mainnet.

Swapping .006 eth for 3 $BANANA, for $20 of $BANANA we're looking at a $25 gas fee with gas at ~50gwei. Can we do better?

MATIC to $BANANA

We can swap for $BANANA directly on Polygon, which should be much cheaper. So head over to Quickswap on Polygon https://quickswap.exchange/#/swap?inputCurrency=ETH&outputCurrency=0xbc91347e80886453f3f8bbd6d7ac07c122d87735. But we don’t have enough MATIC. Try buying MATIC on an exchange?

Kraken to buy MATIC

Try to swap, we have 2 MATIC still left over from the faucet earlier. This only gets us 0.5 $BANANA. For this approach, we can try to buy MATIC and exchange that for $BANANA. Using Transak through the 'Buy' button on Metamask, we're looking at $10 in fees. If we instead use a traditional exchange, Kraken, it charges $0.07 in fees for $50 of MATIC, which is about 35 MATIC at the current price of $1.40/MATIC. Much more reasonable.

Now we Withdraw from Kranken, directly to the Polygon address that we’re using for the Cyberkongz adventure. The address is the same as the original layer 1 eth address we used to buy the Cyberkongz VX on Opensea. But interestingly, Kraken charges a 15 MATIC fee minimum to withdraw any MATIC. This is just the state of things on Kraken. Looking at the fee list, even an Ethereum withdrawal will cost you a $10 fee, which is absurd. The network will already hit us, the extra exchange fee is terrible.

Do we have no way to get around this $20 fee to play on Polygon network? This is not sustainable for the masses!

Coinbase to buy MATIC

Looking at Coinbase, it charges only a $0.30 fee to again buy $50 of MATIC. Now for the withdrawal! To pull out 30 or 100 MATIC I'm charged the same fee, 2.5 MATIC. Still not ideal, but for a few bucks, we do have a winner. I pull the MATIC to my ETH address this time from Coinbase.

Bridge MATIC from Ethereum to Polygon

With Coinbase, we were dealing with the ERC-20 MATIC token on the Ethereum network. To use the cheap Polygon bridge, we need to bridge our MATIC to the Polygon network. https://wallet.polygon.technology/bridge Things are getting slightly complicated, but we'll do the work to save the cash!

Unfortunately, the bridge is going to kill us too. We need to make 2 transactions to move our MATIC to Polygon. The first, $5 for it to access our MATIC. Again, we're in a 30 gwei eth network environment here. And to confirm the transfer, another $15. The $20 fee is unavoidable! Amazing. And it's going to take 7-8 minutes to get this done. Fucking crypto today man.

Finally, we're back to Quickswap. I'll swap 18 MATIC for 4 $BANANA, with a 0.1 MATIC fee. Shows how things are very nice once we're here, but getting here was not easy. Now with our fresh 4 $BANANA, we game!

6. Ok really, now, Adventure!

My wallet back at cyberkongz.com shows 4.09 BANANA. I head back to the Jungle tab and click the Portal icon. In the portal, I can now do an Adventure Run by clicking the Approve button. Only a $0.01 fee this time to approve interaction. Slightly annoying side note, I've been using a Trezor wallet which I've had to click hardware approvals on for each of these transactions. Now click Start to start an adventure run. I get a dialog that tells me 'Adventure Run In Progress’.

What is happening at this time? Chainlink? We’ll dive into the contract interaction in a later post. For now, just play.

Adventure is Completed. I found loot! +4 Kongium and +2 EXP.

PLAY AGAIN!

Click Start, I need more Kongium. Perhaps I'm addicted. Less loot this time though. +3 Kongium, +1 EXP. I'm still only a level 1 Kong.

Wrap up

As we've seen it's still quite expensive to get onto the Polygon network. It took $25 to get a Kong bridged over at very low gas prices. However, it seems we shouldn't need to go back and forth much, so some planning ahead can make this quite reasonable. All $BANANA should be bought in one transaction if needed, but it isn't actually needed if you're willing to play entirely using Fuel Rods.

Play and Kollect is currently in its infancy as a simple text-based game. However, it shows the potential for on-chain interaction with NFTs and tokens. It sets up huge potential for further games to be built out around these core concepts. Anyone could build a traditional game that uses $BANANA to gain entry to a new session, derives logic from a Kong VX's EXP and Kong level data stored in Polygon, and pays out Kongium. This project is moving at a rapid pace and I expect to see them continue to push the limits of the NFT and on-chain gaming space.

METAVERSE_URL

spat.eth — Thu, 07 Apr 2022 23:16:30 GMT

In a previous post, we looked at how NFTs are not ready for the 3D Metaverse. The main reason - we do not have a standard path for the 3D asset to be defined, as we do with PNG or JPG-based NFTs.

An NFT itself is a small record on the blockchain. As we broke down in another post, information about the media stored in the NFT is held in its metadata.

For a PNG or JPG, we store the path to the actual file under the image property in the NFT’s metadata. 3D assets also need an image rendition, along with one or multiple 3D file type renditions. Where to put them?

The official ERC-721 spec defines an optional metadata section but does not go beyond name, image, and description for suggested values.

Here’s what OpenSea suggests for metadata:

It looks like animation_url is the leftover grab bag for a huge variety of file types, which includes 3D file types along with entire HTML web pages. This variety makes it impossible for a Metaverse to know what to expect when it reads an NFT’s metadata, or how to guarantee it can find the 3D file.

METAVERSE_URL

With the options lacking, it seems we need a new property for the 3D Metaverse. The word Metaverse is overplayed already, but it has a beautiful origin in Snow Crash, and we should keep things easy and stick as closely as possible to its original definition. A Metaverse is a 3D virtual world.

metaverse_url - A URL to the asset that an NFT should be represented as in a Metaverse.

This property can be either a string value or a dictionary. As a dictionary, we can store any file type renditions of that 3D asset - glTF, glb, FBX, OBJ, USD. The 3D world is messy, but a strongly typed list of supported types will let applications know what they are getting and where to look for it.

Example as a string:

metaverse_url: "https://spatializes.com/myavatar.glb"

Example as a dictionary:

metaverse_url: {
    glb: "https://spatializes.com/myavatar.glb",
    gltf: "https://spatializes.com/myavatar.gltf",
    fbx: "https://spatializes.com/myavatar.fbx",
    obj: "https://spatializes.com/myavatar.obj",    
    usdz: "https://spatializes.com/myavatar.usdz",
    usd: "https://spatializes.com/myavatar.usd",
}

Preference should be glb (the binary version of glTF), for faster loading over the network and of its buffers into memory.

ANIMATION

When a Metaverse imports a 3D model, each model may have its own animation data set up internally. If not, we won’t be able to do things like walk, run, or attack! Static models are much less fun.

Following the standards set up by templates in VoxEdit seems like the best path forward at this point. VoxEdit is currently the easiest way to model and animate 3D assets that I’ve found so far. Compatibility with the Sandbox will help interoperability.

Voxel robot guy I made in VoxEdit from the standard ‘Small Human’ template, amazingly useful to get these animations for free.

Assets should have at least the following animation channels to allow for a base set of interactivity:

Idle
Walk
Run
Jump
Climb
Attack
Die

With just this small set of animation channels, Metaverses can implement a wide range of functionality. As a Metaverse, on import, we can scan for animation channels that contain these strings. These might be humanoids, creatures, or even more static objects like turrets or buildings (which might also have the ability to attack or die).

This list should continue to expand as we find greater use cases for assets in the Metaverse, but a short simple list to start will be helpful.

Projects adopting this new metadata and model structure will give us a much greater chance of building an open, interoperable, and standardized Metaverse.

3D NFTs are not ready for the Open Metaverse

spat.eth — Wed, 23 Mar 2022 15:52:50 GMT

We hear plenty about closed Metaverses. Facebook is likely building one. Instagram and Snap already operate them.

By Metaverse by the way, I mean the original version defined by Neal Stephenson in Snowcrash - where users appear as avatars, interacting with virtual content on virtual real estate. Although unlike in Snowcrash, this may happen on your desktop, mobile phone, or VR/AR headset. It’s the virtual world and virtual content that are important to us.

What makes a Metaverse closed?

Let’s look at Snap’s current virtual world. To get your content (like a new face mask or 3D hotdog) into Snap, you must upload it through their proprietary marketplace or proprietary creation tool Lens Studio.

Snap may decide they don’t like your art for whatever reason and block your content. Or they might decide they just don’t like you and ban your login. No Metaverse for you.

What could an open Metaverse look like?

Imagine you want to join my open Metaverse, Spativerse (not really a thing). The ideal workflow:

Visit a Metaverse
Connect your wallet
Pick the NFT you want to use as your avatar

You can freely use any NFT you own without permission from the Metaverse. It will load whatever you own in your wallet! Freedom.

This is what I always imagined the NFT dream to be. It is how the JPG based NFTs currently work. We can always expect to look at an NFT’s metadata and find the image url under the image key, then load that image into the Metaverse.

Unfortunately, spoiler alert, this is not how many 3D voxel (VX) projects are set up. We do not have standardized access to the raw 3D assets. So we cannot load them directly from the blockchain into an open Metaverse.

Read on to see a few VX project contracts deconstructed, in our search for the VX asset.

VX NFTS TODAY

Many projects that were originally set up as 2D profile picture (PFP) collections are now looking to release VX versions of their projects. One of the original leaders in this strategy is Cyberkongz.

CYBERKONGZ

Genesis Cyberkongz (0x57a204aa1042f6e66dd7730813f4024114d74f37) were one one of the earliest projects, created on the blockchain April 16th, 2021. This inspired many of the early PFP collections. Funny enough, we can see another quite famous collection, Bored Ape Yacht Club (0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d) came later April 22nd, 2021! Inspiration? Perhaps.

After the success Cyberkongz found, we get Cyberkongz VX (0x7ea3cca10668b8346aec0bf1844a49e995527c8b) on a new contract, created August 15th, 2021.

What’s inside the metadata and contract for a Cyberkongz VX? Is our VX version directly in the NFT? Sadly, not quite.

{
  "image": "https://cyberkongz.fra1.cdn.digitaloceanspaces.com/public/1/1_preview.jpg",
  "external_url": "https://kongz.herokuapp.com/kong-vx/1",
  "name": "CyberKong VX #1",
  "attributes": [
    {
      "value": "Ghost",
      "trait_type": "Legendary"
    },
    {
      "trait_type": "Level",
      "value": 1
    },
    {
      "trait_type": "Status",
      "value": "Unlocked"
    }
  ],
  "animation_url": "https://vxviewer.vercel.app/1",
  "iframe_url": "https://vxviewer.vercel.app/1"
}

From a Cyberkongz VX metadata, we get the standard properties that come with most NFTs like name, attributes, and image. But look at this, we also get external_url, animation_url, and iframe_url! Promising, but unfortunately not the raw asset. These are links to web based app viewers.

The external_url points to a heroku web app which lets me visualize, color, and view animation of the Cyberkongz VX model.

The animation_url and iframe_url both point to the same Vercel app, which is simply a glTF web renderer. If we look at network traffic on the site, we can finally see the actual VX asset delivered, as a glTF file (well glb, the binary version of the common 3D file format glTF). It comes from https://cyberkongz.fra1.cdn.digitaloceanspaces.com/public/4919/4919.glb. More bad news, the asset is delivered from another web2 property, Digital Ocean.

This is quite disappointing from a decentralized tech perspective. WHEN the Heroku and Vercel apps eventually die, and they will, this metadata will point to dead links. Maybe the original VX project did it better?

MEEBITS

Before Cyberkongz actually released their VX Kong, Meebits (0x7bd29408f11d2bfc23c34f18275bbf23bb716bc7) were on the scene May 3rd, 2021!

Let’s look at the metadata for the very first Meebit of the collection.

{
  "name": "Meebit #1",
  "description": "Meebit #1",
  "image": "http://meebits.larvalabs.com/meebitimages/characterimage?index\u003d1\u0026type\u003dfull\u0026imageType\u003djpg",
  "attributes": [
    {
      "trait_type": "Type",
      "value": "Human"
    },
    {
      "trait_type": "Hair Style",
      "value": "Bald"
    },
    {
      "trait_type": "Hat",
      "value": "Backwards Cap"
    },
    {
      "trait_type": "Hat Color",
      "value": "Gray"
    },
    {
      "trait_type": "Shirt",
      "value": "Skull Tee"
    },
    {
      "trait_type": "Overshirt",
      "value": "Athletic Jacket"
    },
    {
      "trait_type": "Overshirt Color",
      "value": "Red"
    },
    {
      "trait_type": "Pants",
      "value": "Cargo Pants"
    },
    {
      "trait_type": "Pants Color",
      "value": "Camo"
    },
    {
      "trait_type": "Shoes",
      "value": "Workboots"
    }
  ]
}

Oh sadness! We get even less than our Cyberkongz VX metadata. Name, description, attributes, and image only. This first of its kind, 3D voxel based NFT, which advertises itself as Metaverse ready:

All Meebit owners can access a T-pose OBJ file that be imported into any most standard 3D modelling and animation software.

is not programmatically Metaverse ready. If I want to load this NFT into my 3D world, how do I get the 3D asset? Maybe the actual contract itself contains methods to get the asset? Nope.

It quickly becomes clear that Meebits are not made for the open Metaverse either. ‘Owner download area’ is the solution that lets Meebits owners download that OBJ file. This feels like a great web2 flow. Buy an asset, go download it from one site, and import it to another. It will work for some workflows, but will fail critically in web3.

larvalabs.com/blog/2021-6-11… ","username":"cryptopunksnfts","name":"CryptoPunks","profile_image_url":"","date":"Fri Jun 11 19:51:08 +0000 2021","photos":[{"img_url":"https://pbs.substack.com/media/E3oCJ-fXMAIeMoK.jpg","link_url":"https://t.co/WfufZyUaH3","alt_text":null}],"quoted_tweet":{},"reply_count":0,"retweet_count":65,"like_count":420,"impression_count":0,"expanded_url":{},"video_url":null,"belowTheFold":true}" data-component-name="Twitter2ToDOM">

CONCLUSION

While it seems NFTs were made to allow JPGs to be freely available and transferable, the same is not true for the 3D file that makes a VX NFT.

The 3D files (obj, gltf, fbx) that represent the VX NFT are not available through a standard contract definition like ERC-721. I need to visit some website, login, and download the file to get it. Why is this a problem?

There is no blockchain record of the 3D asset tied to your wallet address.

Do you actually own your VX if it doesn’t exist on the blockchain or decentralized storage like IPFS? What’s the point of doing any of this on the blockchain when the pointers all lead back to centralized web2 storage?

It seems the great lessons applied to JPG based NFTs were just ignored for VX.

The way Twitter is able to show a validated NFT for your profile picture will not be possible for your 3D avatar in the Metaverse, if there is no way to programmatically find the 3D asset starting from the original NFT.

If this is not fixed for future NFTs, we have a big problem on our hands for interoperability and ownership validation.

Why is NFT metadata stored outside the smart contract?

spat.eth — Mon, 22 Nov 2021 15:31:59 GMT

Once you learn about the basics of Ethereum based NFTs, you realize that your JPEG is not actually stored on the blockchain for most projects. The blockchain only holds a link, which points to a metadata file. That metadata file then points to your JPEG.

The NFT Image

It makes sense that the JPEG isn’t stored on chain, those images can be huge at high quality. Let’s look at a Bored Ape for example, randomly, the 61st most rare bored ape, #7678!

If we dive into the Bored Ape Yacht Club smart contract, and read the tokenURI property for this pizza king crown guy, we find it points to ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq. This is the metadata for ape #7678 (shown fully below if you’re curious). The metadata points to an image stored at ipfs://QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq/7678.

Note: we can look at these ipfs urls in a traditional browser using the schema https://ipfs.io/ipfs/

The image (technically a PNG) is a 631x631 square at 255kb on disk.

According to the Ethereum yellow paper, which lays out the gas fee schedule, a 256 bit word costs 20k gas, or 625 gas for 1 byte (8 bits). That’s 640k gas for 1kb.

255kb image * 640k gas = 163.2m gas for the 255kb image.

So how do we calculate gas fees? The Ethereum docs lay it out prior to the London hard fork:

Total fee = Gas units (limit) * Gas price per unit

And after the London hard fork:

Total fee = Gas units (limit) * (Base fee + Tip)

So with London, instead of just Base fee (gas price per unit) we add in a tip. We’ll ignore the tip for our calculations, call it an approximation, and continue to use the pre-London formula.

Let’s do the math!

What is the price per unit of gas today (11/21/21)? Average has been about 90 gwei. This has fluctuated wildly based on congestion in the network, from 30 gwei up to thousands of gwei, when Shib is pumping or a super hot project is released. What is the cost for our image that will use 163.2 million gas units?

90 gwei per unit * 163.2m units = 14.688b gwei = 14.69 eth

We divide by 1 billion to convert gwei to eth, because 1 gwei is 1 billion wei (the smallest unit of Ether), and 1 eth is 1 billion gwei.

Woah. Can that be right? 14 fucking eth to store my image? How much is eth today? $4350 per eth!

14.69 eth * $4350/eth = $63,901

That seems excessive for a single image. And if the bulls on Reddit are right, Ethereum is headed to $10k per coin. Sounds right to me. Let’s see how accurate that is when we look back in a few years. In any case, it doesn’t seem worth gambling our project on the price of Ethereum. Ethereum would need either an exponential decrease in price, or a large decrease in gas cost, for it to ever make sense to actually store this image on chain as a PNG.

Worse, for BAYC, we need to store 10,000 images. This would cost $639 million. It appears storing the raw image directly in this way is not an option.

The NFT metadata

We pulled the metadata earlier for our super rare Bored Ape Yacht Club #7678, let’s take a look:

{
  "image": "ipfs://QmXtfhV4LEGCRVvRRa788k5wN49rShvSv2yUgtgpJMfNsH",
  "attributes": [
    {
      "trait_type": "Background",
      "value": "Purple"
    },
    {
      "trait_type": "Eyes",
      "value": "Robot"
    },
    {
      "trait_type": "Hat",
      "value": "King's Crown"
    },
    {
      "trait_type": "Fur",
      "value": "Cheetah"
    },
    {
      "trait_type": "Clothes",
      "value": "Sailor Shirt"
    },
    {
      "trait_type": "Mouth",
      "value": "Bored Unshaven Pizza"
    }
  ]
}

Not much! The metadata is a simple JSON string. It contains a link to the NFT’s image with 6 categories of attributes. Impressive in its simplicity. How much data is that?

344 bytes when we ignore whitespace. Now this seems like something we can store on chain. How much according to our calculations above?

625 gas/byte * 344 bytes = 215000 gas

90 gwei per unit * 215000 units = 0.01935 eth = $84.17

It’s a massive reduction in size compared to the image, but $84.17 per property sheet is still not cheap. For BAYC, at 10,000 NFTs for the contract, this would have been $840k. It’s amazing how things add up.

Clearly we should not store these files directly as strings. If anything, we will need a function that generates the strings within the smart contract. Now things start getting complicated.

Why Off Chain?

It should seem pretty obvious at this point why we would want to store these things off chain.

Cost - this is the core of most reasons for storing metadata off chain, and also the official reason given in the ERC-721 Spec metadata section:

Alternatives considered: put all metadata for each asset on the blockchain (too expensive)

Flexibility - you can deploy your contract once, point it at your metadata file, and never update your contract again. Any updates to the JPEG url or properties of the NFT can be done by updating the metadata file without any cost. If this was stored on chain, you would need to pay to write any changes to your contract.
Complexity - because you can’t just store these files raw on the blockchain, we need intelligent schemes to baked into our smart contract to generate the image or metadata tied to the NFT. See below for a project doing just that.
Risk - the logic in your deployed contract on chain is immutable. Many projects are hit by bugs in that logic. There is a risk that the bug cannot be fixed without redeploying your contract and forcing all users to migrate to a new contract, which they may or may not do. Many projects instead die this way. The more code on chain, the greater risk you’ve injected a project ending bug.

It makes perfect sense why we would store our assets and metadata off-chain, but is it possible to store your metadata on-chain? Certainly! The most interesting example I have found is from the Anonymice project. They abide by the ERC-721 spec, which requires metadata be stored in the NFT at the tokenURI property which contains a string of JSON conforming to this schema:

{
    "title": "Asset Metadata",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Identifies the asset to which this NFT represents"
        },
        "description": {
            "type": "string",
            "description": "Describes the asset to which this NFT represents"
        },
        "image": {
            "type": "string",
            "description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive."
        }
    }
}

Which as you can see, the Bored Ape metadata schema gets close to matching as well.

How do the Anonymice do it? They generate a base64 encoded string of the metadata file at the tokenURI, instead of a link to a JSON file on an IPFS server. Smart! You can read about their tactics on their blog, where it is very well explained.

They do need to be clever, because base64 encoding which will actually increase our size by about 33%. In fact, our Bored Ape PNG from above increases from 255kb to 340kb with encoding. So we cannot just store pure base64 encoded images unless we want to pay millions of dollars.

On Chain vs Off Chain?

So what should you do for your project? I love storing and doing as much on chain as possible. I personally start with everything on chain, with links to renders or shortcuts on IPFS as a practical solution. But as we know, IPFS is not forever. Ideally your source of truth can live on chain. It will take clever coding solutions to store these things on chain without making your contract deployment prohibitively expensive or complex.

What happens when you mint an NFT?

spat.eth — Fri, 29 Oct 2021 21:11:26 GMT

So you’ve decided you want a CryptoKitty, a Bored Ape, maybe even a Punk! The JPEG is cool, but what actually happens under the hood? Well the mechanics underlying your NFT can actually be very different for each project.

In this series, we’ll start off with a general TLDR for how most NFT projects work (scroll down if the anticipation is killing you). They follow similar principles which can be interesting if you want only a surface level understanding.

For those who need to understand the fundamentals of a thing, we will next dive deeper. The only way to understand the first principles of an NFT is to look at the smart contract that controls it. Diving into projects running on the Ethereum network, we will break apart the Solidity code of each smart contract. They are surprisingly easy to understand. Short and simple contracts are able to implement powerful concepts.

The series will progress from the earliest projects like CryptoPunks and Mooncats, through the NFT721 standard, into the PFP era led by Bored Ape Yacht Club, and into generative works like ArtBlocks.

This is an investigation I’ve done myself as research for building my own NFT collections. I’ve tried to learn the pros and cons of various techniques to determine the best contract construction. If you’re building your own project, or just want to understand the details of NFTs you’re spending thousands of dollars on for your own collection, I hope this exploration will help inform you.

I found it surprisingly hard to find any information on how these contracts are broken down, so in the spirit of open and decentralized information, I can pass the research on. The sooner we can understand these building blocks, the sooner we can use them to build even higher.

An amazing property of this NFT era is that the entire blockchain is public and free to read. This is what gives us the ability to crack open the smart contract on any NFT and learn all about it. If you follow along, you’ll also learn the techniques for analyzing these contracts yourself for any future NFTs you want to investigate yourself.

Smallest NFT TLDR that still gives you the important insights

Let’s start off with Bored Ape Yacht Club (BAYC) to highlight the basics. We’ll follow up in the next post with a deeper dive into their smart contract.

At the highest level, a project like BAYC has a single Solidity contract that represents the entire collection. Here it is!

The team at BAYC wrote this contract, then published it onto the Ethereum blockchain.

So what happens when you mint? It looks like this:

Each person will use their Ethereum account (through a wallet like MetaMask) to call a mint function on the project’s smart contract. Specifically for BAYC, you call a function called mintApe on that contract. Here’s what the function looks like using Etherscan to explore the functions we have available from the contract.

The mintApe function will no longer work, because the project minted all 10,000 NFTs long ago (long ago… in NFT terms, this was actually only a few months ago).

Assuming you could call mintApe, what would happen? It’s not very complicated. We can even look at code:

_holderTokens[to].add(tokenId);

emit Transfer(address(0), to, tokenId);

You need only a simplistic understand of how programming works to see what’s happening here. In the first line, to is your Ethereum account address. It gets stored in a map called _holderTokens. Your address points to the tokenId (your ape’s Id), which you minted. That’s all that gets saved. It’s all stored on the contract. That’s almost it.

I said almost because there’s one more imporant thing that happens. The contract will send an event out to the Ethereum network with your address and the token you purchased. Now that’s really it.

So when you mint, does anything actually get sent to you or your wallet? No! It feels counter intuitive because of the way applications show us our NFTs. It feels almost like we do physically hold them in our wallets. But this follows the same principles of how the blockchain itself works. There’s just the blockchain. A big ledger. We’re recording line items in a registry that says who owns what. The only record of your NFT ownership is the entery in the BYAC smart contract referencing your Ethereum account address to the NFT token ID and a fired event. Amazing!

It is also interesting to think about how an aggregator like OpenSea can show the NFTs which have been recorded against your Ethereum account address. There is no way they could scan all smart contracts of all projects ever created. Also, they would need to constantly be scanning for any transfers of ownship. Instead, they watch all events and keep their own database of ownership.

We’ve only scratched the surface of what an NFT is. What about the JPEG? Where is it stored? How is it linked to your address or token ID? We’ll need to explore further. This is where things start to deviate between projects. Some may store your image on centrally controlled systems like AWS, others using decentralized external storage like IPFS, while other try to remain pure and store it directly in the smart contract itself. We’ll continue on with our BAYC exploration next to see how they do it.

OK, the real NFT TLDR

To wrap it up, what is an NFT then?

Recording of your Ethereum address with your NFT’s token ID in the smart contract of the NFT project.
An event fired by the project’s Smart Contract.

That’s it!

Done for now, until we dive deeper.