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

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

const simnet = await initSimnet();

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

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

getContractsInterfaces

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

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

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

const simnet = await initSimnet();

const contractInterfaces = simnet.getContractsInterfaces(); 

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

console.log(poolContract);

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
import { initSimnet } from '@hirosystems/clarinet-sdk';

const simnet = await initSimnet();

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

console.log(contractSource);

getContractAST

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

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

WIP

The ContractAST TypeScript is still very simple but will be improved over time.

Parameters

contractId
Required
string

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

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

const simnet = await initSimnet();

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

console.log(contractAST);

Last updated on

Properties