Build a full-stack Solidity + NextJS app that allows users to create custom Mechanical Keyboards on-chain

We're going to build a cool full-stack Ethereum app together when you complete the tutorial and deploy your contract, you'll get this awesome NFT for proof of completion!<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_btWyD6Jwb_daycLhoynC9" uploadmode="upload"></image>In the process, you'll learn about Solidity, Smart Contracts, local development with Hardhat, and more :)<h3 id="before-you-start-community">Before you start - Community</h3><callout color="purple">Join our DiscordIt’s the best place to get help with this tutorial and get involved with the community.👇join here → <url href="https://discord.gg/gzyJEMDY" rendertype="link" content="https://discord.gg/gzyJEMDY"></url><url href="https://discord.gg/FXBr4auFeZ" rendertype="link" content="https://discord.gg/FXBr4auFeZ"></url>You’ll find three channels created specifically for this tutorial#solid-solidity-general - use this space to chat about the tutorial#solid-solidity-help - if you get stuck, this is the best place to ask for help!#solid-solidity-feedback - help us make this tutorial better with your feedback</callout><h3 id="prerequisites">Prerequisites</h3>In this tutorial, we’re building a full-stack Next.js application using the Ethereum ecosystem. 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.Tools:<ul><li><a target="_blank" rel="noopener noreferrer nofollow" class="link link link" href="https://yarnpkg.com/getting-started/install">yarn</a> — A package manager we’ll be using to install our dependencies, like Hardhat.</li><li>a code editor — VSCode or your preferred editor should work fine!</li><li>MetaMask — a Wallet for interacting with your Ethereum account</li></ul><h3 id="what-we're-building">What we're building</h3>We're building a web app that will allow you to create an on-chain mechanical keyboard, view other users' keyboards, and send an ETH tip to your favorites!By the end of it, you'll have a project that's ready to deploy and share with friends.You can see a fully deployed example <a target="_blank" rel="noopener noreferrer nofollow" class="link link link" href="https://solidity-tutorial.vercel.app/">here</a>Let's get to it! 🚀

Welcome 🎉

In this section, you'll get your project setup locally!<h3 id="install-metamask-and-setup-ethereum-wallet">Install Metamask and setup Ethereum Wallet</h3>You should already have your wallet setup if you're viewing this tutorial but if you're not, you can read our guide, you can check it out here -&gt; <a target="_blank" rel="noopener noreferrer nofollow" class="link link" href="https://www.pointer.gg/tutorials/Setting-Up-Your-Wallet">Setting Up Your Wallet</a> <callout color="fuchsia">In order to get the NFT reward for this project, make sure you deploy the contract on the same wallet you used to connect to Pointer! :)</callout><h3 id="request-test-eth">Request Test ETH</h3>We’re going to be deploying to an Ethereum testnet in this tutorial, which is a copy of the Ethereum network that uses fake Ether. Other than that it behaves the same as the real deal, so everything you learn here is applicable to deploying real projects on the mainnet too! There are a number of test networks, we’re going to use Rinkeby. One of the nice benefits of a testnet is that you can just ask for Ether! It’ll only work on that testnet, but it’ll let us deploy some code and interact with it! Here’s a list of faucets where you can request test Ether. You’ll need to either connect your wallet or paste your address.<ul><li>Alchemy faucet : <a target="_blank" rel="noopener noreferrer nofollow" class="link link" href="https://rinkebyfaucet.com">https://rinkebyfaucet.com</a> This is one of the easiest faucets to use. Just paste your wallet address and receive test ETH</li><li>Official faucet: <a target="_blank" rel="noopener noreferrer nofollow" class="link link" href="https://faucet.rinkeby.io">https://faucet.rinkeby.io</a></li><li>MyCrypto: <a target="_blank" rel="noopener noreferrer nofollow" class="link link" href="https://app.mycrypto.com/faucet">https://app.mycrypto.com/faucet</a> On your first visit it’ll direct you through their create an account flow, after that the link will take you to their faucet</li><li>Chainlink: <a target="_blank" rel="noopener noreferrer nofollow" class="link link" href="https://faucets.chain.link/rinkeby">https://faucets.chain.link/rinkeby</a></li></ul><h3 id="download-repo">Download Repo</h3>The repo for this project is located here → <a target="_blank" rel="noopener noreferrer nofollow" class="link link" href="https://github.com/pointer-gg/solidity-tutorial">https://github.com/pointer-gg/solidity-tutorial</a>To clone the project locally run<pre filepath="" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-shell">git clone https://github.com/pointer-gg/solidity-tutorial
</code></pre><h3 id="install-dependencies">Install dependencies</h3>Run the following command inside the project repo to install our dependencies<pre filepath="solidity-tutorial/" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-shell">yarn
</code></pre><h3 id="start-the-project">Start the project</h3>Run the following command to start the next.js server<pre filepath="solidity-tutorial/" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-shell">yarn dev</code></pre>After starting the project visit <a target="_blank" rel="noopener noreferrer nofollow" class="link 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 set up, proceed to the next step!

