# stacks-network/stacks: a Bitcoin layer documented but not implemented here > This repository documents the Stacks layer rather than implementing it, holding a README, notes on sBTC and stacking, and links to the Rust reference implementation and the Clarity book. Useful as an architecture map, useless as something to vendor. **stacks-network/stacks** — Overview of Bitcoin's Stacks layer. - Repository: https://github.com/stacks-network/stacks - Website: https://www.stacks.co/ - Stars: 2,058 · Forks: 258 - Language: Unknown - License: not declared - Published: 2026-10-14 · Updated: 2026-10-14 · Language: en - Canonical page: https://hysenlabs.com/projects/stacks-network-stacks ## The repository holds notes, not the nodes that run Stacks The project's short description calls it an overview of Bitcoin's Stacks layer, and the file inventory matches that line. Alongside `README.md` sit `bitcoin-rollups.md`, `sBTC-FAQ.md`, `stacking.md`, `stacks-l2.md`, `why-stx.md` and three directories, `sBTC/`, `standards/` and `whitepapers/`. No crate, no manifest and no build script appear at the top level, so anyone who clones this expecting a node to compile finds nothing to compile. The Code section of the README hands off instead, pointing at `stacks-blockchain` for the Rust reference implementation, `stacks-network/docs` for community documentation and `stacks.js` for identity, auth and signing in JavaScript. Read it as a reading list with a summary attached: fine for architecture, useless as an integration target. ## Microblocks, Bitcoin settlement and bidding that spends BTC Bitcoin is the settlement layer, and the project's own account calls it minimal by design and meant to not change. Everything Stacks adds sits above it without modifying Bitcoin L1. Thousands of transactions at the layer collapse into a settlement on Bitcoin, while Stacks microblocks give fast confirmations for streaming transactions in between two Bitcoin blocks. Consensus spans both chains through Proof-of-Transfer, and there the roles invert the usual mining picture: miners bid by spending BTC, receive a random probability of becoming leader, and that election is settled on Bitcoin. New blocks are then written on the Stacks layer, using the BTC that was committed. Proof-of-work energy gets recycled rather than burned at the layer that needs ordering. ## What the Nakamoto upgrade adds, and why the tense slips Three capabilities define the change, and all three come from one proposal. SIP-021 adds a trustless two-way Bitcoin peg to move BTC in and out of the layer and write to Bitcoin, secures transactions with Bitcoin finality, and introduces fast transactions between Bitcoin blocks. The tense is not consistent, which matters if you plan against this page. One sentence calls it the next major proposed upgrade, another says fast transactions in between Bitcoin blocks are proposed for it, and the six-item STACKS list then states the same capabilities in the present tense as settled properties. The identifier drifts with it: SIP-021 in the first mention, SIP-21 in the second, both resolving to `sips/sip-021/sip-021-trustless-two-way-peg-for-bitcoin.md`. Treat the acronym page as an intention and the SIP as the specification. ## Clarity is interpreted, decidable and readable on chain Clarity gets introduced twice, and the two introductions disagree about its age. The language section calls it a new language for smart contracts, while the history paragraph says the initial version of Stacks, launched in early 2021, already shipped Clarity for contracts that respond to Bitcoin transactions. On substance both descriptions agree. The language is decidable, meaning you can know with certainty from the code itself what the program will do, it is interpreted rather than compiled, and its source code is published on the blockchain. That last property turns review into a read rather than a rebuild, and the README links an explainer that frames the goal as closing 8 dangerous smart contract vulnerabilities. ```bash https://book.clarity-lang.org/ https://explorer.stacks.co/txid/SP000000000000000000002Q6VF78.pox?chain=mainnet ``` The book is where the syntax and the reference live, with the language site at `clarity-lang.org` for the shorter version. The explorer address is the proof-of-transfer contract on mainnet, whose deployed source is the concrete case of a contract you can read without building anything first. ## STX pays the miners, the gas and the peg signers The token section only makes sense read as one paragraph, because STX carries three jobs at once. It pays the block subsidy that incentivises mining of the layer, it pays incentives for sBTC peg-out signing, and it is the gas for smart contract execution. What those miners protect is a ledger the README admits cannot sit on Bitcoin: that data cannot be stored at the Bitcoin main chain and needs to be stored outside it. Holders get the other side of the deal, locking STX to earn Bitcoin rewards, so one asset funds security while the other pays out to those who sit still. Distribution is stated in a single sentence: STX reached the public through the first-ever SEC qualified token offering in US history, and the project decentralized before the mainnet launch in Jan 2021, with 30+ independent companies working in the ecosystem. ## There is no install command, only three repositories Nothing here can be installed, and no build command, package name or port is given. Its answer to getting started is the documentation site plus a short list of repositories to open, reproduced here exactly as given. ```bash https://docs.stacks.co/ https://github.com/stacks-network/stacks-blockchain https://github.com/stacks-network/docs ``` Open the Rust repository when the question is whether the consensus described in prose exists as code. Open the documentation repository for configuration keys. Keep stacks.js beside any wallet work, since the README names it as the JavaScript library for identity, auth and signing. One action needs no build at all: reading deployed proof-of-transfer source on the mainnet explorer, which is how the interpreted, on-chain claim gets checked by hand. Anything past that, signing blocks or submitting transactions, is documented outside these entries. ## Trustless in the acronym, trust-minimized in the peg The peg gets two different confidence levels inside one file. The STACKS list calls it a trustless Bitcoin peg mechanism, write to Bitcoin, and the section explaining sBTC calls the same machinery trust-minimized, operated by a dynamic group of economically incentivized actors. Those actors are partly paid in the layer's own token, since STX funds incentives for peg-out signing, so the trust being reduced is priced in the asset being bridged. A second gap sits nearby. The documents treated as authoritative, the historical overview, the 2026 overview slides and the 2026 Bitcoin Staking whitepaper that introduces Bitcoin Bonds, are hosted documents and CDN files, so edits to them leave no trace in this repository's history. ```bash https://stacks.co/sbtc https://magic.fun https://lnswap.org ``` Those three addresses are how the README points at BTC moving without a custodian: the sBTC page, Magic BTC atomic swaps and Lightning swaps, with a Catamaran write-up linked from the Hiro blog as the worked example of a swap. ## Prose or Rust: what each route lets you verify Engineers have two real routes, and the difference between them is reviewability rather than capability. Take the prose route and you inherit hosted decks, an acronym page that states outcomes a proposal has not settled, and claims with no landing date behind them. Take the repository route and you read Rust, but it is the implementation that every statement in this README points at, with the improvement proposals under `stacksgov/sips` describing how it is meant to change. The same split runs through the contract layer: Clarity publishes interpreted source on chain, so auditing means reading deployed text, while a compiled pipeline gives artifacts and build steps instead. Neither route settles the versioning question. The last push here was on 2026-05-20 on the master branch, and this repository carries no GitHub releases, so nothing records when a described capability actually reached the runtime. ## Conclusion Read this repository as a map, not an implementation: it holds no consensus code, only a README, the sBTC and stacking notes, and the whitepapers it links. Engineers evaluating the protocol for a build should open the Rust reference implementation next, because every guarantee described here, from the peg to microblock settlement, is implemented elsewhere. Teams wanting one vendorable component will not find it in these entries. Before quoting the six STACKS claims in a design document, check each against the SIP text. ## FAQ ### What is stacks-network/stacks used for? It is the overview repository for the Stacks layer, holding the README, notes such as sBTC-FAQ.md and stacking.md, and links to the whitepapers. Its Code section sends readers to stacks-blockchain for the Rust reference implementation and to stacks.js for JavaScript clients. ### Does Stacks modify Bitcoin itself? No. The layer brings more functionality to Bitcoin without modifying Bitcoin L1, and leader election happens on Bitcoin while new blocks are written on the Stacks layer. ### Which language are smart contracts written in on Stacks? Clarity, described as a decidable language that is interpreted rather than compiled, with contract source code published on the blockchain. The book and the language site are linked for syntax and reference detail. ### How does sBTC move BTC between Bitcoin and the Stacks layer? It is called a trust-minimized Bitcoin peg operated by a dynamic group of economically incentivized actors, while the six-item STACKS list in the same README calls the peg trustless. Peg-out signing is paid for with STX. ### What does the Nakamoto upgrade add to Stacks? A trustless two-way Bitcoin peg for moving BTC in and out of the layer and writing to Bitcoin, transactions secured by Bitcoin finality, and fast transactions between Bitcoin blocks. The upgrade is described as proposed, written as SIP-021 once and SIP-21 once, and both point at the same proposal document. ## Sources - [Issues](https://github.com/stacks-network/stacks/issues) - [Project website](https://www.stacks.co/) - [README](https://github.com/stacks-network/stacks/blob/master/README.md) - [stacks-network/stacks on GitHub](https://github.com/stacks-network/stacks) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stacks-network-stacks