Learn how to use thirdweb to build a NFT Lootbox app

We're going to build a cool full-stack quiz app that rewards correct answers with lootboxes that can be opened to reveal fancy NFTs! When you complete this tutorial you'll get this badass NFT plus 5 $MATIC:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_SQ1G-dOv7dXdrwX9w4b8i" uploadmode="upload"></image><image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_A4mW-JYR5BnTw3_0FKSEa" uploadmode="upload"></image><image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_-zYW6GD-NMgfqQbtGv7ML" uploadmode="upload"></image><image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_KqbKu8T0k7kPoI63_SgrK" uploadmode="upload"></image><image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_8OhovWfd-ZJ-Gmfv46teC" uploadmode="upload"></image>In the process, you'll learn all about NFTs, the super-awesomeness that is thirdweb and loads more!<h3></h3><h3 id="prerequisites">Prerequisites</h3>You’ll need to be familiar with web development. If you’re already a web developer, it should be pretty straightforward to follow along!No prior experience with blockchain development is required, though it would help your understanding if you’ve played with it before. We’re not going to be writing any solidity though, we’ll be able to do everything with Javascript thanks to thirdweb!Tools:<ul><li>A code editor — VSCode or your preferred editor should work fine! If you open our repo using VSCode you’ll get recommended some plugins. They’re optional but should help!</li><li>MetaMask — a Wallet for interacting with your Ethereum account</li></ul><h3>What we're building</h3>We’re building a simple quiz web app that rewards users with a lootbox when they answer questions correctly. They'll be able to open that lootbox to reveal one of our NFTs at random. We’ll also build a fancy page where users can see the NFTs they’ve won and restrict that page to only holders of our NFTs.BTW if you’re not familiar with NFTs, they’re digital assets that can be held in Ethereum wallets (and others). The cool thing is that even though our quiz app will be the one rewarding users with them, they’ll be owned by the user and not locked to our app.By the end of it, you'll have a deployed project that's ready to share with friends.Let's get to it!<h2>Why thirdweb?</h2>Thirdweb makes developing web3 applications way easier. They’ve written a bunch of really cool smart contracts which we can deploy, own, and control. In this tutorial, we’ll use these contracts and won’t need to write any smart contract code ourselves!We’re also going to use their SDK to interact with the contracts from our web app, which is much more straightforward than you might have seen before.Most of thirdweb is also open source! The most relevant repos for us will be:<ul><li>Smart contracts that they deploy for us: <a target="_blank" rel="noopener noreferrer nofollow" class="link link link link" href="https://github.com/nftlabs/nftlabs-protocols">https://github.com/nftlabs/nftlabs-protocols</a></li><li>Typescript SDK: <a target="_blank" rel="noopener noreferrer nofollow" class="link link link link" href="https://github.com/nftlabs/nftlabs-sdk-ts">https://github.com/nftlabs/nftlabs-sdk-ts</a></li></ul>It’s also worth joining their discord, they’re really helpful! <a target="_blank" rel="noopener noreferrer nofollow" class="link link link link" href="https://discord.gg/thirdweb">https://discord.gg/thirdweb</a> Next up, setting up your project! Let's get to it 🚀

Welcome to NFT Lootbox 🎉

