[RFC] Stacks 1.0 -> 2.0 Upgrade Process

Hi everyone,

This post describes the proposed process for upgrading Stacks 1.0 nodes to Stacks 2.0. If you currently operate a Stacks 1.0 node, or plan to mine on Stacks 2.0, please read carefully and provide any feedback in the comments below!

Goals of the upgrade process:

  • Accurate: all relevant data from Stacks 1.0, especially accounts, balances, locks, vesting schedules must be correctly preserved in the upgrade process.
  • Decentralized: the upgrade should be triggered by independent miners expressing interest to mine on Stacks 2.0. No single entity, especially PBC, would have control on the precise timing.
  • Predictable: especially considering the point above, the upgrade process should provide predictability to users, developers, miners, exchanges and other stakeholders in the ecosystem on the mechanics of the upgrade process once the threshold for “sufficient miner interest” has been met.

Proposed upgrade process:

  • Registration: all prospective miners SHOULD register a Stacks ID on Stacks 1.0 under a dedicated namespace (say .miner)
  • Threshold Trigger: the Stacks 1.0 software will watch the .miner namespace, and once there are at least 20 IDs registered in the .miner namespace, it will trigger a countdown for the export step below.
  • Stacks 1.0 Export: 300 Bitcoin blocks (~2 days) after the threshold trigger, the Stacks 1.0 software will generate a snapshot of the Stacks 1.0 chainstate. No new transactions will be accepted after this point, though nodes might still serve read requests.
  • Import into Stacks 2.0 genesis: Stacks 2.0 software will import the exported snapshot from the above step to instantiate the Stacks 2.0 genesis block. The Stacks 2.0 chain will go live 300 (~2 days) Bitcoin blocks after the threshold trigger (so 300 blocks after the export step). Note that this means there’s going to be a “dead time” of ~2 days during which no new Stacks 1.0 transactions would be admitted and Stacks 2.0 would not have launched yet.

The 300 block window between Stacks 1.0 import and Stacks 2.0 genesis events would be useful for node operators and miners to do adequate testing and validation to ensure a correct and orderly Stacks 2.0 launch. This number is subject to change as we gather feedback from node operators and community members.



I wonder how much we should aim for accuracy. When upgrading balances from Stack 1.0 to 2.0 a different kind of stx tokens are created on Stacks 2.0 than they are created through Stacks 2.0 mining. The Stack 1.0 tokens did not pass through the burnchain transfer process, at least those that weren’t paid for in BTC.

The process looks sound - just curious as to the process for those that are not currently 1.0 miners. Where will they get the snapshot from? Will there be a requirement to become a 1.0 miner first


Thank you for this Diwaker.

Think it could make sense for Daemon to include registering a name at the .miner namespace as part of either the registration or prize fulfillment for the upcoming testnet mining contest. Let me know if you disagree.

1 Like

Will this also include names and namespaces?

Great work on this @diwaker! The general process makes sense to me.

At first glance, this time frame (4 days) between trigger and Stacks 2.0 live seems way too short to get everyone on the same page.

I’d imagine something on the order of a couple to a month after trigger to get the word out about the date for Stacks 2.0 genesis block and build up excitement, schedule parties & meetups for the cutover and make sure people have their wallets updated and exchanges pointed to new nodes etc.

Something like January 14 software is available, Perhaps it takes 2-3 days for a quorum of miners to be reached. Trigger reached on January 17. Now people paying close attention know that ~February 17 will be the launch date. Those people can spend the time between then and launch getting the word out to others, helping everyone get their clients and wallets updated and plan celebrations for February 17th!

What? If the blockchain isn’t accurate, what is it doing?

Can you point me to more information about this?

1 Like

It is about accuracy of the migration, not of the blockchain. AFAIK, Bitcoin did not have coins in the genesis block. Does it make a difference if Stacks 2.0 have some or does not have some?

That is the difference I was referring to: coins in the genesis block vs coins that are minted. The former are created at the mercy of the initial miners. The latter are created following the consensus algorithm.

The genesis block was a number of years ago https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/

AFAIK Stacks 2.0 isn’t creating any new coins as part of the hard fork upgrade process…the Stacks 2.0 genesis just accurately copies the state of the existing system.


PBC will publish signed snapshots that others can import, and independently verify.

1 Like

Yes. For the curious, all work (as has always been the case) is happening in the open on our Github. Here’s a link to the upgrade specific issues.

Well, we’ve been talking about Stacks 2.0 mainnet launch already for months, so I’d hope that all interested parties feel they’ve had plenty of time to prepare and get the word out! :sweat_smile:

There are also many in the Stacks ecosystem who (for good reasons) would strongly prefer a launch sooner rather than later. Ultimately the exact timing of the launch will be determined by independent miners. From PBC’s perspective, we’re trying to be feature complete by December 15th and focus all our energy on testing from then until the launch.

1 Like

There’s a difference between getting the word out that this is coming in the future, and having an actual countdown to a scheduled release that we can create specific hype around. I understand why we’re doing it this way, I just think we need to be clear about expectations, and that the sooner rather than later approach may end up being short sighted. We won’t be able to build hype and excitement around the launch in a comparable way to other networks, including Eth 2.0, Polkdadot etc.

I’m also not asking for specific promised dates around engineering releases. This is more about us on the non-technical side being able to do a decent job of marketing and distribution to use arguably the biggest event in Blockstack history to raise awareness and hopefully swell the community. I still believe there’s a middle ground that can be reached here to accomplish that, this just isn’t it.


100% agree with @xan

There’s a difference between talking about a future event in general terms - “Stacks 2.0 will launch somewhere around H2 of 2020” and specific terms “the Stacks 2.0 upgrade will happen at block 123,456.” General terms don’t allow anyone else to plan or take actionable steps.

Users can’t upgrade their wallets, enthusiasts can’t schedule meetups & parties, marketers can’t coordinate with press, bloggers can’t schedule blog posts, etc. There are a lot more moving parts in a crypto ecosystem than in your typical ship fast and break things SV start up.

You can of course shortcut the process by doing a quick and quiet launch, but then you forgo the social value - generating excitement and pulling more people into the ecosystem - of the launch process. I’m not sure why you’d do that.

This is exactly the crux of the issue. If exact timing of the launch is triggered by independent miners then it makes sense to have an adequate period of time between when miners trigger the scheduling of the event and when the event actually happens.

What’s the rush?

I propose increasing the window between threshold trigger and Stacks 1.0 state export from 300 blocks to something more reasonable like 2016 blocks (1 bitcoin difficult adjustment window cycle - ~2 weeks).

I’m not proposing delaying the launch.

Let’s get it right! No need to rush!

1 Like

There are some negatives to delaying that could offset some of any efforts made to build hype/excitement given more time. That is 1) current token holders complaining and trolling/fudding on social channels about the delays, and 2) every month that goes buy about another ~40M tokens unlock and this added inflation puts downward pressure on the token price. And importantly a token with a falling price and market cap produces the opposite of hype/excitement. People get excited about a new up-n-coming project/coin climbing up the coin mkt cap rank.


Thanks for the input and suggestions Larry! I wanted to add some more background. We’ve had a notice up for a while e.g., this Sep post gave the target of Dec 15th for readiness. We have (a) proactively communicated out to parties who need to integrate and (b) been already working on potential marketing events. If anything the marketing/community activities are not the bottleneck here (the Hiro PBC team and others have had time to prepare) but engineering is dictating the timelines here which makes sense given that we want to optimize for safety and a high-quality launch – no one wants to have bugs for a new blockchain launch!

Software will be available Dec 15th with the code freeze. It’s kind of already available given the Xenon release has most of the features.

I think the time to get the word out is between Dec 15th and Jan 14th!

I see where you’re coming from Xan! I think the bottleneck is not additional time for marketing. Hiro PBC growth team for example has a lot of activities planned but the activities are more impactful closer to the actual launch so no matter how much time you introduce here, the last 30 days is where most of the action is going to happen. We are still 40 days out. I’ll let people like Mitchell and Patrick chime in but my understanding is that adding more time for marketing/community actually hurts instead of helping because it’s hard to build excitement for something that is just too far out.

Also, I’m in the camp that the most important thing here is getting the Clarity contracts and earning BTC features live. Stacks 1.0 is a very limited blockchain compared to Stacks 2.0 which is the main design. I’d personally much rather have the main system with full features live sooner rather than later. There is nothing more exciting to me than seeing real Clarity contracts live!


I’m against pushing the date back for marketing reasons. I think we’ve got just about everything we can reasonably do for this launch lined up. Delaying further actually kills the hype and momentum that the ecosystem has been able to establish through campaigns that are already running and the recent slate of news. We just hit an all-time peak in terms of people talking about the project so the conventional wisdom would say to try and strike when the iron is hot.

Ultimately, there is only so much you can market a launch at a point in time, the ‘real’ marketing beings when people can actually use the system.

Of course, if miners or technical folks end up needing more time for a solid technical reason/to ensure security and usability of the network, then of course I would support a different timeline, but it certainly shouldn’t be pushed for marketing reasons imo.

1 Like