Test Your Code With Mainnet Data in Clarinet Simnet

The reality of Web3 development is that it doesn’t occur in a vacuum. Contracts for one project often interact with contracts from other onchain protocols. That is part of Web3’s promise: that code and projects are composable, and you can interact with, and build off of, existing projects.

And to help you build production-ready code that can interact with other contracts on a blockchain network, Clarinet offers a wide variety of tools to help you test and debug your code, including simnet and devnet, test environments that enable you to rapidly and privately test your contracts in the context of a blockchain network before pushing your code to a public testnet and eventually mainnet.

• Simnet: a lightweight environment that simulates chainstate using an in-memory store. This environment is helpful for fast feedback loops and running unit tests and other automated testing against your Clarity code.
• Devnet: a private testnet that can run locally or in the cloud. This environment spins up a local Stacks network (complete with Bitcoin node, Stacks node, an API, etc). Devnet is helpful when you’re developing the rest of your application and need to run integration tests and test your Clarity code alongside your frontend and backend.

However, one area that devs struggle with in development is testing their Clarity code against onchain data that exists on mainnet. For example, if your code relies on an oracle or another DeFi protocol, it’s hard to populate simnet with the right data to accurately test your code.

That changes today.

Bringing Mainnet Data to Simnet

With the latest release of Clarinet, simnet can now ingest mainnet data, so you can more confidently test your Clarity code with real-world data. This is particularly useful if your code interacts with other contracts on mainnet that handle complex data-structures, such as price feeds, PoX historical data, Bitcoin data, and more.

Instead of generating mock data locally (a time-intensive process that introduces its own risks and challenges), you can now rely on data that you’re confident will match what you’ll find on mainnet—because that’s exactly where the data now comes from.

By enabling mainnet data to be used in unit tests and the Clarinet console, you can more confidently test how your code will behave in production, bringing you one step closer to mainnet deployment.

When pulling mainnet data into your simnet instance, you can also configure the desired block height in your project manifest, enabling consistent data retrieval over customized date ranges.

To take advantage of mainnet data in simnet, add the following configuration in your manifest file (Clarinet.toml):

[repl.remote_data]
enabled = true
api_url = 'https://api.hiro.so'
initial_height = 542042

This configuration will tell simnet to fork the mainnet at block height <code-rich-text>542042<code-rich-text>. From there, every interaction with simnet will be able to fetch data from Stacks mainnet, whether it’s through TypeScript unit tests or in the Repl with clarinet console.

For example, you can use this feature to pull Bitcoin’s price into a Clarinet project by pulling the mainnet data from Pyth’s price feed. 

Conclusion

We hope you find this feature useful. The Clarinet team has been cooking, and we have more exciting releases in the works, including a formatter for Clarity code. If you have suggestions for Clarinet, open an issue on GitHub (we welcome contributions!) or reach out to our team in #clarinet in the Hiro Developer Tools channels on Discord.