In this section, you'll get your project set up and ready to work on!<h3>Install Metamask and setup Ethereum Wallet</h3>We have a tutorial on how to set up Metamask to use with an Ethereum wallet. <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://www.pointer.gg/tutorials/Setting-Up-Your-Wallet">You can check it out here →</a><h3>Request Test MATIC</h3>For this tutorial, we’re going to be using the Polygon Mumbai network, which is a test network for Polygon. We’re not going to go into a lot of detail about Polygon here, but we’re using it because it makes things cheaper later on. Polygon uses a token called MATIC for its gas fees instead of ETH. It uses the same address as Ethereum and everything is compatible.As a bonus, if you want to deploy this (or anything else) to a real network, Polygon mainnet is a lot cheaper than Ethereum mainnet!Just like we can with Ethereum testnets, we can just ask for some MATIC on the Polygon Mumbai testnet. It also seems to be much more reliable than the Ethereum equivalents which is nice! The official faucet is <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://faucet.polygon.technology">https://faucet.polygon.technology</a>. Make sure both Mumbai and MATIC Token is selected and paste in your wallet address:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_JcRokrUXIpeMMpuZ1NOgI" uploadmode="upload"></image>You can add Polygon Mumbai network to your MetaMask wallet so that you can see your MATIC balance.<h3>Add Polygon Mumbai to MetaMask</h3>MetaMask by default only shows Ethereum networks. But as we mentioned, Polygon is fully compatible. So we can add the Polygon Mumbai network to MetaMask to see our MATIC balance for each address. Click the button below and MetaMask will prompt you to add it:<chain blockchain="ethereum" network="rinkeby"></chain><h3>Download repo</h3>The repo for this project is located here → <url href="https://github.com/pointer-gg/thirdweb-lootbox-tutorial" rendertype="link" content="https://github.com/pointer-gg/thirdweb-lootbox-tutorial"></url>To clone the project locally run:<pre filepath=""><code class="language-bash"> git clone https://github.com/pointer-gg/thirdweb-lootbox-tutorial</code></pre><h3>Install dependencies</h3>Run the following command inside the project repo to install our dependencies:<pre filepath=""><code class="language-bash">npm install</code></pre><h3>Start the project</h3>Run the following command to start the next.js dev server:<pre filepath=""><code class="language-plaintext">npm run dev</code></pre>After starting the project visit <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="http://localhost:3000">localhost:3000</a> and you should see the starting point for our project!You'll be developing against this repo throughout the tutorial.Once you have the project running locally, and Metamask setup, proceed to the next step! <h2>Creating our project in thirdweb</h2>A thirdweb project is a container for multiple related smart contract modules. It’s also a smart contract itself! Everything in thirdweb is done within a project, so we’ll start by creating one.Go to <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://v1.thirdweb.com/dashboard">the thirdweb dashboard</a> and you should see a button to create a new project:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_N9bTq45TLTvmrteNPZ0IX" uploadmode="upload"></image><callout color="purple">Note that we're currently using thirdweb's v1 dashboard for this tutorial. </callout>You’ll be asked which network to use, as mentioned earlier we’re going to use Polygon Mumbai:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_tGEDDfgjZqvuKp8IHiu6r" uploadmode="upload"></image>Enter a name and optional description, and click Create. Note that since we’re deploying smart contracts you’ll be asked to confirm transactions, these small gas fees will be covered by the test MATIC that we got earlier.You just deployed your first contract using thirdweb! 🎉You should see a screen including your project’s address, which you can click to copy:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_ukTQUn9L6rru7ktBk9UZz" uploadmode="upload"></image>This is the address of the contract that thirdweb have deployed for you, and which you own and control.You can view it in polygonscan (Polygon’s equivalent of etherscan, a way to explore addresses): <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="http://mumbai.polygonscan.com">mumbai.polygonscan.com</a>. For example, here’s one of mine:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_d0OFKwf3KjvNsTRT_ViM7" uploadmode="upload"></image>

Project setup

You might be familiar with lootboxes in video games, where they can be opened to give one or more random in-game items. We’re going to do the same thing with NFTsA lootbox is going to act as a wrapper for what thirdweb calls a “Bundle Collection” - that is a collection of multiple NFTs where each NFT can have multiple copies. The number of copies of each NFT is customizable, so you can have some that are more rare than others by changing the number of them. Note that this is a bit different from many NFT collections where each piece is unique.So we’re going to create and mint a bundle collection in thirdweb. And then we’re going to deploy a Pack and configure it to contain the NFTs from the bundle collection. When a copy of the pack is opened, it’ll reveal one of the NFTs from the bundle at random. The randomness here is super important and we’ll come back to it!As an example, let’s say our bundle collection contains NFTs A and B, and there are 70 of A and 30 of B. So our total bundle size is 70 + 30 = 100, meaning we can open the pack 100 times. The way to think about a pack being opened is that a random number is generated between 1-100. If that number is 1-70 then the pack reveals NFT A, and if that number is 71-100 then it reveals NFT B. So the number of NFTs of each kind in the bundle determines the probabilities of which NFT will be revealed.<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_tDR2ct7snnL2MyzT-1ALX" uploadmode="upload"></image>If you’d like to read more you can check out <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://thirdweb.com/portal/learn/modules/pack">thirdweb’s pack documentation</a> - it’ll become clearer as we build this out!

How does a lootbox work?

Creating our NFTs using thirdweb

Let’s start building our web app that will make use of the thirdweb contracts that we just deployed. If you haven’t yet, start the app:<pre filepath=""><code class="language-bash">npm run dev</code></pre>If you already have it running, restart it - otherwise Next won't pick up the <code class="inline-code">.env</code> file and you'll get weird errors when we try to use that later!It’ll run on <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="http://localhost:3000">localhost:3000</a> by default. You should see something like this:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_mZP3W-3Re0WYsr3BeyXfn" uploadmode="upload"></image>We’ve included quite a bit of starting code here so that we can focus on the lootbox aspect of this app.The main functionality is the quiz mechanic, which uses an API route to check the answer given and then reflects the result:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_mAwSSEXZuTciPh5RBMZJk" uploadmode="upload"></image><image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_4-XHj3JMvK71zZOgnuF8_" uploadmode="upload"></image>Notice that when the answer is correct the message indicates that the user will receive a pack. That’s referring to the packs that we created using thirdweb previously. That won’t work yet, but we’re going to work on that next!We’re not going to go into detail on all this started code, but feel free to look around and see what’s going on. Some areas that you might like to review are:<ul><li><code class="inline-code">lib/questions.ts</code> which contains our questions. Feel free to change them to match the theme you chose for your NFTs!</li><li><code class="inline-code">components/quiz-question.tsx</code> is the quiz question component. It handles displaying the question, submitting the user’s answer, and displaying the result. We’re not going to need to do much work here, but it’s worth making sure you understand what’s going on!</li><li><code class="inline-code">pages/api/check-answer.ts</code> is the API route used to check an answer. We’re going to be doing a lot of work here!</li></ul><callout color="fuchsia">This is a good time to change the questions to match your theme. It'll be way more fun!</callout>We also have a /lounge page that doesn’t really do anything yet:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_e5mII7gux1pxB2Y8J1G6d" uploadmode="upload"></image>We’re going to make this page display the packs that users have received, and the NFTs they received from opening them. We’re also going to token gate this page so that only users with some of our NFTs can see the secret content on it! But we’re getting a bit ahead of ourselves...

