Nakamoto Support Now Live on Simnet and Devnet

The Stacks ecosystem has been hard at work preparing for the upcoming Nakamoto upgrade, a major improvement to the Stacks blockchain, bringing faster block times and 100% Bitcoin finality. 

Nakamoto mainnet activation window opens August 28th, but now, with the latest release of Clarinet, builders can experiment locally with Nakamoto rules and Clarity 3 in simnet and devnet. In this post, we’ll show you how.

Helpful Terms

Before we jump to the Clarinet instructions, here’s a refresher on key terms related to the Nakamoto upgrade.

• Epoch 2.5 and Epoch 3.0
  Epochs refer to specific periods of time in a blockchain’s history. Stacks is currently in epoch 2.5, which instantiated the pox-4 contract, detailed in SIP-021. Nakamoto consensus rules will take effect in epoch 3. For more details, refer to the Nakamoto rollout plan.

• PoX-4 and Clarity 3
  The Nakamoto upgrade necessitates updates to PoX and Clarity. PoX refers to Proof of Transfer, the primary consensus mechanism powering the Stacks blockchain. pox-4 is the latest version of the Proof of Transfer contract, it was introduced with epoch 2.5 upgrade as part of the Nakamoto upgrade. Clarity is the smart contract programming language for the Stacks ecosystem. Clarity 3 refers to the latest version of Clarity. You can read more about Nakamoto-related changes to PoX and Clarity here.
  ‍
• Simnet and devnet are two types of blockchain networks for developing and testing smart contracts. Simnet offers fast feedback loops, ideal for quick code iteration and contract testing through unit tests. It's a preliminary debugging step before moving to a full blockchain environment. A devnet serves as a local blockchain environment tailored for rapid smart contract development, allowing thorough testing on a mock network with miners, nodes, and a stream of mined blocks. This setup provides a realistic environment to validate your smart contracts effectively. Learn more about the differences between simnet, devnet and testnet.

Try it for yourself

With just a few short steps, you can start experimenting with Stacks epoch 3.0 in your local environment. Note, these instructions work for Clarinet. Epoch 3.0 support in the Hiro Platform is not yet available, but is expected to ship in the coming weeks.

Are you a visual learner? Check out this video tutorial from Eric, Hiro's Dev Advocate.

Setting up a fresh Clarinet project

clarinet new nakademo
cd nakademo
clarinet contract new nakademo

We just created a new Clarinet project and a new contract named <code-rich-text>nakademo<code-rich-text>.

By default, this contract will be set to be deployed in epoch 2.5, with Clarity 2. We’ll need to change that to epoch 3.0 and Clarity version 3.

Let's open the <code-rich-text>Clarinet.toml<code-rich-text> file and change this contract settings. Find the <code-rich-text>contract.nakademo<code-rich-text> section and update it to:

# nakademo/Clarinet.toml

[contracts.nakademo]
path = 'contracts/nakademo.clar'
clarity_version = 3
epoch = 3.0

We'll also update the content of the contract itself, for the purpose of this demo, we'll use the new Clarity 3 keywords, <code-rich-text>stacks-block-height<code-rich-text> and <code-rich-text>tenure-height<code-rich-text>.

;; nakademo/contracts/nakademo.clar

(define-read-only (get-heights)
  {
	stacks-block-height: stacks-block-height,
	burn-block-height: burn-block-height,
	tenure-height: tenure-height,
  }
)

(define-public (print-burn-and-stacks-heights)
  (begin
	(print (concat "Burn block height: " (int-to-ascii burn-block-height)))
	(print (concat "Stacks block height: " (int-to-ascii stacks-block-height)))
	(ok true)
  )
)

If you are using VSCode, make sure to have the latest Clarity version (>= 1.14.0). You should be able to hover the new keywords and see the documentation.

Run in Simnet

We can use <code-rich-text>clarinet console<code-rich-text> to make sure that our contract works as expected.

>> ::get_epoch
Current epoch: 3.0
>> (contract-call? .nakademo get-heights)
(tuple (burn-block-height u1) (stacks-block-height u1) (tenure-height u1))
>> (contract-call? .nakademo print-burn-and-stacks-heights)
Events emitted

You should see the events emitted.

Note that in epoch 2.5, the Stacks chain tip and the Bitcoin chain tip advance at the same pace (1 bitcoin block = 1 stacks blocks). In epoch 3.0, Stacks block can advance independently from Bitcoin block (so <code-rich-text>advance_chain_tip<code-rich-text> only advances the stacks block height, not the bitcoin).

Now that you’re in the console and you have simnet up and running, you can try these three commands. 

• Use <code-rich-text>::advance_chain_tip 2<code-rich-text> to mine 2 empty Stacks blocks.
  
• Use <code-rich-text>::advance_burn_chain_tip 1<code-rich-text> to mine 1 Bitcoin block, triggering 1 new Stacks block.
• Call the <code-rich-text>get-heights<code-rich-text> method to see the new values: burn block height, stacks block height and tenure block height.

Run in Devnet

Now, let's deploy the contract in our local devnet. Just like simnet, the devnet is set to run in epoch 2.5 by default. We need to update some settings to preview Nakamoto. Open the <code-rich-text>settings/Devnet.toml<code-rich-text> and update the <code-rich-text>[devnet]<code-rich-text> section with:

# nakademo/settings/Devnet.toml

[devnet]
disable_stacks_explorer = false
disable_stacks_api = false

stacks_node_image_url = "quay.io/hirosystems/stacks-node:devnet-3.0"
stacks_signer_image_url = "quay.io/hirosystems/stacks-signer:devnet-3.0"

epoch_3_0 = 144

You can also double check the <code-rich-text>pox_stacking_orders<code-rich-text> config at the end of the file. You should see 3 of them (for wallets 1, 2, and 3).

[[devnet.pox_stacking_orders]]
start_at_cycle = 1
duration = 10
auto_extend = true
wallet = "wallet_1"
slots = 2
btc_address = "mr1iPkD9N3RJZZxXRk7xF9d36gffa6exNC"

There are a few important things to keep in mind, especially if you want to set up an existing project for epoch 3.0. 

Nakamoto relies on Stackers and Signers to properly work. In devnet, epoch 3.0 has an automatic stacking mechanism (the <code-rich-text>stacking_orders<code-rich-text> setting). Since the stackers are signing the blocks, the minimum stacking threshold must be met for each pox cycle. To achieve this, the three stacking orders should each take 2 slots. Make sure to have <code-rich-text>auto_extend = true<code-rich-text> enabled to keep stacking indefinitely.

Now you're ready to start the devnet:

clarinet devnet start

Clarinet will automatically mine Bitcoin blocks up to height 144 (should take less than a minute), when it'll switch to epoch 3.0. Our <code-rich-text>nakademo<code-rich-text> contract will be deployed then.

Life in the Fast Lane

With Nakamoto support in simnet and devnet, builders can prepare for that activation by developing and testing out their Clarity 3 contracts today. The activation window for the Nakamoto upgrade is right around the corner, bringing with it a new era for Stacks, one with faster block times and 100% Bitcoin finality. See you in the fast lane!

‍