@hirosystems/clarinet-sdk

Clarinet SDK

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

You can use this SDK to:

• call public and read-only functions from smart contracts
• get clarity maps or data-var values
• deploy contracts
• get contract ABI
• write unit tests for Clarity smart contracts

Core

npm install @hirosystems/clarinet-sdk

Usage

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

async function main() {
  const vm = await initVM();

  const accounts = vm.getAccounts();
  const w1 = accounts.get("wallet_1")!;

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

  const counter = vm.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 vm = await initVM("./path/to/Clarinet.toml");

Tests

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

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

Let's go to to an existing project or create a new

I'm setting up a new project

cd ./my-project
ls # here you should see the Clarinet.toml file
npx @hirosystems/clarinet-sdk@latest

I want to use the SDK in an existing project

clarinet new my-project # change my-project to whatever you want
cd ./my-project
npx @hirosystems/clarinet-sdk@latest

The NPM script that was executed should ask you to run npm install, press enter to run it.

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