Introducing our quiz app

The first thing that we need to add is a way for our users to log in to our app using their Ethereum wallet. This will unlock the functionality we need - we’ll be able to display their packs and NFTs and we’ll be able to send NFTs to their address.We’re going to use thirdweb’s React SDK for this. This gives us access to the same component that they use on their website and allows us to easily support multiple wallets/chains if we need to. We’re going to keep it simple here, but there’s a lot of flexibility in their connect button!First, let’s install the react SDK:<pre filepath=""><code class="language-bash">npm install @3rdweb/react</code></pre>Next, we need to add the <code class="inline-code">ThirdwebProvider</code> to our app. This will make thirdweb functionality available to all its children. As we’re in Next we’ll add to our <code class="inline-code">pages/_app.tsx</code>. First, we need to add the import:<pre filepath=""><code class="language-typescript">import { ThirdwebProvider } from "@3rdweb/react";</code></pre>And then we can add it to our <code class="inline-code">MyApp</code> component:<pre filepath=""><code class="language-typescript">export default function MyApp({ Component, pageProps }: AppProps) {
 // Polygon Mumbai chain ID is 80001, see https://chainlist.org
 const supportedChainIds = [80001];

 // We'll only support MetaMask which is an injected connector
 const connectors = {
 injected: {},
 };

 return (
 &lt;&gt;
 &lt;Head&gt;
 &lt;title&gt;{pageProps.title}&lt;/title&gt;
 &lt;/Head&gt;
 &lt;ThirdwebProvider
 connectors={connectors}
 supportedChainIds={supportedChainIds}
 &gt;
 &lt;Layout title={pageProps.title}&gt;
 &lt;Component {...pageProps} /&gt;
 &lt;/Layout&gt;
 &lt;/ThirdwebProvider&gt;
 &lt;/&gt;
 );
}</code></pre>The <code class="inline-code">ThirdwebProvider</code> requires 2 props:<ul><li><code class="inline-code">connectors</code> is a definition of which wallets we want to support. We’re just going to use MetaMask which is an injected wallet.</li><li><code class="inline-code">supportedChainIds</code> is a list of chain IDs that we want our app to support. We need to be able to talk to the contracts that we deployed on the Polygon Mumbai network, so that’s the only chain we’ll support for now. A great resource for finding chain IDs is <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="http://chainlist.org">chainlist.org</a></li></ul>Now all pages of our app will be able to access the thirdweb functionality. Let’s start by adding a connect wallet button!We’ll add the connect wallet button into our top navbar, which is defined in <code class="inline-code">components/navbar.tsx</code>. First add the import:<pre filepath=""><code class="language-typescript">import { ConnectWallet } from '@3rdweb/react'</code></pre>And then let’s add the connect button into our navbar:<pre filepath=""><code class="language-typescript">return (
 &lt;nav className="font-sans flex justify-between pt-4 pb-20 px-4 md:px-20 w-full h-10 "&gt;
 &lt;div className="flex gap-4 md:gap-10"&gt;
 &lt;Link href="/"&gt;&lt;a className="text-2xl no-underline text-grey-darkest hover:text-blue-900"&gt;Quiz&lt;/a&gt;&lt;/Link&gt;
 &lt;Link href="/lounge"&gt;&lt;a className="text-2xl no-underline text-grey-darkest hover:text-blue-900"&gt;Winner's Lounge&lt;/a&gt;&lt;/Link&gt;
 &lt;/div&gt;
 &lt;ConnectWallet /&gt;
 &lt;/nav&gt;
 )</code></pre>Now we’ll see a connect wallet button in our navbar:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_H0QgkeVY88Cd9pt6XcESh" uploadmode="upload"></image>If we click it and connect with MetaMask then we’ll see a nice connected state:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_ndQnUg4qYFMbaukycAE2P" uploadmode="upload"></image>Awesome! We’re able to log in to our app using thirdweb’s connect wallet button. Next, we’ll see how to access and use that connected address within our app.

