@hirosystems/clarinet-sdk
Advanced tools
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:
npm install @hirosystems/clarinet-sdk
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");
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.
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"]
}
3.0.0 (2025-05-07)
While most recent features were shipped in the 2.x series, this 3.0.0 version allows us to stabilize the Clarity Formatter and Mainnet execution simulation features.
With a major version bump comes breaking changes, especially since the Clarinet JS SDK will now use Stacks.js v7. The most significant change for Clarity developers is how Stacks.js handles Clarity values. See the Stacks.js migration guide for more details.
FAQs
A SDK to interact with Clarity Smart Contracts in node.js
We found that @hirosystems/clarinet-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.
Security News
CISA’s 2025 draft SBOM guidance adds new fields like hashes, licenses, and tool metadata to make software inventories more actionable.