Methods

The Clarinet SDK provides several methods that can be used to interact with the simnet.

getAccounts

Retrieve a list of all Stacks addresses configured within the project, including wallets, deployers, and faucets.

import { initSimnet } from '@hirosystems/clarinet-sdk';
const simnet = await initSimnet();

const accounts = simnet.getAccounts(); 

console.log(accounts);

getAssetsMap

Retrieve a list of asset balances associated with Stacks addresses, providing a clear overview of asset distribution.

import { initSimnet } from '@hirosystems/clarinet-sdk';
const simnet = await initSimnet();

const assets = simnet.getAssetsMap(); 
const stxBalances = assets.get('STX')!;

console.log(stxBalances);

getDataVar

Get the value of a data-var defined in a contract.

Parameters

contract
Required
string

The contract identifier of the contract.

Example: "counter"

dataVar
Required
string

The name of the data-var for the contract.

Example: "count"
import { initSimnet } from '@hirosystems/clarinet-sdk';
const simnet = await initSimnet();

const currentCount = simnet.getDataVar('counter', 'count'); 

console.log(currentCount);

getMapEntry

Get the value of a map entry by its key. Note that it will always return an optional value some or none, just like Clarity map-get?.

Parameters

contract
Required
string

The contract identifier of the contract.

Example: "pool"

mapName
Required
string

The name of the map within the contract.

Example: "Participants"

mapKey
Required
ClarityValue

The key to access the value in the map.

Example: Cl.standardPrincipal('ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5')
import { initSimnet } from '@hirosystems/clarinet-sdk';
import { Cl } from '@stacks/transactions';

const simnet = await initSimnet();

const accounts = simnet.getAccounts();
const wallet = accounts.get('wallet_1')!;

const hasParticipated = simnet.getMapEntry("pool", "Participants", Cl.standardPrincipal(wallet)); 

console.log(hasParticipated);

callReadOnlyFn

Call read-only functions exposed by a contract.

This method returns an object with the result of the function call as a ClarityValue. It takes function arguments in the form of Clarity values, available in the package @stacks/transactions.

Parameters

contract
Required
string

The contract identifier of the contract.

Example: "pool"

method
Required
string

The name of the read-only function within the contract.

Example: "get-participant"

args
Required
ClarityValue[]

The arguments to pass to the read-only function. If no arguments are needed, pass an empty array.

Example: [Cl.standardPrincipal('ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5')]

sender
Required
string

The Stacks address of the sender.

Example: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM'
import { initSimnet } from '@hirosystems/clarinet-sdk';
import { Cl } from '@stacks/transactions';

const simnet = await initSimnet();

const accounts = simnet.getAccounts();
const wallet = accounts.get('wallet_1')!;

const isActive = simnet.callReadOnlyFn('pool', 'is-active', [], wallet); 

console.log(isActive.result);

callPublicFn

Call public functions exposed by a contract.

This method returns an object with the result of the function call as a Clarity Value and the events fired during the function execution. It takes function arguments in the form in Clarity Values, available in the package @stacks/transactions.

It will simulate a block being mined and increase the block height by one.

Parameters

contract
Required
string

The contract identifier of the contract.

Example: "pool"

method
Required
string

The name of the public function within the contract.

Example: "register-participant"

args
Required
ClarityValue[]

The arguments to pass to the public function. If no arguments are needed, pass an empty array.

Example: [Cl.standardPrincipal('ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5')]

sender
Required
string

The Stacks address of the sender.

Example: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM'
import { initSimnet } from '@hirosystems/clarinet-sdk';
import { Cl } from '@stacks/transactions';

const simnet = await initSimnet();

const accounts = simnet.getAccounts();
const wallet = accounts.get('deployer')!;

const args = [Cl.standardPrincipal(wallet)];

const registerParticipant = simnet.callPublicFn('pool', 'register-participant', args, wallet); 

console.log(registerParticipant.result);

transferSTX

Transfer STX from an address to an other. The amount is in uSTX.

It will simulate a block being mined and increase the block height by one.

Parameters

amount
Required
number | bigint

The amount of uSTX to transfer.

Example: 1000000, ie 1 STX

recipient
Required
string

The Stacks address of the recipient.

Example: 'ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5'

sender
Required
string

The Stacks address of the sender.