Log in with Ethereum

Currently, our API route at <code class="inline-code">/api/check-answers</code> is just returning when we submit a correct answer:<pre filepath=""><code class="language-typescript">...

// Check the answer, return if incorrect
if (body.answerIndex !== question.correctAnswerIndex) {
 res.status(200).json({
 kind: "incorrect",
 correctAnswerIndex: question.correctAnswerIndex as number,
 });
 return;
}

// If we get here then the answer was correct

// TODO: send the reward!

res.status(200).json({
 kind: "correct",
});</code></pre>We want to have it transfer one of the packs to the user who has sent a correct answer. It’s going to look something like this:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_M8QYmn2IP4a9Uicz9VgCw" uploadmode="upload"></image><ul><li>The web app makes an API call to <code class="inline-code">/api/check-answer</code> (we already have this)</li><li>If the answer is correct then a request is made to transfer a pack to the user</li><li>The API returns without the transfer completing, because blockchain transfers are quite slow and we don’t want to keep the user waiting</li><li>When the transfer is completed the web app receives an event and we can use that to notify the user</li></ul><h3>Sending our address from the app</h3>First, we’re going to need to send the address when we make the API call. Let’s look at how we can get the connected address using thirdweb hooks. We need to install them:<pre filepath=""><code class="language-bash">npm install @3rdweb/hooks</code></pre>The hook that we’re going to use is called <code class="inline-code">useWeb3()</code>. It’s available anywhere that we have the thirdweb context, so anywhere inside our <code class="inline-code">&lt;ThirdwebProvider&gt;</code>. For now, we’ll just use the address from it, but we’ll see what else we can use it for later on.In <code class="inline-code">components/quiz-question.tsx</code> add the import:<pre filepath=""><code class="language-typescript">import { useWeb3 } from "@3rdweb/hooks"</code></pre>And at the top where we have our useState calls, add a new one to get the address from <code class="inline-code">useWeb3</code>:<pre filepath=""><code class="language-typescript">const { address } = useWeb3();</code></pre>Since we want to send a lootbox as a reward for correct answers, let’s stop users from taking our quiz without connecting their wallet. Near the top, just after the useState calls add a check:<pre filepath=""><code class="language-typescript">if (!address) {
 return &lt;p&gt;Please connect your wallet to take the quiz!&lt;/p&gt;
}</code></pre>Now you should see that the quiz UI is only displayed when we have a connected account. If you disconnect using MetaMask then you should see this message displayed instead. Now we know that we have an address whenever the user is taking the quiz!Now we need to pass that address to our <code class="inline-code">/api/check-answer</code> call. The API call is made in <code class="inline-code">handleSubmit</code>, we need to add the address to the payload:<pre filepath=""><code class="language-typescript">const payload: CheckAnswerPayload = {
 address,
 questionIndex,
 answerIndex,
};

const checkResponse = await axios.post("/api/check-answer", payload);</code></pre>TypeScript is going to be upset with this! We’ll need to add <code class="inline-code">address</code> to <code class="inline-code">CheckAnswerPayload</code>. Just ignore it for now, we’ll fix it in a minute.Open up DevTools to the network tab and submit an answer to your quiz. Make sure that you see your connected address being sent:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_jAgNiI-k8WuYKkp_cKtqD" uploadmode="upload"></image>Great, so we’re able to send our address! But an important note here is that our API can’t trust this address. We could pass any arbitrary address in, and our API would send it the pack instead of us. That’s not really a big deal here, but what if our API was charging for usage? We wouldn’t want people to be able to make requests as other users!Fortunately, there’s a solution for this: we can have our app sign a message containing the address. This will cause MetaMask to (with the user’s permission) use their private key to sign it, and we’ll receive that signature. Only the owner of the address can sign a message! Our API will then be able to use the message that was signed + the signed message to identify the address that signed it. So now we’re not sending our address in a way that can be forged, and our API can trust the address that it computes.Here’s how the process works:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial__YsSgCogYoejLb82N0gum" uploadmode="upload"></image>Let’s update our app to use this process!Back in <code class="inline-code">components/quiz-question.tsx</code>we need to additionally get the provider from the useWeb3 hook:<pre filepath=""><code class="language-typescript">const { address, provider } = useWeb3()</code></pre>The <code class="inline-code">provider</code> represents a read-only connection to the blockchain network, in our case that’ll be the Polygon Mumbai test network. It’s a <code class="inline-code">Provider</code> object from the <code class="inline-code">ethers</code> library, you can find further documentation here: <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://docs.ethers.io/v5/api/providers/provider/">https://docs.ethers.io/v5/api/providers/provider/</a>Inside <code class="inline-code">handleSubmit</code>, let’s add a new invariant under the existing one:<pre filepath=""><code class="language-typescript">invariant(provider !== undefined, "Provider must be defined to submit an answer")</code></pre>Here we’re just making sure that <code class="inline-code">provider</code> is defined. It will be as long as the user’s wallet is connected!Now let’s look at how to sign a message and add it to our API payload:<pre filepath=""><code class="language-typescript">const message = "Please sign this message to confirm your identity and submit the answer.This won't cost any gas!"
const signedMessage = await provider.getSigner().signMessage(message)

