@hirosystems/clarinet-sdk

Clarinet SDK

The Clarinet SDK can be used to interact with the simnet from Node.js.

Find the API references of the SDK in our documentation.
Learn more about unit testing Clarity smart contracts in this guide.

You can use this SDK to:

• Call public and read-only functions from smart contracts
• Get clarity maps or data-var values
• Get contract interfaces (available functions and data)
• Write unit tests for Clarity smart contracts

Core

npm install @hirosystems/clarinet-sdk

Usage

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

async function main() {
  const simnet = await initSimnet();

  const accounts = simnet.getAccounts();
  const address1 = accounts.get("wallet_1");
  if (!address1) throw new Error("invalid wallet name.");
  

  const call = simnet.callPublicFn("counter", "add", [Cl.uint(1)], address1);
  console.log(call.result); // Cl.int(Cl.ok(true))

  const counter = simnet.getDataVar("counter", "counter");
  console.log(counter); // Cl.int(2)
}

main();

By default, the SDK will look for a Clarinet.toml file in the current working directory. It's also possible to provide the path to the manifest like so:

 const simnet = await initSimnet("./path/to/Clarinet.toml");

Tests

The SDK can be used to write unit tests for Clarinet projects.

You'll need to have Node.js (>= 18) and NPM setup. If you are not sure how to set it up, Volta is a nice tool to get started.

In the terminal, run node --version to make sure it's available and up to date.

Note: A bit of boilerplate is needed to setup the testing environment. Soon it will be handled by the clarinet-cli.

Open your terminal and go to a new or existing Clarinet project:

cd my-project
ls # you should see a Clarinet.toml file in the list

Run the following command to setup the testing framework:

npx @hirosystems/clarinet-sdk

Visit the clarity starter project to see the testing framework in action.

Type checking

We recommend to use TypeScript to write the unit tests, but it's also possible to do it with JavaScript. To do so, rename your test files to .test.js instead of .test.ts. You can also delete the tsconfig.json and uninstall typescript with npm uninstall typescript.

Note: If you want to write your test in JavaScript but still have a certain level of type safety and autocompletion, VSCode can help you with that. You can create a basic jsconfig.json file:

{
  "compilerOptions": {
    "checkJs": true,
    "strict": true
  },
  "include": ["node_modules/@hirosystems/clarinet-sdk/vitest-helpers/src", "unit-tests"]
}

Contributing

Clone the clarinet repo and go to the clarinet-sdk component directory:

git clone [e-mail]:hirosystems/clarinet.git
cd clarinet/components/clarinet-sdk

Open the SDK workspace in VSCode:

code ./clarinet-sdk.code-workspace

Compile the project (both WASM and JS):

npm install
npm run build

Changelog

1.0.0 (2022-10-06)

New Features

• Introducing our brand new re-architected VSCode extension (README)
• All of our tools (REPL, LSP, Clarinet) are now directly derived from the canonical Clarity VM (#512, #535, #544)
• Ability to trigger chainhooks from unit tests (#564)
• Deno integration upgraded and revisited (#511)
• Ability to specify Deno import maps (#511)
• Ability to specify TS config files (#555)
• Ability to cache Deno libraries locally (a2c2ded3)
• Bitcoin deployment plans now supports transfers to P2WPKH addresses (c50a4c27)
• Ability to detect outdated deployment plans and display diffs (#365)

Bug Fixes

A myriad of issues were addressed in this new version, the most notable being:

• Cannot make http request from within clarinet test (#566)
• Clarinet CPU usage spiking to 100% when using clarinet integrate (#545)
• Clarinet console crashes when it errors (#541)
• Unhandled Division By Zero exception (#525)
• Handle errors from callReadOnlyFn in tests (#407)
• Arithmetic underflow crashes clarity-repl instead of displaying error (#471)
• Improve debugability of chain.mine_block() (#91)

Documentation

• Added new example - How to use Chainhooks for indexing data (cdeca648)
• Added OpenAPI spec for Chainhooks (01e8979c)

Compatibility Issue

Clarinet v1.0.0 is not currently backwards-compatible with older versions of the Clarinet deno library. If you are upgrading Clarinet to Clarinet v1.0.0, you will need to enter the following import command in your test files to perform this update.

import { … } from 'https://deno.land/x/clarinet@v1.0.2/index.ts';

Note The v1.0.0 library is not compatible with Clarinet versions <= 0.33.0. Prior versions of the library also will not be compatible with versions >= 1.0.0 of Clarinet because the layer in charge of the communication between Typescript and Rust was upgraded. If you are using Clarinet in a Github Action, and using the tag latest (now pointing to v1.0.0), the tests will fail if the import upgrade task is not performed. If you do not want to upgrade, this is possible; however, you will need to specify the docker tag v0.33.0, instead of latest.