Install required tools and download starter code

🏗 Project Setup

Build and test our first smart contract in Solidity using Hardhat

Smart Contract

We’ll be working in the <code class="inline-code">pages/index.js</code> file. Our goal here is to get our MetaMask wallet connected to the app so that we can use it to fetch data and make transactions to our contract! This is kind of like logging in to our app!<h3 id="connecting-a-metamask-wallet">Connecting a MetaMask wallet</h3>We’re first going to add two state variables to <code class="inline-code">pages/index.js</code>:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">export default function Home() {

 const [ethereum, setEthereum] = useState(undefined);
 const [connectedAccount, setConnectedAccount] = useState(undefined);

 // everything else stays the same!</code></pre>When MetaMask is installed it sets <code class="inline-code">window.ethereum</code> to an object that allows us to call functions on MetaMask and on the Ethereum blockchain. We’re going to store that in our <code class="inline-code">ethereum</code> state when it’s available.Our <code class="inline-code">connectedAccount</code> will store the address of the account that is logged in. This will be your wallet address once we have everything hooked up!Let’s add some simple render logic:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">import { useState, useEffect } from "react";
import PrimaryButton from "../components/primary-button";

export default function Home() {
 const [ethereum, setEthereum] = useState(undefined);
 const [connectedAccount, setConnectedAccount] = useState(undefined);

 const connectAccount = () =&gt; {};

 if (!ethereum) {
 return &lt;p&gt;Please install MetaMask to connect to this site&lt;/p&gt;
 }

 if (!connectedAccount) {
 return &lt;PrimaryButton onClick={connectAccount}&gt;Connect MetaMask Wallet&lt;/PrimaryButton&gt;
 }

 return &lt;p&gt;Connected Account: {connectedAccount}&lt;/p&gt;
}</code></pre>We have 3 different returns:<ul><li>If <code class="inline-code">ethereum</code> is missing then our app can’t do much, so we ask the user to install MetaMask so they can log in and use it!</li><li>If there’s no connected account then we render a connect button. We’ll make this work soon!</li><li>If there is a connected account then we show it!</li></ul>Now if you refresh the page (<code class="inline-code">yarn dev</code> to run the app if it’s not running), you’ll see the message <code class="inline-code">“Please install MetaMask to connect to this site”.</code><image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_rSXf7rOIt1EtkmHvPiMFB" uploadmode="upload"></image>You probably have MetaMask installed! But we’re seeing this because our app never sets <code class="inline-code">ethereum</code> yet. Let’s fix that!Add these between the <code class="inline-code">useState</code> lines and the returns:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">const handleAccounts = (accounts) =&gt; {
 if (accounts.length &gt; 0) {
 const account = accounts[0];
 console.log('We have an authorized account: ', account);
 setConnectedAccount(account);
 } else {
 console.log("No authorized accounts yet")
 }
};

const getConnectedAccount = async () =&gt; {
 if (window.ethereum) {
 setEthereum(window.ethereum);
 }

 if (ethereum) {
 const accounts = await ethereum.request({ method: 'eth_accounts' });
 handleAccounts(accounts);
 }
};
useEffect(() =&gt; getConnectedAccount(), []);

