A Developer’s Guide to Stacks 2.1

The countdown begins to Stacks 2.1, the next protocol upgrade for Stacks. This major network upgrade for the Stacks blockchain will strengthen its connection to Bitcoin by making it easier to earn Bitcoin yield and easier to create applications that leverage Bitcoin DeFi and Bitcoin NFTs. 

In this blog, we’ll cover how 2.1 will affect the developer experience and Hiro tooling, how 2.1 will impact wallets and exchanges, and finally how 2.1 enables new Bitcoin use cases.

Note: for a general overview of 2.1, please check out this blog post from the Stacks Foundation before reading this post.

Changes in Stacks 2.1 will make stacking easier. These changes require updates to Stack’s unique consensus mechanism, Proof of Transfer (PoX). Throughout the blog, we may refer to these changes as part of “PoX 2.”

Changes to Developer Tooling

Hiro builds developer tools that bring fully expressive smart contracts to Bitcoin. Stacks 2.1 will make it easier for developers to build the future of Web3 on Bitcoin. Here’s what each of our products unlocks for 2.1.

Test Drive Your Smart Contracts on Stacks 2.1 in Clarinet

You don’t have to wait until the release of Stacks 2.1 to test out how the network upgrade will impact your smart contracts. The upcoming release of Clarinet 1.0 will empower developers to test out Stacks 2.1, so you can be fully prepared when the upgrade goes live. In particular, this release will add Clarinet Integrate support for 2.1. Learn more about Clarinet Integrate here. We will share instructions on how to test 2.1 with the next Clarinet release.

Integrating PoX 2 Support to the Stacks API

In preparation for Stacks 2.1, the Stacks API has added support for a number of changes, including:

Support for Distinguishing Between Contract Versions

We augmented existing endpoints /extended/v1/tx/<txid> and /extended/v1/contract/<contract-principal> to return a Clarity version. 

Sample Response for a versioned-smart-contract tx with clarity_version 2:

{
  "tx_id": "0x33c573f5ed06f1feecaa4a9df0225e109416dbba9792abb0cd94869bbad4a88a",
  "canonical": true,
  "contract_id": "ST000000000000000000002AMW42H.pox-2",
  "block_height": 2,
  "clarity_version": 2, <-- NEW
  "source_code": ";; PoX testnet constants\n;; Min/max number of reward cycles uSTX can be locked for..."
}

Sample response for a regular (non-versioned) smart-contract tx, with clarity_version null:

{
  "tx_id": "0x55bb3a37f9b2e8c58905c95099d5fc21aa47d073a918f3b30cc5abe4e3be44c6",
  "canonical": true,
  "contract_id": "ST000000000000000000002AMW42H.bns",
  "block_height": 1,
  "clarity_version": null, <-- NEW
  "source_code": ";;;; Errors\n(define-constant ERR_PANIC 0)..."
}

Coinbase Pay Outs

Stacks 2.1 also adds support for new coinbase transactions that pay to either A) a smart contract or B) an alternative standard principal. The latter permits the miner to pay to a cold storage address automatically. The API now returns a new coinbase alt_recipient property on applicable requests to support coinbase-pay-to-alt-recipient transactions.

Sample Pay-to-alt coinbase with standard principal recipient:

"coinbase_payload": {
        "data": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "alt_recipient": "ST2X2FYCY01Y7YR2TGC2Y6661NFF3SMH0NGXPWTV5"  <-- New
      }
    }

Sample Pay-to-alt coinbase with contract principal recipient:

"coinbase_payload": {
        "data": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "alt_recipient": "ST2X2FYCY01Y7YR2TGC2Y6661NFF3SMH0NGXPWTV5.hello_world"  <-- New
      }

Sample Regular coinbase tx (alt_recipient is null):

"coinbase_payload": {
        "data": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "alt_recipient": null  <-- New
      }

PoX 2 Support‍

Upcoming PoX 2 changes require support for a number of new functions, such as stack-increase, stack-extend, and delegate-stack-extend. Support for these features will be added to the API Rosetta implementation soon, and the locked STX amount will continue to function as expected during and after the PoX transition. More information on the PoX transition phases below.

Here are some additional upcoming changes required to ensure Rosetta stacking functionality works with PoX 2:

• PoX address format changes: Adding support for segwit/taproot/bech32 addresses in PoX 2
• Constructing stacking operations: Rosetta has built-in support for performing various "Stacking" operations, which under the hood perform PoX-1 contract calls. These need to be changed to PoX-2 contract calls.
• Parsing stacking operations: Adding support for performing various "Stacking" operations, which involve PoX-2 contract calls
  

These changes are works in progress and will be available with the next 2.1 compatible release of the API.

Stx-transfer Memo Fields

Stacks 2.1 allows specifying memos when transferring STX within contract calls (which can be done with the new Clarity function stx-transfer-memo). The Stacks API has now added support for parsing, storing, and returning the memo field that can be included in Stacks 2.1’s stx_transfer_event.

Here’s a sample Clarity2 versioned-smart-contract with a memo field:

(stx-transfer-memo? 
  u60
  tx-sender
  'ST2X2FYCY01Y7YR2TGC2Y6661NFF3SMH0NGXPWTV5
  0x74657374206d656d6f206669656c64)

The resulting tx from the API will have a stx-transfer event with the associated memo:

{
  "event_index": 0,
  "event_type": "stx_asset",
  "tx_id": "0x6b0f0d3a28693e834f90e95fb058a70922de778d189e64903f550328e6256520",
  "asset": {
    "asset_event_type": "transfer",
    "sender": "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6",
    "recipient": "ST2X2FYCY01Y7YR2TGC2Y6661NFF3SMH0NGXPWTV5",
    "amount": "60",
    "memo": "0x74657374206d656d6f206669656c64"
  }
}

New Stacking Functions and Versioned Smart Contracts in Stacks.js

Stacks 2.1 makes it easier to earn Bitcoin yield by introducing improvements to stacking. Stacks.js will support this new functionality in the @stacks/stacking package of Stacks.js.

Stacks.js will also have the capability to create and serialize the new “versioned-smart-contracts” transaction types, which allows developers to deploy smart contracts using the new Clarity 2 features. For a work in progress list of those Clarity 2 features, click here.

Example usage:

const transaction = await makeContractDeploy({
  contractName,
  codeBody,
  senderKey,
  clarityVersion: ClarityVersion.Clarity2, // <-- NEW
});

For the coinbase-pay-to-alt-recipient transactions mentioned earlier for coinbase payouts, Stacks.js added an optional arg altRecipient to the coinbase payload builder function. If specified, a CoinbasePayloadToAltRecipient type will be created. If not specified, it will default to the regular CoinbasePayload.

Example usage:

const payload = createCoinbasePayload(
  coinbaseBuffer,
  altRecipient,
);

Improving Subnets

The 2.1 upgrade is mission critical for Subnets—the upcoming scalability solution for Stacks. For example, withdrawals on subnets are dependent on 2.1 features, and multi-party contracts and multi-party signers are both contingent on 2.1 for signing. As part of our efforts to test and improve the subnets' performance, we are focusing on key areas, such as MARF and mempool. Follow subnets' progress on GitHub.

New Data in the Stacks Explorer

Starting with 2.1, the Stacks Explorer will display additional data reflected in the API. For coinbase transactions with alt recipient information, the Explorer will display the smart contract address used for payout instead of the current standard recipient address. 

The Clarity version of a smart contract will also be displayed on the Stacks Explorer. A versioned-smart-contract tx with a clarity_version will display “2”, and a regular (non-versioned) smart-contract tx will display null. Additionally, stx-transfer events with memo information will also be displayed in Explorer after the 2.1 upgrade.

How 2.1 Impacts Wallets and Clients

For developers working on wallets and related clients, 2.1 brings a number of important changes to how stacking is handled. In particular:

• Clients can permit users who have already initiated stacking to extend the number of cycles or increase the number of STX locked from the same address. Users no longer have to wait for their preset number of cycles to end before re-stacking with more STX or for a longer number of cycles, solving the existing “cooldown period” problem.
• Clients that stack should automatically direct STX to a .pox-2 contract. Developers don’t need to do anything for this change to take place, and with it, clients can 1) determine that STX have unlocked after the transition and 2) determine when the .pox-2 contract has been instantiated. For more information on the transition period and how it impacts users who are currently stacking, see the next section.
• Clients will report the correct locked/unlocked balance after the transition. Before the transition, all STX locked in .pox show up as “unlocked.” After the transition, all STX stacked show up as “locked.”
• Clients can permit users to stack to native Segwit or Taproot addresses in addition to legacy addresses. More on that in the Bitcoin use cases section below.

