stacks-core: the Rust node behind the Stacks Bitcoin layer-2

What stacks-core actually is, and who ends up running it

This is a node, not a framework. The README describes stacks-core as the reference implementation of the Stacks blockchain in Rust, and the workspace layout confirms it: stacks-node holds the binary, stackslib holds the chain logic, clarity holds the language implementation, and libsigner and stacks-signer ship alongside. The repository also carries contrib/stacks-inspect, contrib/stacks-cli and contrib/clarity-cli as developer tools in the same workspace.

The problem it solves is specific. Stacks is a layer-2 that uses Bitcoin as a base layer and runs Clarity contracts, with Proof of Transfer mining anchoring leader election to Bitcoin while miners write Stacks blocks separately. Someone has to produce and validate those blocks. stacks-core is that software. The README states plainly that PoX needs no change to Bitcoin to enable smart contracts and decentralized apps.

The audience is narrower than the topic list suggests. If you are standing up a follower to read chain state, running a miner, operating a signer, or building tooling that has to agree byte for byte with the canonical node, this is the code you run. If you want to call Stacks from an application, you want an RPC client or the hosted APIs that docs.stacks.co points to, not a Rust workspace you compile yourself.

Inside the workspace: where blocks, Clarity and signing live

The Cargo.toml workspace members map closely onto the architecture, and reading them is the fastest way to understand the split. stackslib and stacks-common carry shared chain and utility code. clarity and clarity-types implement the contract language and its type system. stx-genesis holds genesis state. stacks-codec and stacks-marf cover serialization and the Merkle-append-only structure used for chain state. pox-locking handles the Proof of Transfer locking logic. libstackerdb and libsigner are the signing-side libraries, with stacks-signer as the binary that wraps them.

Data flow follows from that. The node follows Bitcoin, uses it for PoX anchor blocks and leader election, and produces Stacks blocks that are validated against Clarity execution. Signers participate in block production for the Nakamoto-era flow. The workspace version field is set to 4.0.3 and carries a comment saying the node and signer are released together and share this version, which tells you the two binaries are meant to be deployed as a matched pair rather than upgraded independently.

Two details in the dependency list are worth noting for anyone auditing a build. madhouse and pinny are pulled from git repositories at pinned revisions rather than published crates, so a reproducible build depends on those remotes staying reachable. The Dockerfile builds with the monitoring_prom and slog_json feature flags, which means the container image enables Prometheus monitoring and JSON logging that a plain cargo build --release does not.

Building stacks-core and starting a testnet follower

The README gives an explicit build path, and the first step is a Rust toolchain. It shows the rustup installer plus the rustfmt component, and notes that when building the main branch you should run rustup update to be on the latest stable release.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup component add rustfmt

After that, clone the repository shallowly and move into it. The --depth=1 flag keeps the download to the tip of the branch.

git clone --depth=1 https://github.com/stacks-network/stacks-core.git
cd stacks-core

Now build. The README offers two profiles and is direct about when to use the second: release-lite is described as necessary if the machine has under 16 GB of RAM.

# Fully optimized release build
cargo build --release
# Faster but less optimized build. Necessary if < 16 GB RAM
cargo build --profile release-lite

The README also mentions setting RUSTFLAGS to build for the native CPU, either as an environment variable or by uncommenting the build.rustflags lines in ./cargo/config.toml. That is an optimization, not a requirement, and it makes the resulting binary less portable.

To see the state machine run locally, the README gives a single command that starts the node against the bundled testnet follower config. Expect log output from the node as it follows the testnet chain.

cargo run --bin stacks-node -- start --config ./sample/conf/testnet-follower-conf.toml

If you would rather not build at all, the Dockerfile produces a debian:bookworm-slim image containing stacks-node, stacks-signer and stacks-inspect in /bin, with a default command of stacks-node mainnet. The image is built with cargo build --features monitoring_prom,slog_json --release, so the container has Prometheus metrics and JSON logs enabled by default. The README does not document a published image name or tag, so treat the Dockerfile as a recipe to build rather than a pull command.

Where stacks-core is the wrong tool

