@hirosystems/clarinet-sdk

Clarinet SDK for Node.js

The Clarinet SDK allows to interact with the simnet in Node.js.

If you want to use the Clarinet SDK in web browsers, try @hirosystems/clarinet-sdk-browser.

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:

• Interact with a clarinet project as you would with the Clarinet CLI
• Call public, read-only, and private 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

Installation

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(Cl.prettyPrint(call.result)); // (ok u1)

  const counter = simnet.getDataVar("counter", "counter");
  console.log(Cl.prettyPrint(counter)); // 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.

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

cd my-project
ls # you should see Clarinet.toml and package.json in the list

Install the dependencies and run the test

npm install
npm test

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"]
}

Changelog

2.9.0 (2024-09-30)

New Features

• Slown down burn blocks when getting close to epoch 3.0 transition (#1569) (8fc863d3)
• Customize number of signers in devnet (#1555) (76eba28a)

Refactors

• Consolidate datastore and burn datastore data (#1562) (c56b2d4b)
• Remove internal dependency on the repl (#1511) (cd00c892)
• Auto extend stacking_orders in devnet config by default (#1528) (a3e90023)

Chores

• Add disable_postgres flag and separate from stack_api disabling (#1558) (1bdc2724)
• Update clarity and clarity-wasm (#1560) (b57802e9)
• Upgrade bitcoin cargo dependencies (#1556) (fb709312)
• Upgrade npm dependencies (#1551) (e38d0aef)
• Remove unused Clarinet3.toml (148bc5de)

Continuous Integration

• Upgrade actions/upload-artifacts and download-artifacts to v4 (#1554) (146e32ea)

Documentation Changes

• Fix documentation link (#1508) (ce1ffeaa)

Bug Fixes

• Handle reorg in epoch 3.0 (#1568) (be42dd98)
• Convert correctly from uSTX to STX when applying a deployment (#1563) (dfe40985)

Tests

• Add block time tests (#1541) (5ecaee9a)