Contents
I’m Patrick Gray, the Docs Lead at Hiro. I joined the company at the beginning of May, and have been working to get up to speed on the Stacks documentation over the last couple months. I have been a technical writer for 9 years, and I’ve worked in a variety of different industries. Most recently, I was doing product documentation for map production software in the self-driving car industry. I came to Hiro because I’m interested in the crypto world, and I’m excited about the Stacks vision of a decentralized internet secured by the computing power of Bitcoin. I am here to take Stacks developer documentation to the next level.
In addition to helping improve the documentation, I’ll be providing regular updates through the Stacks blog and other channels to help promote the documentation content and drive community contribution. I have lots of ideas that I’m excited to share with you!
This is a recap of the documentation changes that landed in Q2, and a quick preview of planned content for Q3.
🔮 Clarity content
Smart contracts on Stacks make all sorts of amazing products possible. Due to Stacks having native visibility into Bitcoin state, projects built on Stacks can leverage the huge amounts of capital already locked into the Bitcoin ecosystem.
Clarity is the native language of smart contracts on Stacks. Helping new developers learn the language and take their first steps into developing smart contracts with Clarity is key to growing a thriving ecosystem. The documentation helps new developers through a series of tutorials and examples, which we have been working to expand throughout Q2. Additionally, Hiro released Clarinet, a powerful development tool for Clarity smart contracts.
Clarinet
Clarinet is a local development tool that helps you quickly develop and test smart contracts on your development machine, without the need to deploy the contract to a live blockchain. Clarinet is helpful because it allows you to quickly iterate on Clarity smart contracts. Clarinet consists of a Clarity syntax checker for validating your contract, a local read-evaluate-print loop (REPL) for interactive testing, and a Typescript testing harness for writing automated unit tests. Additionally, Clarinet has been integrated with Github actions for code coverage testing at PR time.
In Q2, we added a comprehensive overview of Clarinet to the Stacks documentation. This overview includes installation instructions, and examples of common uses of Clarinet for local Clarity development.
Clarinet is very actively developed, and new features are being added regularly. You can help get Clarinet included in your OS package manager by going to the Clarinet repository and clicking the ⭐ ️and Watch buttons in the upper right of the repository page.
Tutorial updates
At the beginning of Q2, Stacks documentation had two beginner Clarity tutorials. In order to get new developers working as quickly as possible, these tutorials used a Gitpod environment in browser. Additionally, the tutorials relied on the Stacks CLI and the live testnet environment to deploy and test the tutorial contracts. While the live deployment was a useful skill to build, the reliance on the live testnet often meant that a basic tutorial could take over an hour to complete.
To improve developer experience, and to promote use of the Clarinet development environment, the two beginner tutorials were re-written to use Clarinet. This allows the tutorials to be completed quickly, and leaves the beginner developer with a working development environment. Each tutorial includes an optional step to deploy the contract to the testnet, so developers looking to build that skill can continue to exercise it, without the deployment time being a learning impediment.
Now the beginner tutorials focus primarily on skills new developers need for long term success: a working development environment, familiarity with Clarity’s LISP syntax and how to validate it, and rapid iteration on in-development code. We maintained training on how to deploy contracts to the blockchain, while emphasizing a great foundation for taking the next steps into Clarity.
New Billboard tutorial
A big new addition to the documentation in Q2 was the Billboard tutorial, an intermediate tutorial that demonstrates additional features of Clarity. This tutorial came from workshop material developed by Reed Rosenbluth of the Stacks Platform team at Hiro for the Stacks Accelerator teams Tech Week.
The Billboard tutorial is an example smart contract that stores a UTF-8 string on the blockchain (the billboard), and allows a Stacks user to pay a small fee in STX tokens to update that string. The tutorial covers intermediate skills such as error codes, STX token transfer, on-chain data storage, and unit testing using Clarinet.
If you are looking to build off the Billboard tutorial, we challenge you to develop a frontend for the smart contract that could be used in the documentation as an application case study.
🐴 Heystack
Heystack is an example application developed by Hiro’s UserX team in Q2, during their first internal UserX team hackathon. The app is purpose-built as a documentation demo, and gave the team valuable insight into what it’s like to develop on Stacks.
Heystack is a simple messaging application that allows a user to claim fungible tokens and spend them to send messages that are stored on-chain and displayed in a React frontend. The full source of Heystack is available for demonstration purposes, and the documentation contains a case-study and discussion of relevant snippets of the Heystack code.
The Heystack case study is the first example application in the Stacks documentation to fully demonstrate the capabilities of the Stacks 2.0 blockchain. It serves as a powerful example of the capabilities of Stacks.
🔳 Microblocks
Microblocks are the Stacks block streaming model that allow for rapid resolution of transactions between Bitcoin anchor blocks. A major enhancement to the documentation in Q2 focused around educating users on microblocks, and highlighting API and Stacks.js resources for supporting microblocks in your application.
When a block leader is elected, that miner can elect to stream microblocks, and thus earn a portion of the transaction fees generated by transactions that require rapid resolution. This block streaming model solves a common complaint about Bitcoin: average block times between 10 and 15 minutes. With microblocks, transactions on the Stacks blockchain can be settled in seconds, with the full state transition recorded in the subsequent anchor block.
The documentation provides resources on how to create microblocks transactions, and a small set of best-practices on how to include microblocks in your Stacks app.
📅 Q3 lookahead
Looking ahead to Q3, there are several documentation initiatives in-flight. We’ve been working to improve the visuals on the site, and we’ll be adding additional screenshots and diagrams where appropriate. The first is the completion of an NFT tutorial that was in development for most of Q2. This is another beginner Clarity tutorial that will go over traits and how to use them with Clarinet. We’ll be looking to add at least one more Clarity tutorial during Q3, and a frontend application for that tutorial. I’ll be doing some modifications to the information architecture of the documentation site, and working to prune out outdated and incorrect information from the repo. If you find anything that needs improvement, please file an issue or open a PR.
We are always looking for community contributions to the Stacks documentation. If you want to help but don’t know where to start, check out the issues in the docs repository. Filter by the good first issue and help wanted tags to see where we’re looking for help. You don’t always need to follow the issues though! If you are interested in contributing your own tutorial or other content, let us know in the #documentation channel on Stacks Discord, or just open a PR! Contribution guidelines are available, and more guidance will be coming soon.