const payload: CheckAnswerPayload = {
 questionIndex,
 answerIndex,
 message,
 signedMessage,
};</code></pre>Here we’re asking the user’s wallet to sign the <code class="inline-code">message</code>. Note that when we call <code class="inline-code">provider.getSigner()</code> we get a signer, which represents an account and can be used to take actions on behalf of that account. Here we’re using it to sign messages as the user. We pass both the message and the signed message to the API - remember from the above diagram that we need both to get the address that signed the message.Now if you answer a quiz question you should first see MetaMask ask you to sign the given message:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_oSPBYp3_xz3MsuIuQDOg5" uploadmode="upload"></image>As our message says, this doesn’t cost any gas and in fact, it doesn’t write to the blockchain or make any transactions at all. It’s just cryptography!And now our request payload should look something like this:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_q9eTqALA6SXkLk7Jq81iL" uploadmode="upload"></image>Great! Now we’re ready to get our API making sense of these new fields!<h3>Sending a pack from the API</h3>Let’s jump back into our API <code class="inline-code">pages/api/check-answer.ts</code>First, we can make Typescript happy by adding those new fields to our API’s payload type:<pre filepath=""><code class="language-typescript">export type CheckAnswerPayload = {
 questionIndex: number;
 answerIndex: number;
 message: string;
 signedMessage: string;
};</code></pre>Now we need to get the address that signed <code class="inline-code">message</code> to produce <code class="inline-code">signedMessage</code>. The library <code class="inline-code">ethers</code> provides a utility function for dealing with this.Add this where we have the validations, after <code class="inline-code">const body = req.body as CheckAnswerPayload;</code>:<pre filepath=""><code class="language-typescript">let address = ""
 try {
 address = ethers.utils.verifyMessage(body.message, body.signedMessage)
 } catch (err) {
 res.status(400).json({
 kind: "error",
 error: `Unable to verify message: ${err}`,
 });
 return;
 }</code></pre>You’ll need to add an import:<pre filepath=""><code class="language-typescript">import { ethers, BigNumber } from "ethers"; </code></pre><code class="inline-code">ethers.utils.verifyMessage</code> takes a message and a signature, and returns the address that signed the message to produce the signature. If <code class="inline-code">signedMessage</code> isn’t a valid signature then it’ll throw an error. Since we won’t be able to know which address to send the reward to, we’ll treat this as an error condition and return.One last piece of admin, we’re going to need our pack contract address to transfer a pack. You’ll have that in your scripts from the first section, or you can copy it from thirdweb.Create a new file <code class="inline-code">lib/contractAddresses.ts</code> and add your contract address there:<pre filepath=""><code class="language-plaintext">export const bundleAddress = '0x...';
export const packAddress = '0x...';</code></pre><callout color="green">I've added the <code class="inline-code">bundleAddress</code> too. We don't need that yet but we will soon</callout>Back in <code class="inline-code">pages/api/check-answer.ts</code> add the import:<pre filepath=""><code class="language-plaintext">import { packAddress } from "../../lib/contractAddresses";</code></pre>And now we're ready to send a pack!At the bottom of our function where we have that TODO let’s add our code to initiate the transfer:<pre filepath=""><code class="language-typescript">// If we get here then the answer was correct

// Initialize the Thirdweb SDK using the private key that owns the wallet
const sdk = new ThirdwebSDK(
 new ethers.Wallet(
 process.env.WALLET_PRIVATE_KEY as string,
 // Using Polygon Mumbai network
 ethers.getDefaultProvider("https://rpc-mumbai.maticvigil.com/")
 ),
);

// Transfer a copy of the pack to the user
console.log(`Transferring a pack to ${address}...`);
const packModule = sdk.getPackModule(packAddress);
const packTokenId = '0';
// Note that this is async
packModule.transfer(address, packTokenId, BigNumber.from(1));

