Quickstart

You will learn how to:

Initialize a simulated blockchain environment
Retrieve accounts
Execute public functions of a smart contract in a simulated environment.
Debug smart contract calls by examining return values in the console.

Initialize project

Before we get started using the SDK, let's first create a new Node project in our terminal.

mkdir clarinet-sdk-project
cd clarinet-sdk-project
npm init -y

Install necessary packages

Now that we have our project setup, let's install our required packages: @hirosystems/clarinet-sdk and @stacks/transactions.

npm install @hirosystems/clarinet-sdk @stacks/transactions

Retrieving accounts on simnet

Now let's create a hello-world project. This will scaffold all the necessary files and directories for us to get started.

index.js

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))
}

main();

Create a say-hello contract

Now that our project has been generated we can start creating our first contract. Let's name this one say-hello.

Terminal

cd hello-world
clarinet contract new say-hello

Create a read-only function called say-hi

Now that we have our say-hello.clar file generated, let's create a read-only function that prints out "Hello World".

say-hello.clar

(define-read-only (say-hi)
  (print "Hello World")
)

Verify your contracts

In order to verify that our code is valid, we can run clarinet check inside of our project directory to ensure our say-hi function is valid.

Terminal

clarinet check
✔ 1 contract checked

Note

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');

You will learn how to:

Next step: Add unit tests with the Clarinet SDK

Additional resources

Clarinet SDK API Reference

Common Clarity Errors

On this page