Ctrlk
Quick LinksPlatform
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Latest Updates

Check out the latest Stacks developer updates

More Linting, Less Friction

March 12th, 2026

[Clarinet 3.15.0] This release brings some solid quality-of-life improvements to Clarinet. On the analysis side, there's now static code analysis via CodeLens, and two new linter rules covering at-block and case_binding. Diagnostics now run with and without the #[env(simnet)] annotation during both clarinet check and the LSP. Devnet gets some love too — Docker containers are now grouped, logging is improved in --no-dashboard mode, and the orchestrator has been refactored for better reliability. Under the hood, Chainhooks v1 has been removed, dependencies have been updated, and a fix lands for correctly traversing Clarity 4's as-contract?.

Details

at-block Lint Warning

A SIP is currently up for vote that would remove the at-block function starting in Epoch 3.4. If it passes, any deployed contract calling at-block will start throwing runtime errors after Epoch 3.4 activates, and new contracts using it will be rejected at deployment entirely. To get ahead of this, Clarinet now flags any use of at-block in your code with a lint warning. If you have contracts using at-block, now is the time to audit and refactor. Vote and learn more here.

Static Cost Analysis via CodeLens

You can now see the static max cost of your Clarity functions directly in your editor, displayed inline just above each function definition. No more manually invoking a function and digging through terminal output to get a cost estimate — the analysis is just there, passively, as you write.

Improved devnet start --no-dashboard Logging

Running devnet without the dashboard used to be pretty useless in practice — it would print container status updates, stop once the Bitcoin node was ready, and then go quiet, giving you no visibility into what was actually happening as the chain progressed. That's been fixed. The logs now surface the full chain of events as devnet runs, making it actually usable for local development workflows and, importantly, for AI agents running devnet headlessly in automated pipelines.

case_binding Linter Rule

Clarity convention is kebab-case. The new case_binding lint rule enforces this on let bindings and function argument names, so things like camelCaseVar or snake_case_arg will now generate a diagnostic. If you have a specific binding you want to opt out of the check, you can suppress it with a #[allow(case_binding)] comment on the line above.

Simnet-Only Code Annotations

Clarinet now supports a #[env(simnet)] annotation that lets you mark functions or expressions as simnet-only. Annotated code gets stripped out automatically when deploying to other networks, so test helpers like faucets never accidentally make it to mainnet. To keep things safe, clarinet check and the LSP now run two validation passes: one with the simnet code included and one without, catching any cases where production code accidentally depends on a simnet-only function.

Clarity Plugin for Claude Code

March 11th, 2026

A Clarity plugin for Claude Code is now available via the Stacks Labs Claude plugin marketplace. Install it with two commands and Claude Code will be aware of the Clarity CLI and have access to the Clarity LSP — meaning the agent can actually use the CLI as part of its workflow. More detailed skills around the JS SDK, devnet, deployments, and more are on the roadmap.

Stacks Mesh API for exchanges and institutions

March 10th, 2026

[API] Previously, the Hiro Stacks Blockchain API included an embedded Rosetta implementation, but this was removed due to inefficiency. The standalone Mesh API implementation replaces that prior integration. Mesh (formerly branded as Rosetta) is an open standard originally developed by Coinbase to provide a unified interface for reading data from blockchains. It defines a common set of endpoints that blockchain nodes implement, allowing exchanges and other institutions to write a single parser that works across multiple chains.

Chainstate shrinkage, Signer global state, and more security fixes

March 9th, 2026

[Stacks Core 3.3.0.0.6] This release contains two major infra upgrades: chainstate shrinkage (>20% reduction in daily growth) and the Signer state machine activation (better block production under load). This release also contains several bugfixes and improvements to the stacks-node and stacks-signer binaries, ensuring more consistent block production. Please upgrade if you are a node operator and signer.

sBTC APIs, BNSv2, and new Stacks.js Reference section

March 7th, 2026

