How it all began

Since the release of Stacks 2.0 in January, and the Clarity smart contracting language, writing and testing contracts has been difficult. The best testing framework available was ClarityJS SDK — a TypeScript library that provided access to the Clarity runtime. However, the library was cumbersome to use. Even simple things required workarounds and a great deal of boilerplate code. Troubleshooting was difficult, and the chain-state was only hardly observable.

With that being said, there were some other promising projects in the Stacks ecosystem: The language-server-protocol used in the VSCode Extension for Clarity, the Clarity REPL, and the Jupyter kernel to run Clarity code. However, they were all separate projects and hardly accessible for a beginner Clarity developer. As a result, an idea was born: What if there was a single CLI that would enable a productive flow - similar to the experience Rails is providing?

A few cycles later, and we released the first proof of concept. Codename: Clarinet.

A CLI package including a Clarity runtime, REPL, and testing harness

Clarinet is our new go-to tool for local Clarity smart contract development. It is designed to facilitate rapid smart contract development, testing, and deployment. It consists of a Clarity REPL and a testing harness. These elements used in tandem allow you to rapidly develop and test a Clarity smart contract, without the need to deploy the contract to a local mocknet or testnet.

What does this mean in practice? Let’s take a look at the key capabilities…

Creating new projects and adding contracts

Clarinet can create a folder structure and automatically organize configuration files to control your testing environment. The settings define available networks, associated accounts, token balances, and contracts to load before tests would be executed. You can even define contract dependencies!

# create a new project called my-project
clarinet new my-project

# create a new contract called bbtc
clarinet contract new bbtc

Once your project is set up, you are only one command away from a new contract. It will create a new file for the contract as well as a boilerplate test-suite. Test-driven development couldn’t come any easier.

Writing tests

Clarinet comes with a TypeScript package for easy interactions with the Clarity runtime. It exposes objects to read and update the the chain, individual accounts, and contracts. To simplify contract interactions, the package also includes Clarity type support. Last but not least, the package includes an assert module, so you can define expected results and make assertions.

Here is a small, working test example for illustration purposes:

import { Clarinet, Tx, Chain, Account, Contract, types } from 'https://deno.land/x/clarinet@v0.13.0/index.ts';
import { assertEquals } from "https://deno.land/std@0.90.0/testing/asserts.ts";

Clarinet.test({
    name: "Ensure that ...",
    async fn(chain: Chain, accounts: Map, contracts: Map) {
        let wallet_1 = accounts.get("wallet_1")!;

        let block = chain.mineBlock([
            Tx.contractCall("counter", "increment", [types.uint(1)], wallet_1.address),
        ]);
        assertEquals(block.height, 1);
    },
});

Checking Clarity syntax

While you're developing your contract, you will likely want to check if your contract is syntactically correct. Every contract configured in this project can be checked with a single command <code-rich-text>clarinet check<code-rich-text>.

Running tests and measuring code coverage

You can run defined tests and see results in your terminal by running the command <code-rich-text>clarinet test<code-rich-text>.

You can even configure GitHub actions to run your tests automatically once you check-in your updates in a Github repository. Here is an example from the Arkadiko project.

Interacting with contracts

Clarinet comes with an interactive console that can be used to interact with a Clarity runtime. As you would expect, all configured accounts and contracts will be available for usage. Once loaded, you will see a snapshot of the available contracts and accounts. This is a great way to experiment with the Clarity language.

# start REPL
clarinet console
‍
# call the sai-hi method of the hello-world contract
> (contract-call? .hello-world say-hi)

Deploying contracts to mocknet

Once you reach a high-enough confidence level of your implementation, you can use Clarinet to deploy your contracts to a mocknet. This way, you can start integrating the contract inside your app without repetitive, manual steps.

# deploy all contracts to mocknet
clarinet deploy --mocknet

Coming soon: Integrate contracts in your apps

A little sneak peek for a feature currently in the works. A new command will make it easy for developers to spin up a local developer network with their contracts deployed. With that, developers can integrate contracts within their apps much quicker. Stay tuned for more!

Give it a try and let us know what you think

With Clarinet becoming the new go-to tool for local Clarity smart contract development, we updated the documentation. Give it a try today.

Clarinet is still in the early stages of development. We would love hear thoughts and suggestions. We hope to see you join our conversations in the #clarinet Discord channel. The GitHub repository is the best place for bug reports of feature requests.

Made with Love

As mentioned earlier, this was a project with fantastic community support. We wouldn’t be here without their help, so let’s give a big thank you to the following supporters - in no particular order:

• Arkadiko and Swapr for being our very first early adopters
• CityCoins team
• Syvita team
• The Stacks Foundation
• Daemon Technologies
• Michael Gold
• Friedger Müffke
• … and everyone else we couldn’t cover in this list!