I remember when Ordinals began to first pop off on crypto Twitter. The idea of NFTs on Bitcoin piqued my interest to dive deeper into the Stacks ecosystem and see what it was all about. After researching and learning more about the developer tooling that exists around it, I was fascinated at how easy it was to develop smart contracts on Bitcoin. 

In case you’re unaware of Stacks, it’s essentially a Layer 2 for Bitcoin allowing DeFi, NFTs and dApps (decentralized applications) to be built on top of Bitcoin. Bitcoin has always been more of a store of value as it does not allow for the creation of smart contracts like other networks such as Ethereum, Tezos, etc. Stacks introduces programmability to Bitcoin, extending its use cases beyond merely being “an orange coin to HODL”. 

That said, the smart contract language of the Stacks blockchain is Clarity. If you’d like a good primer on Clarity, I’d recommend heading over to the Hiro blog. Hiro is a company whose focus lies in creating easy-to-use developer tools for building on top of Bitcoin. One of those tools, called Clarinet, is a local testing environment that enables developers to write and test their smart contract code. 

Without any experience using the Stacks blockchain, I was able to develop and deploy a smart contract with ease using Clarinet. 

Let’s run through the process and how I did it. 

Prerequisites for MacOS

In order to begin developing on Clarinet, you need to have a few things installed on your computer first. For the sake of this tutorial, I am using MacOS. 

  • Homebrew

Downloading and installing Homebrew is simple. Simply head to the Terminal app within the launchpad on your PC and paste the following from the download site. 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After pasting the command, you’ll be prompted to enter your password and a few more times shortly. After the installation is successful, you’ll then be prompted to enter two commands to add Homebrew to your PATH. Simply copy, paste and proceed. Type “brew help” to ensure it’s installed properly. 

  • Hiro Web Wallet

Download the Stacks wallet at the following link. Make sure you have Google Chrome, Brave Browser or Firefox already installed as the wallet is a web extension like MetaMask. After downloading, you’ll be given your backup seed phrase (write it down, don’t save as text) and a prompt to create your password. 

  • Request testnet STX

Simply head over to the testnet faucet on the Hiro explorer, connect your wallet, choose your account and request testnet STX. This can take about 15 minutes so grab a nice cup of coffee while you wait. 

  • Install Clarinet

Using Homebrew, simply paste the following command into Terminal. 

brew install clarinet

Creating Smart Contracts on Clarinet

After you’ve completed all the necessary prerequisites, you can now begin using Clarinet to create a new contract, deploy it and interact with the contract on the testnet. 

Firstly, you’ll need to create a new Clarinet project. Simply open a new window in Terminal and paste the following command. You’ll be prompted if you wish to send usage data to Hiro or not to improve their products. 

clarinet new clarity-hello-world && cd clarity-hello-world

Next, you’ll want to create a new Clarity contract. Simply paste the following command in the Terminal window. 

clarinet contract new hello-world

Following this, you’ll then need to open the “hello-world.clar” file you created in a text editor. This file can be accessed by using the Finder application. You’ll need to delete all the existing text within the file and replace it with the following functions. 

The first one is a function called “say-hi“. Simply paste the following text into the text editor. 

(define-public (say-hi)
  (ok “hello world”))

The second function is a read-only function called “echo-number”. Simply paste the following text within the text editor. 

(define-read-only (echo-number (val int))
  (ok val))

Once you’re done, the whole file should look exactly like this.

Once you’ve completed all of these steps, now you can start interacting with the contract you created in the Clarinet console. Heading back over to the “clarity-hello-world” directory in your terminal, paste the following text to make sure no errors arise and the syntax in your contract is correct. 

clarinet check

If errors do show, make sure you follow the above step properly. If none do and you see a green checkmark next to “1 contract checked”, paste the following command into the same terminal window. 

clarinet console

A long list of text with addresses and uSTX should begin to populate. Now you can call the “say-hi” function you created by pasting the following command in the same terminal window. 

(contract-call? .hello-world say-hi)

The contract should immediately return “(ok “hello-world”)”. Next, you’ll want to call the “echo-number” function you created. Simply paste the following command in the same terminal window as well. 

(contract-call? .hello-world echo-number 42)

The contract should immediately return “(ok 42)”. Congrats, you have now created a smart contract with the Clarinet development tool! 

Deploying and Testing Smart Contracts on Clarinet

Following the previous steps, you’ll need to head over to the testnet sandbox in order to deploy your smart contract. Make sure you’re connected to your Stacks web wallet by using the “Connect Wallet” button. Check to make sure “Testnet mode” is on as well. Next, copy and paste your smart contract into the Clarity code editor within the “Write & Deploy” page. 

(define-public (say-hi) 
  (ok “hello world”))
(define-read-only (echo-number (val int))
  (ok val))

Proceed to then click “Deploy” within the Stacks web wallet window. Make sure the information looks accurate in the transaction and click “confirm”. This process can take up to 15 minutes for the transaction to be included in the next block, so it’s time to grab another cup of coffee! If you’d like to monitor the status, you can click on the transaction in your transaction history and see it in the mempool. 

Once the transaction has been confirmed, you can easily navigate to your transaction history and go to the “Call Contract” section by clicking the three lines at the top right of the sandbox dashboard. From there, simply click “Load Contract” to view your “hello-world” contract. 

Now you can play around with some of the functions. Click the “say-hi” function and click “Call Function” to perform the function. Your Stacks web wallet will then prompt you to confirm the transaction. After making sure the information looks correct, click “confirm” to execute the call. 

Once again, this process will take about 15 minutes to complete as you will have to wait for the transaction to be included in the next block. Once it is complete, you will be able to access the transaction summary page within your transaction history. 

Congrats, you’ve successfully learned how to deploy and interact with smart contracts on Stacks!

A Few Notes

After playing around on Clarinet, I found it rather easy to create and deploy smart contracts. If you’re a fellow MacOS user, hopefully this tutorial will find you good use. If you’d like to check out some of Hiro’s great tools for web3 developers, be sure to learn more about their API, SDK, explorer, or the newly launched Hiro Platform!