The API section now includes the sBTC bridge's Emily APIs, allowing you to track peg-in and peg-out statuses directly within the Stacks docs. We've also updated the BNS section to reflect the canonical BNSv2 protocol, ensuring you have accurate informational context for the latest naming system. Finally, the Stacks.js reference pages have been completely overhauled with an exhaustive list of function and type definitions, making it easier than ever to find exactly what you need.

Enhanced Linting, JSON Output, and Performance Improvements

March 3rd, 2026

[Clarinet v3.14.0] This Clarinet release adds powerful new linting capabilities including improved noop detection, an unnecessary_as_max_len lint rule, and JSON output formatting via clarinet check --output=<format>. The update also includes important bug fixes for linter false positives and devnet timing issues, plus a 15% performance improvement in the clarinet-format tool.

Fetch Deposit and Withdrawal Status for USDCx Bridging

March 2nd, 2026

[USDCx] Deposit and withdrawal status endpoints for USDCx give applications a reliable way to track the lifecycle of cross-chain transfers between Stacks and other networks. Instead of manually monitoring multiple transactions and bridge events, developers can query a single endpoint to see whether a deposit or withdrawal is pending, verified, failed, or completed.

Navigate to the USDCx API section here.

Query PoX Activity on Bitcoin with new API endpoints

February 26th, 2026

[Stacks API] The new PoX-related Bitcoin transactions endpoints are now easily discoverable and indexable for applications interacting with Stacks. These endpoints expose Bitcoin-layer activity that participates in Stacks’ Proof of Transfer (PoX) so apps don’t need to manually scan and decode raw Bitcoin blocks.

Improved Deployment Plan Format

February 14th, 2026

[Clarinet] The latest release of Clarinet (v3.14.0) comes with many small improvements. You'll also notice that the structure of the Deployment plans has changed slightly. The old format is still supported and Clarinet will automatically migrate to the new one. This is to help us bring more improvement to deployment plans in the future. You have nothing to do, but don't be surprised by this change.

Reminder: we are still seeing a lot of downloads on the deprecated NPM package @hirosystems/clarinet-sdk, only the new @stacks/clarinet-sdk is maintained.

Deprecation notices for Hiro's Chainhooks v1 & L1 APIs

February 6th, 2026

[Hiro] Chainhooks V2 is now available. This is a huge upgrade with more capability, better performance, and much greater reliability. But it also means that Hiro is deprecating their hosted Chainhooks v1 on March 9th, so if you’re using Chainhooks via the Hiro Platform, now is the time to upgrade. Self hosted Chainhook instances aren’t affected by this.

L1 Bitcoin APIs shutting down March 9th. Hiro is also deprecating their Ordinals, BRC-20, Runes, and Bitcoin Indexer APIs. They've partnered with Xverse to provide a smooth migration path for these use cases, and have put together a detailed migration guide to help you transition.

Details

  • Chainhooks v2 announcement blog post

  • Hiro's L1 metaprotocol APIs deprecation blog post

Enhanced Block Production and New Block Simulation Capabilities

February 4th, 2026

[Stacks Core 3.3.0.0.5] This Stacks Core release (3.3.0.0.2) introduces a new block simulation endpoint and improves block validation while fixing critical bugs to ensure more stable block production. Key updates include enhanced burn-view calculations, streamlined validation tools, and compatibility with stacks-signer 3.3.0.0.5.0.

Start Cookin' with the Cookbook

January 30, 2026

The Cookbook contains detailed coding snippets known as recipes. Recipes are focused and reusable. They are designed to be referenced, copied, and adapted.

This section provides focused, reusable Clarity and Stacks.js code snippets that solve common problems or demonstrate specific patterns—designed to be referenced, copied, and adapted rather than read end-to-end.

New 'Path To Production' Guide

January 26, 2026

Are you a new developer looking for security resources and best practices for when you're ready for testing or deploying? This page provides an outline of checklist items that you can use to further battle-test your contracts. Head to the Path To Production guide to see what steps you can take to harden your project before mainnet production.

Catch Dead Code Early with Clarity Linting

January 14, 2026

The latest Clarinet v3.13.0 release includes a built-in Clarity linter to clarinet check, enabling dead code analysis and no-op detection, with configurable lint levels and inline overrides. The initial release focuses on identifying unused code and expressions that have no effect on execution. Lint behavior can be customized globally or per rule via Clarinet.toml.

