How to Setup a Stacks 2.1 Local Environment to Test Clarity 2 Contract Functions

If you’re a developer, you might want to start testing out a number of different Stacks 2.1 features, including Clarity 2, new keywords and built-in functions, as well as the soon-to-be-deployed PoX and stacking changes (learn more about the changes to Proof of Transfer and stacking). 

The good news is that Clarinet supports such testing. In this post, we’ll provide the Clarinet configuration you need to start experimenting with Stacks 2.1 and testing Clarity 2 features.

The tl;dr for Clarinet and Stacks 2.1 testing

To test your contracts in the Stacks 2.1 epoch, change these two configuration files in the Clarinet project:

In your <code-rich-text>Clarinet.toml<code-rich-text> file, you can change each contract’s specifications:

• <code-rich-text>clarity_version = 1<code-rich-text> → <code-rich-text>2<code-rich-text>

• <code-rich-text>epoch = 2.0<code-rich-text> → <code-rich-text>2.1<code-rich-text>

In your <code-rich-text>settings/Devnet.toml<code-rich-text> file, either add these comments (Clarinet v1.2.0 or earlier) or uncomment them (>v1.2.0):

enable_next_features = true
epoch_2_0 = 100
epoch_2_05 = 101
epoch_2_1 = 102
pox_2_activation = 103

Creating a New Stacks 2.1 Project in Clarinet

With the latest version of Clarinet, you can start a new project in terminal with:

clarinet new stacks-2.1-app && cd stacks-2.1-app

Then create a new contract:

clarinet contract new bridge-contract

Now let’s add one of the new Clarity 2 keywords going live with the 2.1 blockchain update to our contract: <code-rich-text>principal-destruct?<code-rich-text>. You can read more about this new function and its rationale—namely, that it decomposes a standard principal into its component parts—but here we are simply using a new Clarity 2 keyword to demonstrate the changes in Clarinet that support experimenting with Stacks 2.1 (as well as the VS Code extension upgrades for the 2.1 era, including Clarity 2 syntax highlighting, “go to definition” code navigation, and more).

To add the keyword, use the following snippet:

(principal-destruct? tx-sender)

VS Code’s Clarity syntax highlighting defaults to Clarity 1 syntax—and this new keyword is a Clarity 2 feature. Let’s fix syntax highlighting.

In our project’s <code-rich-text>Clarinet.toml<code-rich-text>, there are new settings under the contract we created with defaults, including:

• <code-rich-text>clarity_version = 1<code-rich-text>

• <code-rich-text>epoch = 2.0<code-rich-text>

To test our contracts with Clarity 2 features in a simulated Stacks 2.1 blockchain—and turn on Clarity 2 syntax highlighting within VS Code—we will change these settings to <code-rich-text>2<code-rich-text> and <code-rich-text>2.1<code-rich-text> respectively.

Inside the terminal of the project directory, we can run a <code-rich-text>clarinet check<code-rich-text> to get Clarinet’s feedback on our settings. 

Spawning a Local Devnet

Now let’s spawn a local devnet with <code-rich-text>clarinet integrate<code-rich-text>, which permits developers to test their deployments and contract interactions, and generally evaluate their application. Before we run Clarinet integrate, either add or uncomment these five lines in our <code-rich-text>Devnet.toml<code-rich-text> file found under the project’s <code-rich-text>settings/<code-rich-text> folder, which specify which Stacks blocks these Stacks 2.1 contracts or blockchain changes go into effect:

enable_next_features = true
epoch_2_0 = 100
epoch_2_05 = 101
epoch_2_1 = 102
pox_2_activation = 103

Note: <code-rich-text>pox_2_activation<code-rich-text> has some restrictions on valid block height, given the underlying PoX cycles, and so for that reason, the PoX activation height needs to match with the beginning of a new PoX cycle.

As you can see here, we can activate the 2.1 epoch at any given block height of our locally simulated Stacks blockchain—we chose block 102. This will happen on Stacks mainnet at a specific block <code-rich-text>v1_unlock_height<code-rich-text>, an as-yet-undetermined block to be mined around January 17th, 2023. 

Choosing different block heights for different epochs allows developers to test and see how their contracts work in a multi-epoch environment. For instance, a developer can publish a Clarity 1 contact to a 2.05 epoch, then a Clarity 2 contract in a 2.1 epoch, and test these two contracts interacting, or both contracts interacting with the new PoX-2 contract. 

And here we see Clarinet integrate successfully deploying our Clarity 2 contract, which we named <code-rich-text>bridge-contract<code-rich-text>, to our local devnet.

Conclusion

With these new Clarinet features, users can develop and test out their Clarity 2 contracts in advance of the major blockchain upgrades. See you when 2.1 goes live on mainnet around January 17th, 2023!