Methods

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

Installation

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

getAccounts

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

const accounts = simnet.getAccounts();

getAssetsMap

Retrieve a list of asset balances associated with Stacks addresses, including fungible and non-fungible tokens.

const assets = simnet.getAssetsMap();

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

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
const currentCount = simnet.getDataVar('counter', 'count');

getMapEntry

Get the value of a map entry by its key. Note that this method 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 { Cl } from '@stacks/transactions';

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

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

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, which are 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 { Cl } from '@stacks/transactions';

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

const getContributionAmount = simnet.callReadOnlyFn(
  'pool',
  'get-contribution-amount',
  [Cl.standardPrincipal(wallet)],
  wallet
);  

const response = getContributionAmount.result

callPublicFn

Call public functions exposed by a contract.

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

This method 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 { Cl } from '@stacks/transactions';

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

const registerParticipant = simnet.callPublicFn(
  'pool',
  'register-participant',
  [Cl.standardPrincipal(wallet)],
  wallet
);

const response = registerParticipant.result;

callPrivateFn

Call private functions exposed by a contract.

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

This method 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 private function within the contract.

Example: reward-participant-points

args
Required
ClarityValue[]

The arguments to pass to the private 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 { Cl } from '@stacks/transactions';

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

const rewardParticipantPoints = simnet.callPrivateFn(
  "pool",
  "reward-participant-points",
  [Cl.standardPrincipal(address1)],
  wallet
);

const response = rewardParticipantPoints.result;

transferSTX

Transfer STX from one address to another. The amount transferred is in uSTX.

This method 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 equals 1 STX

recipient
Required
string

The Stacks address of the recipient.

Example: ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5

sender
Required
string

The Stacks address of the sender.

Example: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
const accounts = simnet.getAccounts();
const recipient = accounts.get('wallet_1')!;

const transfer = simnet.transferSTX(
  42000000, // 42 STX
  recipient,
  simnet.deployer
);

deployContract

Deploy a contract to simnet.

This method 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 } | null

sender
Required
string

The Stacks address of the sender.

Example: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
import { cvToValue } from '@stacks/transactions';

const sourceCode = '(define-read-only (say-hi) (ok "Hello World"))';

const contract = simnet.deployContract(
  'hello-world',
  sourceCode,
  null,
  simnet.deployer
);

const response = cvToValue(contract.result);

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.

This method takes 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 simnet methods but instead of performing a transaction, they will build a transaction object that can be passed to the mineBlock function.

In epochs from 3.0 on, the stacks chaintip is advanced separately from the burn chaintip. This means mineBlock will only affect the stacks chaintip. If you'd like to also mine burn blocks, use the mineEmptyBurnBlock function.

Parameters

txs
Required
Tx[]

An array of transactions to be included in the block.

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

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((transaction) => {
  console.log(cvToValue(transaction.result));
  if (transaction.events.length > 0) console.log(transaction.events);
});

mineEmptyBlock

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

Returns the new block height.

simnet.mineEmptyBlock();

const response = 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
simnet.mineEmptyBlocks(5);

const response = simnet.blockHeight;

runSnippet

Execute arbitrary Clarity code directly, which allows you 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 { Cl } from '@stacks/transactions';

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

const response = Cl.prettyPrint(codeSnippet, 2);

getContractsInterfaces

Returns the interfaces of the project contracts as a Map of Contracts, with the keys being the contract addresses.

These interfaces contain information such as the available functions, data-vars, maps, NFTs, and FTs defined in the contract.

const contractInterfaces = simnet.getContractsInterfaces();

const response = contractInterfaces.get(`${simnet.deployer}.pool`);

getContractSource

Get the source code of a contract as a string.

Parameters

contract
Required
string

The identifier of the contract for which the source code is requested.

Example: pool
const contractSource = simnet.getContractSource('pool');

getContractAST

Get the full AST (Abstract Syntax Tree) of a Clarity contract.

This method throws an error if it fails to get the AST or to encode it.

Parameters

contractId
Required
string

The identifier of the contract for which the AST (Abstract Syntax Tree) is requested.

Example: pool
const contractAST = simnet.getContractAST('pool');

Properties

Custom Matchers