Details

Today, Clarinet introduces a built-in Clarity linter as part of clarinet check, designed to help developers catch common mistakes, eliminate dead code, and improve overall contract quality earlier in the development cycle.

This first release focuses on dead code analysis, surfacing declarations and expressions that have no effect on contract execution and are often sources of bugs, confusion, or unnecessary complexity.

Dead Code Analysis (Available Today)

The initial lint set includes seven configurable lints, each targeting a specific class of unused code:

Identifier
Description

unused_const

Detects unused define-constant declarations

unused_data_var

Detects define-data-var values that are never written to

unused_map

Detects define-map declarations that are never accessed

unused_private_fn

Detects private functions that are never called

unused_token

Detects fungible and non-fungible tokens that are never minted

unused_trait

Detects traits imported via use-trait that are never used as parameter types

unused_binding

Detects unused function arguments and let bindings

In addition, Clarinet includes the noop lint (contributed by GitHub user 0xalpharush), which flags expressions that have no effect, such as: (is-eq 1)

Suppressing Lints

Some unused code is intentional—for example, private functions used only in tests or bindings whose evaluation has side effects.

To handle these cases, Clarinet supports:

Identifier-based suppression

Appending a trailing _ to an identifier might generate other kinds of warnings but the linter will allow them to be unused, following a convention similar to Rust. (Note: prefixing identifiers with _ is not yet supported.)

Line-level suppression

Individual lints can also be disabled on a per-line basis using Clarity annotations:

Configuration

All non-style/non-cosmetic lints are enabled by default at warning level. Style lints may be enabled by default at notice eventually.

Configure individual lints

Configure lint groups

What’s Next

This release lays the foundation for a broader linting system in Clarinet. Upcoming work includes:

  • Style lints for consistent and idiomatic Clarity code

  • Performance lints to surface inefficient patterns

  • Safety lints to help identify potentially dangerous constructs

If you have ideas for additional lints, feedback can be shared via the Clarinet GitHub issue or in the community Discord.

Navigate to the Clarinet section on this.

Completion of dimension-specific tenure extension

January 12, 2026

[Stacks Core 3.3.0.0.4] With dimension-specific tenure extensions, Stacks can extend block limits per dimension (likeruntimeandread_countbudgets) instead of stopping early. This ensures DeFi protocols can process critical flows during high-volatility periods. Hear Alex Huth talk about this during the latest DevRel office hours here.

Multiple language support for Learn

January 9, 2026

The Learn section now supports Chinese and Spanish, helping more developers access clear explanations of how Stacks works. You can switch languages using the selector in the top-right corner of the Learn pages.

Bridging USDCx developer guide

January 8, 2026

Developers can now programmatically integrate the USDCx bridging flow into their app. Deposits are initiated on Ethereum and automatically minted on Stacks, while withdrawals are initiated on Stacks and settled on Ethereum. Check out the guide here and start enabling stablecoin liquidity across the Stacks DeFi ecosystem.

Multiple network URLs supported in RPC-API playground

December 29, 2025

The API playground in the RPC-API reference now supports testnet and mainnet. Use the interactive API playground to test API calls on mainnet, testnet, devnet, or for your own locally running Stacks node.

Stacks Blockchain API v8.13.6 is live

December 22, 2025

[Hiro] This is a required upgrade for all API users (incl. partners & exchanges): adds support for smart contracts deployed with empty source code.

It's an easy upgrade: no DB migrations, and fully compatible with the current chainstate.

See more in Hiro's release notes here.

USDCx now live on mainnet

December 18, 2025

New docs section dedicated to the launch of USDCx is now live here. Learn about its interoperable architecture with Circle's xReserve and discover the Clarity contracts behind the new USDCx token.

Stacks Miners — Please Update ASAP!

December 12, 2025

This release activates the new read-count tenure extensions from SIP-034, a highly anticipated upgrade for builders across the ecosystem.

It also includes several important bug fixes, making this an update you don’t want to delay.

Details