The Hiro Wallet team is already at work to support these 2.1 changes by adding the option to increase either the number of cycles or the amount of STX locked for an existing Stacking commitment, instead of having to wait until their STX unlock first. They will also be able to earn BTC to native segwit addresses in addition to legacy ones.

‍Important note: If you are an existing user of the Hiro Wallet with an ongoing stacking commitment at the time Stacks 2.1 goes live, you will need to stack or delegate your STX manually once again, since stacking on Stacks 2.1 is not backwards compatible with Stacks 2.0. Please see the next section for more details.

How 2.1 Impacts Exchanges

Exchanges offering stacking to their users will need to upgrade their code to .pox-2. The original pox code will be defunct after the launch of 2.1. Importantly, the PoX transition will happen in phases. Here are 3 important periods of transition with the 2.1 rollout and how PoX-2 will be fully activated:

• Period 1: We are in Period 1 now, which is pre-Stacks 2.1. Exchanges and clients continue to use .pox code.
• Period 2: This is the transitional period after 2.1 activation and before .pox-2 contracts are fully activated. This period begins with 2.1 activation, which will occur ~81 days after code completion. During this period, the .pox-2 contract will be deployed, but the original .pox contract will still be used to determine rewards. This period will likely last for 1-3 stacking cycles (each stacking cycle is ~2 weeks long) in order to allow time for stacking pools to update their contracts and get users to re-delegate their STX. At the end of this period, all accounts locked using .pox will be unlocked, and any locked funds will be returned to users.
• Period 3: This period begins when the start of the .pox-2 contract activation. By the end of this period, the .pox-2 contract will be fully activated, and afterwards, calls to .pox will no longer work.

These timelines have a critical impact on stacking for users and exchanges: 

• During Period 2, the transitional period between 2.1 activation and PoX 2 not being fully active, users who delegated their STX using the .pox contract (e.g. to a stacking pool) must re-initiate their STX delegations. Developers can enable users to do this via the pox-2.delegate-lock-extend function. Otherwise, the user’s STX may unlock at an earlier cycle than they expected.
• Users who are already stacking from now until PoX 2 is fully activated (Period 1 to 3) and want to seamlessly continue stacking after PoX 2 activation (Period 3) will need to manually call pox-2.stack-extend during the transitional period (Period 2). Otherwise, STX locked in the .pox contract may unlock at an earlier cycle than what the user specified during Period 1.
• During Period 2, clients will only be allowed to initiate stacking or delegated stacking for cycles occurring within Period 2. For example, if Period 2 ends with cycle number 30, stacking for cycle 31 or above will result in a failed transaction.

For more information on these periods, please refer to SIP-015 that details the network upgrade. 

For developers working on exchanges, a testnet (or private testnet) will be available in mid-October to try out the new stacking functionality in order to create a more seamless transition. Developers should also use an officially-supported client library for .pox-2 if they are able, such as the @stacks/stacking package of Stacks.js offered by Hiro.

Bitcoin Use Cases Enabled by Stacks 2.1

One of the most exciting features that the 2.1 upgrade unlocks is the ability to directly send Stacks assets to Bitcoin addresses. Then, only the owner of the Bitcoin address can manipulate the asset on the Stacks chain via a specially-crafted smart contract that can recognize their Bitcoin transactions as contract-calls.

While this can be achieved today if the Bitcoin address owner is willing to create a Stacks address first, Stacks 2.1 removes that requirement altogether. Now use cases like airdropping NFTs to Bitcoin wallets are possible. This simplifies the application-onboarding experience for users and developers alike: users can get started with Stacks applications with only a Bitcoin address.

2.1 also adds support for stacking to a native segwit or taproot address. This saves users Bitcoin transaction fees and enables new stacking functionality, such as building a decentralized stacking pool that pays BTC directly to participants.

Conclusion

Whilst we are near code completion for 2.1, the remainder of Q4 will be spent testing and hardening 2.1.  There are a lot of moving parts to get done before the release of 2.1 in Q4 this year, and we are releasing updates for all Hiro products leading up to the release of 2.1, so as soon as the upgrade is live, you will be able to take full advantage of those changes. You can follow along with progress on Stacks 2.1 here. 

Excited for 2.1? Have more questions than answers? Take a 2.1 quiz from the Stacks Foundation to help us identify any information gaps that need addressing about the upcoming upgrade.