The History of Clarinet
Clarinet is one of the first tools we released at Hiro, debuting in the summer of 2021. Clarinet is a CLI package, which includes a Clarity runtime, REPL, and testing harness, and its core purpose is simple: provide a tool that facilitates rapid smart contract development, deployment, and testing.
The original purpose of Clarinet was to provide a tool that facilitates rapid smart contract development, deployment, and testing.
Over the last two years, we added a number of features to make Clarinet more robust and feature-complete, including the ability to debug Clarity code step by step and the ability to detect contract flaws via static analysis. Today Clarinet also powers Clarity development in the Hiro Platform through testing and debugging as well as supports an improved DevEx around deployment plans, which automate the reconciliation of contract deployments.
- It made it challenging to compile projects in certain environments.
- Clarinet became difficult to release on Homebrew.
- It introduced complications with keeping our dependencies up to date.
To navigate those difficulties, instead of embedding a JS runtime in Clarinet, we can simply export Clarinet as a WASM library (which we already do for certain tools such as the VS Code extension). And so the <code-rich-text>clarinet-sdk<code-rich-text> was born.
Meet the Clarinet SDK
In other words, thanks to this SDK, the third party Deno won’t be needed anymore, and you can now work with a lighter file configuration with lightweight dependencies.
In your workflow, you will likely interact with both Clarinet (the CLI) and the Clarinet SDK. The CLI is still helpful when creating Clarinet projects and contracts, handling deployments and requirements, and interacting with your contract in the console or with the devnet (i.e., <code-rich-text>clarinet integrate<code-rich-text>). Alternatively, you can use the Hiro Platform here as well.
The Clarinet SDK, on the other hand, will be your primary tool when it comes to testing, particularly with unit tests. With this v1.0 release, the SDK has the same features set as <code-rich-text>clarinet test<code-rich-text>. It also brings a few new features, such as accessing data-var and maps entry from smart contracts or saving the cost reports in a file. With this SDK, we aim to provide a simpler API while remaining familiar.
Moving forward, you will run <code-rich-text>npm test<code-rich-text> instead of <code-rich-text>clarinet test<code-rich-text>, which will be deprecated in Clarinet v2, a new release coming in October 2023.
Future Work for the SDK
Part of what makes the Clarinet SDK so exciting is that it opens up a lot of possibilities that we could not explore before. For example, the SDK could potentially run in the browser, and we can offer a number of new features (access private functions in unit tests, better management of costs, code and test generations, fuzz testing, and more). We will be exploring and adding some of these new features in the coming weeks and months, as well as improving performance.
But first, we are at work on Clarinet v2.0, which will not bring any new features, but instead remove the Deno dependency as well as deprecate <code-rich-text>clarinet test<code-rich-text> and <code-rich-text>clarinet run<code-rich-text>, which relied on the embedded Deno version (these commands will now be handled by the SDK). This will allow us to focus on more important aspects in the future such as bug fixes, optimizations and new features.
A note on versioning: for a period of time Clarinet v1.0 and the Clarinet SDK will coexist. Eventually, however, you will have to migrate from Clarinet to the Clarinet SDK in order to benefit from new features and bug fixes because we won’t release any new Clarinet v1.x versions. Only Clarinet v2.x will be maintained from then onward. However, the Clarinet v1.x binaries will still be available on GitHub for older projects that still need access to it.
How to Get Started
Getting started with the SDK is easy. First, you will need Node.js installed on your device. Then you can then install the clarinet-sdk – it pairs well with Stacks.js – and start using it:
Here is a short code sample that shows how to perform some basic interactions with simnet:
This code sample obviously doesn’t fully show what can be done with the SDK, but gives an idea of how it works. It provides an intuitive and fully typed API to interact with a Clarinet session.
Start Building With the SDK
This release marks the beginning of a new era for Clarinet, and we hope you’re as excited about it as we are. Learn more about the SDK in our docs. You can start using the clarinet-sdk to write unit tests for Clarity smart contracts right now, and this guide can help you get started.