res.status(200).json({
 kind: 'correct',
});</code></pre>You'll need to import the <code class="inline-code">ThirdwebSDK</code>:<pre filepath=""><code class="language-typescript">import { ThirdwebSDK } from "@3rdweb/sdk";</code></pre>A lot of this code should look familiar from the scripts that we wrote earlier to interact with thirdweb. We’re initializing the SDK in the same way. Note that Next has something like dotenv built-in, so in API routes <code class="inline-code">process.env.WALLET_PRIVATE_KEY</code> is set from the same local .env file that we used earlier.We initialize a transfer by calling <code class="inline-code">packModule.transfer(address, packTokenId, BigNumber.from(1));</code> and then we return a correct response to the user. Note that this works because the account associated with the <code class="inline-code">WALLET_PRIVATE_KEY</code> owns all instances of the packs, so it can transfer one to the user.Now you should be able to test this out! Take your quiz again and submit a correct answer. You should see in the terminal logs where Next is running:<pre filepath=""><code class="language-bash">Transferring a pack to 0x(your address)...</code></pre>Currently, our UI doesn’t have any way to know that we now own a pack, we’ll get to that! But this is a blockchain transaction so we can check the source of truth, in this case <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="http://mumbai.polygonscan.com">mumbai.polygonscan.com</a>. Search for your pack contract address, and you should see a transaction with the method SafeTransferFrom:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_kO8gM8xxj__fqawus7oXV" uploadmode="upload"></image>And you should also see an event:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_AnhxjsW7Dww5gtCaWmApR" uploadmode="upload"></image>The event type is <code class="inline-code">TransferSingle</code>, and you should notice that <code class="inline-code">topic3</code> (which the signature indicates is <code class="inline-code">address to</code> ) is your address.So our pack contract is emitting an event that identifies a transfer has been made to our address. We’re going to listen for that event and notify users that they’ve received a pack from us.This means that our API returns before the transfer and the user can continue with our quiz straight away, but we’ll let them know when the transfer is complete.

Adding a lootbox reward

At this point, we are transferring a pack to the user when they answer a question completely. You can verify this if you like - check your address on Opensea (you might need to check hidden). But we’re not yet giving the user any feedback when the pack is transferred to them. Let’s fix that! Our app is going to listen for that event that we just saw the contract send.We’re going to use the <code class="inline-code">ethers</code> library to create a <code class="inline-code">Contract</code> object, which we can add event handlers to. We don’t need to write any WebSocket code or any solidity code to make this work. This is a great example of how thirdweb contracts are just normal contracts that we can interact with like any others.The interface for creating a Contract is:<pre filepath=""><code class="language-typescript">const packContract = new ethers.Contract(
 address,
 contractInterface,
 providerOrSigner
)</code></pre>We already know the address of our pack contract. That second parameter is new, we need to provide a contract interface that describes all the functions/events/data types etc. associated with our contract For the third parameter we’ve already seen both providers and signers, we can use a provider here because read-only access to the contract is sufficient to receive its events. We’ve not logged into polygonscan after all, and we can see the events there!The term used for the contract interface is ABI, which stands for Application Binary Interface. When we’re writing our own contracts using hardhat the ABI is one of the files generated, and it’s in JSON format. Of course, we didn’t write our thirdweb contract so we don’t have this file locally. Fortunately, thirdweb makes it super easy to get it!If you browse the thirdweb dashboard to your pack, you’ll see a Code tab:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_Lom-TjCsfMrbTAyX0e_xT" uploadmode="upload"></image>This shows snippets of SDK code that can be used to interact with the contract. Every module in thirdweb has this tab and it can be super useful! If you scroll to the bottom you’ll see a button to copy the ABI:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_nMtrViRsLfYqq3v0oWvlk" uploadmode="upload"></image>That’ll copy the JSON, we’re going to put it in a file where we can import it in our app. Create a new file <code class="inline-code">utils/PackABI.json</code> and paste the copied ABI there. Now we have everything that we need to listen for pack events!We’re going to write our logic in a custom hook. Add a new file <code class="inline-code">hooks/usePackEvents.tsx</code><pre filepath=""><code class="language-typescript">import { ethers } from "ethers";
import type { ContractInterface } from "ethers";
import { useEffect } from "react";
import { packAddress } from "../lib/contractAddresses";
import packABI from "../utils/PackABI.json";
import { useWeb3 } from "@3rdweb/hooks";

