Developing a Full-Stack Project on the Stacks Blockchain with Clarity Smart Contracts and Stacks.js Part I: Intro and Project Setup

Intro

The tech industry is a constantly changing environment. With the emergence of blockchain technology, and more recently web3, or decentralized, applications those changes appear to be happening at a more rapid pace. At Whitelabel, we have expanded our services to include smart contract development for multiple chains. I have personally taken an interest in the Stacks Blockchain, a layer 1 chain that aims to bring programmability to Bitcoin by implementing a consensus mechanism named Proof of Transfer(PoX) that allows for visibility into the Bitcoin state and uses the Bitcoin chain as a settlement layer.

In this post, I will walk through the fundamental steps of creating a front to back application on Stacks. I will demonstrate a simple smart contract in Clarity, the language used to write smart contracts on Stacks, go over unit testing, practice manual contract calls in clarinet console using Clarinet, a CLI package and developer environment for creating smart contracts, build a frontend using Stacks.js Starters to quickly bootstrap a frontend app, hook up the contract to the client, and run a local DevNet instance to demonstrate the application in action as if it was on-chain.

Mainnet vs Testnet vs DevNet

It’s important to understand the difference between the various “nets” and when you would interact with each one. For Stacks there are three “nets”, they are all separate chains and each hold their own data.

Mainnet is the main Stacks blockchain network. This is fully public and where users interact with deployed smart contracts. In web2 development lingo, you can think of an app on mainnet as in production, prior to which it will be in staging on testnet. The Stacks explorer is a browser based tool that allows users to access information on Stacks mainnet. Here you can see things like recent blocks, pending and confirmed transactions, as well as the deployed smart contracts themselves.

Testnet is a separate blockchain from the Stacks mainnet that can be thought of as a sort of staging environment. It is used by developers to test their apps and smart contracts and allows users to interact with the application using test STX tokens rather than their actual tokens. The Stacks explorer allows users to switch to testnet view by clicking Network on the top right of the page and selecting stacks.co testnet. There is also a testnet Sandbox available for writing and deploying, making contract calls, and receiving test STX via the STX faucet.

DevNet is an integration feature provided by our friends at Hiro that allows us to spin up a simulated blockchain locally. This allows developers to perform frontend integration and testing without having to deploy to a public tesnet. DevNet is useful when you are in the early stages of development or buidling incognito.

In this example I will be using DevNet.

Prerequisites

In order to run DevNet there are a few things that need to be installed.

Clarinet

The detailed instructions can be found in the Hiro docs.

Quickstart:

• macOS

brew install clarinet

• windows

winget install clarinet

You can verify whether it has successfully installed by running the following command:

clarinet --version

Docker

Docker is required to be on your machine for running DevNet. Instructions can be found in the Docker docs.

Project structure

From the terminal, in the desired starting directory run:

mkdir gm

This will create a main directory for the project which will hold the frontend and backend folders. Move into this directory with:

cd gm

Initialize the frontend directory with:

npm create stacks --template frontend

This will spin up a Next app called “frontend” with Stacks.js scaffolding which makes getting started a breeze. Writing the frontend code will be the final step in this example, so we will come back to that directory later.

Now to initialize the backend directory; for readability in separating the contracts from the client, I’ll call this clarinet project “backend”:

clarinet new backend

As you can see, running the clarinet new command will generate a number of files and directories. I’ll briefly describe the main ones.

• Clarinet.toml: This is the configuration file. Within this file you’ll notice [contracts.gm] path = "contracts/gm.clar", any contract dependencies whether from contracts you create or import from those deployed on mainnet will show up here.
• /settings/Devnet.toml: This file contains dummy data which you can use for testing your contract. It provides you with a deployer and a number of wallets. I will be interacting closely with this file throughout this example.
• /contracts and /tests: These directories are initialized but remain empty until you create your first contract. I’ll come back to these after the next step.

cd backend

and create a contract with:

clarinet contract new gm

Now, the /contracts and /tests directories have files.

• contracts/gm.clar: This is where the Clarity code goes.
• tests/gm_test.ts: This is where the Typescript unit tests that correspond to each contract go.

With that the Clarity smart contract project is set up.
From here you can write your code inside of gm.clar and write unit tests inside of gm_test.ts

Conclusion

Thanks for reading Part I of this series! Move on to Part II: Backend.