Announcing the Clarinet SDK: a JavaScript Programming Model For Easy Smart Contract Testing

Today, we are thrilled to announce that the Clarinet JS SDK has been released on npm. This library will expose many of Clarinet’s features to the JavaScript ecosystem, including “simnet”.

Simnet allows developers to interact with a virtual and light Stacks network, embedding the same Clarity VM as the one used in production on Stacks mainnet. With this new JavaScript SDK, it is now possible to control the simnet from Node.js in a standard and familiar way.

Clarinet joins the JavaScript world.

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.

In that time, it became clear that one of the most powerful use cases for Clarinet is testing smart contracts and making sure that contracts work as expected. Clarinet is great at debugging, but we knew it could be better. We decided to revisit Clarinet’s design to make the testing framework easier to use and more accessible to JavaScript developers while also fixing the architecture along the way.

In particular, we embedded an old version of the Deno JavaScript runtime within Clarinet v1, which was heavy, hard to maintain and caused a number of issues, including:

• 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

Instead of embedding a whole JavaScript runtime within the CLI, we now have a JavaScript package that will be published on NPM, making Clarinet, and all its testing capabilities, more friendly to JavaScript developers.

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:

npm install @hirosystems/clarinet-sdk @stacks/transactions

Here is a short code sample that shows how to perform some basic interactions with simnet:

import { initSimnet } from "@hirosystems/clarinet-sdk";
import { Cl } from "@stacks/transactions";

async function main() {
  // Initiate Stacks Simnet
  const simnet = await initSimnet();

  // Get the account addresses (from the settings/Devnet.toml file)
  const accounts = simnet.getAccounts();
  const address1 = accounts.get("wallet_1");

  // Call a public function and see the result
  const call = simnet.callPublicFn("counter", "add", [Cl.uint(1)], address1);
  console.log(call.result); // Cl.int(Cl.ok(true))

  // Get the value from a data-var declared in the contract
  const counter = simnet.getDataVar("counter", "counter");
  console.log(counter); // Cl.int(2)
}

main();

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.

All of the Clarity values are handled by Stacks.js, so it should feel familiar for developers that also work on Stacks applications. Because everything in the code is just plain JavaScript, we were able to leverage Vitest to provide a powerful and familiar testing framework. Learn more in the testing guide. If you're a visual learner, check out this tutorial on how to migrate unit tests to the SDK too:

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.

Finally, this GitHub repository shows a “counter” contract along with the unit tests. If you have questions, please reach out to us on the #clarinet channel on Discord.