Contract Interaction

Clarinet provides powerful tools for interacting with your contracts during development. The console gives you an interactive REPL where you can call functions, inspect state, and debug issues in real time. This interactive REPL environment in the console is also referred to as the simnet.

What is a simnet?

• Simnet is a lightweight environment optimized for fast feedback loops, introspection and portability.

• Simnet focuses on letting you quickly iterate on your code and test the code of the contract itself through unit testing. It’s a good preliminary debugging step before introducing the additional variables that come with a fully-fledged blockchain environment.

• Simnet enables you to create a bunch of reports about contract analysis, execution costs, and more and is a useful tool for unit testing your smart contracts.

• In simnet, the blockchain environment is simulated and can be run anywhere (in the terminal with clarinet console, web browsers, GitHub actions, etc).

Starting the console

Use clarinet console to launch an interactive session with your contracts deployed to a local simulated blockchain REPL. This is also referred to as simnet.

clarinet console

Sample startup output:

clarity-repl v3.3.0
Enter "::help" for usage hints.
Connected to a transient in-memory database.

The console supports several useful flags for different development scenarios:

Option	Description
--enable-remote-data	Connect to mainnet or testnet to query real contracts
--deployment-plan-path <path>	Use a specific deployment plan
--manifest-path <path>	Use an alternate Clarinet.toml location
--remote-data-api-url <url>	Specify a custom Stacks API endpoint
--remote-data-initial-height <height>	Set the starting block height for remote data

Working with remote data

One of the most powerful features is the ability to interact with real mainnet or testnet contracts from your local console. This lets you test against actual deployed contracts:

clarinet console --enable-remote-data

Example contract calls:

(contract-call? 'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token get-decimals)
;; (ok u8)

(contract-call? 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.arkadiko-token get-name)
;; (ok "Arkadiko Token")

These capabilities help you:

• Test integrations with existing protocols

• Verify contract behavior against live chain state

• Develop contracts that depend on mainnet deployments

Warning: Remote data requirements

Before using remote data, add the target contract to Clarinet.toml with clarinet requirements add SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token.

Using the Hiro API key

Avoid rate limits by setting the HIRO_API_KEY environment variable before launching the console. Clarinet forwards this key in the x-api-key header for all requests:

export HIRO_API_KEY=your_api_key_here
clarinet console --enable-remote-data

You can request a free API key from the Hiro Platform.

Working with contracts

List all available contracts in the session:

::get_contracts
;; +---------------------------------------------------------+----------------------+
;; | Contract identifier                                    | Public functions    |
;; |---------------------------------------------------------+----------------------|
;; | ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.counter      | (count-up)          |
;; |                                                         | (get-count (who ...))|
;; +---------------------------------------------------------+----------------------+

(contract-call? .counter count-up)
;; (ok true)

(contract-call? .counter get-count tx-sender)
;; u1

Working with different principals

Switch between the provided test wallets to validate multi-user flows:

::get_assets_maps
;; +-------------------------------------------+-----------------+
;; | Address                                   | uSTX            |
;; |-------------------------------------------+-----------------|
;; | ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM | 100000000000000 |
;; | ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5 | 100000000000000 |
;; ...

::set_tx_sender ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5
;; tx-sender switched to ST1SJ3DTE5DN7X54YDH5D64R3BCB6A2AG2ZQ8YPD5

Working with block heights

Advance the chain to test time-dependent logic:

::get_block_height
;; Current block height: 4

::advance_chain_tip 100
;; new burn height: 3
;; new stacks height: 104

::get_block_height
;; Current block height: 104

Tip: Console reference

For a complete list of console commands, see the CLI reference.

Common issues

Contract not found errors

If you see use of unresolved contract errors, the contract may not be deployed or the name might be incorrect:

(contract-call? .missing-contract get-value)
;; error: use of unresolved contract

Solutions:

• Check for typos in the contract identifier

• Confirm the contract is deployed in the current session with ::get_contracts

• Use the correct prefix (. for local contracts)

Remote data connection issues

When you enable remote data, rate limits or connectivity problems can occur:

(contract-call? 'SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.arkadiko-token get-name)
;; error: API rate limit exceeded

Solutions:

1. Set your Hiro API key: export HIRO_API_KEY=your_key_here

2. Use a custom API endpoint: --remote-data-api-url https://your-node.com

3. Wait for rate limit to reset (usually 1 minute)