export default function usePackEvents() {
 const { address, provider } = useWeb3();

 useEffect(() =&gt; {
 if (provider) {
 const abi = packABI as ContractInterface;
 const packContract = new ethers.Contract(packAddress, abi, provider);
 packContract.on("TransferSingle", (_operator, _from, to, _id, _value) =&gt; {
 if (to === address) {
 console.log("We received a pack!")
 }
 });
 }
 }, [!!provider]);
}</code></pre>Let’s go through this a bit.<ul><li>We’re getting the <code class="inline-code">address</code> (this is the connected wallet, not any contract) and <code class="inline-code">provider</code> from <code class="inline-code">useWeb3</code> as we’ve seen before. This gives us the address/connection from the thirdweb connect wallet button</li><li>We’re using a <code class="inline-code">useEffect</code> so this logic only runs on the client.</li><li>We’re reading our <code class="inline-code">utils/PackABI.json</code> as the contract interface. Note that if you’ve exported an ABI before you might be used to doing <code class="inline-code">packABI.abi</code>, we don’t need to do that here because thirdweb only gives us the <code class="inline-code">abi</code> contents.</li><li>We add an event listener using <code class="inline-code">packContract.on</code> . The event we’re listening for is called <code class="inline-code">TransferSingle</code> and we can see its arguments from the polygonscan event that we saw earlier. In our case, we’re only concerned about the <code class="inline-code">to</code> address.</li><li>This will detect <code class="inline-code">TransferSingle</code> events sent to any address, so to make sure we only notify the user about theirs we check <code class="inline-code">if (to === address)</code></li><li>The dependency array <code class="inline-code">[!!provider]</code> means we’re only going to add the event handler when <code class="inline-code">provider</code> goes from unset to set.</li></ul>We’ll add our hook to the <code class="inline-code">components/layout.tsx</code> because we know that’s inside our <code class="inline-code">&lt;ThirdwebProvider&gt;</code> and therefore has access to the connected wallet.Add the import:<pre filepath=""><code class="language-typescript">import usePackEvents from "../hooks/usePackEvents";</code></pre>And add it to the top of the component:<pre filepath=""><code class="language-typescript">export default function Layout({
 children,
 title,
}: React.PropsWithChildren&lt;Props&gt;) {
 usePackEvents();

 return (
 /* no change */
 );
}</code></pre>Now all of our pages will load the event handler. If you answer a quiz question correctly then you should see this event trigger within about 30 seconds:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_UhGep4egEPFVapeYIoryY" uploadmode="upload"></image>Nice! Let’s change it to a fancy toast notification that we can display to the user. You can do whatever you like though!We’ll use <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://react-hot-toast.com/">react-hot-toast</a>:<pre filepath=""><code class="language-plaintext">npm install react-hot-toast</code></pre>To display toast notifications we need to add the <code class="inline-code">&lt;Toaster /&gt;</code> component to our app. We’ll add it to <code class="inline-code">pages/_app.tsx</code> since it can be right at the top of our component tree.Import it:<pre filepath=""><code class="language-typescript">import { Toaster } from "react-hot-toast";</code></pre>And add it to the component:<pre filepath=""><code class="language-typescript">return (
 &lt;&gt;
 &lt;Toaster /&gt;
 &lt;Head&gt;
 &lt;title&gt;{pageProps.title}&lt;/title&gt;
 &lt;/Head&gt;
 &lt;ThirdwebProvider
 connectors={connectors}
 supportedChainIds={supportedChainIds}
 &gt;
 &lt;Layout title={pageProps.title}&gt;
 &lt;Component {...pageProps} /&gt;
 &lt;/Layout&gt;
 &lt;/ThirdwebProvider&gt;
 &lt;/&gt;
 );</code></pre>Nice! Now we can send a <code class="inline-code">toast</code> from anywhere in our app. Let’s add one to <code class="inline-code">usePackEvents.tsx</code>. First, we’ll import it, and also the Next Link component so that we can add a link to our toast:<pre filepath=""><code class="language-typescript">import { toast } from "react-hot-toast";
import Link from "next/link";</code></pre>Now update our event handler:<pre filepath=""><code class="language-typescript">if (to === address) {
 toast.success(
 &lt;div className="flex flex-col gap-2"&gt;
 &lt;p className="text-green-800"&gt;
 {" "}
 Congratulations! You were awarded a fancy cars pack!
 &lt;/p&gt;
 &lt;p&gt;
 View and open it in the{" "}
 &lt;Link href="/lounge"&gt;
 &lt;a className="underline hover:no-underline"&gt;lounge&lt;/a&gt;
 &lt;/Link&gt;
 !
 &lt;/p&gt;
 &lt;/div&gt;,
 {
 duration: 5000,
 }
 );
}</code></pre>And now when you answer a question correctly you’ll see a nice toast notification sent when the pack is received:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/74a9e8a6-6f70-4c59-90e0-6edadaec3461/tutorial_txVSUhmJSENe8aLOYT81I" uploadmode="upload"></image>Nice! Now our users are being notified when they receive a pack and prompted to go to the lounge to open it. Next, we’re going to build that lounge page to display the packs a user has received, and let them open a pack to reveal what’s inside!

Receiving packs

Building a token gated lounge