const connectAccount = () =&gt; {};</code></pre>We have a <code class="inline-code">useEffect</code> so that <code class="inline-code">getConnectedAccount</code> function runs on the client when the page is loaded. Note that <code class="inline-code">window</code> doesn’t exist server-side so we need to make sure this function only runs on the client.It sets the <code class="inline-code">ethereum</code> state to the <code class="inline-code">window.ethereum</code> provided by MetaMask.We also have our first request to MetaMask, <code class="inline-code">const accounts = await ethereum.request({ method: 'eth_accounts' });</code>. This requests the accounts from MetaMask that have been connected to our app. There won’t be any yet!The <code class="inline-code">handleAccounts</code> function just gets us the first account if there are any and sets <code class="inline-code">connectedAccount</code> . And it has some debug logging. We’ll use this again in a moment!If you reload the app you should now see that we’ve moved into our second state: we have MetaMask (and therefore ethereum is defined) but we don’t have an account connected. We render a button to connect an account.<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_q7IpBQJGkiGcxUJPN-PgE" uploadmode="upload"></image>Clicking this button won’t do anything yet, it runs our <code class="inline-code">connectAccount</code> function which is currently empty. Let’s see how to write that!<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">const connectAccount = async () =&gt; {
 if (!ethereum) {
 alert('MetaMask is required to connect an account');
 return;
 }

 const accounts = await ethereum.request({ method: 'eth_requestAccounts' });
 handleAccounts(accounts);
};
</code></pre>Another request to MetaMask, this time <code class="inline-code">eth_requestAccounts</code>. This will actually open MetaMask and ask the user to give permission to connect to the app. It’ll return us whichever accounts they authorized. We only want to deal with one account so we call our <code class="inline-code">handleAccounts</code> function again to select the first one.If you reload the app again, click the button and authorize a MetaMask account, then you should get the 3rd state showing we’re connected! BTW make sure your MetaMask is on Rinkeby at this point, that’ll be essential when we connect to our contract!<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_tpAQUIFynD55IZrWpjWf6" uploadmode="upload"></image>And in the console you should see a message from <code class="inline-code">handleAccounts</code>: We have an authorized account: 0x05526ab44d5c35a313fccbc5d0c2b209a0eba8c8. Of course, with your public key of whichever account you authorized!And that’s it! We’ve connected an Ethereum address to our site! Web3 makes logging in super easy, and it works the same on every site.<h3 id="connecting-to-your-contract">Connecting to your contract</h3>There are two pieces of information that our web app needs to connect to our contract: its address (the one we got when we deployed it) and its ABI, which describes all the functionality that it has. We actually already have both of these!First the address, just add it under the <code class="inline-code">useState</code> lines:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[4]"><code class="language-javascript">const [ethereum, setEthereum] = useState(undefined);
const [connectedAccount, setConnectedAccount] = useState(undefined);

const contractAddress = '0x...';</code></pre>Make sure you use your contract’s address!The ABI was generated for us by hardhat automatically when it compiled our contract. You can see it in <code class="inline-code">artifacts/contracts/Keyboards.sol/Keyboards.json</code>. Let’s just copy that file into a new <code class="inline-code">utils/</code> directory that we’ll import into our app.BTW ABI stands for “Application Binary Interface” and it’s a way of describing the interface of our contract - it tells our app what functions can be called, how they can be called and what they return.Now we can import the ABI:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">import abi from "../utils/Keyboards.json"

...

 const contractAddress = '0x96748c2E34dF3A435fbCa90199f9F153Fa9F4Cde';
 const contractABI = abi.abi;
</code></pre>Awesome! Now our app can talk to our deployed contract. Let’s see how that works! We’re going to read our keyboards from the deployed contract.First add another state, which we’ll use to hold the retrieved keyboards:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">const [ethereum, setEthereum] = useState(undefined);
const [connectedAccount, setConnectedAccount] = useState(undefined);
const [keyboards, setKeyboards] = useState([])</code></pre>Add the <code class="inline-code">ethers</code> import<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">import { ethers } from "ethers";</code></pre>And then let’s add another <code class="inline-code">useEffect</code> to get them:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">const getKeyboards = async () =&gt; {
 if (ethereum &amp;&amp; connectedAccount) {
 const provider = new ethers.providers.Web3Provider(ethereum);
 const signer = provider.getSigner();
 const keyboardsContract = new ethers.Contract(contractAddress, contractABI, signer);

 const keyboards = await keyboardsContract.getKeyboards();
 console.log('Retrieved keyboards...', keyboards)
 setKeyboards(keyboards)
 }
 }
 useEffect(() =&gt; getKeyboards(), [connectedAccount])</code></pre>There’s a lot new here! We’re only going to do this if we have a connected account, because we can’t call a contract without being connected.Let’s go through the code.<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="false" data-line-highlights="[]"><code class="language-jsx">const provider = new ethers.providers.Web3Provider(ethereum);