For the latest release: https://github.com/stacks-network/stacks-core/releases/tag/3.3.0.0.2

Details on what was updated

Added

  • Fixed an issue where event.committed was always equal to true in the block replay RPC endpoint

  • Added result_hex and post_condition_aborted to the block replay RPC endpoint

  • Added --epoch <epoch_number> flag to clarity-cli commands to specify the epoch context for evaluation.

  • Support read-count tenure extends

  • Added read_count_idle_timeout_secs config option to set the amount of seconds of idle time must pass before a read-count tenure extend is allowed (defaults to 20 seconds)

  • Send a read-count tenure extend timestamp in the block responses

  • Approve a block with a read-count tenure extend when the appropriate amount of idle time has passed

Fixed

  • Correctly produce the receipt for the costs-4 contract, which was deployed on epoch 3.3 activation. Users who consume node events and want to fill in the missing receipt (e.g. the Hiro API) will need to revert their chainstate to before the 3.3 activation and then resume sync to receive the previously missing event.

Upgrade to Dual Stacking contracts

December 10, 2025

Dual Stacking contracts will be upgraded on Dec 15. This upgrade enables more flexible reward parameters and allows users to view their sBTC holdings and corresponding rewards within the Dual Stacking app.

Details

tl;dr

  • If you enrolled in Dual Stacking you'll be moved over automatically with no action needed.

  • If you did not enroll in the web app but were receiving Dual Stacking rewards through a participating app, you need to enroll on the web app.

To check your enrollment status go to app.stacks.co.

The contract will upgrade from .dual-stacking-v1 to .dual-stacking-v2_0_2 .

Deploy in Clarinet using encrypted mnemonics

December 9, 2025

clarinet 3.11.0 contains support for encrypted mnemonics. This feature gives users the option to encrypt the mnemonic seed phrase in their deployment files, so if a user's machine is compromised by a filesystem reading vulnerability, the seed phrase is not leaked to the attacker.

Details

To use this feature, a user must first run clarinet deployments encrypt, which will prompt the user for the seed phrase and a password, then print the encrypted mnemonic to the console. The user can then put the resulting ciphertext into their deployment config file using the key encrypted_mnemonic. The next time the user runs clarinet deployments apply, they will be prompted for the password, and the mnemonic will be decrypted for use in that session.

For example, if your settings/Mainnet.toml file looks like this:

You would then run:

You would then replace the mnemonic field in your settings file with the encrypted_mnemonic output above:

Then the next time you deploy your package, you will be prompted for the password:

New Tutorials section

December 7, 2025

The new Tutorials section is now live on the Stacks docs!

First up: the beloved Bitcoin Primer by Kenny Rogers.

We’re building a collection of the best full, end-to-end tutorials in the Stacks ecosystem. If you want to contribute a complete end-to-end tutorial related to developing on Stacks, let us know!

Clarity 4 is now LIVE!

November 18, 2025

SIP-033 and SIP-034 have officially activated at Bitcoin block 923222 – bringing Clarity 4 live on Stacks, the smart contract layer secured by Bitcoin.

This upgrade introduces Version 4 of the Clarity smart contract language, marking a major step forward for the Stacks ecosystem. For users, it delivers safer, smarter contracts with enhanced built-in protections.

For builders, it unlocks five powerful new functions that make developing secure, flexible, and Bitcoin-native DeFi applications easier than ever.

Details

What Clarity 4 Means for Bitcoin Builders

1. On-chain Contract Verification

Developers can now fetch the hash of another contract’s code body.

contract-hash?

This makes it possible for one contract to verify that another follows a specific template before interacting with it – a major step toward safer, more trustless bridges and marketplaces that can support a wider range of assets.

2. Allowing Contracts to Set Post-Conditions

New functions allow contracts to set post-conditions that protect their assets.

restrict-assets?

This means a contract can safely call external contracts (such as traits) and automatically roll back any changes if the executed code moves assets beyond what’s allowed.

3. Convert Simple Values into ASCII Strings

Clarity 4 adds a function to convert simple values like booleans or principals into ASCII strings.

to-ascii?