Our app has a long-running API route which is sending the packs in response to correct answers. While the API returns a result to the user quickly, behind the scenes it needs to stay alive long enough to successfully send the pack. This means that we can’t deploy our app to Vercel, because their free tier doesn’t keep API functions alive for long enough. If we try deploying to Vercel then we’ll find that our packs are never sent to users, which isn’t much fun!Instead, we’re going to deploy to the <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="http://fly.io">fly.io</a> free tier. Fly allows us to deploy any Docker image to their platform, and makes it super easy to run it in multiple locations if you need to - so you’re always close to users and super fast. They also have a nice free tier - we can run up to 3 instances 24/7 with none of the cold starts of Vercel, for free.We’ve included a Dockerfile for you so you don’t need to worry about it. It’s from the Next with-docker example here: <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://github.com/vercel/next.js/tree/canary/examples/with-docker">https://github.com/vercel/next.js/tree/canary/examples/with-docker</a>First, we need to install the Fly CLI. Their guide is <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://fly.io/docs/getting-started/installing-flyctl/">https://fly.io/docs/getting-started/installing-flyctl/</a> - it’ll just be a single line command to run but it’s different for different operating systems.<callout color="orange">One slightly confusing thing is that there’s a <code class="inline-code">fly</code> and <code class="inline-code">flyctl</code> command. They’re kinda interchangeable, but I’ll use the one they use in their docs here for each thing we do.</callout>Once you have the CLI installed you can create an account on Fly. Run <code class="inline-code">flyctl auth signup</code> . You can create an account with either an email + password or log in with Github if you prefer. Note that you will need to provide payment details, but you won’t be charged for anything we do here. If you already have an account with Fly you can log in using <code class="inline-code">flyctl auth login</code> instead.Now let’s create our app in Fly! Run fly launch and it’ll guide you through:<pre filepath=""><code class="language-bash">$ fly launch
Creating app in /Users/callummcintyre/projects/thirdweb-lootbox
Scanning source code
Detected a Dockerfile app
? App Name (leave blank to use an auto-generated name): lootbox-quiz
Automatically selected personal organization: Callum McIntyre
? Select region: lhr (London, United Kingdom)
Created app lootbox-quiz in organization personal
Wrote config file fly.toml
? Would you like to deploy now? No
Your app is ready. Deploy with `flyctl deploy`</code></pre>It’ll scan the directory and detect the Dockerfile that we’ll use to build the app. You can choose an app name, and then it’ll ask you to select a region - your closest city will be pre-selected and is a good choice! Then it’ll ask if you want to deploy, click N (which is the default) for now. We need to do a tiny bit of config before we deploy.You’ll have a new file called <code class="inline-code">fly.toml</code>. There’s nothing secret here, it can be checked in to git. It contains a section called services which should look something like this:<pre filepath=""><code class="language-plaintext">[[services]]
 http_checks = []
 internal_port = 8080
 processes = ["app"]
 protocol = "tcp"
 script_checks = []</code></pre>Change the <code class="inline-code">internal_port = 8080</code> to <code class="inline-code">internal_port = 3000</code>. This describes the port that our app runs on, which for Next is 3000 by default. That’s why we always access our app in development on <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="http://localhost:3000">localhost:3000</a> too!Final thing before we deploy - we need that <code class="inline-code">WALLET_PRIVATE_KEY</code> environment variable so that our API can send packs while running in Fly just like it does locally. We can add environment variables to the <code class="inline-code">fly.toml</code> but we definitely don’t want a private key in plaintext, so we’ll use Fly’s secrets feature instead. We can set secrets on Fly and they’ll be stored encrypted and made available to our app as environment variables. That’s exactly what we want here!Run:<pre filepath=""><code class="language-bash">$ flyctl secrets set WALLET_PRIVATE_KEY=...
Secrets are staged for the first deployment</code></pre>Awesome, now we can deploy! Run <code class="inline-code">fly deploy</code>Now depending on your local machine, it’ll work slightly differently. If you have Docker running locally then it’ll use that to build the Docker image using the Dockerfile, and then it’ll be pushed up to Fly. If you don’t have Docker running locally then it’ll use a remote builder in Fly, which is always free. Either way, it’ll take a few minutes! If you do have any issues and you have Docker running locally, it’s worth trying <code class="inline-code">fly deploy --remote-only</code> to force it to use a remote builder.When it completes you should see a release created:<pre filepath=""><code class="language-plaintext">...
deployment-1643115278: digest: sha256:a8d9da5f208f9e9cb11a5d6a3967c72dc10a083741b4fcbeb5673a0f5495e0c1 size: 2616
--&gt; Pushing image done
image: registry.fly.io/lootbox-quiz:deployment-1643115278
image size: 136 MB
==&gt; Creating release
--&gt; release v0 created

--&gt; You can detach the terminal anytime without stopping the deployment
==&gt; Monitoring deployment

 1 desired, 1 placed, 1 healthy, 0 unhealthy
--&gt; v0 deployed successfully</code></pre>Your app will be deployed to a <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="http://fly.dev">fly.dev</a> subdomain. You can open it in your browser by running <code class="inline-code">fly open</code>. Once you open it and it looks good, you’re done! You can send your quiz app to your friends and they’ll be rewarded with lootboxes that they can open!

Deploying our app

Congrats! :) We hope you had a blast!See you in the next tutorial!