const signer = provider.getSigner();</code></pre>We’ll use this code each time we want to make a call on behalf of the connected account in MetaMask. It just gets us a <code class="inline-code">signer</code> who can call contracts!<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="false" data-line-highlights="[]"><code class="language-jsx">const keyboardsContract = new ethers.Contract(contractAddress, contractABI, signer);</code></pre>Here we’re using that information about our contract. Once we have this we can make calls to it!<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="false" data-line-highlights="[]"><code class="language-jsx">const keyboards = await keyboardsContract.getKeyboards();</code></pre>Here we’re calling a function on our contract! This is sort-of like calling a backend server API. Note that the function name is exactly the same as the one we defined in our contract. If you search in the ABI file for <code class="inline-code">getKeyboards</code> you’ll see it defined there:<pre filepath="utils/Keyboards.json" data-show-line-numbers="false" showcopybutton="false" data-line-highlights="[]"><code class="language-json">...
{
 "inputs": [],
 "name": "getKeyboards",
 "outputs": [
 {
 "internalType": "string[]",
 "name": "",
 "type": "string[]"
 }
 ],
 "stateMutability": "view",
 "type": "function"
}
...</code></pre>And once we’ve fetched the keyboards from the contract, we just log them out and record them in that <code class="inline-code">keyboards</code> variable:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="false" data-line-highlights="[]"><code class="language-jsx">console.log('Retrieved keyboards...', keyboards)
setKeyboards(keyboards)</code></pre>You should see this log if you refresh the app:<pre filepath="browser console" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-shell">Retrieved keyboards... []</code></pre>Of course, we don’t have any keyboards yet, so this is empty. Let’s build a form so that we can add one!Change that last return value to:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">return (
 &lt;div className="flex flex-col gap-y-8"&gt;
 &lt;form className="flex flex-col gap-y-2"&gt;
 &lt;div&gt;
 &lt;label htmlFor="keyboard-description" className="block text-sm font-medium text-gray-700"&gt;
 Keyboard Description
 &lt;/label&gt;
 &lt;/div&gt;
 &lt;input
 name="keyboard-type"
 className="mt-1 block w-full pl-3 pr-10 py-2 text-base border-gray-300 focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 sm:text-sm rounded-md"
 value={newKeyboard}
 onChange={(e) =&gt; { setNewKeyboard(e.target.value) }}
 /&gt;
 &lt;PrimaryButton type="submit" onClick={submitCreate}&gt;
 Create Keyboard!
 &lt;/PrimaryButton&gt;
 &lt;/form&gt;
 &lt;/div&gt;
)
</code></pre>Just a form with a single input to describe our keyboard!We’ll also need to add a new state variable to hold the value for that input:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[4]"><code class="language-jsx">const [ethereum, setEthereum] = useState(undefined);
const [connectedAccount, setConnectedAccount] = useState(undefined);
const [keyboards, setKeyboards] = useState([])
const [newKeyboard, setNewKeyboard] = useState("")</code></pre>And finally, we need to add our <code class="inline-code">submitCreate</code> function which runs when the submit button is clicked. A lot of this will look familiar!<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[]"><code class="language-jsx">const submitCreate = async (e) =&gt; {
 e.preventDefault();

 if (!ethereum) {
 console.error('Ethereum object is required to create a keyboard');
 return;
 }

 const provider = new ethers.providers.Web3Provider(ethereum);
 const signer = provider.getSigner();
 const keyboardsContract = new ethers.Contract(contractAddress, contractABI, signer);

 const createTxn = await keyboardsContract.create(newKeyboard);
 console.log('Create transaction started...', createTxn.hash);

 await createTxn.wait();
 console.log('Created keyboard!', createTxn.hash);

 await getKeyboards();
 }