Example: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM'
import { initSimnet } from '@hirosystems/clarinet-sdk';
import { Cl } from '@stacks/transactions';

const simnet = await initSimnet();

const accounts = simnet.getAccounts();
const recipient = accounts.get('wallet_1')!;
const amount = 42000000; // 42 STX

const transferSTX = simnet.transferSTX(amount, recipient, simnet.deployer); 

console.log(transferSTX);

deployContract

Deploy a contract to the Simnet.

It will simulate a block being mined and increase the block height by one.

Parameters

name
Required
string

The name of the contract to be deployed.

Example: 'hello-world'

content
Required
string

The Clarity source code (or content) of the contract.

Example: '(define-read-only (say-hi) (ok "Hello World"))'

optionsDeployContractOptions | null

An object to specify options, such as the Clarity version.

Example: { clarityVersion: 2 }

sender
Required
string

The Stacks address of the sender.

Example: 'ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM'
import { initSimnet } from '@hirosystems/clarinet-sdk';
import { Cl, cvToValue } from '@stacks/transactions';

const simnet = await initSimnet();

const sourceCode = '(define-read-only (say-hi) (ok "Hello World"))';
const deployContract = simnet.deployContract('hello-world', sourceCode, null, simnet.deployer); 

const normalizedDeployContract = cvToValue(deployContract.result); 

console.log(normalizedDeployContract);

mineBlock

The callPublicFn, transferSTX, and deployContract methods all mine one block with only one transaction. It can also be useful to mine a block with multiple transactions.

This is what mineBlock is for.

It take an array of transaction objects. The transactions can be built with the tx helper exported by the SDK.

The tx helper has three methods

  • callPublicFn
  • transferSTX
  • deployContract

These methods have the same interface as the Simnet methods but instead of performing a transaction, it will build a transaction object than can be passed to the mineBlock function.

Parameters

txs
Required
Tx[]

An array of transactions to be included in the block.

Example: [tx.transferSTX(100, recipient, sender), ...]
import { initSimnet, tx } from '@hirosystems/clarinet-sdk'; 
import { Cl, cvToValue } from '@stacks/transactions';

const simnet = await initSimnet();

const accounts = simnet.getAccounts();
const wallet = accounts.get("wallet_1")!;

const block = simnet.mineBlock([ 
  tx.callPublicFn("counter", "increment", [], simnet.deployer), 
  tx.callPublicFn("counter", "add", [Cl.uint(10)], simnet.deployer), 
  tx.transferSTX(19000000, wallet, simnet.deployer), 
]); 

block.forEach((tx) => {
  console.log(cvToValue(tx.result));
  if (tx.events.length > 0) console.log(tx.events);
});

mineEmptyBlock

Mine one empty block and increase the block height by one.

Returns the new block height.

import { initSimnet } from '@hirosystems/clarinet-sdk';

const simnet = await initSimnet();

console.log(`simnet.blockHeight: ${simnet.blockHeight}`);

const newBlockHeight = simnet.mineEmptyBlock(); 

console.log(`newBlockHeight: ${newBlockHeight}`);
console.log(`simnet.blockHeight: ${simnet.blockHeight}`);

mineEmptyBlocks

Mine multiple empty blocks to reach a certain block height.

Returns the new block height.

Parameters

countnumber

The number of empty blocks to mine. This parameter is optional.

Example: 5
import { initSimnet } from '@hirosystems/clarinet-sdk';

const simnet = await initSimnet();

console.log(`simnet.blockHeight: ${simnet.blockHeight}`);

const newHeight = simnet.mineEmptyBlocks(5); 

console.log(`newBlockHeight: ${newBlockHeight}`);
console.log(`simnet.blockHeight: ${simnet.blockHeight}`);

runSnippet

Execute arbitrary Clarity code directly, allowing to test and interact with smart contract functions without deploying them.

Parameters

snippet
Required
string

The Clarity code snippet to be executed.

Example: '(define-read-only (get-balance) (ok stx-balance))'
import { initSimnet } from '@hirosystems/clarinet-sdk';

import type { ClarityValue } from "@stacks/transactions"; 

const simnet = await initSimnet();

const codeSnippet = simnet.runSnippet('(stx-account tx-sender)') as ClarityValue; 

console.log(Cl.prettyPrint(codeSnippet, 2));

Last updated on

Properties