This makes it easier to generate readable, string-based messages – a useful tool for developers building cross-chain features and integrations.

4. Get the Timestamp of the Current Block

A new keyword lets developers retrieve the timestamp of the current block.

stacks-block-time

This addition enables time-based logic in smart contracts – an essential capability for building features like yield schedules, lockups, or expiration conditions in DeFi applications.

5. Native Passkey Integration

Clarity 4 introduces a new function enabling on-chain verification of secp256r1 signatures.

secp256r1-verify

This lays the groundwork for passkey-based authentication, opening the door to features like hardware-secured wallets and biometric transaction signing.

6. Dimension-specific Tenure Extensions

The SIP-033 vote also included technical rider SIP-034, which introduces dimension-specific tenure extensions. Signers can approve resets to one budget dimension (e.g., read-count) without resetting the others, allowing high-throughput workloads even when the cost model is pessimistic.

Why This Matters for Bitcoin

Clarity 4 strengthens Stacks' position as Bitcoin's liquidity layer by giving developers the tools to build more sophisticated Bitcoin DeFi applications – all secured by Bitcoin through Stacks' Proof of Transfer mechanism.

Whether you're building Bitcoin lending protocols, yield products with sBTC, or the next generation of BTCFi applications, Clarity 4 delivers the security and functionality Bitcoin capital markets demand.

Check out the full SIP-033 & SIP-034 specifications.

Additional Resources

  • [Hiro Youtube] A Dev N' Tell with Brice on new Clarity 4 features

Clarinet was migrated to Stacks Labs

November 5, 2025

You may have noticed that the Clarinet repository now belongs to the stx-labs organization.

With the 3.9.0 release, a few other things have changed:

  • The NPM packages are now published under the @stacks organization.

  • The Clarity VSCode extension is now published under the Stacks Labs organization.

Details

tl;dr

Checklist: ✅ Update NPM packages:

  • "@stacks/clarinet-sdk": "^3.10.0"

  • "vitest-environment-clarinet": "3.0.2" ✅ Replace all imports of @hiroystems/clarinet-sdk to @stacks/clarinet-sdk ✅ Optionally, update Vitest to v4 and update vitest config

How to migrate?

VSCode

In VSCode (or similar variants such as Cursor), you'll have to uninstall the Hiro Systems "Clarity" extension in favor of the new "Clarity - Stacks Labs" extension published by Stacks Labs. The name of the extension will eventually revert to "Clarity" at some point, once the Hiro one is deprecated. You can also see it in the online marketplace - feel free to leave a 5 ⭐ review if you enjoy Clarinet!

NPM

New Clarinet projects created with 3.9.0 will automatically use the @stacks/ NPM package.

However, older projects require a few manual updates to be migrated.

package.json

In your package.json, replace @hirosystems/clarinet-sdk with the @stacks one, and upgrade vitest-environement-clarinet to version 3.0.1. Your dependencies should look like that.

Optionally, you can upgrade to Vitest@4, more on that below

tsconfig.json

In the tsconfig.json, you need to update the "includes" config like so, so that is using @stacks/clarinet-sdk

vitest.config.ts (or .js)

Your Vitest config has to import @stacks/clarinet-sdk/vitest.

Double check that you import defineConfig from "vitest/config" and not "vite".

If you upgraded to Vitest v4, a few other changes are needed in defineConfig:

Docker image

The Clarinet Docker image has been moved from Docker Hub to GitHub Container Registry (ghcr). It can be used like so:

Double check

Search for all occurrences of @hirosystems/clarinet-sdk in your project; they'll likely need to be updated to @stacks/clarinet-sdk.

If you're using third-party tools like Rendezvous or Clarigen, they now both support @stacks/clarinet-sdk.

See it in action

See how the clarity-starter project was updated in this PR: stx-labs/clarity-starter#17

Conclusion

We understand that these types of breaking changes can be frustrating. Although it's not ideal, we need it to move forward.

If you experience any issues with the migrations, reach out to us in the #clarinet channel on Discord or reply to this discussion.

PreviousAI
NextOverview

Last updated

Was this helpful?