</code></pre>We’re getting the provider, signer and contract in exactly the same way as the <code class="inline-code">getKeyboards()</code> function.And then we’re calling the <code class="inline-code">create</code> function on our contract. Remember when we did this in our test code? Our <code class="inline-code">create</code> function returned a transaction and we had to await that. That’s exactly what we’re doing here!Once our transaction has been confirmed, we call <code class="inline-code">getKeyboards()</code> again to get the latest state.Here’s how things should look:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_OLw5sX-xvydFU5gfSYxYT" uploadmode="upload"></image>And when you click the button you should see the transaction created and then completed in the console:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_ly3jumeUFh_vd-h_26sv2" uploadmode="upload"></image>Note that this might take longer than it did locally, maybe 30 seconds or so. While you’re waiting you can check the transaction address on <a target="_blank" rel="noopener noreferrer nofollow" class="link link link" href="http://rinkeby.etherscan.io">rinkeby.etherscan.io</a> again, which will show its state. There’s a lot of information on that page, feel free to dig around! You can also see pending transactions in MetaMask. Before we move on, create a few keyboards with whatever descriptions you like!<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_fea8mPVUTj_OUk0IXyJVK" uploadmode="upload"></image>Notice that if you refresh the page we will get these keyboards! So we’ve permanently stored these in the state of our contract, anybody who connects to our contract will be able to get them.<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_11ttQ3CjmQKUWKNAjhGxl" uploadmode="upload"></image>Let’s do something more interesting than just logging them when we fetch them. Update that last return to add after that form:<pre filepath="pages/index.js" data-show-line-numbers="false" showcopybutton="true" data-line-highlights="[3]"><code class="language-jsx"> &lt;/form&gt;
 
 &lt;div&gt;{keyboards.map((keyboard, i) =&gt; &lt;p key={i}&gt;{keyboard}&lt;/p&gt;)}&lt;/div&gt;
&lt;/div&gt;</code></pre>Pretty simple! We’re just mapping over our <code class="inline-code">keyboards</code> state and writing each keyboard in its own paragraph.If you refresh the app you should now see the keyboards are displayed:<image src="https://gcyrkvfwpvlwjrrklxnh.supabase.co/storage/v1/object/public/tutorials/b71ebdf5-d544-49fb-a52f-6f1f261f83d0/tutorial_jhvj2zaXwlL4JVsP2qFhe" uploadmode="upload"></image>We did it!You’ve got all the basics here: you can write a contract that stores stuff, and you can write a website that talks to that contract to store stuff and retrieve the stuff you’ve stored. You can use a smart contract as your database!We’re going to make this app a bit more real and show some more fancy Ethereum functionality in this tutorial, but we’ve covered loads of ground so far!

Get the NextJS app connected to our contract and start calling contract functions

Connecting a NextJS app to your contract

Update our app to store a keyboard struct instead of just strings

Storing structured data instead of strings

Add tipping to the app and refactor the NextJS code

Tipping your favorite keyboards!

Our app is complete! You can deploy it like any other NextJS app wherever you like. It can be built as a completely static site, there’s no serverside props and there’s no API endpoints. All the backend functionality is provided by our smart contract!You just built a full-stack Ethereum application 🤯!!!!<callout color="purple"><h3 id="verify-deployment-to-earn-your-nft!">Verify deployment to earn your NFT!</h3>Paste the contract address you created in this tutorial belowl! We'll send the NFT to your wallet once we have verified you deployed this smart contract.<deployment-verifier blockchain="ethereum" network="rinkeby"></deployment-verifier></callout>Congrats :) We hope you had a blast! Hop in our discord and let us know you finished!<h3 id="tweet-about-your-awesome-work-and-tag-us-@pointer_gg!">Tweet about your awesome work, and tag us <a target="_blank" rel="noopener noreferrer nofollow" class="link" href="https://twitter.com/pointer_gg">@pointer_gg</a>! 🎉</h3>See you in the next tutorial! Also, if you have any feedback about the product or tutorial specifically, we’d love to hear it in our discord server so we can make the product better!