The build is the first wall. A full optimized Rust build of a workspace this size is not a five-minute operation, and the README's own note that release-lite is necessary below 16 GB of RAM tells you the default profile expects a real machine. If you are looking for a lightweight client to embed in a mobile app or a serverless function, this is not it. There is no documented library-only entry point for embedding the chain in another process; the workspace produces binaries and crates aimed at the node itself.

Testing on Windows is the second rough edge, and the README says so without hedging: many tests will fail there, mainly due to parallelism, and running them individually may be needed to mitigate it. The recommended test invocation for the testnet suite passes --test-threads=1, which serializes execution at a real cost in wall-clock time. The nextest path warns that a full run typically takes a few minutes.

The third limit is scope. Nothing in the README describes wallet management, key custody or a hosted API. Running a node gives you a view of the chain and, for miners and signers, participation in it. It does not give you an application backend. Teams that adopt stacks-core expecting a batteries-included service usually end up writing the RPC layer themselves, and docs/rpc-endpoints.md is where that work starts.

Finally, the signer pairing is a real operational constraint. Because the workspace comment states the node and signer are released together and share the version, mixing a stacks-node from one release with a stacks-signer from another is not a supported configuration, and the release notes are the place to confirm which pair belongs together.

How it differs from Bitcoin Core and from an indexer

The obvious comparison is Bitcoin Core, and the difference is not a matter of degree. Bitcoin Core validates and relays Bitcoin blocks and has no notion of Clarity contracts or PoX reward cycles. stacks-core follows Bitcoin for anchoring and leader election but maintains a separate Stacks chain with its own state, its own block production and its own execution environment. Running one does not substitute for the other. A Stacks follower depends on access to Bitcoin data, so in practice you run or connect to both.

The second comparison is with an indexer or an RPC provider. An indexer reads a chain and serves queries about it; it does not validate blocks and it does not participate in consensus. stacks-core does both, at the cost of the resources described above. If your only requirement is to read balances or call read-only Clarity functions, a provider endpoint is cheaper and faster to integrate than a node, and the trade-off is trust in that provider rather than verification of the chain yourself.

A third distinction sits inside the repository. contrib/stacks-inspect, contrib/clarity-cli and contrib/stacks-cli exist in the same workspace but are developer utilities rather than the node. They are useful for inspecting state and running Clarity code without standing up a full follower, and the README does not present them as alternatives to stacks-node.

Licence, release cadence and the cost of staying current

stacks-core is released under GPL-3.0, and the README states that the code and documentation copyright are attributed to stacks.org, with the docs under a Creative Commons licence. The practical point for anyone embedding this: GPL-3.0 is a copyleft licence, so distributing a modified stacks-core as part of a larger product carries obligations that a permissive licence would not. That is a statement about the licence text, not legal advice, and any product that links or ships these crates deserves a real review.

The release history shows a steady cadence: 4.0.1 on 2026-07-15, 4.0.2 on 2026-08-11 and 4.0.3 on 2026-09-03, with the workspace version field bumped to 4.0.3. The repository is not archived and its last push was on 2026-09-23. That combination means operators should expect to track releases rather than pin once and forget, and that the changelog.d directory and CHANGELOG.md are the places to read before upgrading. The README points to docs/release-process.md for how releases are cut, which is useful if you need to know what a version bump implies for the node and signer pair.

The upgrade cost is mostly build time and re-verification. There is no documented in-place upgrade path or rollback procedure in the README, so a node operator changing versions is doing a rebuild and restart, and the state migration behaviour is something to confirm from the changelog for the specific version rather than assume.

Editorial conclusion

Adopt stacks-core if you need to run a Stacks follower or miner, or if you are writing against the node's RPC and event interfaces and want the reference behaviour rather than a reimplementation. Do not adopt it if you want a library that embeds a chain into your own process, or if a GPL-3.0 derivative of your product is a problem. Before committing, verify three things: that your machine can complete the release build (the README points to release-lite when RAM is under 16 GB), that the exact tag you intend to run matches the node and signer version you plan to deploy, and that your use of the RPC endpoints in docs/rpc-endpoints.md covers what your integration needs. The repository is not archived and its last push was on 2026-09-23.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. stacks-network/stacks-core on GitHub